From 15e67ee2ff411f8b80520115426ac0d18dc850a3 Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Wed, 17 Sep 2014 22:34:18 -0400 Subject: [PATCH] Checkpoint: description of parallel arrays is in olace. --- microjson.asc | 112 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/microjson.asc b/microjson.asc index 1ba5d9e..c97053a 100644 --- 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). -- 2.43.0