LIBMJ(3) BSD Library Functions Manual LIBMJ(3)NAMElibmj — minimalist JSON lightweight data interchange library
LIBRARY
library “libmj”
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 func‐
tions:
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);
DESCRIPTIONlibmj 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 in the ECMA standard. 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 pro‐
duce 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() 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 allo‐
cate 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 dif‐
fers 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 inte‐
ger 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 imple‐
mented 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 immedi‐
ately after the string. A value of -1 may be used if the string length
is not known.
EXAMPLES
The follow code fragment will make a JSON object out of the string “Hello
<USERNAME>\n” in the buffer called “buf” where “USERNAME” 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);
and 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-termi‐
nated string in it.
SEE ALSOcalloc(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.
BSD June 22, 2011 BSD
