From: Eric S. Raymond <esr@thyrsus.com>
Date: Tue, 23 Sep 2014 21:22:52 +0000 (-0400)
Subject: Document how defaulting works.
X-Git-Tag: 1.0~11
X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=45d7d60355c605ba56c05b1d31590e4b690115c1;p=microjson.git

Document how defaulting works.
---

diff --git a/microjson.asc b/microjson.asc
index 7f54bfa..76bd835 100644
--- a/microjson.asc
+++ b/microjson.asc
@@ -150,6 +150,13 @@ that character to a C +char+ location.
 optional fractional decimal seconds, interpret as seconds since 
 the Unix epoch UTC, store in a C double location..
 
+Associated with each simple value type's storage (in the +addr+
+union) is a correspondingly-named field in the +dflt+ union).
+This is a default value which is copied to the target storage
+when the JSON object does not contain the corresponding attribute.
+You can turn off this defaulting behavior by setting the +nodefault+
+member to +true+.
+
 === Compound Value Types ===
 
 The following cases do not parse JSON value atoms:
@@ -240,6 +247,14 @@ 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.
 
+More formally: parallel object arrays take one base address per object
+subfield, and are mapped into parallel C arrays (one per subfield).
+Strings are not supported in this kind of array, as they don't have a
+"natural" fixed size to use as an offset multiplier.
+
+The default of array elements is always zero (false for booleans, NULL
+for strings).
+
 ==== Structure arrays ====
 
 There's a different way to parse arrays that can unpack an
@@ -326,7 +341,15 @@ 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 ==
+More formally: 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).  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.
+
+== Some Grubby Details ==
 
 You have to specify the shape of the JSON you expect to parse in advance.
 
@@ -356,26 +379,6 @@ object or a JSON array.
 
 JSON "float" quantities are actually stored as doubles.
 
-This parser processes object arrays in one of two different ways,
-defending on whether the array subtype is declared as object or
-structobject.
-
-Object arrays take one base address per object subfield, and are
-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.
-
-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).
-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).
-
 == Advanced Usage ==
 
 This code is designed to be stripped down still further; do not be