Kotlin JSON
Kotlin JSON is a lightweight, highly stylized JavaScript Object Notation (JSON) for The Kotlin Programming Language.
Stylistic
Kotlin JSON allows developers to use the stylistic abilities of Kotlin's DSL API to create a stylish but highly readable and functional Domain Specifying Language:
fun main(args: Array<String>) {
val json = JSObject {
"message" to "Hello, World!"
}
println(json.string("message"))
}
// Hello, World!
Full Type Support
Kotlin JSON supports JSON Objects, JSON Arrays, as well as normal JSON values such as Strings, Booleans, Numbers, and null values!
fun main(args: Array<String>) {
JSObject {
"null" to null
"string" to "Hello, World!"
"int" to 123
"long" to 1234567891011121314L
"float" to 123.4
"double" to 12345678.9101112
"object" to JSObject { }
"array" to JSArray()
}
}
The following types are supported
Featured
Kotlin JSON packs standard string parsing and IO operations which allow you to simplistically read JSON text from anything from a String to an InputStream!
fun main(args: Array<String>) {
// my-json-file.json
// {
// "message": "Hello, this is from a file!"
// }
val myJsonFile = File("my-json-file.json")
val json = myJsonFile.readJSObject()
println(json.string("message"))
}
// Hello, this is from a file!
Familiar
Kotlin JSON embraces kotlin style in order to create streamlined operations between it and the kotlin standard library.
fun main(args: Array<String>) {
// similar to mapOf()
jsObjectOf("foo" to "bar")
// similar to listOf()
jsArrayOf("foo", "bar", "baz")
// similar to toMap()
mapOf("foo" to "bar").toJSObject()
// similar to toList()
listOf("foo", "bar", "baz").toJSArray()
}
The library provides the interfaces JSObject
and JSArray
which both extend the MutableMap
and MutableList
interfaces respectively, and allow for a familiar writing style to the rest of the kotlin language.
Reflective (EXPERIMENTAL)
The reflect
module of the library uses reflection based operations to easily and efficiently serialize and deserialize JSObjects
from and into class instances!
For the upcoming examples, consider the following 2 data classes:
data class House(
val address: String,
val tenants: List<Person>
)
data class Person(
val name: String,
val age: Int,
@JSOptional val mother: Person? = null,
@JSOptional val father: Person? = null
)
Using the JSDeserializer, JSObjects can be transformed into instances of data classes, as well as other types.
fun main(args: Array<String>) {
val deserializer = JSDeserializer()
val json = JSObject {
"address" to "123 JSON Lane"
val mother = JSObject {
"name" to "Maxine"
"age" to 42
}
val father = JSObject {
"name" to "Logan"
"age" to 45
}
val child = JSObject {
"name" to "James"
"age" to 16
"mother" to mother
"father" to father
}
"tenants" to JSArray(mother, father, child)
}
val house = deserializer.deserialize(json, House::class)
for(tenant in house.tenants) {
println("${tenant.name} is ${tenant.age}")
}
}
// Maxine is 42
// Logan is 45
// James is 16
You can also easily serialize any type into a JSObject using an instance of JSSerializer
!
fun main(args: Array<String>) {
val serializer = JSSerializer()
val house = House(
address = "123 JSON Lane",
tenants = listOf(
Person(name = "John", age = 22),
Person(name = "Jill", age = 20)
)
)
val json = serializer.serialize(house)
println(json)
}
// {"address":"123 JSON Lane","tenants":[{"name":"John","age":22}, {"name":"Jill","age":20}]}
Dependency Setup
Gradle
repositories {
jcenter()
}
dependencies {
compile "me.kgustave:kotlin-json:${kotlin_json_version}"
// for reflection support add this
compile "me.kgustave:kotlin-json-reflect:${kotlin_json_version}"
}
Maven
<repositories>
<repository>
<id>jcenter</id>
<name>jcenter-bintray</name>
<url>https://jcenter.bintray.com</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>me.kgustave</groupId>
<artifactId>kotlin-json</artifactId>
<version>${kotlin_json_version}</version>
<type>pom</type>
</dependency>
<!-- for reflection support add this -->
<dependency>
<groupId>me.kgustave</groupId>
<artifactId>kotlin-json-reflect</artifactId>
<version>${kotlin_json_version}</version>
</dependency>
</dependencies>
License
kotlin-json is licensed under the Apache 2.0 License
Copyright 2018 Kaidan Gustave
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.