0a6a1f1d05
This brings our tree to NetBSD 7.0, as found on -current on the 10-10-2015. This updates: - LLVM to 3.6.1 - GCC to GCC 5.1 - Replace minix/commands/zdump with usr.bin/zdump - external/bsd/libelf has moved to /external/bsd/elftoolchain/ - Import ctwm - Drop sprintf from libminc Change-Id: I149836ac18e9326be9353958bab9b266efb056f0
284 lines
7.3 KiB
Groff
284 lines
7.3 KiB
Groff
.\" $NetBSD: libmj.3,v 1.7 2014/02/17 07:23:18 agc Exp $
|
|
.\"
|
|
.\" Copyright (c) 2010 Alistair Crooks <agc@NetBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd February 16, 2014
|
|
.Dt LIBMJ 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libmj
|
|
.Nd minimalist JSON lightweight data interchange library
|
|
.Sh LIBRARY
|
|
.Lb libmj
|
|
.Sh SYNOPSIS
|
|
.In mj.h
|
|
.Ft int
|
|
.Fo mj_create
|
|
.Fa "mj_t *atom" "const char *text" "..."
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_parse
|
|
.Fa "mj_t *atom" "const char *text" "int *tokfrom" "int *tokto" "int *toktype"
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_append
|
|
.Fa "mj_t *atom" "const char *text" "..."
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_append_field
|
|
.Fa "mj_t *atom" "const char *fieldname" "const char *text" "..."
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_deepcopy
|
|
.Fa "mj_t *dest" "mj_t *src"
|
|
.Fc
|
|
.Ft void
|
|
.Fo mj_delete
|
|
.Fa "mj_t *atom"
|
|
.Fc
|
|
.Pp
|
|
Access to objects and array entries is made using the following functions:
|
|
.Ft int
|
|
.Fo mj_arraycount
|
|
.Fa "mj_t *atom"
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_object_find
|
|
.Fa "mj_t *atom" "const char *name" "const unsigned startpoint"
|
|
.Fa "const unsigned incr"
|
|
.Fc
|
|
.Ft mj_t *
|
|
.Fo mj_get_atom
|
|
.Fa "mj_t *atom" "..."
|
|
.Fc
|
|
.Pp
|
|
JSON object output functions:
|
|
.Ft int
|
|
.Fo mj_snprint
|
|
.Fa "char *buffer" "size_t size" "mj_t *atom"
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_asprint
|
|
.Fa "char **buffer" "mj_t *atom"
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_string_size
|
|
.Fa "mj_t *atom"
|
|
.Fc
|
|
.Ft int
|
|
.Fo mj_pretty
|
|
.Fa "mj_t *atom" "void *stream" "unsigned depth" "const char *trailer"
|
|
.Fc
|
|
.Ft const char *
|
|
.Fo mj_string_rep
|
|
.Fa "mj_t *atom"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
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
|
|
.Nm
|
|
is derived from a further acronym of
|
|
.Dq minimalist JSON .
|
|
.\" Hey, Mary!
|
|
.Pp
|
|
The
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
JSON contains basic units called atoms, the two
|
|
basic atoms being strings and numbers.
|
|
Three other useful atomic values are provided:
|
|
.Dq null ,
|
|
.Dq false ,
|
|
and
|
|
.Dq true .
|
|
Atoms can be grouped together as key/value pairs in an
|
|
.Dq object ,
|
|
and as individual, ordered atoms, in an
|
|
.Dq array .
|
|
.Pp
|
|
To create a new object, the
|
|
.Fn mj_create
|
|
function is used.
|
|
It can be deleted using the
|
|
.Fn mj_delete
|
|
function.
|
|
.Pp
|
|
Atoms, objects and arrays can be appended
|
|
to arrays and objects using the
|
|
.Fn mj_append
|
|
function.
|
|
.Pp
|
|
Objects can be printed out
|
|
by using the
|
|
.Fn mj_snprint
|
|
function.
|
|
The size of a string of JSON text can be calculated
|
|
using the
|
|
.Fn mj_string_size
|
|
function.
|
|
A utility function
|
|
.Fn mj_asprint
|
|
is provided which will allocate space dynamically,
|
|
using
|
|
.Xr calloc 3 ,
|
|
and the JSON serialised text is copied into it.
|
|
This memory can later be de-allocated using
|
|
.Xr free 3 .
|
|
For formatted output to a
|
|
.Vt FILE *
|
|
stream, the
|
|
.Fn mj_pretty
|
|
function is used.
|
|
The calling interface gives the ability to indent the
|
|
output to a given
|
|
.Fa depth
|
|
and for the formatted output to be followed by a
|
|
.Fa trailer
|
|
string, which is usually
|
|
.Dv NULL
|
|
for external calls, but can be any valid string.
|
|
Output is sent to the
|
|
.Fa stream
|
|
file stream.
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
argument given to the
|
|
.Fn mj_create ,
|
|
.Fn mj_append ,
|
|
and
|
|
.Fn mj_append_field
|
|
functions is taken from a list of
|
|
.Dq false
|
|
.Dq true
|
|
.Dq null
|
|
.Dq number
|
|
.Dq integer
|
|
.Dq string
|
|
.Dq array
|
|
and
|
|
.Dq 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.
|
|
.Pp
|
|
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
|
|
.Fn mj_object_find
|
|
function.
|
|
.Pp
|
|
The way objects arrays are implemented in
|
|
.Nm
|
|
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
|
|
.Fn 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.
|
|
.Pp
|
|
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
|
|
.Dv \-1
|
|
may be used if the string length is not known.
|
|
.Sh EXAMPLES
|
|
The following code fragment will make a JSON object
|
|
out of the string
|
|
.Dq Hello <USERNAME>\en
|
|
in the
|
|
buffer called
|
|
.Va buf
|
|
where
|
|
.Dq USERNAME
|
|
is the name of the user taken from the runtime environment.
|
|
The encoded text will be in an allocated buffer called
|
|
.Va s
|
|
.Bd -literal -offset indent
|
|
mj_t atom;
|
|
char buf[BUFSIZ];
|
|
char *s;
|
|
int cc;
|
|
|
|
(void) memset(\*[Am]atom, 0x0, sizeof(atom));
|
|
cc = snprintf(buf, sizeof(buf), "Hello %s\en", getenv("USER"));
|
|
mj_create(\*[Am]atom, "string", buf, cc);
|
|
cc = mj_asprint(\*[Am]s, \*[Am]atom, MJ_JSON_ENCODE);
|
|
.Ed
|
|
.Pp
|
|
Next, the following example will take the (binary) text which has been encoded into
|
|
JSON and is in the buffer
|
|
.Va buf ,
|
|
such as in the previous example, and re-create the original text:
|
|
.Bd -literal -offset indent
|
|
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);
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va s
|
|
pointer points to allocated storage with the original NUL-terminated string
|
|
in it.
|
|
.Sh SEE ALSO
|
|
.Xr calloc 3 ,
|
|
.Xr free 3
|
|
.Rs
|
|
.%Q Ecma International
|
|
.%D December 2009
|
|
.%T ECMA-262: ECMAScript Language Specification
|
|
.%U http://www.ecma-international.org/publications/files/ecma-st/ECMA-262.pdf
|
|
.%O 5th Edition
|
|
.Re
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
library first appeared in
|
|
.Nx 6.0 .
|
|
.Sh AUTHORS
|
|
.An Alistair Crooks Aq Mt agc@NetBSD.org
|
|
wrote this implementation and manual page.
|