changeset 3:e6626e8d6433

Update/clarify README docs
author Norman Gray <norman@astro.gla.ac.uk>
date Thu, 05 Sep 2013 21:08:28 +0100
parents 27a0f5a39536
children f737659096e9
files README.md src/jason.c src/jason.h src/json2der.c
diffstat 4 files changed, 52 insertions(+), 16 deletions(-) [+]
line wrap: on
line diff
--- a/README.md	Thu Sep 05 20:34:52 2013 +0100
+++ b/README.md	Thu Sep 05 21:08:28 2013 +0100
@@ -62,12 +62,12 @@
 
 Parse the JSON object given in the string.  If the string cannot be
 parsed, then this returns `NULL`, and an explanation is available from
-the function `const char* unsupported_message()`.
+the function `const char* unsupported_message()`.  The returned object
+should be freed by `free_json_object`.
 
-    void free_json_object(JsonObject o, int free_contents);
+    void free_json_object(JsonObject o);
 
-Free the object.  If the argument `free_contents` is true, then any
-contents (such as a string, for example) are freed also.
+Free the object.  Any allocated memory within the object is freed also.
 
     const char* print_json_object(JsonObject obj);
 
@@ -76,21 +76,21 @@
 
     byte* get_der_encoding(JsonObject obj, size_t *len);
 
-Get the DER-encoding of the object.  The object should not be freed by
+Get the DER-encoding of the object.  The object must not be freed by
 the caller.
 
     char* bytes_to_string(byte* b, size_t blen);
 
 Utility method to serialise a byte sequence to a printable string of
-hex digits.
+hex digits.  The returned object must be freed by the caller.
 
     JsonObject parse_der_bytes(byte*, size_t, size_t*);
 
 Decode a sequence of bytes which are the DER encoding of a JSON
-object, and return the object.  The result should be freed by
-`free_json_object` when no longer required.  If the byte sequence
+object, and return the object.  If the byte sequence
 cannot be parsed, then this returns `NULL`, and an explanation is
 available from the function `const char* unsupported_message()`.
+The result should be freed by `free_json_object` when no longer required.  
 
     const char* jason_version_string(void);
     int jason_version_number(void);
@@ -119,7 +119,7 @@
 terms of the [GNU General Public Licence, v3.0][]
 
 The distribution includes the [`lcut` unit-testing framework][lcut],
-which is Copyright 2005-2010 Tony Bai, and released under the terms of
+which is Copyright 2005–2010 Tony Bai, and released under the terms of
 the Apache Licence, Version 2.0.
 
 Norman Gray  
--- a/src/jason.c	Thu Sep 05 20:34:52 2013 +0100
+++ b/src/jason.c	Thu Sep 05 21:08:28 2013 +0100
@@ -56,7 +56,7 @@
     return r;
 }
 
-void free_json_object(JsonObject o, int free_contents)
+static void free_json_object_internal(JsonObject o, int free_contents)
 {
     if (o == NULL)
         return;
@@ -68,7 +68,7 @@
             break;
           case JSON_KVPAIR:
             free((void*)o->x.kv.k);
-            free_json_object(o->x.kv.v, 1);
+            free_json_object_internal(o->x.kv.v, 1);
             break;
           case JSON_OBJECT:
           case JSON_ARRAY:
@@ -78,7 +78,7 @@
                 size_t np = o->x.a.len;
                 
                 for (i=0; i<np; i++) {
-                    free_json_object(p[i], 1);
+                    free_json_object_internal(p[i], 1);
                 }
             }
             break;
@@ -91,6 +91,14 @@
     free((void*)o);
 }
 
+/**
+ * Free the object.
+ * Any allocated memory within the object is freed also.
+ */
+void free_json_object(JsonObject o)
+{
+    free_json_object_internal(o, 1);
+}
 
 // JSON object to string
 //
@@ -213,6 +221,11 @@
     append_to_buffer_s(sb, " }");
 }
 
+/**
+ * Serialise the object to a string.
+ *
+ * The string must be subsequently freed by the caller.
+ */
 const char* print_json_object(JsonObject obj)
 {
     const char* rval;
@@ -423,6 +436,10 @@
     return b;
 }
 
+/**
+ * Get the DER-encoding of the object.
+ * The object must not be freed by the caller.
+ */
 byte* get_der_encoding(JsonObject obj, size_t *len) 
 {
     byte* rval;
@@ -449,6 +466,10 @@
     return rval;
 }
 
+/**
+ * Utility method to serialise a byte sequence to a printable string of
+ * hex digits.  The returned object must be freed by the caller.
+ */
 char* bytes_to_string(byte* b, size_t blen)
 {
     static char* buf = NULL;
@@ -992,6 +1013,12 @@
     unsupported_operation("Parsing error: %s", msg);
 }
 
+/**
+ * Parse the JSON object given in the string.  If the string cannot be
+ * parsed, then this returns `NULL`, and an explanation is available from
+ * the function `const char* unsupported_message()`.  The returned object
+ * should be freed by @{link #free_json_object}.
+ */
 JsonObject parse_json_string(const char* json_string)
 {
     JsonObject rval;
@@ -1205,8 +1232,8 @@
 #endif
 
         obj = make_kv(key->x.s, value);
-        free_json_object(key, 0);
-        free_json_object(array_obj, 0);
+        free_json_object_internal(key, 0);
+        free_json_object_internal(array_obj, 0);
         
         b += olen;
         blen -= olen;
@@ -1302,6 +1329,15 @@
     return rval;
 }
 
+/**
+ * Decode a sequence of bytes which are the DER encoding of a JSON
+ * object, and return the object.  If the byte sequence
+ * cannot be parsed, then this returns `NULL`, and an explanation is
+ * available from the function {@link #unsupported_message}.
+ *
+ * The result should be freed by
+ * {@link #free_json_object} when no longer required.
+ */
 JsonObject parse_der_bytes(byte* b, size_t blen, size_t* actuallen)
 {
     JsonObject rval = NULL;
--- a/src/jason.h	Thu Sep 05 20:34:52 2013 +0100
+++ b/src/jason.h	Thu Sep 05 21:08:28 2013 +0100
@@ -49,7 +49,7 @@
 typedef struct json_object* JsonObject;
 
 JsonObject initialise_json_object(JsonObject, JsonType);
-void free_json_object(JsonObject o, int free_contents);
+void free_json_object(JsonObject o);
 const char* print_json_object(JsonObject obj);
 byte* get_der_encoding(JsonObject obj, size_t *len);
 char* bytes_to_string(byte* b, size_t blen);
--- a/src/json2der.c	Thu Sep 05 20:34:52 2013 +0100
+++ b/src/json2der.c	Thu Sep 05 21:08:28 2013 +0100
@@ -169,7 +169,7 @@
         }
     }
 
-    free_json_object(parse_val, 1);
+    free_json_object(parse_val);
 }
 
 // defined in json_lex.c