On 02/26/2014 05:45 PM, Andres Freund wrote:
> On 2014-02-26 16:23:12 -0500, Andrew Dunstan wrote:
>> On 02/10/2014 09:11 PM, Andres Freund wrote:
>>> Is it just me or is jsonapi.h not very well documented?
>>
>> What about it do you think is missing? In any case, it's hardly relevant to
>> this patch, so I'll take that as obiter dicta.
> It's relevant insofer because I tried to understand it, to understand
> whether this patch's usage is sensible.
>
> O n a quick reread of the header, what I am missing is:
> * what's semstate in JsonSemAction? Private data?
> * what's object_start and object_field_start? Presumably object vs
> keypair? Why not use element as ifor the array?
> * scalar_action is called for which types of tokens?
> * what's exactly the meaning of the isnull parameter for ofield_action
> and aelem_action?
> * How is one supposed to actually access data in the callbacks, not
> obvious for all the callbacks.
> * are scalar callbacks triggered for object keys, object/array values?
> ...
You realize that this API dates from 9.3 and has been used in numerous
extensions, right? So the names are pretty well fixed, for good or ill.
semstate is private data. This is at least implied:
* parse_json will parse the string in the lex calling the * action functions in sem at the appropriate points.
Itis * up to them to keep what state they need in semstate. If they * need access to the state of the lexer,
thenits pointer * should be passed to them as a member of whatever semstate * points to.
object_start is called, as its name suggests, at the start of on object.
object_field_start is called at the start of a key/value pair.
isnull is true iff the value in question is a json null.
scalar action as not called for object keys, but is called for scalar
object values or array elements, in fact for any value that's not an
object or array (i.e. for a (non-key) string, number, true, false, null).
You access json fragments by pulling them from the lexical object.
jsonfuncs.c is chock full of examples.
cheers
andrew
