From 858701c5f1730e5e1af74c57d5a96e79457349eb Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Tue, 23 Sep 2014 12:11:35 -0400 Subject: [PATCH] Better documentation. --- microjson.asc | 35 ++++++++++++++++++++++------------- microjson.c | 2 +- 2 files changed, 23 insertions(+), 14 deletions(-) diff --git a/microjson.asc b/microjson.asc index 78d543f..d8551ba 100644 --- a/microjson.asc +++ b/microjson.asc @@ -115,6 +115,11 @@ value; the target address tells it where to put the value. Syntax errors, or any unknown attribute name, terminate the parse. +One consequence to be aware of is that if an input JSON object +contains multiple attribute-value pairs with the same attribute, +the associated storage will be modified each time and only +the last setting will be effective. + === Simple Value Types === The type field of a +json_attr_t+ structure can have the following @@ -141,17 +146,18 @@ 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 ++t_time+: Accept a string in the format of an RFC3339 UTC date with optional fractional decimal seconds, interpret as seconds since -the Unix epoch UTC, storte in a C double location.. +the Unix epoch UTC, store in a C double location.. === Compound Value Types === -The following four values do not parse JSON value atoms: +The following cases do not parse JSON value atoms: ==== Skip fields ==== -t_ignore: Value of this attribute is ignored. +t_ignore: Value of this attribute is ignored. Significant because +unexpected attribute names cause the parse to trminate with error ==== Parallel arrays === @@ -320,9 +326,9 @@ what is going on. STRUCTOBJECT is a thin wrapper around offsetof(); STRUCTARRAY sets up the parser to walk through the array of structures, filling each element as it goes. +== The Grubby Details == - - +You have to specify the shape of the JSON you expect to parse in advance. The "shape" of a JSON object in the type signature of its attributes (and attribute values, and so on recursively down through @@ -336,13 +342,14 @@ The preceding paragraph told one fib. A single attribute may actually have a span of multiple specifications with different syntactically distinguishable types (e.g. string vs. real vs. integer vs. boolean, but not signed integer vs. unsigned integer). The parser will match -the right spec against the actual data. +the right spec against the actual data. (There's an instance +of this in Example 3.) -The dialect this parses has some limitations. First, it cannot -recognize the JSON "null" value. Secondly, arrays may only have -objects or strings - not reals or integers or floats - as elements -(this limitation could be easily removed if required). Third, all -elements of an array must be of the same type. + The dialect this parses has some limitations. First, it cannot +recognize the JSON "null" value. Second, all elements of an array must +be of the same type. Third, some types (t_time, t_character) may not +ve array elements (this restriction could be lifted, and might be +in a future release). There are separate entry points for beginning a parse of either JSON object or a JSON array. JSON "float" quantities are actually stored as @@ -357,7 +364,7 @@ mapped into parallel C arrays (one per subfield). Strings are not supported in this kind of array, as they don't have a "natural" size to use as an offset multiplier. - Structobjects arrays are a way to parse a list of objects to a set + Structobject arrays are a way to parse a list of objects to a set of modifications to a corresponding array of C structs. The trick is that the array object initialization has to specify both the C struct array's base address and the stride length (the size of the C struct). @@ -367,3 +374,5 @@ has to be inline in the struct. The default of array elements is always zero (false for booleans, NULL for strings). + +// end diff --git a/microjson.c b/microjson.c index 9887044..921c815 100644 --- a/microjson.c +++ b/microjson.c @@ -29,7 +29,7 @@ will match the right spec against the actual data. The dialect this parses has some limitations. First, it cannot recognize the JSON "null" value. Second, all elements of an array must be of the same type. Third, some types (t_time, t_character) may not -ve array elements (this restriction ciuld be lifted) +ve array elements (this restriction could be lifted) There are separate entry points for beginning a parse of either JSON object or a JSON array. JSON "float" quantities are actually -- 2.43.0