element:
96M
**** The Key Modifier ({k:})
The key modifier is used to indicate that a particular field helps
uniquely identify an instance of list data.
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
xo_open_instance("user");
xo_emit("User {k:name} has {:count} tickets\n",
user[i].u_name, user[i].u_tickets);
xo_close_instance("user");
}
xo_close_list("user");
Currently the key modifier is only used when generating XPath value
for the HTML output style when XOF_XPATH is set, but other uses are
likely in the near future.
**** The Leaf-List Modifier ({l:})
The leaf-list modifier is used to distinguish lists where each
instance consists of only a single value. In XML, these are
rendered as single elements, where JSON renders them as arrays.
EXAMPLE:
for (i = 0; i < num_users; i++) {
xo_emit("Member {l:user}\n", user[i].u_name);
}
XML:
phil
pallavi
JSON:
"user": [ "phil", "pallavi" ]
The name of the field must match the name of the leaf list.
**** The No-Quotes Modifier ({n:})
The no-quotes modifier (and its twin, the 'quotes' modifier) affect
the quoting of values in the JSON output style. JSON uses quotes for
string value, but no quotes for numeric, boolean, and null data.
xo_emit applies a simple heuristic to determine whether quotes are
needed, but often this needs to be controlled by the caller.
EXAMPLE:
const char *bool = is_true ? "true" : "false";
xo_emit("{n:fancy/%s}", bool);
JSON:
"fancy": true
**** The Plural Modifier ({p:}) @plural-modifier@
The plural modifier selects the appropriate plural form of an
expression based on the most recent number emitted and the current
language settings. The contents of the field should be the singular
and plural English values, separated by a comma:
xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
The plural modifier is meant to work with the gettext modifier ({g:})
but can work independently. See ^gettext-modifier^.
When used without the gettext modifier or when the message does not
appear in the message catalog, the first token is chosen when the last
numeric value is equal to 1; otherwise the second value is used,
mimicking the simple pluralization rules of English.
When used with the gettext modifier, the ngettext(3) function is
called to handle the heavy lifting, using the message catalog to
convert the singular and plural forms into the native language.
**** The Quotes Modifier ({q:})
The quotes modifier (and its twin, the 'no-quotes' modifier) affect
the quoting of values in the JSON output style. JSON uses quotes for
string value, but no quotes for numeric, boolean, and null data.
xo_emit applies a simple heuristic to determine whether quotes are
needed, but often this needs to be controlled by the caller.
EXAMPLE:
xo_emit("{q:time/%d}", 2014);
JSON:
"year": "2014"
The heuristic is based on the format; if the format uses any of the
following conversion specifiers, then no quotes are used:
d i o u x X D O U e E f F g G a A c C p
**** The Trim Modifier ({t:})
The trim modifier removes any leading or trailing whitespace from
the value.
EXAMPLE:
xo_emit("{t:description}", " some input ");
JSON:
"description": "some input"
**** The White Space Modifier ({w:})
The white space modifier appends a single space to the data value:
EXAMPLE:
xo_emit("{Lw:Name}{:name}\n", "phil");
TEXT:
Name phil
The white space modifier is only used for the TEXT and HTML output
styles. It is commonly combined with the colon modifier ('{c:}').
It is purely a convenience feature.
Note that the sense of the 'w' modifier is reversed for the units role
({Uw:}); a blank is added before the contents, rather than after it.
*** Field Formatting
The field format is similar to the format string for printf(3). Its
use varies based on the role of the field, but generally is used to
format the field's contents.
If the format string is not provided for a value field, it defaults to
"%s".
Note a field definition can contain zero or more printf-style
'directives', which are sequences that start with a '%' and end with
one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive
is matched by one of more arguments to the xo_emit function.
The format string has the form:
'%' format-modifier * format-character
The format- modifier can be:
- a '#' character, indicating the output value should be prefixed with
'0x', typically to indicate a base 16 (hex) value.
- a minus sign ('-'), indicating the output value should be padded on
the right instead of the left.
- a leading zero ('0') indicating the output value should be padded on the
left with zeroes instead of spaces (' ').
- one or more digits ('0' - '9') indicating the minimum width of the
argument. If the width in columns of the output value is less than
the minimum width, the value will be padded to reach the minimum.
- a period followed by one or more digits indicating the maximum
number of bytes which will be examined for a string argument, or the maximum
width for a non-string argument. When handling ASCII strings this
functions as the field width but for multi-byte characters, a single
character may be composed of multiple bytes.
xo_emit will never dereference memory beyond the given number of bytes.
- a second period followed by one or more digits indicating the maximum
width for a string argument. This modifier cannot be given for non-string
arguments.
- one or more 'h' characters, indicating shorter input data.
- one or more 'l' characters, indicating longer input data.
- a 'z' character, indicating a 'size_t' argument.
- a 't' character, indicating a 'ptrdiff_t' argument.
- a ' ' character, indicating a space should be emitted before
positive numbers.
- a '+' character, indicating sign should emitted before any number.
Note that 'q', 'D', 'O', and 'U' are considered deprecated and will be
removed eventually.
The format character is described in the following table:
|-----+-----------------+----------------------|
| Ltr | Argument Type | Format |
|-----+-----------------+----------------------|
| d | int | base 10 (decimal) |
| i | int | base 10 (decimal) |
| o | int | base 8 (octal) |
| u | unsigned | base 10 (decimal) |
| x | unsigned | base 16 (hex) |
| X | unsigned long | base 16 (hex) |
| D | long | base 10 (decimal) |
| O | unsigned long | base 8 (octal) |
| U | unsigned long | base 10 (decimal) |
| e | double | [-]d.ddde+-dd |
| E | double | [-]d.dddE+-dd |
| f | double | [-]ddd.ddd |
| F | double | [-]ddd.ddd |
| g | double | as 'e' or 'f' |
| G | double | as 'E' or 'F' |
| a | double | [-]0xh.hhhp[+-]d |
| A | double | [-]0Xh.hhhp[+-]d |
| c | unsigned char | a character |
| C | wint_t | a character |
| s | char * | a UTF-8 string |
| S | wchar_t * | a unicode/WCS string |
| p | void * | '%#lx' |
|-----+-----------------+----------------------|
The 'h' and 'l' modifiers affect the size and treatment of the
argument:
|-----+-------------+--------------------|
| Mod | d, i | o, u, x, X |
|-----+-------------+--------------------|
| hh | signed char | unsigned char |
| h | short | unsigned short |
| l | long | unsigned long |
| ll | long long | unsigned long long |
| j | intmax_t | uintmax_t |
| t | ptrdiff_t | ptrdiff_t |
| z | size_t | size_t |
| q | quad_t | u_quad_t |
|-----+-------------+--------------------|
*** UTF-8 and Locale Strings
For strings, the 'h' and 'l' modifiers affect the interpretation of
the bytes pointed to argument. The default '%s' string is a 'char *'
pointer to a string encoded as UTF-8. Since UTF-8 is compatible with
ASCII data, a normal 7-bit ASCII string can be used. '%ls' expects a
'wchar_t *' pointer to a wide-character string, encoded as a 32-bit
Unicode values. '%hs' expects a 'char *' pointer to a multi-byte
string encoded with the current locale, as given by the LC_CTYPE,
LANG, or LC_ALL environment varibles. The first of this list of
variables is used and if none of the variables are set, the locale
defaults to "UTF-8".
libxo will convert these arguments as needed to either UTF-8 (for XML,
JSON, and HTML styles) or locale-based strings for display in text
style.
xo_emit("All strings are utf-8 content {:tag/%ls}",
L"except for wide strings");
"%S" is equivalent to "%ls".
|--------+-----------------+-------------------------------|
| Format | Argument Type | Argument Contents |
|--------+-----------------+-------------------------------|
| %s | const char * | UTF-8 string |
| %S | const char * | UTF-8 string (alias for '%s') |
| %ls | const wchar_t * | Wide character UNICODE string |
| %hs | const char * | locale-based string |
|--------+-----------------+-------------------------------|
For example, a function is passed a locale-base name, a hat size,
and a time value. The hat size is formatted in a UTF-8 (ASCII)
string, and the time value is formatted into a wchar_t string.
void print_order (const char *name, int size,
struct tm *timep) {
char buf[32];
const char *size_val = "unknown";
if (size > 0)
snprintf(buf, sizeof(buf), "%d", size);
size_val = buf;
}
wchar_t when[32];
wcsftime(when, sizeof(when), L"%d%b%y", timep);
xo_emit("The hat for {:name/%hs} is {:size/%s}.\n",
name, size_val);
xo_emit("It was ordered on {:order-time/%ls}.\n",
when);
}
It is important to note that xo_emit will perform the conversion
required to make appropriate output. Text style output uses the
current locale (as described above), while XML, JSON, and HTML use
UTF-8.
UTF-8 and locale-encoded strings can use multiple bytes to encode one
column of data. The traditional "precision'" (aka "max-width") value
for "%s" printf formatting becomes overloaded since it specifies both
the number of bytes that can be safely referenced and the maximum
number of columns to emit. xo_emit uses the precision as the former,
and adds a third value for specifying the maximum number of columns.
In this example, the name field is printed with a minimum of 3 columns
and a maximum of 6. Up to ten bytes of data at the location given by
'name' are in used in filling those columns.
xo_emit("{:name/%3.10.6s}", name);
*** Characters Outside of Field Definitions
Characters in the format string that are not part of a field
definition are copied to the output for the TEXT style, and are
ignored for the JSON and XML styles. For HTML, these characters are
placed in a
with class "text".
EXAMPLE:
xo_emit("The hat is {:size/%s}.\n", size_val);
TEXT:
The hat is extra small.
XML:
extra small
JSON:
"size": "extra small"
HTML:
The hat is
extra small
.
*** "%m" Is Supported
libxo supports the '%m' directive, which formats the error message
associated with the current value of "errno". It is the equivalent
of "%s" with the argument strerror(errno).
xo_emit("{:filename} cannot be opened: {:error/%m}", filename);
xo_emit("{:filename} cannot be opened: {:error/%s}",
filename, strerror(errno));
*** "%n" Is Not Supported
libxo does not support the '%n' directive. It's a bad idea and we
just don't do it.
*** The Encoding Format (eformat)
The "eformat" string is the format string used when encoding the field
for JSON and XML. If not provided, it defaults to the primary format
with any minimum width removed. If the primary is not given, both
default to "%s".
*** Content Strings
For padding and labels, the content string is considered the content,
unless a format is given.
*** Argument Validation @printf-like@
Many compilers and tool chains support validation of printf-like
arguments. When the format string fails to match the argument list,
a warning is generated. This is a valuable feature and while the
formatting strings for libxo differ considerably from printf, many of
these checks can still provide build-time protection against bugs.
libxo provide variants of functions that provide this ability, if the
"--enable-printflike" option is passed to the "configure" script.
These functions use the "_p" suffix, like "xo_emit_p()",
xo_emit_hp()", etc.
The following are features of libxo formatting strings that are
incompatible with printf-like testing:
- implicit formats, where "{:tag}" has an implicit "%s";
- the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to
ten bytes of data can be inspected to fill a minimum of 4 columns and
a maximum of 6;
- percent signs in strings, where "{:filled}%" makes a single,
trailing percent sign;
- the "l" and "h" modifiers for strings, where "{:tag/%hs}" means
locale-based string and "{:tag/%ls}" means a wide character string;
- distinct encoding formats, where "{:tag/#%s/%s}" means the display
styles (text and HTML) will use "#%s" where other styles use "%s";
If none of these features are in use by your code, then using the "_p"
variants might be wise.
|------------------+------------------------|
| Function | printf-like Equivalent |
|------------------+------------------------|
| xo_emit_hv | xo_emit_hvp |
| xo_emit_h | xo_emit_hp |
| xo_emit | xo_emit_p |
| xo_emit_warn_hcv | xo_emit_warn_hcvp |
| xo_emit_warn_hc | xo_emit_warn_hcp |
| xo_emit_warn_c | xo_emit_warn_cp |
| xo_emit_warn | xo_emit_warn_p |
| xo_emit_warnx_ | xo_emit_warnx_p |
| xo_emit_err | xo_emit_err_p |
| xo_emit_errx | xo_emit_errx_p |
| xo_emit_errc | xo_emit_errc_p |
|------------------+------------------------|
*** Retaining Parsed Format Information @retain@
libxo can retain the parsed internal information related to the given
format string, allowing subsequent xo_emit calls, the retained
information is used, avoiding repetitive parsing of the format string.
SYNTAX:
int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
EXAMPLE:
xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
some, thing, fancy);
To retain parsed format information, use the XOEF_RETAIN flag to the
xo_emit_f() function. A complete set of xo_emit_f functions exist to
match all the xo_emit function signatures (with handles, varadic
argument, and printf-like flags):
|------------------+------------------------|
| Function | Flags Equivalent |
|------------------+------------------------|
| xo_emit_hv | xo_emit_hvf |
| xo_emit_h | xo_emit_hf |
| xo_emit | xo_emit_f |
| xo_emit_hvp | xo_emit_hvfp |
| xo_emit_hp | xo_emit_hfp |
| xo_emit_p | xo_emit_fp |
|------------------+------------------------|
The format string must be immutable across multiple calls to xo_emit_f(),
since the library retains the string. Typically this is done by using
static constant strings, such as string literals. If the string is not
immutable, the XOEF_RETAIN flag must not be used.
The functions xo_retain_clear() and xo_retain_clear_all() release
internal information on either a single format string or all format
strings, respectively. Neither is required, but the library will
retain this information until it is cleared or the process exits.
const char *fmt = "{:name} {:count/%d}\n";
for (i = 0; i < 1000; i++) {
xo_open_instance("item");
xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
}
xo_retain_clear(fmt);
The retained information is kept as thread-specific data.
*** Example
In this example, the value for the number of items in stock is emitted:
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
instock);
This call will generate the following output:
TEXT:
In stock: 144
XML:
144
JSON:
"in-stock": 144,
HTML:
Clearly HTML wins the verbosity award, and this output does
not include XOF_XPATH or XOF_INFO data, which would expand the
penultimate line to:
144
** Representing Hierarchy
For XML and JSON, individual fields appear inside hierarchies which
provide context and meaning to the fields. Unfortunately, these
encoding have a basic disconnect between how lists is similar objects
are represented.
XML encodes lists as set of sequential elements:
phil
pallavi
sjg
JSON encodes lists using a single name and square brackets:
"user": [ "phil", "pallavi", "sjg" ]
This means libxo needs three distinct indications of hierarchy: one
for containers of hierarchy appear only once for any specific parent,
one for lists, and one for each item in a list.
*** Containers
A "container" is an element of a hierarchy that appears only once
under any specific parent. The container has no value, but serves to
contain other nodes.
To open a container, call xo_open_container() or
xo_open_container_h(). The former uses the default handle and
the latter accepts a specific handle.
int xo_open_container_h (xo_handle_t *xop, const char *name);
int xo_open_container (const char *name);
To close a level, use the xo_close_container() or
xo_close_container_h() functions:
int xo_close_container_h (xo_handle_t *xop, const char *name);
int xo_close_container (const char *name);
Each open call must have a matching close call. If the XOF_WARN flag
is set and the name given does not match the name of the currently open
container, a warning will be generated.
Example:
xo_open_container("top");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
domainname ? "." : "", domainname ?: "");
xo_close_container("system");
xo_close_container("top");
Sample Output:
Text:
my-host.example.org
XML:
my-host.example.org
JSON:
"top" : {
"system" : {
"host-name": "my-host.example.org"
}
}
HTML:
my-host.example.org
*** Lists and Instances
A list is set of one or more instances that appear under the same
parent. The instances contain details about a specific object. One
can think of instances as objects or records. A call is needed to
open and close the list, while a distinct call is needed to open and
close each instance of the list:
xo_open_list("item");
for (ip = list; ip->i_title; ip++) {
xo_open_instance("item");
xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
xo_close_instance("item");
}
xo_close_list("item");
Getting the list and instance calls correct is critical to the proper
generation of XML and JSON data.
*** DTRT Mode
Some users may find tracking the names of open containers, lists, and
instances inconvenient. libxo offers a "Do The Right Thing" mode, where
libxo will track the names of open containers, lists, and instances so
the close function can be called without a name. To enable DTRT mode,
turn on the XOF_DTRT flag prior to making any other libxo output.
xo_set_flags(NULL, XOF_DTRT);
Each open and close function has a version with the suffix "_d", which
will close the open container, list, or instance:
xo_open_container("top");
...
xo_close_container_d();
This also works for lists and instances:
xo_open_list("item");
for (...) {
xo_open_instance("item");
xo_emit(...);
xo_close_instance_d();
}
xo_close_list_d();
Note that the XOF_WARN flag will also cause libxo to track open
containers, lists, and instances. A warning is generated when the
name given to the close function and the name recorded do not match.
*** Markers
Markers are used to protect and restore the state of open constructs.
While a marker is open, no other open constructs can be closed. When
a marker is closed, all constructs open since the marker was opened
will be closed.
Markers use names which are not user-visible, allowing the caller to
choose appropriate internal names.
In this example, the code whiffles through a list of fish, calling a
function to emit details about each fish. The marker "fish-guts" is
used to ensure that any constructs opened by the function are closed
properly.
for (i = 0; fish[i]; i++) {
xo_open_instance("fish");
xo_open_marker("fish-guts");
dump_fish_details(i);
xo_close_marker("fish-guts");
}
* Command-line Arguments @options@
libxo uses command line options to trigger rendering behavior. The
following options are recognised:
- --libxo
- --libxo=
- --libxo:
The following invocations are all identical in outcome:
my-app --libxo warn,pretty arg1
my-app --libxo=warn,pretty arg1
my-app --libxo:WP arg1
Programs using libxo are expecting to call the xo_parse_args function
to parse these arguments. See ^xo_parse_args^ for details.
** Option keywords
Options is a comma-separated list of tokens that correspond to output
styles, flags, or features:
|-------------+-------------------------------------------------------|
| Token | Action |
|-------------+-------------------------------------------------------|
| color | Enable colors/effects for display styles (TEXT, HTML) |
| colors=xxxx | Adjust color output values |
| dtrt | Enable "Do The Right Thing" mode |
| flush | Flush after every libxo function call |
| flush-line | Flush after every line (line-buffered) |
| html | Emit HTML output |
| indent=xx | Set the indentation level |
| info | Add info attributes (HTML) |
| json | Emit JSON output |
| keys | Emit the key attribute for keys (XML) |
| log-gettext | Log (via stderr) each gettext(3) string lookup |
| log-syslog | Log (via stderr) each syslog message (via xo_syslog) |
| no-humanize | Ignore the {h:} modifier (TEXT, HTML) |
| no-locale | Do not initialize the locale setting |
| no-retain | Prevent retaining formatting information |
| no-top | Do not emit a top set of braces (JSON) |
| not-first | Pretend the 1st output item was not 1st (JSON) |
| pretty | Emit pretty-printed output |
| retain | Force retaining formatting information |
| text | Emit TEXT output |
| underscores | Replace XML-friendly "-"s with JSON friendly "_"s |
| units | Add the 'units' (XML) or 'data-units (HTML) attribute |
| warn | Emit warnings when libxo detects bad calls |
| warn-xml | Emit warnings in XML |
| xml | Emit XML output |
| xpath | Add XPath expressions (HTML) |
|-------------+-------------------------------------------------------|
Most of these option are simple and direct, but some require
additional details:
- "colors" is described in ^color-mapping^.
- "flush-line" performs line buffering, even when the output is not
directed to a TTY device.
- "info" generates additional data for HTML, encoded in attributes
using names that state with "data-".
- "keys" adds a "key" attribute for XML output to indicate that a leaf
is an identifier for the list member.
- "no-humanize"avoids "humanizing" numeric output (see
humanize_number(3) for details).
- "no-locale" instructs libxo to avoid translating output to the
current locale.
- "no-retain" disables the ability of libxo to internally retain
"compiled" information about formatting strings.
- "underscores" can be used with JSON output to change XML-friendly
names with dashes into JSON-friendly name with underscores.
- "warn" allows libxo to emit warnings on stderr when application code
make incorrect calls.
- "warn-xml" causes those warnings to be placed in XML inside the
output.
** Brief Options
The brief options are simple single-letter aliases to the normal
keywords, as detailed below:
|--------+---------------------------------------------|
| Option | Action |
|--------+---------------------------------------------|
| c | Enable color/effects for TEXT/HTML |
| F | Force line-buffered flushing |
| H | Enable HTML output (XO_STYLE_HTML) |
| I | Enable info output (XOF_INFO) |
| i | Indent by |
| J | Enable JSON output (XO_STYLE_JSON) |
| k | Add keys to XPATH expressions in HTML |
| n | Disable humanization (TEXT, HTML) |
| P | Enable pretty-printed output (XOF_PRETTY) |
| T | Enable text output (XO_STYLE_TEXT) |
| U | Add units to HTML output |
| u | Change "-"s to "_"s in element names (JSON) |
| W | Enable warnings (XOF_WARN) |
| X | Enable XML output (XO_STYLE_XML) |
| x | Enable XPath data (XOF_XPATH) |
|--------+---------------------------------------------|
** Color Mapping
The "colors" option takes a value that is a set of mappings from the
pre-defined set of colors to new foreground and background colors.
The value is a series of "fg/bg" values, separated by a "+". Each
pair of "fg/bg" values gives the colors to which a basic color is
mapped when used as a foreground or background color. The order is
the mappings is:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
Pairs may be skipped, leaving them mapped as normal, as are missing
pairs or single colors.
For example consider the following xo_emit call:
xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n");
To turn all colored output to red-on-blue, use eight pairs of
"red/blue" mappings separated by "+"s:
--libxo colors=red/blue+red/blue+red/blue+red/blue+\
red/blue+red/blue+red/blue+red/blue
To turn the red-on-green text to magenta-on-cyan, give a "magenta"
foreground value for red (the second mapping) and a "cyan" background
to green (the third mapping):
--libxo colors=+magenta+/cyan
Consider the common situation where blue output looks unreadable on a
terminal session with a black background. To turn both "blue"
foreground and background output to "yellow", give only the fifth
mapping, skipping the first four mappings with bare "+"s:
--libxo colors=++++yellow/yellow
* The libxo API
This section gives details about the functions in libxo, how to call
them, and the actions they perform.
** Handles @handles@
libxo uses "handles" to control its rendering functionality. The
handle contains state and buffered data, as well as callback functions
to process data.
Handles give an abstraction for libxo that encapsulates the state of a
stream of output. Handles have the data type "xo_handle_t" and are
opaque to the caller.
The library has a default handle that is automatically initialized.
By default, this handle will send text style output (XO_STYLE_TEXT) to
standard output. The xo_set_style and xo_set_flags functions can be
used to change this behavior.
For the typical command that is generating output on standard output,
there is no need to create an explicit handle, but they are available
when needed, e.g., for daemons that generate multiple streams of
output.
Many libxo functions take a handle as their first parameter; most that
do not use the default handle. Any function taking a handle can be
passed NULL to access the default handle. For the convenience of
callers, the libxo library includes handle-less functions that
implicitly use the default handle.
For example, the following are equivalent:
xo_emit("test");
xo_emit_h(NULL, "test");
Handles are created using xo_create() and destroy using xo_destroy().
*** xo_create
A handle can be allocated using the xo_create() function:
xo_handle_t *xo_create (unsigned style, unsigned flags);
Example:
xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN);
....
xo_emit_h(xop, "testing\n");
See also ^styles^ and ^flags^.
*** xo_create_to_file
By default, libxo writes output to standard output. A convenience
function is provided for situations when output should be written to
a different file:
xo_handle_t *xo_create_to_file (FILE *fp, unsigned style,
unsigned flags);
Use the XOF_CLOSE_FP flag to trigger a call to fclose() for
the FILE pointer when the handle is destroyed.
*** xo_set_writer
The xo_set_writer function allows custom 'write' functions
which can tailor how libxo writes data. An opaque argument is
recorded and passed back to the write function, allowing the function
to acquire context information. The 'close' function can
release this opaque data and any other resources as needed.
The flush function can flush buffered data associated with the opaque
object.
void xo_set_writer (xo_handle_t *xop, void *opaque,
xo_write_func_t write_func,
xo_close_func_t close_func);
xo_flush_func_t flush_func);
*** xo_set_style
To set the style, use the xo_set_style() function:
void xo_set_style(xo_handle_t *xop, unsigned style);
To use the default handle, pass a NULL handle:
xo_set_style(NULL, XO_STYLE_XML);
*** xo_get_style
To find the current style, use the xo_get_style() function:
xo_style_t xo_get_style(xo_handle_t *xop);
To use the default handle, pass a NULL handle:
style = xo_get_style(NULL);
**** Output Styles (XO_STYLE_*) @styles@
The libxo functions accept a set of output styles:
|---------------+-------------------------|
| Flag | Description |
|---------------+-------------------------|
| XO_STYLE_TEXT | Traditional text output |
| XO_STYLE_XML | XML encoded data |
| XO_STYLE_JSON | JSON encoded data |
| XO_STYLE_HTML | HTML encoded data |
|---------------+-------------------------|
**** xo_set_style_name
The xo_set_style_name() can be used to set the style based on a name
encoded as a string:
int xo_set_style_name (xo_handle_t *xop, const char *style);
The name can be any of the styles: "text", "xml", "json", or "html".
EXAMPLE:
xo_set_style_name(NULL, "html");
*** xo_set_flags
To set the flags, use the xo_set_flags() function:
void xo_set_flags(xo_handle_t *xop, unsigned flags);
To use the default handle, pass a NULL handle:
xo_set_style(NULL, XO_STYLE_XML);
**** Flags (XOF_*) @flags@
The set of valid flags include:
|-------------------+----------------------------------------|
| Flag | Description |
|-------------------+----------------------------------------|
| XOF_CLOSE_FP | Close file pointer on xo_destroy() |
| XOF_COLOR | Enable color and effects in output |
| XOF_COLOR_ALLOWED | Allow color/effect for terminal output |
| XOF_DTRT | Enable "do the right thing" mode |
| XOF_INFO | Display info data attributes (HTML) |
| XOF_KEYS | Emit the key attribute (XML) |
| XOF_NO_ENV | Do not use the LIBXO_OPTIONS env var |
| XOF_NO_HUMANIZE | Display humanization (TEXT, HTML) |
| XOF_PRETTY | Make 'pretty printed' output |
| XOF_UNDERSCORES | Replaces hyphens with underscores |
| XOF_UNITS | Display units (XML, HMTL) |
| XOF_WARN | Generate warnings for broken calls |
| XOF_WARN_XML | Generate warnings in XML on stdout |
| XOF_XPATH | Emit XPath expressions (HTML) |
| XOF_COLUMNS | Force xo_emit to return columns used |
| XOF_FLUSH | Flush output after each xo_emit call |
|-------------------+----------------------------------------|
The XOF_CLOSE_FP flag will trigger the call of the close_func
(provided via xo_set_writer()) when the handle is destroyed.
The XOF_COLOR flag enables color and effects in output regardless of
output device, while the XOF_COLOR_ALLOWED flag allows color and
effects only if the output device is a terminal.
The XOF_PRETTY flag requests 'pretty printing', which will trigger the
addition of indentation and newlines to enhance the readability of
XML, JSON, and HTML output. Text output is not affected.
The XOF_WARN flag requests that warnings will trigger diagnostic
output (on standard error) when the library notices errors during
operations, or with arguments to functions. Without warnings enabled,
such conditions are ignored.
Warnings allow developers to debug their interaction with libxo.
The function "xo_failure" can used as a breakpoint for a debugger,
regardless of whether warnings are enabled.
If the style is XO_STYLE_HTML, the following additional flags can be
used:
|---------------+-----------------------------------------|
| Flag | Description |
|---------------+-----------------------------------------|
| XOF_XPATH | Emit "data-xpath" attributes |
| XOF_INFO | Emit additional info fields |
|---------------+-----------------------------------------|
The XOF_XPATH flag enables the emission of XPath expressions detailing
the hierarchy of XML elements used to encode the data field, if the
XPATH style of output were requested.
The XOF_INFO flag encodes additional informational fields for HTML
output. See ^info^ for details.
If the style is XO_STYLE_XML, the following additional flags can be
used:
|---------------+-----------------------------------------|
| Flag | Description |
|---------------+-----------------------------------------|
| XOF_KEYS | Flag 'key' fields for xml |
|---------------+-----------------------------------------|
The XOF_KEYS flag adds 'key' attribute to the XML encoding for
field definitions that use the 'k' modifier. The key attribute has
the value "key":
xo_emit("{k:name}", item);
XML:
truck
**** xo_clear_flags
The xo_clear_flags() function turns off the given flags in a specific
handle.
void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags);
**** xo_set_options
The xo_set_options() function accepts a comma-separated list of styles
and flags and enables them for a specific handle.
int xo_set_options (xo_handle_t *xop, const char *input);
The options are identical to those listed in ^options^.
*** xo_destroy
The xo_destroy function releases a handle and any resources it is
using. Calling xo_destroy with a NULL handle will release any
resources associated with the default handle.
void xo_destroy(xo_handle_t *xop);
** Emitting Content (xo_emit)
The following functions are used to emit output:
int xo_emit (const char *fmt, ...);
int xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
The "fmt" argument is a string containing field descriptors as
specified in ^format-strings^. The use of a handle is optional and
NULL can be passed to access the internal 'default' handle. See
^handles^.
The remaining arguments to xo_emit() and xo_emit_h() are a set of
arguments corresponding to the fields in the format string. Care must
be taken to ensure the argument types match the fields in the format
string, since an inappropriate cast can ruin your day. The vap
argument to xo_emit_hv() points to a variable argument list that can
be used to retrieve arguments via va_arg().
*** Single Field Emitting Functions (xo_emit_field) @xo_emit_field@
The following functions can also make output, but only make a single
field at a time:
int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod,
const char *contents, const char *fmt,
const char *efmt, va_list vap);
int xo_emit_field_h (xo_handle_t *xop, const char *rolmod,
const char *contents, const char *fmt,
const char *efmt, ...);
int xo_emit_field (const char *rolmod, const char *contents,
const char *fmt, const char *efmt, ...);
These functions are intended to avoid the scenario where one
would otherwise need to compose a format descriptors using
snprintf(). The individual parts of the format descriptor are
passed in distinctly.
xo_emit("T", "Host name is ", NULL, NULL);
xo_emit("V", "host-name", NULL, NULL, host-name);
*** Attributes (xo_attr) @xo_attr@
The xo_attr() function emits attributes for the XML output style.
int xo_attr (const char *name, const char *fmt, ...);
int xo_attr_h (xo_handle_t *xop, const char *name,
const char *fmt, ...);
int xo_attr_hv (xo_handle_t *xop, const char *name,
const char *fmt, va_list vap);
The name parameter give the name of the attribute to be encoded. The
fmt parameter gives a printf-style format string used to format the
value of the attribute using any remaining arguments, or the vap
parameter passed to xo_attr_hv().
EXAMPLE:
xo_attr("seconds", "%ld", (unsigned long) login_time);
struct tm *tmp = localtime(login_time);
strftime(buf, sizeof(buf), "%R", tmp);
xo_emit("Logged in at {:login-time}\n", buf);
XML:
00:14
xo_attr is placed on the next container, instance, leaf, or leaf list
that is emitted.
Since attributes are only emitted in XML, their use should be limited
to meta-data and additional or redundant representations of data
already emitted in other form.
*** Flushing Output (xo_flush)
libxo buffers data, both for performance and consistency, but also to
allow some advanced features to work properly. At various times, the
caller may wish to flush any data buffered within the library. The
xo_flush() call is used for this:
void xo_flush (void);
void xo_flush_h (xo_handle_t *xop);
Calling xo_flush also triggers the flush function associated with the
handle. For the default handle, this is equivalent to
"fflush(stdio);".
*** Finishing Output (xo_finish)
When the program is ready to exit or close a handle, a call to
xo_finish() is required. This flushes any buffered data, closes
open libxo constructs, and completes any pending operations.
int xo_finish (void);
int xo_finish_h (xo_handle_t *xop);
void xo_finish_atexit (void);
Calling this function is vital to the proper operation of libxo,
especially for the non-TEXT output styles.
xo_finish_atexit is suitable for use with atexit(3).
** Emitting Hierarchy
libxo represents to types of hierarchy: containers and lists. A
container appears once under a given parent where a list contains
instances that can appear multiple times. A container is used to hold
related fields and to give the data organization and scope.
To create a container, use the xo_open_container and
xo_close_container functions:
int xo_open_container (const char *name);
int xo_open_container_h (xo_handle_t *xop, const char *name);
int xo_open_container_hd (xo_handle_t *xop, const char *name);
int xo_open_container_d (const char *name);
int xo_close_container (const char *name);
int xo_close_container_h (xo_handle_t *xop, const char *name);
int xo_close_container_hd (xo_handle_t *xop);
int xo_close_container_d (void);
The name parameter gives the name of the container, encoded in UTF-8.
Since ASCII is a proper subset of UTF-8, traditional C strings can be
used directly.
The close functions with the "_d" suffix are used in "Do The Right
Thing" mode, where the name of the open containers, lists, and
instances are maintained internally by libxo to allow the caller to
avoid keeping track of the open container name.
Use the XOF_WARN flag to generate a warning if the name given on the
close does not match the current open container.
For TEXT and HTML output, containers are not rendered into output
text, though for HTML they are used when the XOF_XPATH flag is set.
EXAMPLE:
xo_open_container("system");
xo_emit("The host name is {:host-name}\n", hn);
xo_close_container("system");
XML:
foo
*** Lists and Instances
Lists are sequences of instances of homogeneous data objects. Two
distinct levels of calls are needed to represent them in our output
styles. Calls must be made to open and close a list, and for each
instance of data in that list, calls must be make to open and close
that instance.
The name given to all calls must be identical, and it is strongly
suggested that the name be singular, not plural, as a matter of
style and usage expectations.
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
xo_open_instance("user");
xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n",
pw[i].pw_name, pw[i].pw_uid,
pw[i].pw_gid, pw[i].pw_dir);
xo_close_instance("user");
}
xo_close_list("user");
TEXT:
phil:1001:1001:/home/phil
pallavi:1002:1002:/home/pallavi
XML:
phil
1001
1001
/home/phil
pallavi
1002
1002
/home/pallavi
JSON:
user: [
{
"name": "phil",
"uid": 1001,
"gid": 1001,
"home": "/home/phil",
},
{
"name": "pallavi",
"uid": 1002,
"gid": 1002,
"home": "/home/pallavi",
}
]
** Support Functions
*** Parsing Command-line Arguments (xo_parse_args) @xo_parse_args@
The xo_parse_args() function is used to process a program's
arguments. libxo-specific options are processed and removed
from the argument list so the calling application does not
need to process them. If successful, a new value for argc
is returned. On failure, a message it emitted and -1 is returned.
argc = xo_parse_args(argc, argv);
if (argc < 0)
exit(EXIT_FAILURE);
Following the call to xo_parse_args, the application can process the
remaining arguments in a normal manner. See ^options^
for a description of valid arguments.
*** xo_set_program
The xo_set_program function sets name of the program as reported by
functions like xo_failure, xo_warn, xo_err, etc. The program name is
initialized by xo_parse_args, but subsequent calls to xo_set_program
can override this value.
xo_set_program(argv[0]);
Note that the value is not copied, so the memory passed to
xo_set_program (and xo_parse_args) must be maintained by the caller.
*** xo_set_version
The xo_set_version function records a version number to be emitted as
part of the data for encoding styles (XML and JSON). This version
number is suitable for tracking changes in the content, allowing a
user of the data to discern which version of the data model is in use.
void xo_set_version (const char *version);
void xo_set_version_h (xo_handle_t *xop, const char *version);
*** Field Information (xo_info_t) @info@
HTML data can include additional information in attributes that
begin with "data-". To enable this, three things must occur:
First the application must build an array of xo_info_t structures,
one per tag. The array must be sorted by name, since libxo uses a
binary search to find the entry that matches names from format
instructions.
Second, the application must inform libxo about this information using
the xo_set_info() call:
typedef struct xo_info_s {
const char *xi_name; /* Name of the element */
const char *xi_type; /* Type of field */
const char *xi_help; /* Description of field */
} xo_info_t;
void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
Like other libxo calls, passing NULL for the handle tells libxo to use
the default handle.
If the count is -1, libxo will count the elements of infop, but there
must be an empty element at the end. More typically, the number is
known to the application:
xo_info_t info[] = {
{ "in-stock", "number", "Number of items in stock" },
{ "name", "string", "Name of the item" },
{ "on-order", "number", "Number of items on order" },
{ "sku", "string", "Stock Keeping Unit" },
{ "sold", "number", "Number of items sold" },
};
int info_count = (sizeof(info) / sizeof(info[0]));
...
xo_set_info(NULL, info, info_count);
Third, the emission of info must be triggered with the XOF_INFO flag
using either the xo_set_flags() function or the "--libxo=info" command
line argument.
The type and help values, if present, are emitted as the "data-type"
and "data-help" attributes:
GRO-000-533
*** Memory Allocation
The xo_set_allocator function allows libxo to be used in environments
where the standard realloc() and free() functions are not available.
void xo_set_allocator (xo_realloc_func_t realloc_func,
xo_free_func_t free_func);
realloc_func should expect the same arguments as realloc(3) and return
a pointer to memory following the same convention. free_func will
receive the same argument as free(3) and should release it, as
appropriate for the environment.
By default, the standard realloc() and free() functions are used.
*** LIBXO_OPTIONS @LIBXO_OPTIONS@
The environment variable "LIBXO_OPTIONS" can be set to a subset of
libxo options, including:
- color
- flush
- flush-line
- no-color
- no-humanize
- no-locale
- no-retain
- pretty
- retain
- underscores
- warn
For example, warnings can be enabled by:
% env LIBXO_OPTIONS=warn my-app
Since environment variables are inherited, child processes will have
the same options, which may be undesirable, making the use of the
"--libxo" option is preferable in most situations.
*** Errors, Warnings, and Messages
Many programs make use of the standard library functions err() and
warn() to generate errors and warnings for the user. libxo wants to
pass that information via the current output style, and provides
compatible functions to allow this:
void xo_warn (const char *fmt, ...);
void xo_warnx (const char *fmt, ...);
void xo_warn_c (int code, const char *fmt, ...);
void xo_warn_hc (xo_handle_t *xop, int code,
const char *fmt, ...);
void xo_err (int eval, const char *fmt, ...);
void xo_errc (int eval, int code, const char *fmt, ...);
void xo_errx (int eval, const char *fmt, ...);
void xo_message (const char *fmt, ...);
void xo_message_c (int code, const char *fmt, ...);
void xo_message_hc (xo_handle_t *xop, int code,
const char *fmt, ...);
void xo_message_hcv (xo_handle_t *xop, int code,
const char *fmt, va_list vap);
These functions display the program name, a colon, a formatted message
based on the arguments, and then optionally a colon and an error
message associated with either "errno" or the "code" parameter.
EXAMPLE:
if (open(filename, O_RDONLY) < 0)
xo_err(1, "cannot open file '%s'", filename);
*** xo_error
The xo_error function can be used for generic errors that should be
reported over the handle, rather than to stderr. The xo_error
function behaves like xo_err for TEXT and HTML output styles, but puts
the error into XML or JSON elements:
EXAMPLE::
xo_error("Does not %s", "compute");
XML::
Does not compute
JSON::
"error": { "message": "Does not compute" }
*** xo_no_setlocale
libxo automatically initializes the locale based on setting of the
environment variables LC_CTYPE, LANG, and LC_ALL. The first of this
list of variables is used and if none of the variables, the locale
defaults to "UTF-8". The caller may wish to avoid this behavior, and
can do so by calling the xo_no_setlocale() function.
void xo_no_setlocale (void);
** Emitting syslog Messages
syslog is the system logging facility used throughout the unix world.
Messages are sent from commands, applications, and daemons to a
hierarchy of servers, where they are filtered, saved, and forwarded
based on configuration behaviors.
syslog is an older protocol, originally documented only in source
code. By the time RFC 3164 published, variation and mutation left the
leading "" string as only common content. RFC 5424 defines a new
version (version 1) of syslog and introduces structured data into the
messages. Structured data is a set of name/value pairs transmitted
distinctly alongside the traditional text message, allowing filtering
on precise values instead of regular expressions.
These name/value pairs are scoped by a two-part identifier; an
enterprise identifier names the party responsible for the message
catalog and a name identifying that message. Enterprise IDs are
defined by IANA, the Internet Assigned Numbers Authority:
https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
Use the ^xo_set_syslog_enterprise_id^() function to set the Enterprise
ID, as needed.
The message name should follow the conventions in ^good-field-names^,
as should the fields within the message.
/* Both of these calls are optional */
xo_set_syslog_enterprise_id(32473);
xo_open_log("my-program", 0, LOG_DAEMON);
/* Generate a syslog message */
xo_syslog(LOG_ERR, "upload-failed",
"error <%d> uploading file '{:filename}' "
"as '{:target/%s:%s}'",
code, filename, protocol, remote);
xo_syslog(LOG_INFO, "poofd-invalid-state",
"state {:current/%u} is invalid {:connection/%u}",
state, conn);
The developer should be aware that the message name may be used in the
future to allow access to further information, including
documentation. Care should be taken to choose quality, descriptive
names.
*** Priority, Facility, and Flags @priority@
The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of
flags which provide the priority of the message, the source facility,
and some additional features. These values are OR'd together to
create a single integer argument:
xo_syslog(LOG_ERR | LOG_AUTH, "login-failed",
"Login failed; user '{:user}' from host '{:address}'",
user, addr);
These values are defined in .
The priority value indicates the importance and potential impact of
each message.
|-------------+-------------------------------------------------------|
| Priority | Description |
|-------------+-------------------------------------------------------|
| LOG_EMERG | A panic condition, normally broadcast to all users |
| LOG_ALERT | A condition that should be corrected immediately |
| LOG_CRIT | Critical conditions |
| LOG_ERR | Generic errors |
| LOG_WARNING | Warning messages |
| LOG_NOTICE | Non-error conditions that might need special handling |
| LOG_INFO | Informational messages |
| LOG_DEBUG | Developer-oriented messages |
|-------------+-------------------------------------------------------|
The facility value indicates the source of message, in fairly generic
terms.
|---------------+-------------------------------------------------|
| Facility | Description |
|---------------+-------------------------------------------------|
| LOG_AUTH | The authorization system (e.g. login(1)) |
| LOG_AUTHPRIV | As LOG_AUTH, but logged to a privileged file |
| LOG_CRON | The cron daemon: cron(8) |
| LOG_DAEMON | System daemons, not otherwise explicitly listed |
| LOG_FTP | The file transfer protocol daemons |
| LOG_KERN | Messages generated by the kernel |
| LOG_LPR | The line printer spooling system |
| LOG_MAIL | The mail system |
| LOG_NEWS | The network news system |
| LOG_SECURITY | Security subsystems, such as ipfw(4) |
| LOG_SYSLOG | Messages generated internally by syslogd(8) |
| LOG_USER | Messages generated by user processes (default) |
| LOG_UUCP | The uucp system |
| LOG_LOCAL0..7 | Reserved for local use |
|---------------+-------------------------------------------------|
In addition to the values listed above, xo_open_log accepts a set of
addition flags requesting specific behaviors.
|------------+----------------------------------------------------|
| Flag | Description |
|------------+----------------------------------------------------|
| LOG_CONS | If syslogd fails, attempt to write to /dev/console |
| LOG_NDELAY | Open the connection to syslogd(8) immediately |
| LOG_PERROR | Write the message also to standard error output |
| LOG_PID | Log the process id with each message |
|------------+----------------------------------------------------|
*** xo_syslog
Use the xo_syslog function to generate syslog messages by calling it
with a log priority and facility, a message name, a format string, and
a set of arguments. The priority/facility argument are discussed
above, as is the message name.
The format string follows the same conventions as xo_emit's format
string, with each field being rendered as an SD-PARAM pair.
xo_syslog(LOG_ERR, "poofd-missing-file",
"'{:filename}' not found: {:error/%m}", filename);
... [poofd-missing-file@32473 filename="/etc/poofd.conf"
error="Permission denied"] '/etc/poofd.conf' not
found: Permission denied
*** Support functions
**** xo_vsyslog
xo_vsyslog is identical in function to xo_syslog, but takes the set of
arguments using a va_list.
void my_log (const char *name, const char *fmt, ...)
{
va_list vap;
va_start(vap, fmt);
xo_vsyslog(LOG_ERR, name, fmt, vap);
va_end(vap);
}
**** xo_open_log
xo_open_log functions similar to openlog(3), allowing customization of
the program name, the log facility number, and the additional option
flags described in ^priority^.
void
xo_open_log (const char *ident, int logopt, int facility);
**** xo_close_log
xo_close_log functions similar to closelog(3), closing the log file
and releasing any associated resources.
void
xo_close_log (void);
**** xo_set_logmask
xo_set_logmask function similar to setlogmask(3), restricting the set
of generated log event to those whose associated bit is set in
maskpri. Use LOG_MASK(pri) to find the appropriate bit, or
LOG_UPTO(toppri) to create a mask for all priorities up to and
including toppri.
int
xo_set_logmask (int maskpri);
Example:
setlogmask(LOG_UPTO(LOG_WARN));
**** xo_set_syslog_enterprise_id
Use the xo_set_syslog_enterprise_id to supply a platform- or
application-specific enterprise id. This value is used in any
future syslog messages.
Ideally, the operating system should supply a default value via the
"kern.syslog.enterprise_id" sysctl value. Lacking that, the
application should provide a suitable value.
void
xo_set_syslog_enterprise_id (unsigned short eid);
Enterprise IDs are administered by IANA, the Internet Assigned Number
Authority. The complete list is EIDs on their web site:
https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
New EIDs can be requested from IANA using the following page:
http://pen.iana.org/pen/PenApplication.page
Each software development organization that defines a set of syslog
messages should register their own EID and use that value in their
software to ensure that messages can be uniquely identified by the
combination of EID + message name.
** Creating Custom Encoders
The number of encoding schemes in current use is staggering, with new
and distinct schemes appearing daily. While libxo provide XML, JSON,
HMTL, and text natively, there are requirements for other encodings.
Rather than bake support for all possible encoders into libxo, the API
allows them to be defined externally. libxo can then interfaces with
these encoding modules using a simplistic API. libxo processes all
functions calls, handles state transitions, performs all formatting,
and then passes the results as operations to a customized encoding
function, which implements specific encoding logic as required. This
means your encoder doesn't need to detect errors with unbalanced
open/close operations but can rely on libxo to pass correct data.
By making a simple API, libxo internals are not exposed, insulating the
encoder and the library from future or internal changes.
The three elements of the API are:
- loading
- initialization
- operations
The following sections provide details about these topics.
libxo source contain an encoder for Concise Binary Object
Representation, aka CBOR (RFC 7049) which can be used as used as an
example for the API.
*** Loading Encoders
Encoders can be registered statically or discovered dynamically.
Applications can choose to call the xo_encoder_register()
function to explicitly register encoders, but more typically they are
built as shared libraries, placed in the libxo/extensions directory,
and loaded based on name. libxo looks for a file with the name of the encoder
and an extension of ".enc". This can be a file or a symlink to the
shared library file that supports the encoder.
% ls -1 lib/libxo/extensions/*.enc
lib/libxo/extensions/cbor.enc
lib/libxo/extensions/test.enc
*** Encoder Initialization
Each encoder must export a symbol used to access the library, which
must have the following signature:
int xo_encoder_library_init (XO_ENCODER_INIT_ARGS);
XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines
an argument called "arg", a pointer of the type
xo_encoder_init_args_t. This structure contains two fields:
- xei_version is the version number of the API as implemented within
libxo. This version is currently as 1 using XO_ENCODER_VERSION. This
number can be checked to ensure compatibility. The working assumption
is that all versions should be backward compatible, but each side may
need to accurately know the version supported by the other side.
xo_encoder_library_init can optionally check this value, and must then
set it to the version number used by the encoder, allowing libxo to
detect version differences and react accordingly. For example, if
version 2 adds new operations, then libxo will know that an encoding
library that set xei_version to 1 cannot be expected to handle those
new operations.
- xei_handler must be set to a pointer to a function of type
xo_encoder_func_t, as defined in xo_encoder.h. This function
takes a set of parameters:
-- xop is a pointer to the opaque xo_handle_t structure
-- op is an integer representing the current operation
-- name is a string whose meaning differs by operation
-- value is a string whose meaning differs by operation
-- private is an opaque structure provided by the encoder
Additional arguments may be added in the future, so handler functions
should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate
"extern" declaration is provided to help catch errors.
Once the encoder initialization function has completed processing, it
should return zero to indicate that no error has occurred. A non-zero
return code will cause the handle initialization to fail.
*** Operations
The encoder API defines a set of operations representing the
processing model of libxo. Content is formatted within libxo, and
callbacks are made to the encoder's handler function when data is
ready to be processed.
|-----------------------+---------------------------------------|
| Operation | Meaning (Base function) |
|-----------------------+---------------------------------------|
| XO_OP_CREATE | Called when the handle is created |
| XO_OP_OPEN_CONTAINER | Container opened (xo_open_container) |
| XO_OP_CLOSE_CONTAINER | Container closed (xo_close_container) |
| XO_OP_OPEN_LIST | List opened (xo_open_list) |
| XO_OP_CLOSE_LIST | List closed (xo_close_list) |
| XO_OP_OPEN_LEAF_LIST | Leaf list opened (xo_open_leaf_list) |
| XO_OP_CLOSE_LEAF_LIST | Leaf list closed (xo_close_leaf_list) |
| XO_OP_OPEN_INSTANCE | Instance opened (xo_open_instance) |
| XO_OP_CLOSE_INSTANCE | Instance closed (xo_close_instance) |
| XO_OP_STRING | Field with Quoted UTF-8 string |
| XO_OP_CONTENT | Field with content |
| XO_OP_FINISH | Finish any pending output |
| XO_OP_FLUSH | Flush any buffered output |
| XO_OP_DESTROY | Clean up resources |
| XO_OP_ATTRIBUTE | An attribute name/value pair |
| XO_OP_VERSION | A version string |
|-----------------------+---------------------------------------|
For all the open and close operations, the name parameter holds the
name of the construct. For string, content, and attribute operations,
the name parameter is the name of the field and the value parameter is
the value. "string" are differentiated from "content" to allow differing
treatment of true, false, null, and numbers from real strings, though
content values are formatted as strings before the handler is called.
For version operations, the value parameter contains the version.
All strings are encoded in UTF-8.
* The "xo" Utility
The "xo" utility allows command line access to the functionality of
the libxo library. Using "xo", shell scripts can emit XML, JSON, and
HTML using the same commands that emit text output.
The style of output can be selected using a specific option: "-X" for
XML, "-J" for JSON, "-H" for HTML, or "-T" for TEXT, which is the
default. The "--style