Merge branch 'release/0.3'

dhiraj · dhiraj · commit c75dc278f20b · 2018-08-09T12:37:02.000+05:30
diff --git a/.idea/misc.xml b/.idea/misc.xml
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ Adds [JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901) support to
 and modifying original fork by [John Lombardo](https://github.com/johnnylambada/gson). 
 
 ## Usage
-This library provides a simple lookup implementation, that tries to always provide a valid Kotlin object for quick and easy dereferencing and direct usage of JSON pointers to read values from Gson's JsonParser when you don't want to keep making specific Kotlin data classes for one off use cases or specific error handling.
+This library provides a simple lookup implementation, that tries to always provide a valid Kotlin object for quick and easy dereferencing and direct usage of JSON pointers to read values from Gson's JsonParser when you don't want to keep making specific Kotlin data classes for one off use cases or specific error handling. By using the provided _safeX_ extension properties on JsonElement, you can rest assured that you'll always get a good value back instead of an Exception at runtime.
 
 ### Parse JSON using Gson
 Consider a JSON error response that you're receiving from your API like this:
@@ -36,16 +36,22 @@ Once you have a JsonElement you can get a JsonPointer with it as root, using the
     //pointer is JsonPointer    
 ```
 
-Once you have a JsonPointer, you can directly access values anywhere in the whole JSON tree using pointer syntax:
+Once you have a JsonPointer, you can directly access a JsonPointer anywhere in the whole JSON tree using pointer syntax:
 ```kotlin
-    val message = pointer.at("/email/0")
+    val message = pointer.at("/email/0").safeString
     //message is the first error String, "Enter a valid email address"
 ```
 
-**Note:** The `at()` function always tries to return a valid value. It will never return a null. In case of a JSON null, it will return an empty string, `""`
+###Safe value retreival 
+The `at()` function always returns a valid JsonElement, even when there is no match. You can use the standard `isJsonPrimitive` or other similar methods to determine what you got back. You can more easily use the provided convenience get properties to get either the actual value at the node or a default value that you can check and flow against.
+
+* `JsonElement.safeNumber` returns any `Number` found at the pointer, or a `0`
+* `JsonElement.safeString` returns any `String` found at the pointer, or a `""`
+* `JsonElement.safeBoolean` returns any `Boolean` found at the pointer, or a `false`
+* `JsonElement.safeJsonObject` returns any `JsonObject` found at the pointer, or a `JsonObject()`, which works out to an empty JSON object:  `{}`
+* `JsonElement.safeJsonArray` returns any `JsonArray` found at the pointer, or a `JsonArray()`, which works out to an empty JSON Array, `[]`
+
 
-### Access a JsonElement
-**(Optional)** In case you _do_ need to get access to a JsonElement and not the actual value within it, you can use the `dereference()` method which will return a normal `JsonElement` for further evaluation.
 
 ## Installation
 GsonPointer uses JitPack.io to distribute the library.
diff --git a/com.traversient.gsonpointer/src/main/java/com/traversient/gsonpointer/JsonPointer.kt b/com.traversient.gsonpointer/src/main/java/com/traversient/gsonpointer/JsonPointer.kt
@@ -21,36 +21,24 @@ import com.google.gson.JsonObject
  * {"foo":{"bar":"baz"}}
 ` *
  */
-class JsonPointer(val element: JsonElement) {
-
-    fun at(pointer: String): Any{
-        val elem = dereference(pointer)
-        return when{
-            elem == null -> ""
-            elem.isJsonObject -> elem.asJsonObject
-            elem.isJsonArray -> elem.asJsonArray
-            elem.isJsonPrimitive && elem.asJsonPrimitive.isBoolean -> elem.asBoolean
-            elem.isJsonPrimitive && elem.asJsonPrimitive.isString -> elem.asString
-            elem.isJsonPrimitive && elem.asJsonPrimitive.isNumber -> elem.asNumber
-            else -> ""
-        }
-    }
+class JsonPointer internal constructor(val element: JsonElement) {
 
-    fun dereference(pointer: String, generation: Int = 0): JsonElement? {
+    @JvmOverloads
+    fun at(pointer: String, generation: Int = 0): JsonElement {
         val list = getPath(pointer, false)
         return list[list.size - 1 - generation]
     }
 
     operator fun set(pointer: String, value: JsonElement) {
         val last = getLastElement(pointer)
-        val `object` = last.element!!.asJsonObject
+        val `object` = last.element.asJsonObject
         `object`.remove(last.name)
         `object`.add(last.name, value)
     }
 
-    private fun getPath(pointer: String, mutative: Boolean): List<JsonElement?> {
+    private fun getPath(pointer: String, mutative: Boolean): List<JsonElement> {
         val tokens = pointer.split("/".toRegex()).toTypedArray()
-        val ret = ArrayList<JsonElement?>(tokens.size)
+        val ret = ArrayList<JsonElement>(tokens.size)
         var element: JsonElement? = null
         for (i in tokens.indices) {
             val token = unescape(tokens[i])
@@ -81,10 +69,10 @@ class JsonPointer(val element: JsonElement) {
                             null
                     }
                 }
-                ret.add(element)
                 if (element == null) {
                     break
                 }
+                ret.add(element)
             }
         }
         return ret
@@ -144,7 +132,7 @@ class JsonPointer(val element: JsonElement) {
         }
     }
 
-    private class Element(internal val element: JsonElement?, internal val name: String)
+    private class Element(internal val element: JsonElement, internal val name: String)
 }
 
 //Extension property on JsonElement to get a pointer
@@ -153,3 +141,42 @@ val JsonElement.pointer: JsonPointer
         return JsonPointer(this)
     }
 
+val JsonElement.safeNumber: Number
+    get() {
+        if (this.isJsonPrimitive && !this.isJsonNull && this.asJsonPrimitive.isNumber) {
+            return this.asNumber
+        }
+        return 0
+    }
+
+val JsonElement.safeString: String
+    get() {
+        if (this.isJsonPrimitive && !this.isJsonNull && this.asJsonPrimitive.isString) {
+            return this.asString
+        }
+        return ""
+    }
+
+val JsonElement.safeBoolean: Boolean
+    get() {
+        if (this.isJsonPrimitive && !this.isJsonNull && this.asJsonPrimitive.isBoolean) {
+            return this.asBoolean
+        }
+        return false
+    }
+
+val JsonElement.safeJsonObject: JsonObject
+    get() {
+        if (!this.isJsonNull && this.isJsonObject) {
+            return this.asJsonObject
+        }
+        return JsonObject()
+    }
+
+val JsonElement.safeJsonArray: JsonArray
+    get() {
+        if (!this.isJsonNull && this.isJsonArray) {
+            return this.asJsonArray
+        }
+        return JsonArray()
+    }
diff --git a/com.traversient.gsonpointer/src/test/java/com/traversient/gsonpointer/JsonPointerTest.kt b/com.traversient.gsonpointer/src/test/java/com/traversient/gsonpointer/JsonPointerTest.kt
@@ -1,12 +1,9 @@
 package com.traversient.gsonpointer
 
+import com.google.gson.*
 import org.junit.Test
 
 import org.junit.Assert.*
-import com.google.gson.JsonElement
-import com.google.gson.JsonObject
-import com.google.gson.JsonParser
-import com.google.gson.JsonPrimitive
 
 import com.traversient.gsonpointer.JsonPointer
 
@@ -82,6 +79,35 @@ class JsonPointerTest {
             "      \"m~n\": 8\n" +
             "   }"
 
+    private val JSON_Multi = "{\n" +
+            "  \"widget\": {\n" +
+            "    \"debug\": \"on\",\n" +
+            "    \"window\": {\n" +
+            "      \"title\": \"Sample Konfabulator Widget\",\n" +
+            "      \"name\": \"main_window\",\n" +
+            "      \"width\": 500,\n" +
+            "      \"height\": 500\n" +
+            "    },\n" +
+            "    \"image\": {\n" +
+            "      \"src\": \"Images/Sun.png\",\n" +
+            "      \"name\": \"sun1\",\n" +
+            "      \"hOffset\": 250,\n" +
+            "      \"vOffset\": 250,\n" +
+            "      \"alignment\": \"center\"\n" +
+            "    },\n" +
+            "    \"text\": {\n" +
+            "      \"data\": \"Click Here\",\n" +
+            "      \"size\": 36,\n" +
+            "      \"style\": \"bold\",\n" +
+            "      \"name\": \"text1\",\n" +
+            "      \"hOffset\": 250,\n" +
+            "      \"vOffset\": 100,\n" +
+            "      \"alignment\": \"center\",\n" +
+            "      \"onMouseUp\": \"sun1.opacity = (sun1.opacity / 100) * 90;\"\n" +
+            "    }\n" +
+            "  }\n" +
+            "}"
+
     @Test
     @Throws(Exception::class)
             /**
@@ -90,18 +116,18 @@ class JsonPointerTest {
     fun rfc6901Test() {
         val root = JsonParser().parse(JSON_6901)
         val json = root.pointer
-        assertEquals(root, json.dereference(""))
-        assertEquals(JsonParser().parse("[\"bar\", \"baz\"]"), json.dereference("/foo"))
-        assertEquals("bar", json.dereference("/foo/0")!!.getAsString())
-        assertEquals(0, json.dereference("/")!!.getAsInt())
-        assertEquals(1, json.dereference("/a~1b")!!.getAsInt())
-        assertEquals(2, json.dereference("/c%d")!!.getAsInt())
-        assertEquals(3, json.dereference("/e^f")!!.getAsInt())
-        assertEquals(4, json.dereference("/g|h")!!.getAsInt())
-        assertEquals(5, json.dereference("/i\\j")!!.getAsInt())
-        assertEquals(6, json.dereference("/k\"l")!!.getAsInt())
-        assertEquals(7, json.dereference("/ ")!!.getAsInt())
-        assertEquals(8, json.dereference("/m~0n")!!.getAsInt())
+        assertEquals(root, json.at(""))
+        assertEquals(JsonParser().parse("[\"bar\", \"baz\"]"), json.at("/foo"))
+        assertEquals("bar", json.at("/foo/0")!!.getAsString())
+        assertEquals(0, json.at("/")!!.getAsInt())
+        assertEquals(1, json.at("/a~1b")!!.getAsInt())
+        assertEquals(2, json.at("/c%d")!!.getAsInt())
+        assertEquals(3, json.at("/e^f")!!.getAsInt())
+        assertEquals(4, json.at("/g|h")!!.getAsInt())
+        assertEquals(5, json.at("/i\\j")!!.getAsInt())
+        assertEquals(6, json.at("/k\"l")!!.getAsInt())
+        assertEquals(7, json.at("/ ")!!.getAsInt())
+        assertEquals(8, json.at("/m~0n")!!.getAsInt())
     }
 
 
@@ -118,7 +144,7 @@ class JsonPointerTest {
     fun getRootTest() {
         val expected = JsonParser().parse(JSON)
         val json = expected.pointer
-        val actual = json.dereference("")
+        val actual = json.at("")
         assertEquals(expected, actual)
     }
 
@@ -127,7 +153,7 @@ class JsonPointerTest {
     fun getSimpleStringTest() {
         val json = JsonParser().parse(JSON).pointer
         val expected = "library of congress"
-        val actual = json.dereference("/library/name")!!.getAsString()
+        val actual = json.at("/library/name")!!.getAsString()
         assertEquals(expected, actual)
     }
 
@@ -136,7 +162,7 @@ class JsonPointerTest {
     fun getSimpleStringInArrayTest() {
         val json = JsonParser().parse(JSON).pointer
         val expected = "sci-fi"
-        val actual = json.dereference("/library/section/0/name")!!.getAsString()
+        val actual = json.at("/library/section/0/name")!!.getAsString()
         assertEquals(expected, actual)
     }
 
@@ -145,7 +171,7 @@ class JsonPointerTest {
     fun getDeepArrayTest() {
         val json = JsonParser().parse(JSON).pointer
         val expected = "Jerry Pournelle"
-        val actual = json.dereference("/library/section/0/title/0/book/author/1")!!.getAsString()
+        val actual = json.at("/library/section/0/title/0/book/author/1")!!.getAsString()
         assertEquals(expected, actual)
     }
 
@@ -156,19 +182,10 @@ class JsonPointerTest {
         val expected = "hello world"
         val pointer = "/this/is/a/new/thing"
         json.set(pointer, JsonPrimitive(expected))
-        val actual = json.dereference(pointer)!!.getAsString()
+        val actual = json.at(pointer)!!.getAsString()
         assertEquals(expected, actual)
     }
 
-    @Test
-    fun alwaysValidValue() {
-        val json = JsonParser().parse(JSON).pointer
-        assertTrue(json.at("/library") is JsonObject)
-        assertEquals(json.at("/"), "")
-        assertEquals(json.at("/nothing"), "")
-        assertEquals(json.at("/"), "")
-    }
-
     @Test
     @Throws(Exception::class)
     fun setStringTestWithArrays() {
@@ -178,11 +195,11 @@ class JsonPointerTest {
         val thingPointer = "/4/this/is/a/0/new/thing"
         val pointer = JsonParser().parse(originalJson).pointer
 
-        assertEquals(null, pointer.dereference(thingPointer))
+        assertEquals(JsonArray(), pointer.at(thingPointer))
         pointer.set(thingPointer, JsonPrimitive(originalValue))
-        assertEquals(originalValue, pointer.dereference(thingPointer)!!.getAsString())
+        assertEquals(originalValue, pointer.at(thingPointer)!!.getAsString())
         pointer.set(thingPointer, JsonPrimitive(expectedValue))
-        assertEquals(expectedValue, pointer.dereference(thingPointer)!!.getAsString())
+        assertEquals(expectedValue, pointer.at(thingPointer)!!.getAsString())
     }
 
     @Test
@@ -194,11 +211,11 @@ class JsonPointerTest {
         val thingPointer = "/this/is/a/0/new/thing"
         val pointer = JsonParser().parse(originalJson).pointer
 
-        assertEquals(null, pointer.dereference(thingPointer))
+        assertEquals(JsonObject(), pointer.at(thingPointer))
         pointer.set(thingPointer, JsonPrimitive(originalValue))
-        assertEquals(originalValue, pointer.dereference(thingPointer)!!.getAsString())
+        assertEquals(originalValue, pointer.at(thingPointer)!!.getAsString())
         pointer.set(thingPointer, JsonPrimitive(expectedValue))
-        assertEquals(expectedValue, pointer.dereference(thingPointer)!!.getAsString())
+        assertEquals(expectedValue, pointer.at(thingPointer)!!.getAsString())
     }
 
     @Test
@@ -210,11 +227,11 @@ class JsonPointerTest {
         val thingPointer = "/this/is/a/0/new/thing"
         val pointer = JsonParser().parse(originalJson).pointer
 
-        assertEquals(null, pointer.dereference(thingPointer))
+        assertEquals(JsonObject(), pointer.at(thingPointer))
         pointer.set(thingPointer, JsonPrimitive(originalValue))
-        assertEquals(originalValue, pointer.dereference(thingPointer)!!.getAsBoolean())
+        assertEquals(originalValue, pointer.at(thingPointer)!!.getAsBoolean())
         pointer.set(thingPointer, JsonPrimitive(expectedValue))
-        assertEquals(expectedValue, pointer.dereference(thingPointer)!!.getAsBoolean())
+        assertEquals(expectedValue, pointer.at(thingPointer)!!.getAsBoolean())
     }
 
     @Test
@@ -225,9 +242,9 @@ class JsonPointerTest {
         val reasonPointer = "/data/extensions/currentVisit/reason"
         val pointer = JsonParser().parse(originalJson).pointer
 
-        assertEquals(null, pointer.dereference(reasonPointer))
+        assertEquals(JsonObject(), pointer.at(reasonPointer))
         pointer.set(reasonPointer, JsonPrimitive(expectedValue))
-        assertEquals(expectedValue, pointer.dereference(reasonPointer)!!.getAsString())
+        assertEquals(expectedValue, pointer.at(reasonPointer)!!.getAsString())
     }
 
     @Test
@@ -240,13 +257,13 @@ class JsonPointerTest {
         val value2 = 1
         val value3 = true
 
-        assertEquals(null, pointer.dereference(thingPointer))
+        assertEquals(JsonObject(), pointer.at(thingPointer))
         pointer.set(thingPointer, JsonPrimitive(value1))
-        assertEquals(value1, pointer.dereference(thingPointer)!!.getAsString())
+        assertEquals(value1, pointer.at(thingPointer)!!.getAsString())
         pointer.set(thingPointer, JsonPrimitive(value2))
-        assertEquals(value2, pointer.dereference(thingPointer)!!.getAsInt())
+        assertEquals(value2, pointer.at(thingPointer)!!.getAsInt())
         pointer.set(thingPointer, JsonPrimitive(value3))
-        assertEquals(value3, pointer.dereference(thingPointer)!!.getAsBoolean())
+        assertEquals(value3, pointer.at(thingPointer)!!.getAsBoolean())
     }
 
     @Test
@@ -257,9 +274,9 @@ class JsonPointerTest {
         val reasonPointer = "/foo/bar"
         val pointer = JsonParser().parse(originalJson).pointer
 
-        assertEquals(null, pointer.dereference(reasonPointer))
+        assertEquals(JsonObject(), pointer.at(reasonPointer))
         pointer.set(reasonPointer, JsonPrimitive(expectedValue))
-        assertEquals(expectedValue, pointer.dereference(reasonPointer)!!.getAsString())
+        assertEquals(expectedValue, pointer.at(reasonPointer)!!.getAsString())
         println(pointer.element.toString())
     }
 }
