NAME
libmj —
minimalist JSON lightweight
data interchange library
LIBRARY
Minimalist JSON library (libmj, -lmj)
SYNOPSIS
#include <mj.h>
int
mj_create(
mj_t *atom,
const char *text,
...);
int
mj_parse(
mj_t *atom,
const char *text,
int *tokfrom,
int *tokto,
int *toktype);
int
mj_append(
mj_t *atom,
const char *text,
...);
int
mj_append_field(
mj_t *atom,
const char *fieldname,
const char
*text,
...);
int
mj_deepcopy(
mj_t *dest,
mj_t *src);
void
mj_delete(
mj_t *atom);
Access to objects and array entries is made using the following functions:
int
mj_arraycount(
mj_t *atom);
int
mj_object_find(
mj_t *atom,
const char *name,
const unsigned
startpoint,
const unsigned incr);
mj_t *
mj_get_atom(
mj_t *atom,
...);
JSON object output functions:
int
mj_snprint(
char *buffer,
size_t size,
mj_t *atom);
int
mj_asprint(
char **buffer,
mj_t *atom);
int
mj_string_size(
mj_t *atom);
int
mj_pretty(
mj_t *atom,
void *stream,
unsigned depth,
const char *trailer);
const char *
mj_string_rep(
mj_t *atom);
DESCRIPTION
libmj is a small library interface to allow JSON text to be
created and parsed. JSON is the Java Script Object Notation, a lightweight
data-interchange format, standardised by the ECMA. The library name
libmj is derived from a further acronym of “minimalist
JSON”.
The
libmj library can be used to create a string in memory
which contains a textual representation of a number of objects, arbitrarily
structured. The library can also be used to reconstruct the structure. Data
can thus be serialised easily and efficiently, and data structures rebuilt to
produce the original structure of the data.
JSON contains basic units called atoms, the two basic atoms being strings and
numbers. Three other useful atomic values are provided: “null”,
“false”, and “true”. Atoms can be grouped together as
key/value pairs in an “object”, and as individual, ordered atoms,
in an “array”.
To create a new object, the
mj_create() function is used. It
can be deleted using the
mj_delete() function.
Atoms, objects and arrays can be appended to arrays and objects using the
mj_append() function.
Objects can be printed out by using the
mj_snprint() function.
The size of a string of JSON text can be calculated using the
mj_string_size() function. A utility function
mj_asprint() is provided which will allocate space
dynamically, using
calloc(3),
and the JSON serialised text is copied into it. This memory can later be
de-allocated using
free(3). For
formatted output to a
FILE * stream, the
mj_pretty() function is used. The calling interface gives
the ability to indent the output to a given
depth and
for the formatted output to be followed by a
trailer
string, which is usually
NULL
for external calls, but
can be any valid string. Output is sent to the
stream
file stream.
The
type argument given to the
mj_create(),
mj_append(), and
mj_append_field() functions is taken from a list of
“false” “true” “null” “number”
“integer” “string” “array” and
“object” types. An integer differs from a number in that it cannot
take on any floating point values. It is implemented internally using a signed
64-bit integer type. This restriction of values for an integer type may be
removed at a later date.
Within a JSON object, the key values can be iterated over using an integer index
to access the individual JSON objects. The index can also be found using the
mj_object_find() function.
The way objects arrays are implemented in
libmj is by using
varying-sized arrays internally. Objects have the field name as the even entry
in this internal array, with the value being the odd entry. Arrays are
implemented as a simple array. Thus, to find an object in an array using
mj_object_find(), a value of 1 should be used as the
increment value. This means that every entry in the internal array will be
examined, and the first match after the starting point will be returned. For
objects, an incremental value of 2 should be used, and an even start value
should be specified.
String values should be created and appended using two parameters in the stdarg
fields, that of the string itself, and its length in bytes immediately after
the string. A value of
-1
may be used if the string
length is not known.
EXAMPLES
The following code fragment will make a JSON object out of the string
“Hello <USERNAME>\n” in the buffer called
buf where “USER” is the name of the user
taken from the runtime environment. The encoded text will be in an allocated
buffer called
s.
mj_t atom;
char buf[BUFSIZ];
char *s;
int cc;
(void) memset(&atom, 0x0, sizeof(atom));
cc = snprintf(buf, sizeof(buf), "Hello %s\n", getenv("USER"));
mj_create(&atom, "string", buf, cc);
cc = mj_asprint(&s, &atom, MJ_JSON_ENCODE);
Next, the following example will take the (binary) text which has been encoded
into JSON and is in the buffer
buf, such as in the
previous example, and re-create the original text:
int from, to, tok, cc;
char *s;
mj_t atom;
(void) memset(&atom, 0x0, sizeof(atom));
from = to = tok = 0;
mj_parse(&atom, buf, &from, &to, &tok);
cc = mj_asprint(&s, &atom, MJ_HUMAN);
printf("%.*s", cc, s);
The
s pointer points to allocated storage with the
original NUL-terminated string in it.
SEE ALSO
calloc(3),
free(3)
ECMA-262: ECMAScript Language
Specification,
http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf,
Ecma International, December
2009, 5th Edition.
HISTORY
The
libmj library first appeared in
NetBSD
6.0.
AUTHORS
Alistair Crooks
<
agc@NetBSD.org> wrote
this implementation and manual page.