GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  LIBMJ (3)

NAME

libmj - minimalist JSON lightweight data interchange library

CONTENTS

Library
Synopsis
Description
Examples
See Also
History
Authors

LIBRARY


.Lb libmj

SYNOPSIS


.In mj.h int
.Fo mj_create mj_t *atom const char *text ...
.Fc int
.Fo mj_parse mj_t *atom const char *text int *tokfrom int *tokto int *toktype
.Fc int
.Fo mj_append mj_t *atom const char *text ...
.Fc int
.Fo mj_append_field mj_t *atom const char *fieldname const char *text ...
.Fc int
.Fo mj_deepcopy mj_t *dest mj_t *src
.Fc void
.Fo mj_delete mj_t *atom
.Fc

Access to objects and array entries is made using the following functions: int
.Fo mj_arraycount mj_t *atom
.Fc int
.Fo mj_object_find mj_t *atom const char *name const unsigned startpoint const unsigned incr
.Fc mj_t *
.Fo mj_get_atom mj_t *atom ...
.Fc

JSON object output functions: int
.Fo mj_snprint char *buffer size_t size mj_t *atom
.Fc int
.Fo mj_asprint char **buffer mj_t *atom
.Fc int
.Fo mj_string_size mj_t *atom
.Fc int
.Fo mj_pretty mj_t *atom void *stream unsigned depth const char *trailer
.Fc const char *
.Fo mj_string_rep mj_t *atom
.Fc

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
.Vt 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 "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(Am]atom, 0x0, sizeof(atom)); cc = snprintf(buf, sizeof(buf), "Hello %s\n", getenv("USER")); mj_create(Am]atom, "string", buf, cc); cc = mj_asprint(Am]s, Am]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(Am]atom, 0x0, sizeof(atom)); from = to = tok = 0; mj_parse(Am]atom, buf, Am]from, Am]to, Am]tok); cc = mj_asprint(Am]s, Am]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)
.Rs ECMA-262: ECMAScript Language Specification
.Re

HISTORY

The libmj library first appeared in
.Nx 6.0 .

AUTHORS


.An Alistair Crooks Aq Mt agc@NetBSD.org wrote this implementation and manual page.
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.