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 *	xjsonEscape (const char *src, int maxLength)
char *	xjsonFieldToIndentedString (int indent, const XField *f)
char *	xjsonFieldToString (const XField *f)
int	xjsonGetIndent ()
XField *	xjsonParseField (const char *str, char **tail)
XStructure *	xjsonParseFile (FILE *fp, size_t length)
XStructure *	xjsonParsePath (const char *path)
XStructure *	xjsonParseString (const char *str, char **tail)
void	xjsonSetErrorStream (FILE *fp)
void	xjsonSetIndent (int nchars)
char *	xjsonToString (const XStructure *s)
char *	xjsonUnescape (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

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

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

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

xjsonParsePath()

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

xjsonParseField()

XField * xjsonParseField	(	const char *	str,
		char **	tail
	)

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

Parameters

	str	String pointer from which to parse.
[out]	tail	Pointer in which to return parse position after.

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
	)

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

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

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

xjsonParsePath()

xjsonParseAt()

xjsonToString()

References x_error().

xjsonParsePath()

XStructure * xjsonParsePath

(

const char *

path

)

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

Parameters

[in]

path

File name/path to parse.

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

xjsonParseString()

XStructure * xjsonParseString	(	const char *	str,
		char **	tail
	)

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

Parameters

	str	Pointer to string from which to parse JSON
[out]	tail	Pointer to return parse position, or NULL if not required.

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

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

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

xjsonParsePath()

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