svn commit: r277353 - in head: contrib/libxo contrib/libxo/bin contrib/libxo/doc contrib/libxo/libxo contrib/libxo/packaging contrib/libxo/tests/core contrib/libxo/tests/core/saved contrib/libxo/xo...

Marcel Moolenaar marcel at FreeBSD.org
Mon Jan 19 02:22:05 UTC 2015 

Author: marcel
Date: Mon Jan 19 02:22:03 2015
New Revision: 277353
URL: https://svnweb.freebsd.org/changeset/base/277353

Log:
  Upgrade libxo to 0.2.0.
  
  Obtained from:	https://github.com/Juniper/libxo
  Requested by: Phil Shafer <phil at juniper.net>
  
  Revisions 276253 & 276273 were incorporated into 0.2.0.
  Revision 276260 has been merged-in.

Added:
  head/contrib/libxo/libxo/xo_error.3   (contents, props changed)
  head/contrib/libxo/packaging/libxo.rb.base.in   (contents, props changed)
  head/contrib/libxo/tests/core/saved/test_08.H.err
  head/contrib/libxo/tests/core/saved/test_08.H.out
  head/contrib/libxo/tests/core/saved/test_08.HIPx.err
  head/contrib/libxo/tests/core/saved/test_08.HIPx.out
  head/contrib/libxo/tests/core/saved/test_08.HP.err
  head/contrib/libxo/tests/core/saved/test_08.HP.out
  head/contrib/libxo/tests/core/saved/test_08.J.err
  head/contrib/libxo/tests/core/saved/test_08.J.out
  head/contrib/libxo/tests/core/saved/test_08.JP.err
  head/contrib/libxo/tests/core/saved/test_08.JP.out
  head/contrib/libxo/tests/core/saved/test_08.T.err
  head/contrib/libxo/tests/core/saved/test_08.T.out
  head/contrib/libxo/tests/core/saved/test_08.X.err
  head/contrib/libxo/tests/core/saved/test_08.X.out
  head/contrib/libxo/tests/core/saved/test_08.XP.err
  head/contrib/libxo/tests/core/saved/test_08.XP.out
  head/contrib/libxo/tests/core/saved/test_09.H.err
  head/contrib/libxo/tests/core/saved/test_09.H.out
  head/contrib/libxo/tests/core/saved/test_09.HIPx.err
  head/contrib/libxo/tests/core/saved/test_09.HIPx.out
  head/contrib/libxo/tests/core/saved/test_09.HP.err
  head/contrib/libxo/tests/core/saved/test_09.HP.out
  head/contrib/libxo/tests/core/saved/test_09.J.err
  head/contrib/libxo/tests/core/saved/test_09.J.out
  head/contrib/libxo/tests/core/saved/test_09.JP.err
  head/contrib/libxo/tests/core/saved/test_09.JP.out
  head/contrib/libxo/tests/core/saved/test_09.T.err
  head/contrib/libxo/tests/core/saved/test_09.T.out
  head/contrib/libxo/tests/core/saved/test_09.X.err
  head/contrib/libxo/tests/core/saved/test_09.X.out
  head/contrib/libxo/tests/core/saved/test_09.XP.err
  head/contrib/libxo/tests/core/saved/test_09.XP.out
  head/contrib/libxo/tests/core/test_08.c   (contents, props changed)
  head/contrib/libxo/tests/core/test_09.c   (contents, props changed)
Modified:
  head/contrib/libxo/Makefile.am
  head/contrib/libxo/bin/Zaliases
  head/contrib/libxo/configure.ac
  head/contrib/libxo/doc/libxo.txt
  head/contrib/libxo/libxo/libxo.3
  head/contrib/libxo/libxo/libxo.c
  head/contrib/libxo/libxo/xo.h
  head/contrib/libxo/libxo/xo_attr.3
  head/contrib/libxo/libxo/xo_create.3
  head/contrib/libxo/libxo/xo_emit.3
  head/contrib/libxo/libxo/xo_err.3
  head/contrib/libxo/libxo/xo_finish.3
  head/contrib/libxo/libxo/xo_flush.3
  head/contrib/libxo/libxo/xo_format.5
  head/contrib/libxo/libxo/xo_no_setlocale.3
  head/contrib/libxo/libxo/xo_open_container.3
  head/contrib/libxo/libxo/xo_open_list.3
  head/contrib/libxo/libxo/xo_parse_args.3
  head/contrib/libxo/libxo/xo_set_allocator.3
  head/contrib/libxo/libxo/xo_set_flags.3
  head/contrib/libxo/libxo/xo_set_info.3
  head/contrib/libxo/libxo/xo_set_options.3
  head/contrib/libxo/libxo/xo_set_style.3
  head/contrib/libxo/libxo/xo_set_writer.3
  head/contrib/libxo/libxo/xoconfig.h
  head/contrib/libxo/libxo/xoconfig.h.in
  head/contrib/libxo/libxo/xoversion.h
  head/contrib/libxo/tests/core/Makefile.am
  head/contrib/libxo/tests/core/saved/test_01.H.out
  head/contrib/libxo/tests/core/saved/test_01.HIPx.out
  head/contrib/libxo/tests/core/saved/test_01.HP.out
  head/contrib/libxo/tests/core/saved/test_01.J.out
  head/contrib/libxo/tests/core/saved/test_01.JP.out
  head/contrib/libxo/tests/core/saved/test_01.T.out
  head/contrib/libxo/tests/core/saved/test_01.X.out
  head/contrib/libxo/tests/core/saved/test_01.XP.out
  head/contrib/libxo/tests/core/saved/test_02.J.out
  head/contrib/libxo/tests/core/saved/test_02.JP.out
  head/contrib/libxo/tests/core/saved/test_07.J.out
  head/contrib/libxo/tests/core/saved/test_07.JP.out
  head/contrib/libxo/tests/core/test_01.c
  head/contrib/libxo/tests/core/test_07.c
  head/contrib/libxo/xo/xo.1
  head/contrib/libxo/xo/xo.c
  head/contrib/libxo/xolint/Makefile.am
  head/contrib/libxo/xolint/xolint.1
  head/lib/libxo/Makefile

Modified: head/contrib/libxo/Makefile.am
==============================================================================
--- head/contrib/libxo/Makefile.am	Mon Jan 19 00:33:32 2015	(r277352)
+++ head/contrib/libxo/Makefile.am	Mon Jan 19 02:22:03 2015	(r277353)
@@ -35,6 +35,7 @@ docs:
 
 DIST_FILES_DIR = ~/Dropbox/dist-files/
 GH_PAGES_DIR = gh-pages/
+GH_PAGES_DIR_VER = gh-pages/${PACKAGE_VERSION}
 PACKAGE_FILE = ${PACKAGE_TARNAME}-${PACKAGE_VERSION}.tar.gz
 
 upload: dist upload-docs
@@ -45,10 +46,14 @@ upload-docs: docs
 	@echo "Uploading libxo-manual.html ... "
 	@-[ -d ${GH_PAGES_DIR} ] \
 		&& echo "Updating manual on gh-pages ..." \
+		&& mkdir -p ${GH_PAGES_DIR_VER} \
 		&& cp doc/libxo-manual.html ${GH_PAGES_DIR} \
+		&& cp doc/libxo-manual.html ${GH_PAGES_DIR_VER} \
 		&& (cd ${GH_PAGES_DIR} \
+			&& git add ${PACKAGE_VERSION} \
+			&& git add libxo-manual.html \
 			&& git commit -m 'new docs' \
-                               libxo-manual.html \
+                               libxo-manual.html ${PACKAGE_VERSION} \
 			&& git push origin gh-pages ) ; true
 
 pkgconfigdir=$(libdir)/pkgconfig
@@ -66,7 +71,7 @@ UPDATE_PACKAGE_FILE = \
     -e "s;__SHA256__;SHA256 (textproc/${PACKAGE_FILE}) = $$SHA256;" \
     -e "s;__SIZE__;SIZE (textproc/${PACKAGE_FILE}) = $$SIZE;"
 
-GH_PACKAGING_DIR = packaging/${PACKAGE_VERSION}
+GH_PACKAGING_DIR = ${PACKAGE_VERSION}/packaging
 GH_PAGES_PACKAGE_DIR = ${GH_PAGES_DIR}/${GH_PACKAGING_DIR}
 
 packages:
@@ -75,7 +80,6 @@ packages:
 		&& SHA1="`openssl sha1 ${PACKAGE_FILE} | awk '{print $$2}'`" \
 		&& SHA256="`openssl sha256 ${PACKAGE_FILE} | awk '{print $$2}'`" \
 		&& SIZE="`ls -l ${PACKAGE_FILE} | awk '{print $$5}'`" \
-		&& mkdir -p ${GH_PAGES_PACKAGE_DIR}/freebsd \
 		&& echo "... ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.rb ..." \
 		&& sed ${UPDATE_PACKAGE_FILE} \
 			packaging/${PACKAGE_NAME}.rb.base \
@@ -83,20 +87,10 @@ packages:
 		&& echo "... ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.spec ..." \
 		&& cp packaging/${PACKAGE_NAME}.spec \
 			${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.spec \
-		&& echo "... ${GH_PAGES_PACKAGE_DIR}/freebsd ..." \
-		&& sed ${UPDATE_PACKAGE_FILE} \
-			${srcdir}/packaging/freebsd/distinfo.base \
-			> ${GH_PAGES_PACKAGE_DIR}/freebsd/distinfo \
-		&& cp ${srcdir}/packaging/freebsd/pkg-descr \
-			${GH_PAGES_PACKAGE_DIR}/freebsd/pkg-descr \
-		&& cp ${srcdir}/packaging/freebsd/pkg-plist \
-			${GH_PAGES_PACKAGE_DIR}/freebsd/pkg-plist \
-		&& cp ${srcdir}/packaging/freebsd/pkg-plist \
-			${GH_PAGES_PACKAGE_DIR}/freebsd/pkg-plist \
-		&& cp packaging/freebsd/port-Makefile \
-			${GH_PAGES_PACKAGE_DIR}/freebsd/Makefile \
 		&& (cd ${GH_PAGES_DIR} \
 			&& git add ${GH_PACKAGING_DIR} \
+			&& git add ${GH_PACKAGING_DIR}/libxo.rb \
+                                   ${GH_PACKAGING_DIR}/libxo.spec \
 			&& git commit -m 'new packaging data' \
                                ${GH_PACKAGING_DIR} \
 			&& git push origin gh-pages ) ; true

Modified: head/contrib/libxo/bin/Zaliases
==============================================================================
--- head/contrib/libxo/bin/Zaliases	Mon Jan 19 00:33:32 2015	(r277352)
+++ head/contrib/libxo/bin/Zaliases	Mon Jan 19 02:22:03 2015	(r277353)
@@ -1,5 +1,5 @@
 set top_src=`pwd`
-alias Zautoreconf "(cd $top_src ; autoreconf --install)"
+alias Zautoreconf "(cd $top_src ; autoreconf)"
 
 set opts=' \
 --with-libslax-prefix=/Users/phil/work/root \

Modified: head/contrib/libxo/configure.ac
==============================================================================
--- head/contrib/libxo/configure.ac	Mon Jan 19 00:33:32 2015	(r277352)
+++ head/contrib/libxo/configure.ac	Mon Jan 19 02:22:03 2015	(r277353)
@@ -12,7 +12,7 @@
 #
 
 AC_PREREQ(2.2)
-AC_INIT([libxo], [0.1.6], [phil at juniper.net])
+AC_INIT([libxo], [0.2.0], [phil at juniper.net])
 AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability])
 
 # Support silent build rules.  Requires at least automake-1.11.
@@ -57,8 +57,10 @@ AC_CHECK_FUNCS([getpass])
 AC_CHECK_FUNCS([sysctlbyname])
 AC_CHECK_FUNCS([flock])
 AC_CHECK_FUNCS([asprintf])
+AC_CHECK_FUNCS([__flbf])
 
 AC_CHECK_HEADERS([dlfcn.h])
+AC_CHECK_HEADERS([stdio_ext.h])
 AC_CHECK_HEADERS([tzfile.h])
 AC_CHECK_HEADERS([stdtime/tzfile.h])
 AC_CHECK_FUNCS([dlfunc])
@@ -164,7 +166,6 @@ AC_ARG_ENABLE([libxo-options],
 AC_MSG_RESULT([$LIBXO_OPTS])
 AM_CONDITIONAL([NO_LIBXO_OPTIONS], [test "$LIBXO_OPTS" != "yes"])
 
-
 case $host_os in
      darwin*)
         LIBTOOL=glibtool
@@ -238,6 +239,7 @@ AC_CONFIG_FILES([
   tests/core/Makefile
   tests/xo/Makefile
   packaging/libxo.spec
+  packaging/libxo.rb.base
 ])
 AC_OUTPUT
 

Modified: head/contrib/libxo/doc/libxo.txt
==============================================================================
--- head/contrib/libxo/doc/libxo.txt	Mon Jan 19 00:33:32 2015	(r277352)
+++ head/contrib/libxo/doc/libxo.txt	Mon Jan 19 02:22:03 2015	(r277353)
@@ -12,14 +12,15 @@
 
 libxo - A Library for Generating Text, XML, JSON, and HTML Output
 
-You live in the present, but you want to live in the future.  You'd
-love a flying car, but need to get to work today.  You want to support
-features like XML, JSON, and HTML rendering to allow integration with
-NETCONF, REST, and web browsers, but you need to make text output for
-command line users.  And you don't want multiple code paths that can't
-help but get out of sync.  None of this "if (xml) {... } else {...}"
-logic.  And ifdefs are right out.  But you'd really, really like all
-the fancy features that modern encoding formats can provide.
+You want to prepare for the future, but you need to live in the
+present.  You'd love a flying car, but need to get to work today.  You
+want to support features like XML, JSON, and HTML rendering to allow
+integration with NETCONF, REST, and web browsers, but you need to make
+text output for command line users.  And you don't want multiple code
+paths that can't help but get out of sync.  None of this "if (xml)
+{... } else {...}"  logic.  And ifdefs are right out.  But you'd
+really, really like all the fancy features that modern encoding
+formats can provide.  libxo can help.
 
 The libxo library allows an application to generate text, XML, JSON,
 and HTML output using a common set of function calls.  The application
@@ -83,31 +84,37 @@ The latest release of libxo is available
 
   https://github.com/Juniper/libxo/releases
 
-We are following the branching scheme from 
-^http://nvie.com/posts/a-successful-git-branching-model/^
-which means we will do development under the "develop" branch, and
-release from the master.  To clone a developer tree, run the following
+We are following the branching scheme from
+^http://nvie.com/posts/a-successful-git-branching-model/^ which means
+we will do development under the "develop" branch, and release from
+the "master" branch.  To clone a developer tree, run the following
 command:
 
   git clone https://github.com/Juniper/libxo.git -b develop
 
-We're using semantic release numbering.
+We're using semantic release numbering, as defined in
+^http://semver.org/spec/v2.0.0.html^.
+
+libxo is open source, distributed under the BSD license.  It
+is shipped as part of FreeBSD 11.0.
 
 * Overview
 
 Most unix commands emit text output aimed at humans.  It is designed
-to be parsed and understood by a user.  Humans are gifted at extracted
-details and pattern matching.  Often programmers need to extract
-information from this human-oriented output.  Programmers use tools
-like grep, awk, and regular expressions to ferret out the pieces of
-information they need.  Such solutions are fragile and require
-updates when output contents change or evolve, requiring testing and
-validation.
+to be parsed and understood by a user.  Humans are gifted at
+extracting details and pattern matching in such output.  Often
+programmers need to extract information from this human-oriented
+output.  Programmers use tools like grep, awk, and regular expressions
+to ferret out the pieces of information they need.  Such solutions are
+fragile and require maintenance when output contents change or evolve,
+along with testing and validation.
 
-Modern tool developers favors encoding schemes like XML and JSON,
+Modern tool developers favor encoding schemes like XML and JSON,
 which allow trivial parsing and extraction of data.  Such formats are
 simple, well understood, hierarchical, easily parsed, and often
-integrate easier with common tools and environments.
+integrate easier with common tools and environments.  Changes to
+content can be done in ways that do not break existing users of the
+data, which can reduce maintenance costs and increase feature velocity.
 
 In addition, modern reality means that more output ends up in web
 browsers than in terminals, making HTML output valuable.
@@ -278,7 +285,7 @@ content.  The roles are listed below; on
 |---+--------------+-------------------------------------------------|
 | M | Name         | Description                                     |
 |---+--------------+-------------------------------------------------|
-| D | decoration   | Field is non-text (e.g. colon, comma)           |
+| D | decoration   | Field is non-text (e.g., colon, comma)          |
 | E | error        | Field is an error message                       |
 | L | label        | Field is text that prefixes a value             |
 | N | note         | Field is text that follows a value              |
@@ -321,7 +328,7 @@ the field descriptor, or a printf-style 
 if preceded by a slash ("/"):
 
     xo_emit("{P:        }{Lwc:Cost}{:cost/%u}\n", cost);
-    xo_emit("{P:/30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
+    xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
 
 **** The Title Role ({T:})
 
@@ -333,6 +340,16 @@ if preceded by a slash ("/"):
     xo_emit("{T:Interface Statistics}\n");
     xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
 
+Title fields have an extra convenience feature; if both content and
+format are specified, instead of looking to the argument list for a
+value, the content is used, allowing a mixture of format and content
+within the field descriptor:
+
+    xo_emit("{T:Name/%20s}{T:Count/%6s}\n");
+
+Since the incoming argument is a string, the format must be "%s" or
+something suitable.
+
 **** The Units Role ({U:})
 
 Units are the dimension by which values are measured, such as degrees,
@@ -412,6 +429,7 @@ content emitted for some output styles:
 | d | display      | Only emit field for display styles (text/HTML)  |
 | e | encoding     | Only emit for encoding styles (XML/JSON)        |
 | k | key          | Field is a key, suitable for XPath predicates   |
+| l | leaf-list    | Field is a leaf-list
 | n | no-quotes    | Do not quote the field when using JSON style    |
 | q | quotes       | Quote the field when using JSON style           |
 | w | white space  | A blank (" ") is appended after the label       |
@@ -433,7 +451,7 @@ The colon modifier appends a single colo
       Name:phil
 
 The colon modifier is only used for the TEXT and HTML output
-styles. It is commonly combined with the space modifier ('{w:').
+styles. It is commonly combined with the space modifier ('{w:}').
 It is purely a convenience feature.
 
 **** The Display Modifier ({d:})
@@ -485,6 +503,24 @@ Currently the key modifier is only used 
 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:
+        <user>phil</user>
+        <user>pallavi</user>
+    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
@@ -522,7 +558,7 @@ The white space modifier appends a singl
       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:').
+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
@@ -530,14 +566,15 @@ Note that the sense of the 'w' modifier 
 
 *** Field Formatting
 
-The field format is similar to the format string for printf(3).  It's
-used varies based on the role of the field, but generally is used to
+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 not provided, the format string defaults to "%s".
+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 a
+'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.
 
@@ -557,7 +594,7 @@ argument.  If the width in columns of th
 the minumum 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 is
+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.
@@ -630,8 +667,8 @@ ASCII data, a normal 7-bit ASCII string 
 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, the locale defaults to
-"UTF-8".
+variables is used and if none of the variables are set, the locale
+defaults to "UTF-8".
 
 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)
@@ -676,10 +713,10 @@ columns. 
 
 *** Characters Outside of Field Definitions
 
-Characters in the format string 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 <div> with
-class "text".
+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 <div> with class "text".
 
   EXAMPLE:
       xo_emit("The hat is {:size/%s}.\n", size_val);
@@ -854,7 +891,7 @@ container, a warning will be generated.
 *** Lists and Instances
 
 A list is set of one or more instances that appear under the same
-parent.  The instances contains details about a specific object.  One
+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:
@@ -874,8 +911,8 @@ generation of XML and JSON data.
 
 *** DTRT Mode
 
-Some user may find tracking the names of open containers, lists, and
-instances inconvenient.  libxo offers "Do The Right Thing" mode, where
+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.
@@ -889,10 +926,42 @@ will close the open container, list, or 
     ...
     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 with the
+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");
+    }
+
 ** Handles
 
 libxo uses "handles" to control its rendering functionality.  The
@@ -952,7 +1021,7 @@ be passed NULL to access the default han
 
 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
+when needed, e.g., for daemons that generate multiple streams of
 output.
 
 *** xo_create
@@ -972,7 +1041,7 @@ See also ^styles^ and ^flags^.
 
 By default, libxo writes output to standard output.  A convenience
 function is provided for situations when output should be written to
-different file:
+a different file:
 
     xo_handle_t *xo_create_to_file (FILE *fp, unsigned style,
                                     unsigned flags);
@@ -987,10 +1056,13 @@ which can tailor how libxo writes data. 
 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
 
@@ -1068,7 +1140,7 @@ XML, JSON, and HTML output.  Text output
 
 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 warning enabled,
+operations, or with arguments to functions.  Without warnings enabled,
 such conditions are ignored.
 
 Warnings allow developers to debug their interaction with libxo.
@@ -1178,6 +1250,13 @@ parameter passed to xo_attr_hv().
     XML:
         <login-time seconds="1408336270">00:14</login-time>
 
+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
@@ -1188,6 +1267,10 @@ 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
@@ -1250,7 +1333,7 @@ styles.  Calls must be made to open and 
 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 strong
+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.
 
@@ -1314,6 +1397,16 @@ Following the call to xo_parse_args, the
 remaining arguments in a normal manner.  See ^command-line-arguments^
 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.
+
+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.
+
 *** Field Information (xo_info_t) @info@
 
 HTML data can include additional information in attributes that
@@ -1353,7 +1446,7 @@ known to the application:
     ...
     xo_set_info(NULL, info, info_count);
 
-Third, the emitting of info must be triggered with the XOF_INFO flag
+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.
 
@@ -1405,6 +1498,10 @@ Complete HTML output can be generated wi
 
     % env LIBXO_OPTIONS=HXI 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
@@ -1435,6 +1532,20 @@ message associated with either "errno" o
         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::
+        <error><message>Does not compute</message></error>
+    JSON::
+        "error": { "message": "Does not compute" }
+
 *** xo_no_setlocale
 
 libxo automatically initializes the locale based on setting of the
@@ -1580,7 +1691,7 @@ and errors, warning, or informational me
 | -X         | Extract samples from xolint, suitable for testing |
 |------------+---------------------------------------------------|
 
-Output message contain the source filename and line number, the
+The output message will contain the source filename and line number, the
 class of the message, the message, and, if -p is given, the
 line that contains the error:
 
@@ -1627,6 +1738,88 @@ libxo is an effort to mix the best aspec
 FreeBSD in a seemless way, allowing commands to make printf-like
 output calls without needing to care how the output is rendered.
 
+*** Did the complex semantics of format strings evolve over time?
+
+The history is both long and short: libxo's functionality is based
+on what JUNOS does in a data modeling language called ODL (output
+definition language).  In JUNOS, all subcomponents generate XML,
+which is feed to the CLI, where data from the ODL files tell is
+how to render that XML into text.  ODL might had a set of tags
+like:
+
+     tag docsis-state {
+         help "State of the DOCSIS interface";
+         type string;
+     }
+
+     tag docsis-mode {
+         help "DOCSIS mode (2.0/3.0) of the DOCSIS interface";
+         type string;
+     }
+
+     tag docsis-upstream-speed {
+         help "Operational upstream speed of the interface";
+         type string;
+     }
+
+     tag downstream-scanning {
+         help "Result of scanning in downstream direction";
+         type string;
+     }
+
+     tag ranging {
+         help "Result of ranging action";
+         type string;
+     }
+
+     tag signal-to-noise-ratio {
+         help "Signal to noise ratio for all channels";
+         type string;
+     }
+
+     tag power {
+         help "Operational power of the signal on all channels";
+         type string;
+     }
+
+     format docsis-status-format {
+         picture "
+   State   : @, Mode: @, Upstream speed: @
+   Downstream scanning: @, Ranging: @
+   Signal to noise ratio: @
+   Power: @
+";
+         line {
+             field docsis-state;
+             field docsis-mode;
+             field docsis-upstream-speed;
+             field downstream-scanning;
+             field ranging;
+             field signal-to-noise-ratio;
+             field power;
+         }
+     }
+
+These tag definitions are compiled into field definitions
+that are triggered when matching XML elements are seen.  ODL
+also supports other means of defining output.
+
+The roles and modifiers describe these details.
+
+In moving these ideas to bsd, two things had to happen: the
+formatting had to happen at the source since BSD won't have
+a JUNOS-like CLI to do the rendering, and we can't depend on
+external data models like ODL, which was seen as too hard a
+sell to the BSD community.
+
+The results were that the xo_emit strings are used to encode the
+roles, modifiers, names, and formats.  They are dense and a bit
+cryptic, but not so unlike printf format strings that developers will
+be lost.
+
+libxo is a new implementation of these ideas and is distinct from
+the previous implementation in JUNOS.
+
 *** What makes a good field name?
 
 To make useful, consistent field names, follow these guidelines:
@@ -1660,7 +1853,7 @@ Nothing's worse than writing expressions
     }
 
 Find someone else who is expressing similar data and follow their
-field's and hierarchy.  Remember the quote is not "Consistency is the
+fields and hierarchy.  Remember the quote is not "Consistency is the
 hobgoblin of little minds", but "A foolish consistency is the
 hobgoblin of little minds".
 = Think about your users
@@ -1670,7 +1863,7 @@ content with xo_attr() calls (^xo_attr^)
 (^e-modifier^) to make the data useful.
 = Don't use an arbitrary number postfix
 What does "errors2" mean?  No one will know.  "errors-after-restart"
-would be a better choice.  Think of you users, and think of the
+would be a better choice.  Think of your users, and think of the
 future.  If you make "errors2", the next guy will happily make
 "errors3" and before you know it, someone will be asking what's the
 difference between errors37 and errors63.
@@ -1689,7 +1882,7 @@ After using "xolint" to find errors in y
 "xolint -V" to spell check your field names and to detect different
 names for the same data.  "dropped-short" and "dropped-too-short" are
 both reasonable names, but using them both will lead users to ask the
-difference between the two fields.  If there isn't a difference,
+difference between the two fields.  If there is no difference,
 use only one of the field names.  If there is a difference, change the
 names to make that difference more obvious.
 

Modified: head/contrib/libxo/libxo/libxo.3
==============================================================================
--- head/contrib/libxo/libxo/libxo.3	Mon Jan 19 00:33:32 2015	(r277352)
+++ head/contrib/libxo/libxo/libxo.3	Mon Jan 19 02:22:03 2015	(r277353)
@@ -7,7 +7,7 @@
 .\" # LICENSE.
 .\" # Phil Shafer, July 2014
 .\" 
-.Dd July, 2014
+.Dd December 8, 2014
 .Dt LIBXO 3
 .Os
 .Sh NAME
@@ -19,58 +19,82 @@
 .In libxo/xo.h
 .Sh DESCRIPTION
 The functions defined in
-.Lb libxo
+.Nm
 are used to generate a choice of
 .Em TEXT ,
 .Em XML ,
 .Em JSON ,
 or
 .Em HTML
-output.  A common set of functions are used, with
+output.
+A common set of functions are used, with
 command line switches passed to the library to control the details of
 the output.
 .Pp
-Most commands emit text output aimed at humans.  It is designed
-to be parsed and understood by a user.  Humans are gifted at extracted
-details and pattern matching.  Often programmers need to extract
-information from this human-oriented output.  Programmers use tools
-like grep, awk, and regular expressions to ferret out the pieces of
-information they need.  Such solutions are fragile and require
+Most commands emit text output aimed at humans.
+It is designed
+to be parsed and understood by a user.
+Humans are gifted at extracting
+details and pattern matching.
+Often programmers need to extract
+information from this human-oriented output.
+Programmers use tools
+like
+.Xr grep 1 ,
+.Xr awk 1 ,
+and regular expressions to ferret out the pieces of
+information they need.
+Such solutions are fragile and require
 updates when output contents change or evolve, requiring testing and
 validation.
 .Pp
-Modern tool developers favors encoding schemes like XML and JSON,
-which allow trivial parsing and extraction of data.  Such formats are
+Modern tool developers favor encoding schemes like XML and JSON,
+which allow trivial parsing and extraction of data.
+Such formats are
 simple, well understood, hierarchical, easily parsed, and often
 integrate easier with common tools and environments.
 .Pp
 In addition, modern reality means that more output ends up in web
 browsers than in terminals, making HTML output valuable.
 .Pp
-.Em libxo
+.Nm
 allows a single set of function calls in source code to generate
-traditional text output, as well as XML and JSON formatted data.  HTML
+traditional text output, as well as XML and JSON formatted data.
+HTML
 can also be generated; "<div>" elements surround the traditional text
 output, with attributes that detail how to render the data.
 .Pp
-There are four encoding styles supported by libxo: TEXT, HTML, JSON,
-and XML.  JSON and XML are suitable for encoding data, while TEXT and
-HTML are suited for display to the user.  TEXT output can be display
+There are four encoding styles supported by
+.Nm :
+TEXT, HTML, JSON,
+and XML.
+JSON and XML are suitable for encoding data, while TEXT and
+HTML are suited for display to the user.
+TEXT output can be display
 on a terminal session, allowing compatibility with traditional usage.
 HTML can be matched with a small CSS file to permit rendering in any
-HTML5 browser.  XML output is suitable for tools like XPath and
-protocols like NETCONF.  JSON output can be used for RESTful APIs.
+HTML5 browser.
+XML output is suitable for tools like XPath and
+protocols like NETCONF.
+JSON output can be used for RESTful APIs.
 .Pp
 The
-.Em libxo
+.Nm
 library allows an application to generate text, XML, JSON,
-and HTML output using a common set of function calls.  The application
-decides at run time which output style should be produced.  The
+and HTML output using a common set of function calls.
+The application
+decides at run time which output style should be produced.
+The
 application calls a function
-.Fn xo_emit
+.Xr xo_emit 3
 to product output that is
-described in a format string.  A "field descriptor" tells libxo what
-the field is and what it means.  Each field descriptor is placed in
+described in a format string.
+A
+.Dq field descriptor
+tells
+.Nm
+what the field is and what it means.
+Each field descriptor is placed in
 braces with a printf-like format string:
 .Bd -literal -offset indent
     xo_emit(" {:lines/%7ju} {:words/%7ju} "
@@ -79,55 +103,199 @@ braces with a printf-like format string:
 .Ed
 .Pp
 Each field can have a role, with the 'value' role being the default,
-and the role tells libxo how and when to render that field, as well as
+and the role tells
+.Nm
+how and when to render that field, as well as
 a
-.Xr printf 3 -like
+.Xr printf 3 Ns -like
 format string.
 .Pp
 Output
 can then be generated in various style, using the "--libxo" option.
 .Sh DEFAULT HANDLE
-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
+Handles give an abstraction for
+.Nm
+that encapsulates the state of a
+stream of output.
+Handles have the data type "xo_handle_t" and are
 opaque to the caller.
-
+.Pp
 The library has a default handle that is automatically initialized.
 By default, this handle will send text style output to standard output.
-The xo_set_style and xo_set_flags functions can be used to change this
+The
+.Xr xo_set_style 3
+and
+.Xr xo_set_flags 3
+functions can be used to change this
 behavior.
-
-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.
-
+.Pp
+Many
+.Nm
+functions take a handle as their first parameter; most that
+do not use the default handle.
+Any function taking a handle can
+be passed
+.Dv NULL
+to access the default handle.
+.Pp
 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
+when needed, e.g., for daemons that generate multiple streams of
 output.
+.Sh FUNCTION OVERVIEW
+The
+.Nm
+library includes the following functions:
+.Bl -tag -width "xo_close_container_hd"
+.It Sy "Function               Description"
+.It Fn xo_attr
+.It Fn xo_attr_h
+.It Fn xo_attr_hv
+Allows the caller to emit XML attributes with the next open element.
+.It Fn xo_create
+.It Fn xo_create_to_file
+Allow the caller to create a new handle.
+Note that
+.Nm
+has a default handle that allows the caller to avoid use of an
+explicitly created handle.
+Only callers writing to files other than
+.Dv stdout
+would need to call
+.Fn xo_create .
+.It Fn xo_destroy
+Frees any resources associated with the handle, including the handle
+itself.
+.It Fn xo_emit
+.It Fn xo_emit_h
+.It Fn xo_emit_hv
+Emit formatted output.
+The
+.Fa fmt
+string controls the conversion of the remaining arguments into
+formatted output.
+See
+.Xr xo_format 5
+for details.
+.It Fn xo_warn
+.It Fn xo_warnx
+.It Fn xo_warn_c
+.It Fn xo_warn_hc
+.It Fn xo_err
+.It Fn xo_errc
+.It Fn xo_errx
+.It Fn xo_message
+.It Fn xo_message_c
+.It Fn xo_message_hc
+.It Fn xo_message_hcv
+These functions are meant to be compatible with their standard libc namesakes.
+.It Fn xo_finish
+.It Fn xo_finish_h
+Flush output, close open construct, and complete any pending
+operations.
+.It Fn xo_flush
+.It Fn xo_flush_h
+Allow the caller to flush any pending output for a handle.
+.It Fn xo_no_setlocale
+Direct
+.Nm
+to avoid initializing the locale.
+This function should be called before any other
+.Nm
+function is called.
+.It Fn xo_open_container
+.It Fn xo_open_container_h
+.It Fn xo_open_container_hd
+.It Fn xo_open_container_d
+.It Fn xo_close_container
+.It Fn xo_close_container_h
+.It Fn xo_close_container_hd
+.It Fn xo_close_container_d
+Containers a singleton levels of hierarchy, typically used to organize
+related content.
+.It Fn xo_open_list_h
+.It Fn xo_open_list
+.It Fn xo_open_list_hd
+.It Fn xo_open_list_d
+.It Fn xo_open_instance_h
+.It Fn xo_open_instance
+.It Fn xo_open_instance_hd
+.It Fn xo_open_instance_d
+.It Fn xo_close_instance_h
+.It Fn xo_close_instance
+.It Fn xo_close_instance_hd
+.It Fn xo_close_instance_d
+.It Fn xo_close_list_h
+.It Fn xo_close_list
+.It Fn xo_close_list_hd
+.It Fn xo_close_list_d
+Lists are levels of hierarchy that can appear multiple times within
+the same parent.
+Two calls are needed to encapsulate them, one for
+the list and one for each instance of that list.
+Typically
+.Fn xo_open_list
+and
+.Fn xo_close_list
+are called outside a
+for-loop, where
+.Fn xo_open_instance
+it called at the top of the loop, and
+.Fn xo_close_instance
+is called at the bottom of the loop.
+.It Fn xo_parse_args
+Inspects command line arguments for directions to
+.Nm .
+This function should be called before
+.Va argv
+is inspected by the application.
+.It Fn xo_set_allocator
+Instructs
+.Nm
+to use an alternative memory allocator and deallocator.
+.It Fn xo_set_flags
+.It Fn xo_clear_flags
+Change the flags set for a handle.
+.It Fn xo_set_info
+Provides additional information about elements for use with HTML
+rendering.
+.It Fn xo_set_options
+Changes formatting options used by handle.
+.It Fn xo_set_style
+.It Fn xo_set_style_name
+Changes the output style used by a handle.
+.It Fn xo_set_writer
+Instructs
+.Nm
+to use an alternative set of low-level output functions.
+.El
 .Sh ADDITIONAL DOCUMENTATION
-.Pp
 Complete documentation can be found on github:
 .Bd -literal -offset indent
 http://juniper.github.io/libxo/libxo-manual.html
 .Ed
 .Pp
-libxo lives on github as:
+.Nm
+lives on github as:
 .Bd -literal -offset indent
 https://github.com/Juniper/libxo
 .Ed
 .Pp
-The latest release of libxo is available at:
+The latest release of
+.Nm
+is available at:
 .Bd -literal -offset indent
 https://github.com/Juniper/libxo/releases
 .Ed
 .Sh SEE ALSO
+.Xr xo 1 ,
+.Xr xolint 1 ,
 .Xr xo_attr 3 ,
 .Xr xo_create 3 ,
 .Xr xo_emit 3 ,
 .Xr xo_err 3 ,
 .Xr xo_finish 3 ,
 .Xr xo_flush 3 ,
-.Xr xo_format 5 ,
 .Xr xo_no_setlocale 3 ,
 .Xr xo_open_container 3 ,
 .Xr xo_open_list 3 ,
@@ -138,12 +306,11 @@ https://github.com/Juniper/libxo/release
 .Xr xo_set_options 3 ,
 .Xr xo_set_style 3 ,
 .Xr xo_set_writer 3 ,
-.Xr xo 1 ,
-and
-.Xr xolint 1 .
+.Xr xo_format 5
 .Sh HISTORY
 The
-.Fa libxo
-library was added in FreeBSD 11.0.
+.Nm

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***

More information about the svn-src-head mailing list