From c2ffc11f82eb9bc52db3045c1edd37d579b5a434 Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Tue, 23 Sep 2014 13:35:43 -0400 Subject: [PATCH] More documentation. --- README | 4 ++-- control | 4 ++-- microjson.asc | 19 ++++++++++++++++--- 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/README b/README index 815d459..611d093 100644 --- a/README +++ b/README @@ -1,7 +1,7 @@ microjson README -microjson parses a large subset of JSON directly into static C -structures without using malloc(3). +microjson parses the largest possible subset of JSON that can be +unpacked directly into static C structures, without using malloc(3). microjson is very small and very low-footprint, intended for use in constrained embedded environments. It may also be of interest for diff --git a/control b/control index 5a32f9e..b5c8ef8 100644 --- a/control +++ b/control @@ -4,8 +4,8 @@ Package: microjson Description: Tiny JSON parser in C that uses only fixed-extent storage. - This code parses a large subset of JSON directly into static C - structures without using malloc(3). It is very small and very low-footprint, + This code parses the largest subset of JSON that can be unpacked into static C + structures, without using malloc(3). It is very small and very low-footprint, intended for use in constrained embedded environments. It may also be of interest for code where malloc is verboten to reduce reliability and sexurity vulnerabilities. diff --git a/microjson.asc b/microjson.asc index 61de65e..0e302d3 100644 --- a/microjson.asc +++ b/microjson.asc @@ -3,8 +3,8 @@ Eric S. Raymond == Overview == -microjson is a tiny parser for a large subset of JSON (JavaScript Object -Notation) with the distinguishing feature that it uses entirely +microjson is a tiny parser for the largest subset of JSON (JavaScript Object +Notation) that can be unpacked to C static storage. It uses entirely fixed-extent memory, no malloc(). It is thus very suitable for use in memory-constrained environments such as embedded systems; also for long-running service daemons that must provably not leak memory. @@ -348,7 +348,7 @@ of this in Example 3.) 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 +be 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 @@ -375,4 +375,17 @@ 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 +afraid to copy mjson.c and drop out the parts you don't need (but +please leave in my name somewhere as original author). The GPSD +instance conditions out the support for arrays of ints/reals/bools. +For many applications time_t or real_t support could be removed +entirely. + +It is a good idea, when possible, to generate your parse-template +structures programmatically from a higher-level description of the +JSON. GPSD uses this technique extensively. + // end -- 2.43.0