xjson.c File Reference

A set of functions for parsing and creating JSON description of data. More...

Macros
#define	__XCHANGE_INTERNAL_API__
	Use internal definitions.
#define	FALSE   0
	Boolean 'false' in case it isn't already defined.
#define	TRUE   1
	Boolean 'true' in case it isn't already defined.

Functions
char *	xjsonEscapeString (const char *src, int maxLength)
int	xjsonGetIndent ()
XStructure *	xjsonParseAt (char **pos, int *lineNumber)
XStructure *	xjsonParseFile (FILE *fp, size_t length, int *lineNumber)
XStructure *	xjsonParseFilename (const char *fileName, int *lineNumber)
void	xjsonSetErrorStream (FILE *fp)
void	xjsonSetIndent (int nchars)
char *	xjsonToString (const XStructure *s)
char *	xjsonUnescapeString (const char *str)

Detailed Description

A set of functions for parsing and creating JSON description of data.

Date

Oct 25, 2020

Author

Attila Kovacs

Function Documentation

xjsonEscapeString()

char * xjsonEscapeString	(	const char *	src,
		int	maxLength
	)

Converts a native string to its JSON representation.

Parameters

src	Pointer to the native (unescaped) string, which may contain special characters.
maxLength	The number of characters in the input string if not terminated, or <=0 if always teminated arbitrary length string.

Returns

The JSON representation of the original string, in which special characters appear in escaped form (without the surrounding double quotes).

See also

xjsonUnescapeString()

References x_error(), X_SUCCESS, and x_trace_null().

xjsonGetIndent()

int xjsonGetIndent

(

)

Returns the number of spaces per indentation when emitting JSON formatted output.

Returns

(bytes) the number of white space character of indentation used.

See also

xjsonSetIndent()

xjsonToString()

xjsonParseAt()

XStructure * xjsonParseAt	(	char **	pos,
		int *	lineNumber
	)

Parses a JSON object from the given parse position, returning the structured data and updating the parse position. Parse errors are reported to stderr or the alternate stream set by xSetErrorStream().

Parameters

[in,out]	pos	Pointer to current parse position, which will be updated to point to after the last character consumed by the JSON parser.
[out]	lineNumber	Optional pointer that holds a line number of the parse position, or NULL if not required. Line numbers may be useful to report where the parser run into an error if the parsing failed. Line numbers start at 1, and are counted from the initial parse position.

Returns

Structured data created from the JSON description, or NULL if there was an error parsing the data (errno is set to EINVAL). The lineNumber argument can be used to determine where the error occurred.

See also

xjsonToString()

xjsonParseFile()

xjsonParseFileName()

References x_error().

xjsonParseFile()

XStructure * xjsonParseFile	(	FILE *	fp,
		size_t	length,
		int *	lineNumber
	)

Parses a JSON object from the current position in a file, returning the described structured data. Parse errors are reported to stderr or the alternate stream set by xSetErrorStream().

Parameters

[in]	fp	File pointer, opened with read permission ("r").
[in]	length	[bytes] The number of bytes to parse / available, or 0 to read to the end of the file. (In the latter case the file must support fseek with SEEK_END to automatically determine the length, or else this function will return NULL).
[out]	lineNumber	Optional pointer that holds a line number of the parse position, or NULL if not required. Line numbers may be useful to report where the parser run into an error if the parsing failed. Line numbers start at 1, and are counted from the initial parse position.

Returns

Structured data created from the JSON description, or NULL if there was an error parsing the data (errno is set to EINVAL). The lineNumber argument can be used to determine where the error occurred).

See also

xjsonParseFilename()

xjsonParseAt()

xjsonToString()

References x_error().

xjsonParseFilename()

XStructure * xjsonParseFilename	(	const char *	fileName,
		int *	lineNumber
	)

Parses a JSON object from the beginning of a file, returning the described structured data. Parse errors are reported to stderr or the alternate stream set by xSetErrorStream().

Parameters

[in]	fileName	File name/path to parse.
[out]	lineNumber	Optional pointer that holds a line number of the parse position, or NULL if not required. Line numbers may be useful to report where the parser run into an error if the parsing failed. Line numbers start at 1, and are counted from the initial parse position.

Returns

Structured data created from the JSON description, or NULL if there was an error parsing the data (errno is set to EINVAL). The lineNumber argument can be used to determine where the error occurred).

See also

xjsonParseFile()

xjsonParseAt()

xjsonToString()

References x_error(), xIsVerbose(), and xjsonParseFile().

xjsonSetErrorStream()

void xjsonSetErrorStream

(

FILE *

fp

)

Change the file to which XJSON reports errors. By default it will use stderr.

Parameters

fp	File to which to write errors or NULL to suppress errors.

References FALSE, NULLDEV, and TRUE.

xjsonSetIndent()

void xjsonSetIndent

(

int

nchars

)

Sets the number of spaces per indentation when emitting JSON formatted output.

Parameters

nchars

(bytes) the new number of white space character of indentation to use. Negative values map to 0.

See also

xjsonGetIndent()

xjsonToString()

xjsonToString()

char * xjsonToString

(

const XStructure *

s

)

Converts structured data into its JSON representation. Conversion errors are reported to stderr or the altenate stream set by xSetErrorStream().

Parameters

s	Pointer to structured data

Returns

String JSON representation, or NULL if there was an error (errno set to EINVAL).

See also

xjsonSetIndent()

xjsonParseAt()

xjsonParseFile()

xjsonParseFilename()

References FALSE, x_error(), X_NULL, and xErrorDescription().

xjsonUnescapeString()

char * xjsonUnescapeString

(

const char *

str

)

Converts a an escaped string in JSON representation to a native string

Parameters

str	The JSON representation of the string, in which special characters appear in escaped form (without the surrounding double quotes).

Returns

The native string, which may contain special characters.

See also

xjsonEscapeString()

References x_error().