forge

Functional style JSON parsing in Kotlin

License

License

GroupId

GroupId

com.github.kittinunf.forge
ArtifactId

ArtifactId

forge
Last Version

Last Version

1.0.0-alpha3
Release Date

Release Date

Type

Type

jar
Description

Description

forge
Functional style JSON parsing in Kotlin
Project URL

Project URL

https://github.com/kittinunf/Forge
Source Code Management

Source Code Management

https://github.com/kittinunf/Forge

Download forge

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.kittinunf.forge/forge/ -->
<dependency>
    <groupId>com.github.kittinunf.forge</groupId>
    <artifactId>forge</artifactId>
    <version>1.0.0-alpha3</version>
</dependency>
// https://jarcasting.com/artifacts/com.github.kittinunf.forge/forge/
implementation 'com.github.kittinunf.forge:forge:1.0.0-alpha3'
// https://jarcasting.com/artifacts/com.github.kittinunf.forge/forge/
implementation ("com.github.kittinunf.forge:forge:1.0.0-alpha3")
'com.github.kittinunf.forge:forge:jar:1.0.0-alpha3'
<dependency org="com.github.kittinunf.forge" name="forge" rev="1.0.0-alpha3">
  <artifact name="forge" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.github.kittinunf.forge', module='forge', version='1.0.0-alpha3')
)
libraryDependencies += "com.github.kittinunf.forge" % "forge" % "1.0.0-alpha3"
[com.github.kittinunf.forge/forge "1.0.0-alpha3"]

Dependencies

runtime (3)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib jar 1.4.0
org.json : json jar 20190722
com.github.kittinunf.result : result jar 3.1.0

Project Modules

There are no modules declared in this project.

Forge

Kotlin jcenter MavenCentral Build Status Codecov

Forge is a JSON parsing library that helps you map your Kotlin class from a JSON in a functional way. Forge is highly inspired by Aeson, JSON parsing library in Haskell.

Ideology

Have you ever wonder that how other JSON libraries out there work? Magic under the hood? or a complex annnotation processing? If that is something that you don't want, with Forge, we don't do any of those.

Forge aims to provide a full control over how to parse JSON into a Kotlin class, no more magic, no more annotation.

Installation

Gradle

repositories {
    jcenter() //or mavenCentral()
}

dependencies {
    compile 'com.github.kittinunf.forge:forge:<latest-version>'
}

Usage (tl;dr:)

Given you have JSON as such

{
  "id": 1,
  "name": "Clementina DuBuque",
  "age": 46,
  "email": "[email protected]",
  "phone": {
    "name": "My Phone",
    "model": "Pixel 3XL"
  },
  "friends": [
    {
        "id": 11,
        "name": "Ervin Howell",
        "age": 32,
        "email": "[email protected]",
        "phone": {
            "name": "My iPhone",
            "model": "iPhone X"
        },
        "friends": []
    }
  ],
  "dogs": [
    {
      "name": "Lucy",
      "breed": "Dachshund",
      "is_male": false
    }
  ]
}

You can write your Kotlin class definition as such

data class User(val id: Int,
                val name: String,
                val age: Int,
                val email: String?,
                val phone: Phone,
                val friends: List<User>,
                val dogs: List<Dog>?)

data class Phone(val name: String, val model: String)
data class Dog(val name: String, val breed: String, val male: Boolean)

fun userDeserializer(json: JSON) =
    ::User.create.
        map(json at "id").
        apply(json at "name").
        apply(json at "age").
        apply(json maybeAt "email").
        apply(json.at("phone", phoneDeserializer)),  // phoneDeserializer is a lambda, use it directly
        apply(json.list("friends", ::userDeserializer)).  //userDeserializer is a function, use :: as a function reference
        apply(json.maybeList("dogs", dogDeserializer))

val phoneDeserializer = { json: JSON ->
    ::Dog.create.
        map(json at "name").
        apply(json at "model")
}

val dogDeserializer = { json: JSON ->
    ::Dog.create.
        map(json at "name").
        apply(json at "breed").
        apply(json at "is_male")
}

Viola!, then, you can deserialize your JSON like

//jsonContent is when you receive data as a JSON
val result = Forge.modelFromJson(jsonContent, ::userDeserializer)

when (result) {
    DeserializedResult.Success -> {
        val user = result.value
        //success, do something with user
    }

    DeserializedResult.Failure -> {
        val error = result.error
        //failure, do something with error
    }
}

Credits

Forge is brought to you by contributors.

Licenses

Forge is released under the MIT license.

Versions

Version
1.0.0-alpha3