diff --git a/configure.ac b/configure.ac index 56b33c4c5e30..03affa949211 100644 --- a/configure.ac +++ b/configure.ac @@ -12,7 +12,7 @@ # AC_PREREQ(2.2) -AC_INIT([libxo], [0.9.0], [phil@juniper.net]) +AC_INIT([libxo], [1.0.2], [phil@juniper.net]) AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability]) # Support silent build rules. Requires at least automake-1.11. diff --git a/doc/api.rst b/doc/api.rst index 98df01c99edb..ef5f985a8162 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -400,28 +400,28 @@ 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`. -.. c:function:: int xo_emit (const char *fmt, ...) +.. c:function:: xo_ssize_t xo_emit (const char *fmt, ...) :param fmt: The format string, followed by zero or more arguments :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t -.. c:function:: int xo_emit_h (xo_handle_t *xop, const char *fmt, ...) +.. c:function:: xo_ssize_t xo_emit_h (xo_handle_t *xop, const char *fmt, ...) :param xop: Handle for modify (or NULL for default handle) :type xop: xo_handle_t \* :param fmt: The format string, followed by zero or more arguments :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t -.. c:function:: int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap) +.. c:function:: xo_ssize_t xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap) :param xop: Handle for modify (or NULL for default handle) :type xop: xo_handle_t \* :param fmt: The format string :param va_list vap: A set of variadic arguments :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t .. index:: xo_emit_field @@ -434,7 +434,7 @@ scenario where one would otherwise need to compose a format descriptors using `snprintf`. The individual parts of the format descriptor are passed in distinctly. -.. c:function:: int xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) +.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) :param rolmod: A comma-separated list of field roles and field modifiers :type rolmod: const char * @@ -445,7 +445,7 @@ descriptor are passed in distinctly. :param efmt: Encoding format string, followed by additional arguments :type efmt: const char * :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t :: @@ -453,7 +453,7 @@ descriptor are passed in distinctly. xo_emit_field("T", "Host name is ", NULL, NULL); xo_emit_field("V", "host-name", NULL, NULL, host-name); -.. c:function:: int xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) +.. c:function:: xo_ssize_t xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) :param xop: Handle for modify (or NULL for default handle) :type xop: xo_handle_t \* @@ -466,9 +466,9 @@ descriptor are passed in distinctly. :param efmt: Encoding format string, followed by additional arguments :type efmt: const char * :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t -.. c:function:: int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, va_list vap) +.. c:function:: xo_ssize_t xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, va_list vap) :param xop: Handle for modify (or NULL for default handle) :type xop: xo_handle_t \* @@ -482,7 +482,7 @@ descriptor are passed in distinctly. :type efmt: const char * :param va_list vap: A set of variadic arguments :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted - :rtype: int + :rtype: xo_ssize_t .. index:: xo_attr .. _xo_attr: @@ -505,14 +505,14 @@ 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. -.. c:function:: int xo_attr (const char *name, const char *fmt, ...) +.. c:function:: xo_ssize_t xo_attr (const char *name, const char *fmt, ...) :param name: Attribute name :type name: const char * :param fmt: Attribute value, as variadic arguments :type fmt: const char * :returns: -1 for error, or the number of bytes in the formatted attribute value - :rtype: int + :rtype: xo_ssize_t :: @@ -525,7 +525,7 @@ already emitted in other form. 00:14 -.. c:function:: int xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...) +.. c:function:: xo_ssize_t xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...) :param xop: Handle for modify (or NULL for default handle) :type xop: xo_handle_t \* @@ -533,7 +533,7 @@ already emitted in other form. The `xo_attr_h` function follows the conventions of `xo_attr` but adds an explicit libxo handle. -.. c:function:: int xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap) +.. c:function:: xo_ssize_t xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap) The `xo_attr_h` function follows the conventions of `xo_attr_h` but replaced the variadic list with a variadic pointer. diff --git a/doc/libxo-manual.html b/doc/libxo-manual.html index a10e056b4954..f65bdd18b4ac 100644 --- a/doc/libxo-manual.html +++ b/doc/libxo-manual.html @@ -515,7 +515,7 @@ li.indline1 { } @top-right { - content: "May 2018"; + content: "April 2019"; } @top-center { @@ -22011,7 +22011,7 @@ jQuery(function ($) { -May 21, 2018 +April 2, 2019

libxo: The Easy Way to Generate text, XML, JSON, and HTML output
libxo-manual

diff --git a/doc/xo.rst b/doc/xo.rst index 9475c103b1ba..2556b01f2208 100644 --- a/doc/xo.rst +++ b/doc/xo.rst @@ -75,7 +75,7 @@ prepend data to the XPath values used for HTML output style:: EXAMPLE; #!/bin/sh xo --open top/data - xo --depth 2 '{tag}' value + xo --depth 2 '{:tag}' value xo --close top/data XML: @@ -90,6 +90,84 @@ prepend data to the XPath values used for HTML output style:: } } +When making partial lines of output (where the format string does not +include a newline), use the `--continuation` option to let secondary +invocations know they are adding data to an existing line. + +When emitting a series of objects, use the `--not-first` option to +ensure that any details from the previous object (e.g. commas in JSON) +are handled correctly. + +Use the `--top-wrap` option to ensure any top-level object details are +handled correctly, e.g. wrap the entire output in a top-level set of +braces for JSON output. + + EXAMPLE; + #!/bin/sh + xo --top-wrap --open top/data + xo --depth 2 'First {:tag} ' value1 + xo --depth 2 --continuation 'and then {:tag}\n' value2 + xo --top-wrap --close top/data + TEXT: + First value1 and then value2 + HTML: +
+
First
+
value1
+
+
and then
+
value2
+
+ XML: + + + value1 + value2 + + + JSON: + { + "top": { + "data": { + "tag": "value1", + "tag": "value2" + } + } + } + +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. + +Use the `--open-list` and `--open-instances` to open lists and +instances. Use the `--close-list` and `--close-instances` to close +them. Each of these options take a `name` parameter, providing the +name of the list and instance. + +In the following example, a list named "machine" is created with three +instances: + + opts="--json" + xo $opts --open-list machine + NF= + for name in red green blue; do + xo $opts --depth 1 $NF --open-instance machine + xo $opts --depth 2 "Machine {k:name} has {:memory}\n" $name 55 + xo $opts --depth 1 --close-instance machine + NF=--not-first + done + xo $opts $NF --close-list machine + +The normal `libxo` functions use a state machine to help these +transitions, but since each `xo` command is invoked independent of the +previous calls, the state must be passed in explicitly via these +command line options. + Command Line Options -------------------- @@ -97,15 +175,23 @@ Command Line Options Usage: xo [options] format [fields] --close Close tags for the given path + --close-instance Close an open instance name + --close-list Close an open list name + --continuation OR -C Output belongs on same line as previous output --depth Set the depth for pretty printing --help Display this help text --html OR -H Generate HTML output --json OR -J Generate JSON output --leading-xpath Add a prefix to generated XPaths (HTML) + --not-first Indicate this object is not the first (JSON) --open Open tags for the given path + --open-instance Open an instance given by name + --open-list Open a list given by name + --option -or -O Give formatting options --pretty OR -p Make 'pretty' output (add indent, newlines) --style