Checkpoint: description of parallel arrays is in olace.

diff --git a/microjson.asc b/microjson.asc
index 1ba5d9e03cf3579e82b29f4d563aa74a91b2df5f..c97053abc567d55b479537aee9fcb3bfe09157fb 100644 (file)
--- a/microjson.asc
+++ b/microjson.asc
@@ -83,7 +83,7 @@ instructions.
 
 When an unexpected attribute name is encountered, the parser terminates,
 returning an error status.  Attributes and values parsed before the 
-error their storage.
+error modify their target storage.
 
 The parser recognizes a wider range of types than this, and the
 template structures can specify defaults when an expected JSON 
@@ -99,6 +99,113 @@ value; the target address tells it where to put the value.
 
 Syntax errors, or any unknown attribute name, terminate the parse.
 
+===  Simple Value Types ===
+
+The type field of a +json_attr_t+ structure can have the following
+'simple' alternatives, each corresponding to an atomic JSON value:
+
++t_check+: Value of this attribute must match a specified string,
+or the parse will fail with a distinguishable error.
+
++t_integer+: Parse a single signed integer literal, copy the value 
+to a C +int+ location.  Uses +strtol()+.
+
++t_uinteger+: Parse a single signed integer literal, copy the value 
+to a C +unsigned int+ location. Uses +strtoul()+.
+
++t_real+: Parse a single signed float literal, copy the value 
+to a C +double+ location. Uses +strtod()+.
+
++t_boolean+: Accept one of the JSON literals +true+ or +false+,
+copy the value to a C +bool+ location.
+
++t_string+: Accept a JSON string literal, copy the contents to a
+C char buffer.
+
++t_character+: Accept a single-character JSON string literal, copy
+that character to a C +char+ location.
+
++t_time+: Accept a string in the format of an ISO8601 UTC date with
+optional fractional decimal seconds, interpret as seconds since 
+the Unix epoch UTC, storte in a C double location..
+
+=== Compound Value Types ===
+
+The following four values do not parse JSON value atoms:
+
+==== Skip fields ====
+
+t_ignore: Value of this attribute is ignored.
+
+==== Parallel arrays ===
+
+t_array: Value of this attribute is expected to be a homogenous array.
+Another field of the structure specifies the array's element type,
+which can be any simple type or t_object (meaning a JSON subobject).
+
+If the array has simple elements, two three additional things must be
+specified: the base address of the array's storage, the maximum number
+of elements it can have, and an integer address where the parser will
+place a count of elements filled in.
+
+Simple array values always default to zero for numeric types, +false+
+for booleans, and NULL for strings.
+
+The array element type may be +t_object+, as in the +satellites+ field
+in this example:  
+
+------------------------------------------------------------------------
+bool usedflags[MAXCHANNELS];
+int PRN[MAXCHANNELS];
+int elevation[MAXCHANNELS];
+int azimuth[MAXCHANNELS];
+int visible;
+
+const struct json_attr_t sat_attrs[] = {
+    {"PRN",    t_integer, .addr.integer = PRN},
+    {"el",     t_integer, .addr.integer = elevation},
+    {"az",     t_integer, .addr.integer = azimuth},
+    {"used",   t_boolean, .addr.boolean = usedflags},
+    {NULL},
+};
+
+const struct json_attr_t json_attrs_sky[] = {
+    {"class",      t_check,   .dflt.check = "SKY"},
+    {"satellites", t_array,   .addr.array.element_type = t_object,
+                             .addr.array.arr.objects.subtype=sat_attrs,
+                             .addr.array.maxlen = MAXCHANNELS,
+                             .addr.array.count = &visible},
+    {NULL},
+    };
+------------------------------------------------------------------------
+
+An example of the shape of JSON this would unpack is:
+
+--------------------------------------------------------
+{"class":"SKY","satellites":[
+         {"PRN":10,"el":45,"az":196,"used":true},
+         {"PRN":29,"el":67,"az":310,"used":true},
+         {"PRN":28,"el":59,"az":108,"used":true},
+         {"PRN":26,"el":51,"az":304,"used":true},
+         {"PRN":8, "el":44,"az":58, "used":true},
+         {"PRN":27,"el":16,"az":66, "used":true},
+         {"PRN":21,"el":10,"az":301,"used":false}
+]}
+--------------------------------------------------------
+
+In this case, the parser needs to be told where to find a template
+array describing how to parse the elment objects. The target addresses
+in this structure will point to the base addressees of parallel arrays.
+The arrays are filled in until the parser runs out of conforming JSON
+sub-objects to parse or would exceed the +maxlen+ count of elements.
+
+==== Structure arrays ====
+
+t_structobject: this also parses 
+
+
+
+
 
 
 
@@ -144,4 +251,5 @@ If you initialize the offset fields with the correct offsetof calls,
 everything will work. Strings are supported but all string storage
 has to be inline in the struct.
 
-
+The default of array elements is always zero (false for booleans, NULL
+for strings).