From 8daa90e98c625e7920bce78cf8d29bc133b64f54 Mon Sep 17 00:00:00 2001 From: Phil Shafer Date: Wed, 3 Apr 2019 21:47:19 +0000 Subject: [PATCH] Import libxo 1.0.2 --- configure.ac | 2 +- doc/api.rst | 32 +-- doc/libxo-manual.html | 4 +- doc/xo.rst | 88 ++++++- libxo/Makefile.am | 1 + libxo/libxo.c | 341 ++++++++++++++++--------- libxo/xo.h | 38 ++- libxo/xo_attr.3 | 6 +- libxo/xo_buf.h | 7 +- libxo/xo_emit.3 | 6 +- libxo/xo_emit_f.3 | 6 +- libxo/xo_explicit.h | 61 +++++ libxo/xo_finish.3 | 4 +- libxo/xo_flush.3 | 4 +- libxo/xo_open_container.3 | 16 +- libxo/xo_open_list.3 | 32 +-- libxo/xo_open_marker.3 | 8 +- libxo/xo_set_writer.3 | 2 +- tests/core/saved/test_01.J.out | 3 +- tests/core/saved/test_02.J.out | 3 +- tests/core/saved/test_03.J.out | 3 +- tests/core/saved/test_04.J.out | 3 +- tests/core/saved/test_05.J.out | 4 +- tests/core/saved/test_05.JP.out | 3 +- tests/core/saved/test_06.J.out | 3 +- tests/core/saved/test_07.J.out | 3 +- tests/core/saved/test_08.J.out | 3 +- tests/core/saved/test_09.J.out | 3 +- tests/core/saved/test_10.J.out | 3 +- tests/core/saved/test_11.J.out | 3 +- tests/core/saved/test_12.E.err | 4 + tests/core/saved/test_12.E.out | 4 + tests/core/saved/test_12.H.err | 4 + tests/core/saved/test_12.H.out | 2 +- tests/core/saved/test_12.HIPx.err | 4 + tests/core/saved/test_12.HIPx.out | 6 + tests/core/saved/test_12.HP.err | 4 + tests/core/saved/test_12.HP.out | 6 + tests/core/saved/test_12.J.err | 4 + tests/core/saved/test_12.J.out | 3 +- tests/core/saved/test_12.JP.err | 4 + tests/core/saved/test_12.JP.out | 6 +- tests/core/saved/test_12.T.err | 4 + tests/core/saved/test_12.T.out | 1 + tests/core/saved/test_12.X.err | 4 + tests/core/saved/test_12.X.out | 2 +- tests/core/saved/test_12.XP.err | 4 + tests/core/saved/test_12.XP.out | 4 + tests/core/test_12.c | 5 + tests/gettext/po/pig_latin/strerror.po | 4 + tests/gettext/saved/gt_01.J.out | 3 +- tests/gettext/strerror.pot | 4 + tests/xo/Makefile.am | 10 +- tests/xo/saved/xo_01.H.out | 2 +- tests/xo/saved/xo_01.HIPx.out | 4 + tests/xo/saved/xo_01.HP.out | 4 + tests/xo/saved/xo_01.J.out | 2 +- tests/xo/saved/xo_01.JP.out | 2 +- tests/xo/saved/xo_01.T.out | 1 + tests/xo/saved/xo_02.H.err | 25 ++ tests/xo/saved/xo_02.H.out | 1 + tests/xo/saved/xo_02.HIPx.err | 25 ++ tests/xo/saved/xo_02.HIPx.out | 83 ++++++ tests/xo/saved/xo_02.HP.err | 25 ++ tests/xo/saved/xo_02.HP.out | 83 ++++++ tests/xo/saved/xo_02.J.err | 25 ++ tests/xo/saved/xo_02.J.out | 7 + tests/xo/saved/xo_02.JP.err | 25 ++ tests/xo/saved/xo_02.JP.out | 84 ++++++ tests/xo/saved/xo_02.T.err | 25 ++ tests/xo/saved/xo_02.T.out | 14 + tests/xo/saved/xo_02.X.err | 25 ++ tests/xo/saved/xo_02.X.out | 1 + tests/xo/saved/xo_02.XP.err | 25 ++ tests/xo/saved/xo_02.XP.out | 74 ++++++ tests/xo/xo_01.sh | 3 + tests/xo/xo_02.sh | 57 +++++ xo/xo.1 | 11 + xo/xo.c | 120 ++++++++- 79 files changed, 1293 insertions(+), 251 deletions(-) create mode 100644 libxo/xo_explicit.h create mode 100644 tests/xo/saved/xo_02.H.err create mode 100644 tests/xo/saved/xo_02.H.out create mode 100644 tests/xo/saved/xo_02.HIPx.err create mode 100644 tests/xo/saved/xo_02.HIPx.out create mode 100644 tests/xo/saved/xo_02.HP.err create mode 100644 tests/xo/saved/xo_02.HP.out create mode 100644 tests/xo/saved/xo_02.J.err create mode 100644 tests/xo/saved/xo_02.J.out create mode 100644 tests/xo/saved/xo_02.JP.err create mode 100644 tests/xo/saved/xo_02.JP.out create mode 100644 tests/xo/saved/xo_02.T.err create mode 100644 tests/xo/saved/xo_02.T.out create mode 100644 tests/xo/saved/xo_02.X.err create mode 100644 tests/xo/saved/xo_02.X.out create mode 100644 tests/xo/saved/xo_02.XP.err create mode 100644 tests/xo/saved/xo_02.XP.out create mode 100755 tests/xo/xo_02.sh 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