Detailed Description

JSON Parser Callback Interface.

Collaboration diagram for JSON Parser Callback:

Classes
struct	JDecoderStackNode
	Used internally in JDecoder for nested data structures. More...

struct	JDecoderV
	Used internally in JDecoder, where one instance represents one node in the pointer value tree. More...

struct	JDecoder
	JDecoder implements the parser callback API JParserIntf and builds a pointer value tree when JDecoder::get is called. More...

struct	JParserIntf
	The JParserIntf interface class is the interface between the parser and an object that implements the JParserIntf interface. More...

struct	JParserValFact
	JParserValFact is the JVal JSON parser factory class. More...

Macros
#define	JD_MNUM(o, m) #m, &(o)->m
	JDecoder::get helper macro, used when setting a number pointer in an object. More...

#define	JD_MSTR(o, m) #m, &(o)->m, sizeof((o)->m)
	JDecoder::get helper macro, used when setting a string pointer in an object. More...

#define	JD_ASTR(o, m) &(o)->m, sizeof((o)->m)
	JDecoder::get helper macro, used when setting a string pointer in an array. More...

#define	JParserIntf_constructor(o, serviceMA) (o)->service=serviceMA
	Initialize the callback interface. More...

#define	JParserIntf_serviceCB(o, v, recLev) (o)->service(o,v,recLev)
	Invoke the callback synchronously. More...

#define	JParserValFact_getFirstVal(o) ((o)->vStack && (o)->vStack ? (o)->vStack : 0)

Typedefs
typedef JDecoder	JDecoder
	JDecoder implements the parser callback API JParserIntf and builds a pointer value tree when JDecoder::get is called. More...

typedef int(*	JParserIntf_Service) (struct JParserIntf o, struct JParserVal v, int recLevel)
	Receive one parsed value or container boundary synchronously. More...

typedef struct JParserIntf	JParserIntf
	The JParserIntf interface class is the interface between the parser and an object that implements the JParserIntf interface. More...

typedef JParserValFact	JParserValFact
	JParserValFact is the JVal JSON parser factory class. More...

Enumerations
enum	JDecoderS { JDecoderS_FormatErr = -100 , JDecoderS_NameNotFound , JDecoderS_Overflow , JDecoderS_StringOverflow , JDecoderS_Unbalanced , JDecoderS_Underflow , JDecoderS_Unknown , JDecoderS_BufNotAligned , JDecoderS_ChainedErr , JDecoderS_OK = 0 }
	JDecoder Status. More...

Functions
int	JDecoder_vget (JDecoder o, const char fmt, va_list *argList)
	Build the same schema as get(), consuming a variable argument list. More...

int	JDecoder_get (JDecoder o, const char fmt,...)
	Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance. More...

void	JDecoder_constructor (JDecoder o, U8 buf, int bufSize, int extraStackLen)
	Create/initialize a JDecoder instance. More...

BA_API void	JParserValFact_constructor (JParserValFact o, AllocatorIntf vAlloc, AllocatorIntf *dAlloc)
	Initialize a factory without allocating a tree. More...

BA_API JVal *	JParserValFact_manageFirstVal (JParserValFact *o)
	Detach the current root and reset the node counter when a root exists. More...

BA_API void	JParserValFact_termFirstVal (JParserValFact *o)
	Free the attached tree and factory stack, preparing for another document. More...

BA_API void	JParserValFact_destructor (JParserValFact *o)
	Free the attached root and all factory stack storage. More...

int	JDecoder::vget (const char fmt, va_list argList)
	Build the same schema as get(), consuming a variable argument list. More...

int	JDecoder::get (const char *fmt,...)
	Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance. More...

	JDecoder::JDecoder (U8 *buf, int bufSize, int extraStackLen=0)
	Create/initialize a JDecoder instance. More...

int	JParserIntf::serviceCB (JParserVal *v, int recLevel)
	Calling the JParserIntf service function is typically performed in a design using a chained parser callback interface. More...

	JParserValFact::JParserValFact (AllocatorIntf vAlloc, AllocatorIntf dAlloc)
	Initialize a factory without allocating a tree. More...

JVal *	JParserValFact::getFirstVal ()

JVal *	JParserValFact::manageFirstVal ()
	Detach the current root and reset the node counter when a root exists. More...

void	JParserValFact::termFirstVal ()
	Free the attached tree and factory stack, preparing for another document. More...

	JParserValFact::~JParserValFact ()
	Free the attached root and all factory stack storage. More...

Macro Definition Documentation

◆ JD_ASTR

#define JD_ASTR	(	o,
		m
	)	&(o)->m, sizeof((o)->m)

JDecoder::get helper macro, used when setting a string pointer in an array.

decoder.get("[s]", JD_ASTR(structval, membername));

◆ JD_MNUM

#define JD_MNUM	(	o,
		m
	)	#m, &(o)->m

JDecoder::get helper macro, used when setting a number pointer in an object.

decoder.get("{d}", JD_MNUM(structval, membername));

◆ JD_MSTR

#define JD_MSTR	(	o,
		m
	)	#m, &(o)->m, sizeof((o)->m)

JDecoder::get helper macro, used when setting a string pointer in an object.

decoder.get("{s}", JD_MSTR(structval, membername));

◆ JParserIntf_constructor

#define JParserIntf_constructor	(	o,
		serviceMA
	)	(o)->service=serviceMA

Initialize the callback interface.

Parameters

o	Required storage.
serviceMA	Required JParserIntf_Service callback.

◆ JParserIntf_serviceCB

#define JParserIntf_serviceCB	(	o,
		v,
		recLev
	)	(o)->service(o,v,recLev)

Invoke the callback synchronously.

Parameters

o	Required initialized interface.
v	Required borrowed event.
recLev	Nesting depth relative to this callback.

Returns: Callback result unchanged; zero continues, nonzero stops.

◆ JParserValFact_getFirstVal

#define JParserValFact_getFirstVal ( o ) ((o)->vStack && *(o)->vStack ? *(o)->vStack : 0)

Returns: Borrowed current root, or NULL when absent. After a parse failure the tree may be partial; only treat it as complete after successful parsing.

Parameters

o	Required initialized factory.

Typedef Documentation

◆ JDecoder

typedef JDecoder JDecoder

JDecoder implements the parser callback API JParserIntf and builds a pointer value tree when JDecoder::get is called.

The pointer value tree is used by the parser callback when the parser feeds the callback with parsed data.

See the JSON and UBJSON tutorial for more information on using JDecoder.

◆ JParserIntf

typedef struct JParserIntf JParserIntf

The JParserIntf interface class is the interface between the parser and an object that implements the JParserIntf interface.

◆ JParserIntf_Service

typedef int(* JParserIntf_Service) (struct JParserIntf *o, struct JParserVal *v, int recLevel)

Receive one parsed value or container boundary synchronously.

Parameters

o	Required application callback interface.
v	Borrowed event record. Its strings/member name and lengths are valid only during this call; copy anything needed later. Do not retain v or free the parser from its callback.
recLevel	Container depth: top-level begin/end events use zero, their immediate primitive children use one, and nested levels increase it.

Returns: Zero to continue, nonzero to stop parsing with JParsStat_IntfErr. The callback's numeric error is not returned unchanged by JParser::parse.

◆ JParserValFact

typedef JParserValFact JParserValFact

JParserValFact is the JVal JSON parser factory class.

An instance of this class is connected to an instance of the JParser. The JParser communicates with the JVal factory when parsing JSON, and the JVal factory creates JVal objects.

Method getFirstVal returns the first value in the syntax tree.

The class automatically manages the nodes allocated. The allocated nodes are automatically de-allocated when the destructor runs. You can manage the values by calling JParserValFact::manageFirstVal or by calling JVal::manageJ on any of the children.

See also: JValFact; JDecoder

Enumeration Type Documentation

◆ JDecoderS

enum JDecoderS

JDecoder Status.

Enumerator
JDecoderS_FormatErr	Parsed data does not match the value tree that was created when method JDecoder::get was called.
JDecoderS_NameNotFound	Parsed data includes a member whose name is not in value tree.
JDecoderS_Overflow	Unconsumed schema values remain when a container ends; also used for excessive schema nesting.
JDecoderS_StringOverflow	Parsed string longer than buffer provided.
JDecoderS_Unbalanced	Incorrect use of '{', '}', '[', or ']' in JDecoder::get.
JDecoderS_Underflow	Input supplies another value after all schema children were consumed.
JDecoderS_Unknown	Unknown error.
JDecoderS_BufNotAligned	Memory buffer(s) provided in JDecoder constructor must be word aligned.
JDecoderS_ChainedErr	A chained parser callback, provided via the 'X' format flag in JDecoder::get, reported an error.
JDecoderS_OK	OK, no errors.

Function Documentation

◆ get()

int JDecoder::get	(	const char *	fmt,
			...
	)

Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance.

Parameters

fmt

format flags:

JSON type	Format flag	C type
Number	d	S32*
Number	l	S64*
Number	f	double*
boolean	b	BaBool* or U8*
string	s	char* buffer, size_t capacity
Start object	{	n/a
End object	}	n/a
Start array	[	n/a
End array	]	n/a
N/A	X	JParserIntf*

See the JSON and UBJSON tutorial for more information on using this method.

See also: JD_MNUM; JD_MSTR; JD_ASTR; JEncoder::set The format must describe a complete top-level object or array. Object members take a borrowed NUL-terminated name before their destination arguments. For s, pass a writable char buffer and a size_t capacity. The current length check requires at least string-byte-length + 2 bytes, including spare space beyond the terminator. JSON null mapped to s stores an empty C string. Numeric values must match the expected kind, except S32 input can populate S64 or double destinations. X delegates a container to a borrowed JParserIntf. All destination pointers and member-name strings must remain valid throughout parsing. Values can be partially updated before a later decoding error. Call get() again before decoding another document; consuming a document modifies the pointer tree.

Returns: Zero after schema construction, -1 on setup failure. Inspect status for decoder details, but a too-small schema buffer can return -1 with status still JDecoderS_OK. A successful get() does not mean input has been parsed.

◆ getFirstVal()

JVal * JParserValFact::getFirstVal ( )

Returns: Borrowed current root, or NULL when absent. After a parse failure the tree may be partial; only treat it as complete after successful parsing.

◆ JDecoder()

JDecoder::JDecoder	(	U8 *	buf,
		int	bufSize,
		int	extraStackLen = `0`
	)

Create/initialize a JDecoder instance.

Parameters

buf	is a pointer to a buffer used internally for memory storage when building the pointer value tree. The minimum size must be greater than sizeof(JDecoderV) * N, where N is the number of format flags minus the end of array/object flags (] or }).
bufSize	Positive byte capacity of buf. Keep the schema byte offsets representable in U16 (less than 65536); allocation and growth are not performed. buf must be aligned to sizeof(J_ALIGNMT), normally pointer alignment, and remain writable throughout schema construction and parsing.
extraStackLen	is an undocumented value and must be set to 0.

◆ JDecoder_constructor()

void JDecoder_constructor	(	JDecoder *	o,
		U8 *	buf,
		int	bufSize,
		int	extraStackLen
	)

Create/initialize a JDecoder instance.

Parameters

buf	is a pointer to a buffer used internally for memory storage when building the pointer value tree. The minimum size must be greater than sizeof(JDecoderV) * N, where N is the number of format flags minus the end of array/object flags (] or }).
bufSize	Positive byte capacity of buf. Keep the schema byte offsets representable in U16 (less than 65536); allocation and growth are not performed. buf must be aligned to sizeof(J_ALIGNMT), normally pointer alignment, and remain writable throughout schema construction and parsing.
extraStackLen	is an undocumented value and must be set to 0.
o	Required storage to initialize.

◆ JDecoder_get()

int JDecoder_get	(	JDecoder *	o,
		const char *	fmt,
			...
	)

Build a pointer value tree that is used by the integrated parser callback function when the parser feeds elements to the JDecoder instance.

Parameters

fmt

format flags:

JSON type	Format flag	C type
Number	d	S32*
Number	l	S64*
Number	f	double*
boolean	b	BaBool* or U8*
string	s	char* buffer, size_t capacity
Start object	{	n/a
End object	}	n/a
Start array	[	n/a
End array	]	n/a
N/A	X	JParserIntf*

See the JSON and UBJSON tutorial for more information on using this method.

See also: JD_MNUM; JD_MSTR; JD_ASTR; JEncoder::set The format must describe a complete top-level object or array. Object members take a borrowed NUL-terminated name before their destination arguments. For s, pass a writable char buffer and a size_t capacity. The current length check requires at least string-byte-length + 2 bytes, including spare space beyond the terminator. JSON null mapped to s stores an empty C string. Numeric values must match the expected kind, except S32 input can populate S64 or double destinations. X delegates a container to a borrowed JParserIntf. All destination pointers and member-name strings must remain valid throughout parsing. Values can be partially updated before a later decoding error. Call get() again before decoding another document; consuming a document modifies the pointer tree.

Returns: Zero after schema construction, -1 on setup failure. Inspect status for decoder details, but a too-small schema buffer can return -1 with status still JDecoderS_OK. A successful get() does not mean input has been parsed.

Parameters

o	Required initialized decoder.

◆ JDecoder_vget()

int JDecoder_vget	(	JDecoder *	o,
		const char *	fmt,
		va_list *	argList
	)

Build the same schema as get(), consuming a variable argument list.

Parameters

fmt	Required format string, as for get().
argList	Required pointer to an initialized va_list, consumed by this call. Match the exact argument types documented by get().

Returns: Zero on success, -1 on schema setup failure.

Parameters

o	Required initialized decoder.

◆ JParserValFact()

JParserValFact::JParserValFact	(	AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Initialize a factory without allocating a tree.

Parameters

vAlloc	Required borrowed allocator for nodes.
dAlloc	Required borrowed allocator for strings and factory stack. Allocators may be the same and must outlive all storage they allocate. NULL does not select a default. The factory owns its attached root.

◆ JParserValFact_constructor()

BA_API void JParserValFact_constructor	(	JParserValFact *	o,
		AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Initialize a factory without allocating a tree.

Parameters

vAlloc	Required borrowed allocator for nodes.
dAlloc	Required borrowed allocator for strings and factory stack. Allocators may be the same and must outlive all storage they allocate. NULL does not select a default. The factory owns its attached root.
o	Required storage to initialize.

◆ JParserValFact_destructor()

BA_API void JParserValFact_destructor ( JParserValFact * o )

Free the attached root and all factory stack storage.

Detached nodes remain caller-owned. Borrowed allocators are not destroyed.

Parameters

o	Required initialized factory.

◆ JParserValFact_manageFirstVal()

BA_API JVal * JParserValFact_manageFirstVal ( JParserValFact * o )

Detach the current root and reset the node counter when a root exists.

Returns: Caller-owned root, or NULL if absent. Release with JVal::terminate using the original allocators. The factory retains stack storage and status.

Parameters

o	Required initialized factory.

◆ JParserValFact_termFirstVal()

BA_API void JParserValFact_termFirstVal ( JParserValFact * o )

Free the attached tree and factory stack, preparing for another document.

Detached trees are unaffected. The stored status is not cleared; after a failure, reinitialize the cleaned factory before reuse.

Parameters

o	Required initialized factory.

◆ manageFirstVal()

JVal * JParserValFact::manageFirstVal ( )

Detach the current root and reset the node counter when a root exists.

Returns: Caller-owned root, or NULL if absent. Release with JVal::terminate using the original allocators. The factory retains stack storage and status.

◆ serviceCB()

int JParserIntf::serviceCB	(	JParserVal *	v,
		int	recLevel
	)

Calling the JParserIntf service function is typically performed in a design using a chained parser callback interface.

Parameters

v	the parsed value provided by JParser
recLevel	Nonnegative nesting level adjusted for the chained callback.

Returns: The callback result unchanged; zero continues, nonzero reports failure.

◆ termFirstVal()

void JParserValFact::termFirstVal ( )

Free the attached tree and factory stack, preparing for another document.

Detached trees are unaffected. The stored status is not cleared; after a failure, reinitialize the cleaned factory before reuse.

◆ vget()

int JDecoder::vget	(	const char *	fmt,
		va_list *	argList
	)

Build the same schema as get(), consuming a variable argument list.

Parameters

fmt	Required format string, as for get().
argList	Required pointer to an initialized va_list, consumed by this call. Match the exact argument types documented by get().

Returns: Zero on success, -1 on schema setup failure.

◆ ~JParserValFact()

JParserValFact::~JParserValFact ( )

Free the attached root and all factory stack storage.

Detached nodes remain caller-owned. Borrowed allocators are not destroyed.

Detailed Description

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ JD_ASTR

◆ JD_MNUM

◆ JD_MSTR

◆ JParserIntf_constructor

◆ JParserIntf_serviceCB

◆ JParserValFact_getFirstVal

Typedef Documentation

◆ JDecoder

◆ JParserIntf

◆ JParserIntf_Service

◆ JParserValFact

Enumeration Type Documentation

◆ JDecoderS

Function Documentation

◆ get()

◆ getFirstVal()

◆ JDecoder()

◆ JDecoder_constructor()

◆ JDecoder_get()

◆ JDecoder_vget()

◆ JParserValFact()

◆ JParserValFact_constructor()

◆ JParserValFact_destructor()

◆ JParserValFact_manageFirstVal()

◆ JParserValFact_termFirstVal()

◆ manageFirstVal()

◆ serviceCB()

◆ termFirstVal()

◆ vget()

◆ ~JParserValFact()