xjson.h File Reference

Macros
#define	NULLDEV   "/dev/null"
	null device on system
#define	XJSON_DEFAULT_INDENT   2
	Number of characters to indent.

Functions
char *	xjsonEscape (const char *src, int maxLength)
char *	xjsonFieldToIndentedString (int indent, const XField *f)
char *	xjsonFieldToString (const XField *f)
int	xjsonGetIndent ()
XStructure *	xjsonParseAt (char **src, int *lineNumber)
XField *	xjsonParseFieldAt (char **src, int *lineNumber)
XStructure *	xjsonParseFile (FILE *file, 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 *	xjsonUnescape (const char *json)

Detailed Description

Date

Nov 29, 2020

Author

Attila Kovacs

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

Function Documentation

xjsonEscape()

char * xjsonEscape	(	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

xjsonUnescape()

References x_error().

xjsonFieldToIndentedString()

char * xjsonFieldToIndentedString	(	int	indent,
		const XField *	f
	)

Converts an XField into its JSON representation, with the specified indentation of white spaces in front of every line. Conversion errors are reported to stderr or the altenate stream set by xSetErrorStream().

Parameters

indent	Number of white spaces to insert in front of each line.
f	Pointer to field

Returns

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

See also

xjsonFieldToString()

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

xjsonFieldToString()

char * xjsonFieldToString

(

const XField *

f

)

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

Parameters

f	Pointer to field

Returns

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

See also

xjsonToString()

xjsonSetIndent()

xjsonParseAt()

xjsonParseFile()

xjsonParseFilename()

References xjsonFieldToIndentedString().

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()

References XJSON_DEFAULT_INDENT.

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

xjsonParseFieldAt()

xjsonToString()

xjsonParseFile()

xjsonParseFileName()

References x_error().

xjsonParseFieldAt()

XField * xjsonParseFieldAt	(	char **	pos,
		int *	lineNumber
	)

Parses a JSON field from the given parse position, returning the field's data in the xchange format 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

xjsonParseAt()

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()

References x_error().

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

xjsonFieldToString()

xjsonSetIndent()

xjsonParseAt()

xjsonParseFile()

xjsonParseFilename()

References xErrorDescription(), and xStringCopyOf().

xjsonUnescape()

char * xjsonUnescape

(

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

xjsonEscape()

References x_error().