Update Json man page.

TODO.txt

@@ -24,7 +24,7 @@ Milestone: v0.2.0
 
 [~] Documentation
     [x] User functions
-    [ ] Json functions
+    [x] Json functions
     [ ] Db functions
     [ ] Uia (move docs from Matrix)
 

man/man3/Json.3

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: November 30 2022 $
+.Dd $Mdocdate: March 6 2023 $
 .Dt JSON 3
 .Os Telodendria Project
 .Sh NAME
@@ -46,6 +46,10 @@
 .Fn JsonEncode "HashMap *" "FILE *"
 .Ft HashMap *
 .Fn JsonDecode "FILE *"
+.Ft JsonValue *
+.Fn JsonGet "HashMap *" "size_t" "..."
+.Ft JsonValue *
+.Fn JsonSet "HashMap *" "size_t" "..."
 .Sh DESCRIPTION
 .Nm
 is a fully-featured JSON API for C using
@@ -195,6 +199,19 @@ everything accessible from the passed object.
 .Fn JsonDecode
 does the opposite; it reads from a JSON stream and decodes it
 into a hash map of JsonValues.
+.Pp
+.Fn JsonSet
+and
+.Fn JsonGet
+are convenience functions that allow the caller to retrieve and
+manipulate arbitrarily deep keys within a JSON object. They take
+a root JSON object, the number of levels deep to go, and then that
+number of keys as a varargs list. All keys must have objects
+as values, with the exception of the last one, which is the one
+being retrieved or set.
+.Fn JsonSet
+will create any intermediate objects as necessary to set the
+proper key.
 .Sh RETURN VALUES
 .Pp
 .Fn JsonValueType
@@ -223,6 +240,13 @@ success value.
 .Fn JsonDecode
 returns a hash map of JsonValues that can be manipulated by
 this API, or NULL if there was an error parsing the JSON.
+.Pp
+.Fn JsonGet
+returns a JsonValue, or NULL if the requested key is not set
+in the object.
+.Fn JsonGet
+returns the previous value of the provided key, or NULL if there
+was no previous value.
 .Sh SEE ALSO
 .Xr HashMap 3 ,
 .Xr Array 3

src/Json.c

@@ -1165,7 +1165,8 @@ JsonSet(HashMap * json, JsonValue * newVal, size_t nArgs,...)
         val = HashMapGet(tmp, key);
         if (!val)
         {
-            goto finish;
+            val = JsonValueObject(HashMapCreate());
+            HashMapSet(tmp, key, val);
         }
 
         if (JsonValueType(val) != JSON_OBJECT)
@@ -1183,53 +1184,3 @@ finish:
     va_end(argp);
     return val;
 }
-
-int
-JsonCreate(HashMap * json, JsonValue * newVal, size_t nArgs,...)
-{
-    HashMap *tmp = json;
-    JsonValue *val = NULL;
-    size_t i;
-    char *key;
-    int ret = 0;
-
-    va_list argp;
-
-    if (!json || !newVal || !nArgs)
-    {
-        return 0;
-    }
-
-    va_start(argp, nArgs);
-
-    for (i = 0; i < nArgs - 1; i++)
-    {
-        key = va_arg(argp, char *);
-
-        val = HashMapGet(tmp, key);
-        if (!val)
-        {
-            val = JsonValueObject(HashMapCreate());
-            HashMapSet(tmp, key, val);
-        }
-        else if (JsonValueType(val) != JSON_OBJECT)
-        {
-            goto finish;
-        }
-
-        tmp = JsonValueAsObject(val);
-    }
-
-    key = va_arg(argp, char *);
-    if (HashMapGet(tmp, key))
-    {
-        goto finish;
-    }
-
-    HashMapSet(tmp, key, newVal);
-    ret = 1;
-
-finish:
-    va_end(argp);
-    return ret;
-}

src/include/Json.h

@@ -110,7 +110,4 @@ extern JsonValue *
 extern JsonValue *
  JsonSet(HashMap *, JsonValue *, size_t,...);
 
-extern int
- JsonCreate(HashMap *, JsonValue *, size_t,...);
-
 #endif                             /* TELODENDRIA_JSON_H */