Unix/Linux Go Back    


NetBSD 6.1.5 - man page for libmj (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LIBMJ(3)			   BSD Library Functions Manual 			 LIBMJ(3)

NAME
     libmj -- 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 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 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 repre-
     sentation 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() 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() func-
     tion.

     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 fol-
     lowed 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 float-
     ing 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() func-
     tion.

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

BSD					  June 22, 2011 				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:35 AM.