Index: vendor/Juniper/libxo/1.3.0/Makefile.am
===================================================================
--- vendor/Juniper/libxo/1.3.0/Makefile.am (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/Makefile.am (revision 354426)
@@ -0,0 +1,144 @@
+#
+# $Id$
+#
+# Copyright 2014, Juniper Networks, Inc.
+# All rights reserved.
+# This SOFTWARE is licensed under the LICENSE provided in the
+# ../Copyright file. By downloading, installing, copying, or otherwise
+# using the SOFTWARE, you agree to be bound by the terms of that
+# LICENSE.
+
+ACLOCAL_AMFLAGS = -I m4
+
+SUBDIRS = libxo xo xopo xolint xohtml tests doc encoder
+bin_SCRIPTS=libxo-config
+dist_doc_DATA = Copyright
+
+EXTRA_DIST = \
+ libxo-config.in \
+ warnings.mk \
+ README.md \
+ INSTALL.md \
+ packaging/libxo.spec
+
+.PHONY: test tests
+
+test tests:
+ @(cd tests ; ${MAKE} test)
+
+errors:
+ @(cd tests/errors ; ${MAKE} test)
+
+docs:
+ @(cd doc ; ${MAKE} 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
+
+XOHTML_FILES = \
+ ${top_srcdir}/xohtml/xohtml.css \
+ ${top_srcdir}/xohtml/xohtml.js \
+ ${top_srcdir}/xohtml/external/jquery.js \
+ ${top_srcdir}/xohtml/external/jquery.qtip.css \
+ ${top_srcdir}/xohtml/external/jquery.qtip.js
+
+upload: dist upload-docs upload-xohtml-files
+ @echo "Remember to run:"
+ @echo " gt tag ${PACKAGE_VERSION}"
+
+upload-docs: docs upload-html
+
+upload-html:
+ @echo "Uploading html ... "
+ @-[ -d ${GH_PAGES_DIR} -a -d doc/html ] \
+ && echo "Updating html on gh-pages ..." \
+ && mkdir -p ${GH_PAGES_DIR_VER}/html \
+ && cp doc/top-link.html ${GH_PAGES_DIR}/libxo.html \
+ && cp -r doc/html/* ${GH_PAGES_DIR_VER}/html/ \
+ && (cd ${GH_PAGES_DIR} \
+ && git add libxo.html \
+ && git add ${PACKAGE_VERSION}/html \
+ && git commit -m 'new docs' \
+ libxo.html ${PACKAGE_VERSION}/html \
+ && git push origin gh-pages ) ; true
+
+upload-xohtml-files:
+ @echo "Uploading xohtml files ... "
+ @-[ -d ${GH_PAGES_DIR} ] \
+ && echo "Updating xohtml files on gh-pages ..." \
+ && mkdir -p ${GH_PAGES_DIR_VER}/xohtml \
+ && cp ${XOHTML_FILES} ${GH_PAGES_DIR_VER}/xohtml \
+ && (cd ${GH_PAGES_DIR} \
+ && git add ${PACKAGE_VERSION}/xohtml \
+ && git commit -m 'new xohtml files' \
+ ${PACKAGE_VERSION}/xohtml \
+ && git push origin gh-pages ) ; true
+
+pkgconfigdir=$(libdir)/pkgconfig
+pkgconfig_DATA = packaging/${PACKAGE_NAME}.pc
+
+get-wiki:
+ git clone https://github.com/Juniper/${PACKAGE_NAME}.wiki.git wiki
+
+get-gh-pages:
+ git clone https://github.com/Juniper/${PACKAGE_NAME}.git \
+ gh-pages -b gh-pages
+
+UPDATE_PACKAGE_FILE = \
+ -e "s;__SHA1__;$$SHA1;" \
+ -e "s;__SHA256__;SHA256 (textproc/${PACKAGE_FILE}) = $$SHA256;" \
+ -e "s;__SIZE__;SIZE (textproc/${PACKAGE_FILE}) = $$SIZE;"
+
+GH_PACKAGING_DIR = ${PACKAGE_VERSION}/packaging
+GH_PAGES_PACKAGE_DIR = ${GH_PAGES_DIR}/${GH_PACKAGING_DIR}
+
+packages:
+ @-[ -d ${GH_PAGES_DIR} ] && set -x \
+ && echo "Updating packages on gh-pages ..." \
+ && mkdir -p ${GH_PAGES_DIR}/${GH_PACKAGING_DIR} \
+ && SHA1="`openssl sha1 ${PACKAGE_FILE} | awk '{print $$2}'`" \
+ && SHA256="`openssl sha256 ${PACKAGE_FILE} | awk '{print $$2}'`" \
+ && SIZE="`ls -l ${PACKAGE_FILE} | awk '{print $$5}'`" \
+ && echo "... ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.rb ..." \
+ && sed ${UPDATE_PACKAGE_FILE} \
+ packaging/${PACKAGE_NAME}.rb.base \
+ > ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.rb \
+ && echo "... ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.spec ..." \
+ && cp packaging/${PACKAGE_NAME}.spec \
+ ${GH_PAGES_PACKAGE_DIR}/${PACKAGE_NAME}.spec \
+ && (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
+
+ANALYZE_DIR = ~/trash/libxo
+ANALYZE_CMD = scan-build-mp-3.6
+
+analyze:
+ ${MAKE} clean
+ ${ANALYZE_CMD} -o ${ANALYZE_DIR} ${MAKE}
+
+SANIFLAGS=-fno-omit-frame-pointer -g -O2
+
+sanitize-address:
+ ${MAKE} clean
+ ${MAKE} CFLAGS="-fsanitize=address ${SANIFLAGS}"
+ ${MAKE} install
+ ${MAKE} test
+
+sanitize-undefined:
+ ${MAKE} clean
+ ${MAKE} CFLAGS="-fsanitize=undefined ${SANIFLAGS}"
+ ${MAKE} install
+ ${MAKE} test
+
+sanitize-memory:
+ ${MAKE} clean
+ ${MAKE} CFLAGS="-fsanitize=memory ${SANIFLAGS}"
+ ${MAKE} install
+ ${MAKE} test
Property changes on: vendor/Juniper/libxo/1.3.0/Makefile.am
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+FreeBSD=%H
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+text/plain
\ No newline at end of property
Index: vendor/Juniper/libxo/1.3.0/README.md
===================================================================
--- vendor/Juniper/libxo/1.3.0/README.md (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/README.md (revision 354426)
@@ -0,0 +1,67 @@
+libxo
+=====
+
+libxo - A Library for Generating Text, XML, JSON, and HTML Output
+
+The libxo 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
+application calls a function "xo_emit" to product output that is
+described in a format string. A "field descriptor" tells libxo what
+the field is and what it means.
+
+Imagine a simplified ``wc`` that emits its output fields in a single
+xo_emit call:
+
+```
+ xo_emit(" {:lines/%7ju/%ju} {:words/%7ju/%ju} "
+ "{:characters/%7ju/%ju}{d:filename/%s}\n",
+ linect, wordct, charct, file);
+```
+
+Output can then be generated in various style, using the "--libxo"
+option:
+
+```
+ % wc /etc/motd
+ 25 165 1140 /etc/motd
+ % wc --libxo xml,pretty,warn /etc/motd
+
+
+ /etc/motd
+ 25
+ 165
+ 1140
+
+
+ % wc --libxo json,pretty,warn /etc/motd
+ {
+ "wc": {
+ "file": [
+ {
+ "filename": "/etc/motd",
+ "lines": 25,
+ "words": 165,
+ "characters": 1140
+ }
+ ]
+ }
+ }
+ % wc --libxo html,pretty,warn /etc/motd
+
+
+
25
+
+
165
+
+
1140
+
+
/etc/motd
+
+```
+
+View the beautiful documentation at:
+
+http://juniper.github.io/libxo/libxo-manual.html
+
+[![Analytics](https://ga-beacon.appspot.com/UA-56056421-1/Juniper/libxo/Readme)](https://github.com/Juniper/libxo)
Index: vendor/Juniper/libxo/1.3.0/configure.ac
===================================================================
--- vendor/Juniper/libxo/1.3.0/configure.ac (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/configure.ac (revision 354426)
@@ -0,0 +1,500 @@
+#
+# $Id$
+#
+# See ./INSTALL for more info
+#
+
+#
+# Release numbering: even numbered dot releases are official ones, and
+# odd numbers are development ones. The svn version of this file will
+# only (ONLY!) ever (EVER!) contain odd numbers, so I'll always know if
+# a particular user has the dist or svn release.
+#
+
+AC_PREREQ(2.2)
+AC_INIT([libxo], [1.3.0], [phil@juniper.net])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability])
+
+# Support silent build rules. Requires at least automake-1.11.
+# Disable with "configure --disable-silent-rules" or "make V=1"
+m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
+
+AC_PROG_CC
+AC_PROG_INSTALL
+AC_CONFIG_MACRO_DIR([m4])
+AC_PROG_LN_S
+
+# Must be after AC_PROG_AR
+LT_INIT([dlopen shared])
+
+AC_PATH_PROG(BASENAME, basename, /usr/bin/basename)
+AC_PATH_PROG(BISON, bison, /usr/bin/bison)
+AC_PATH_PROG(CAT, cat, /bin/cat)
+AC_PATH_PROG(CHMOD, chmod, /bin/chmod)
+AC_PATH_PROG(CP, cp, /bin/cp)
+AC_PATH_PROG(DIFF, diff, /usr/bin/diff)
+AC_PATH_PROG(MKDIR, mkdir, /bin/mkdir)
+AC_PATH_PROG(MV, mv, /bin/mv)
+AC_PATH_PROG(RM, rm, /bin/rm)
+AC_PATH_PROG(SED, sed, /bin/sed)
+
+AC_STDC_HEADERS
+
+# Checks for typedefs, structures, and compiler characteristics.
+AC_C_INLINE
+AC_TYPE_SIZE_T
+
+# Checks for library functions.
+AC_FUNC_ALLOCA
+AC_FUNC_MALLOC
+AC_FUNC_REALLOC
+AC_CHECK_FUNCS([bzero memmove strchr strcspn strerror strspn])
+AC_CHECK_FUNCS([sranddev srand strlcpy])
+AC_CHECK_FUNCS([fdopen getrusage])
+AC_CHECK_FUNCS([gettimeofday ctime])
+AC_CHECK_FUNCS([getpass])
+AC_CHECK_FUNCS([getprogname])
+AC_CHECK_FUNCS([sysctlbyname])
+AC_CHECK_FUNCS([flock])
+AC_CHECK_FUNCS([asprintf])
+AC_CHECK_FUNCS([__flbf])
+AC_CHECK_FUNCS([sysctlbyname])
+
+
+AC_CHECK_HEADERS([dlfcn.h])
+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])
+
+AC_CHECK_HEADERS([sys/time.h])
+AC_CHECK_HEADERS([ctype.h errno.h stdio.h stdlib.h])
+AC_CHECK_HEADERS([string.h sys/param.h unistd.h ])
+AC_CHECK_HEADERS([sys/sysctl.h])
+AC_CHECK_HEADERS([threads.h])
+AC_CHECK_HEADERS([monitor.h])
+
+dnl humanize_number(3) is a great function, but it's not standard.
+dnl Note Macosx has the function in libutil.a but doesn't ship the
+dnl header file, so I'll need to carry my own implementation. See:
+dnl https://devforums.apple.com/thread/271121
+AC_CHECK_HEADERS([libutil.h])
+AC_CHECK_LIB([util], [humanize_number],
+ [HAVE_HUMANIZE_NUMBER=$ac_cv_header_libutil_h],
+ [HAVE_HUMANIZE_NUMBER=no])
+
+AC_MSG_RESULT(humanize_number results: :${HAVE_HUMANIZE_NUMBER}:${ac_cv_header_libutil_h}:)
+
+if test "$HAVE_HUMANIZE_NUMBER" = "yes"; then
+ AC_DEFINE([HAVE_HUMANIZE_NUMBER], [1], [humanize_number(3)])
+fi
+
+AM_CONDITIONAL([HAVE_HUMANIZE_NUMBER], [test "$HAVE_HUMANIZE_NUMBER" = "yes"])
+
+AC_ARG_ENABLE([gettext],
+ [ --disable-gettext Turn off support for gettext],
+ [GETTEXT_ENABLE=$enableval],
+ [GETTEXT_ENABLE=yes])
+
+dnl Looking for gettext(), assumably in libintl
+AC_ARG_WITH(gettext,
+ [ --with-gettext=[PFX] Specify location of gettext installation],
+ [GETTEXT_PREFIX=$withval],
+ [GETTEXT_PREFIX=/usr],
+)
+
+HAVE_GETTEXT=no
+
+if test "$GETTEXT_ENABLE" != "no"; then
+
+ AC_MSG_CHECKING([gettext in ${GETTEXT_PREFIX}])
+
+ _save_cflags="$CFLAGS"
+ CFLAGS="$CFLAGS -I${GETTEXT_PREFIX}/include -L${GETTEXT_PREFIX}/lib -Werror -lintl"
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[#include ]
+ [int main() {char *cp = dgettext(NULL, "xx"); return 0; }]])],
+ [HAVE_GETTEXT=yes],
+ [HAVE_GETTEXT=no])
+ CFLAGS="$_save_cflags"
+
+ AC_MSG_RESULT([$HAVE_GETTEXT])
+
+ if test "$HAVE_GETTEXT" != "yes"; then
+ GETTEXT_PREFIX=/opt/local
+ AC_MSG_CHECKING([gettext in ${GETTEXT_PREFIX}])
+
+ _save_cflags="$CFLAGS"
+ CFLAGS="$CFLAGS -I${GETTEXT_PREFIX}/include -L${GETTEXT_PREFIX}/lib -Werror -lintl"
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[#include ]
+ [int main() {char *cp = dgettext(NULL, "xx"); return 0; }]])],
+ [HAVE_GETTEXT=yes],
+ [HAVE_GETTEXT=no])
+ CFLAGS="$_save_cflags"
+
+ AC_MSG_RESULT([$HAVE_GETTEXT])
+ fi
+
+ if test "$HAVE_GETTEXT" != "yes"; then
+ GETTEXT_PREFIX=/usr/local
+ AC_MSG_CHECKING([gettext in ${GETTEXT_PREFIX}])
+
+ _save_cflags="$CFLAGS"
+ CFLAGS="$CFLAGS -I${GETTEXT_PREFIX}/include -L${GETTEXT_PREFIX}/lib -Werror -lintl"
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[#include ]
+ [int main() {char *cp = dgettext(NULL, "xx"); return 0; }]])],
+ [HAVE_GETTEXT=yes],
+ [HAVE_GETTEXT=no])
+ CFLAGS="$_save_cflags"
+
+ AC_MSG_RESULT([$HAVE_GETTEXT])
+ fi
+fi
+
+if test "$HAVE_GETTEXT" = "yes"; then
+ AC_DEFINE([HAVE_GETTEXT], [1], [gettext(3)])
+ GETTEXT_CFLAGS="-I${GETTEXT_PREFIX}/include"
+ GETTEXT_LIBS="-L${GETTEXT_PREFIX}/lib -lintl"
+else
+ GETTEXT_PREFIX=none
+ GETTEXT_CFLAGS=
+ GETTEXT_LIBS=
+fi
+AC_SUBST(GETTEXT_CFLAGS)
+AC_SUBST(GETTEXT_LIBS)
+
+GETTEXT_LIBDIR=${GETTEXT_PREFIX}/lib
+AC_SUBST(GETTEXT_LIBDIR)
+if test -x ${GETTEXT_PREFIX}/bin/msgfmt ; then
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/bin
+elif test -x ${GETTEXT_PREFIX}/local/bin/msgfmt ; then
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/local/bin
+else
+ AC_MSG_NOTICE("could not find msgfmt tool")
+ # Use a (bad) fall back value
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/bin
+fi
+AC_SUBST(GETTEXT_BINDIR)
+
+AM_CONDITIONAL([HAVE_GETTEXT], [test "$HAVE_GETTEXT" = "yes"])
+
+dnl Looking for how to do thread-local variables
+AC_ARG_WITH(threads,
+ [ --with-threads=[STYLE] Specify style of thread-local support (none)],
+ [THREAD_LOCAL=$withval],
+ [THREAD_LOCAL=unknown],
+)
+
+AC_MSG_CHECKING([thread-locals are ${THREAD_LOCAL}])
+
+if test "$THREAD_LOCAL" = "unknown"; then
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[]
+ [__thread int foo; int main() { foo++; return foo; }]])],
+ [THREAD_LOCAL=before],
+ [THREAD_LOCAL=unknown])
+
+ AC_MSG_RESULT([$THREAD_LOCAL])
+fi
+
+if test "$THREAD_LOCAL" = "unknown"; then
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[]
+ [int __thread foo; int main() { foo++; return foo; }]])],
+ [THREAD_LOCAL=after],
+ [THREAD_LOCAL=unknown])
+ AC_MSG_RESULT([$THREAD_LOCAL])
+fi
+
+if test "$THREAD_LOCAL" = "unknown"; then
+ AC_LINK_IFELSE([AC_LANG_SOURCE([[]
+ [__declspec(int) foo; int main() { foo++; return foo; }]])],
+ [THREAD_LOCAL=declspec],
+ [THREAD_LOCAL=unknown])
+ AC_MSG_RESULT([$THREAD_LOCAL])
+fi
+
+if test "$THREAD_LOCAL" != "unknown"; then
+ AC_DEFINE_UNQUOTED([HAVE_THREAD_LOCAL],
+ THREAD_LOCAL_${THREAD_LOCAL}, [thread-local setting])
+fi
+
+dnl Looking for libcrypto....
+AC_CHECK_LIB([crypto], [MD5_Init])
+AM_CONDITIONAL([HAVE_LIBCRYPTO], [test "$HAVE_LIBCRYPTO" != "no"])
+
+AC_CHECK_MEMBER([struct sockaddr_un.sun_len],
+ [HAVE_SUN_LEN=yes ;
+ AC_DEFINE([HAVE_SUN_LEN], [1], [Have struct sockaddr_un.sun_len])],
+ [HAS_SUN_LEN=no], [[#include ]])
+
+AC_CHECK_DECLS([__isthreaded], [], [], [#include ])
+HAVE_ISTHREADED=${ac_cv_have_decl___isthreaded}
+
+dnl
+dnl Some packages need to be checked against version numbers so we
+dnl define a function here for later use
+dnl
+AC_DEFUN([VERSION_TO_NUMBER],
+[`$1 | sed -e 's/lib.* //' | awk 'BEGIN { FS = "."; } { printf "%d", ([$]1 * 1000 + [$]2) * 1000 + [$]3;}'`])
+
+LIBSLAX_CONFIG_PREFIX=""
+LIBSLAX_SRC=""
+
+AC_ARG_WITH(libslax-prefix,
+ [ --with-libslax-prefix=[PFX] Specify location of libslax config],
+ LIBSLAX_CONFIG_PREFIX=$withval
+)
+
+AC_MSG_CHECKING(for libslax)
+if test "x$LIBSLAX_CONFIG_PREFIX" != "x"
+then
+ SLAX_CONFIG=${LIBSLAX_CONFIG_PREFIX}/bin/slax-config
+else
+ SLAX_CONFIG=slax-config
+fi
+
+dnl
+dnl make sure slax-config is executable,
+dnl test version and init our variables
+dnl
+
+if ${SLAX_CONFIG} --libs > /dev/null 2>&1
+then
+ LIBSLAX_VERSION=`$SLAX_CONFIG --version`
+ SLAX_BINDIR="`$SLAX_CONFIG --bindir | head -1`"
+ SLAX_OXTRADOCDIR="`$SLAX_CONFIG --oxtradoc | head -1`"
+ AC_MSG_RESULT($LIBSLAX_VERSION found)
+ HAVE_OXTRADOC=yes
+else
+ LIBSLAX_VERSION=
+ SLAX_BINDIR=
+ SLAX_OXTRADOCDIR=
+ AC_MSG_RESULT([no])
+ HAVE_OXTRADOC=no
+fi
+AM_CONDITIONAL([HAVE_OXTRADOC], [test "$HAVE_OXTRADOC" != "no"])
+
+AC_SUBST(SLAX_BINDIR)
+AC_SUBST(SLAX_OXTRADOCDIR)
+
+AC_MSG_CHECKING([whether to build with warnings])
+AC_ARG_ENABLE([warnings],
+ [ --enable-warnings Turn on compiler warnings],
+ [LIBXO_WARNINGS=$enableval],
+ [LIBXO_WARNINGS=no])
+AC_MSG_RESULT([$LIBXO_WARNINGS])
+AM_CONDITIONAL([LIBXO_WARNINGS_HIGH], [test "$LIBXO_WARNINGS" != "no"])
+
+AC_MSG_CHECKING([whether to build with debugging])
+AC_ARG_ENABLE([debug],
+ [ --enable-debug Turn on debugging],
+ [LIBXO_DEBUG=yes; AC_DEFINE([LIBXO_DEBUG], [1], [Enable debugging])],
+ [LIBXO_DEBUG=no])
+AC_MSG_RESULT([$LIBXO_DEBUG])
+AM_CONDITIONAL([LIBXO_DEBUG], [test "$LIBXO_DEBUG" != "no"])
+
+AC_MSG_CHECKING([whether to use int return codes])
+AC_ARG_ENABLE([int-return-codes],
+ [ --enable-int-return-codes Use int return codes (instead of ssize_t)],
+ [USE_INT_RETURN_CODES=yes; AC_DEFINE([USE_INT_RETURN_CODES], [1], [Use int return codes])],
+ [USE_INT_RETURN_CODES=no])
+AC_MSG_RESULT([$USE_INT_RETURN_CODES])
+
+AC_MSG_CHECKING([whether to build with text-only rendering])
+AC_ARG_ENABLE([text-only],
+ [ --enable-text-only Turn on text-only rendering],
+ [LIBXO_TEXT_ONLY=yes; AC_DEFINE([LIBXO_TEXT_ONLY], [1], [Enable text-only rendering])],
+ [LIBXO_TEXT_ONLY=no])
+AC_MSG_RESULT([$LIBXO_TEXT_ONLY])
+AM_CONDITIONAL([LIBXO_TEXT_ONLY], [test "$LIBXO_TEXT_ONLY" != "no"])
+
+AC_MSG_CHECKING([whether to build with local wcwidth implementation])
+AC_ARG_ENABLE([wcwidth],
+ [ --disable-wcwidth Disable local wcwidth implementation],
+ [LIBXO_WCWIDTH=$enableval],
+ [LIBXO_WCWIDTH=yes])
+AC_MSG_RESULT([$LIBXO_WCWIDTH])
+if test "${LIBXO_WCWIDTH}" != "no"; then
+ AC_DEFINE([LIBXO_WCWIDTH], [1], [Enable local wcwidth implementation])
+fi
+
+AC_MSG_CHECKING([retain hash bucket size])
+AC_ARG_WITH(retain-size,
+ [ --with-retain-size=[DIR] Specify retain hash bucket size (in bits)],
+ [XO_RETAIN_SIZE=$withval],
+ [XO_RETAIN_SIZE=default]
+)
+
+AC_MSG_RESULT([$XO_RETAIN_SIZE])
+if test "${XO_RETAIN_SIZE}" != "default"; then
+ AC_DEFINE_UNQUOTED([XO_RETAIN_SIZE], ${XO_RETAIN_SIZE}, [Retain hash bucket size])
+fi
+
+AC_CHECK_LIB([m], [lrint])
+AM_CONDITIONAL([HAVE_LIBM], [test "$HAVE_LIBM" != "no"])
+
+AC_MSG_CHECKING([compiler for gcc])
+HAVE_GCC=no
+if test "${CC}" != ""; then
+ HAVE_GCC=`${CC} --version 2>&1 | grep GCC`
+ if test "${HAVE_GCC}" != ""; then
+ HAVE_GCC=yes
+ else
+ HAVE_GCC=no
+ fi
+fi
+AC_MSG_RESULT([$HAVE_GCC])
+AM_CONDITIONAL([HAVE_GCC], [test "$HAVE_GCC" = "yes"])
+
+AC_MSG_CHECKING([whether to build with printflike])
+AC_ARG_ENABLE([printflike],
+ [ --enable-printflike Enable use of GCC __printflike attribute],
+ [HAVE_PRINTFLIKE=yes;
+ AC_DEFINE([HAVE_PRINTFLIKE], [1], [Support printflike])],
+ [HAVE_PRINTFLIKE=no])
+AC_MSG_RESULT([$HAVE_PRINTFLIKE])
+AM_CONDITIONAL([HAVE_PRINTFLIKE], [test "$HAVE_PRINTFLIKE" != ""])
+
+AC_MSG_CHECKING([whether to build with LIBXO_OPTIONS])
+AC_ARG_ENABLE([libxo-options],
+ [ --disable-libxo-options Turn off support for LIBXO_OPTIONS],
+ [LIBXO_OPTS=$enableval],
+ [LIBXO_OPTS=yes])
+AC_MSG_RESULT([$LIBXO_OPTS])
+AM_CONDITIONAL([NO_LIBXO_OPTIONS], [test "$LIBXO_OPTS" != "yes"])
+
+case $host_os in
+ darwin*)
+ LIBTOOL=glibtool
+ XO_LIBEXT=dylib
+ ;;
+ Linux*|linux*)
+ CFLAGS="-D_GNU_SOURCE $CFLAGS"
+ LDFLAGS=-ldl
+ XO_LIBEXT=so
+ ;;
+ cygwin*|CYGWIN*)
+ LDFLAGS=-no-undefined
+ XO_LIBEXT=ddl
+ ;;
+esac
+
+case $prefix in
+ NONE)
+ prefix=/usr/local
+ ;;
+esac
+
+XO_LIBS=-lxo
+XO_SRCDIR=${srcdir}
+XO_LIBDIR=${libdir}
+XO_BINDIR=${bindir}
+XO_INCLUDEDIR=${includedir}
+XO_CFLAGS="${CFLAGS}"
+
+AC_SUBST(XO_LIBS)
+AC_SUBST(XO_SRCDIR)
+AC_SUBST(XO_LIBDIR)
+AC_SUBST(XO_BINDIR)
+AC_SUBST(XO_INCLUDEDIR)
+AC_SUBST(XO_LIBEXT)
+AC_SUBST(XO_CFLAGS)
+
+AC_ARG_WITH(encoder-dir,
+ [ --with-encoder-dir=[DIR] Specify location of encoder libraries],
+ [XO_ENCODERDIR=$withval],
+ [XO_ENCODERDIR=$libdir/libxo/encoder]
+)
+AC_SUBST(XO_ENCODERDIR)
+
+AC_ARG_WITH(share-dir,
+ [ --with-share-dir=[DIR] Specify location of shared files],
+ [XO_SHAREDIR=$withval],
+ [XO_SHAREDIR=$datarootdir/libxo]
+)
+XO_SHAREDIR=`echo $XO_SHAREDIR | sed "s;\\${prefix};$prefix;"`
+AC_SUBST(XO_SHAREDIR)
+
+dnl for the spec file
+RELDATE=`date +'%Y-%m-%d%n'`
+AC_SUBST(RELDATE)
+
+AC_MSG_RESULT(Using configure dir $ac_abs_confdir)
+
+if test -d $ac_abs_confdir/.git ; then
+ extra=`git branch | awk '/\*/ { print $2 }'`
+ if test "$extra" != "" -a "$extra" != "master"
+ then
+ LIBXO_VERSION_EXTRA="-git-$extra"
+ fi
+fi
+
+LIBXO_VERSION=$PACKAGE_VERSION
+LIBXO_VERSION_NUMBER=VERSION_TO_NUMBER(echo $PACKAGE_VERSION)
+AC_SUBST(LIBXO_VERSION)
+AC_SUBST(LIBXO_VERSION_NUMBER)
+AC_SUBST(LIBXO_VERSION_EXTRA)
+
+AC_DEFINE_UNQUOTED(LIBXO_VERSION, ["$LIBXO_VERSION"],
+ [Version number as dotted value])
+AC_DEFINE_UNQUOTED(LIBXO_VERSION_NUMBER, [$LIBXO_VERSION_NUMBER],
+ [Version number as a number])
+AC_DEFINE_UNQUOTED(LIBXO_VERSION_STRING, ["$LIBXO_VERSION_NUMBER"],
+ [Version number as string])
+AC_DEFINE_UNQUOTED(LIBXO_VERSION_EXTRA, ["$LIBXO_VERSION_EXTRA"],
+ [Version number extra information])
+
+AC_CONFIG_HEADERS([libxo/xo_config.h])
+AC_CONFIG_FILES([
+ Makefile
+ libxo-config
+ xohtml/xohtml.sh
+ libxo/Makefile
+ libxo/add.man
+ encoder/Makefile
+ encoder/cbor/Makefile
+ encoder/csv/Makefile
+ encoder/test/Makefile
+ xo/Makefile
+ xolint/Makefile
+ xohtml/Makefile
+ xopo/Makefile
+ packaging/libxo.pc
+ doc/Makefile
+ doc/top-link.html
+ tests/Makefile
+ tests/core/Makefile
+ tests/gettext/Makefile
+ tests/xo/Makefile
+ packaging/libxo.spec
+ packaging/libxo.rb.base
+])
+AC_OUTPUT
+
+AC_MSG_NOTICE([summary of build options:
+
+ libxo version: ${VERSION} ${LIBXO_VERSION_EXTRA}
+ host type: ${host} / ${host_os}
+ install prefix: ${prefix}
+ srcdir: ${XO_SRCDIR}
+ libdir: ${XO_LIBDIR}
+ bindir: ${XO_BINDIR}
+ includedir: ${XO_INCLUDEDIR}
+ share dir: ${XO_SHAREDIR}
+ extensions dir: ${XO_ENCODERDIR}
+ oxtradoc dir: ${SLAX_OXTRADOCDIR}
+
+ compiler: ${CC} (${HAVE_GCC:-no})
+ compiler flags: ${CFLAGS}
+ library types: Shared=${enable_shared}, Static=${enable_static}
+
+ warnings: ${LIBXO_WARNINGS:-no}
+ debug: ${LIBXO_DEBUG:-no}
+ printf-like: ${HAVE_PRINTFLIKE:-no}
+ libxo-options: ${LIBXO_OPTS:-no}
+ text-only: ${LIBXO_TEXT_ONLY:-no}
+ gettext: ${HAVE_GETTEXT:-no} (${GETTEXT_PREFIX})
+ isthreaded: ${HAVE_ISTHREADED:-no}
+ thread-local: ${THREAD_LOCAL:-no}
+ local wcwidth: ${LIBXO_WCWIDTH:-no}
+ retain size: ${XO_RETAIN_SIZE:-no}
+])
Index: vendor/Juniper/libxo/1.3.0/doc/Makefile.am
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/Makefile.am (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/Makefile.am (revision 354426)
@@ -0,0 +1,29 @@
+#
+# $Id$
+#
+# Copyright 2014, Juniper Networks, Inc.
+# All rights reserved.
+# This SOFTWARE is licensed under the LICENSE provided in the
+# ../Copyright file. By downloading, installing, copying, or otherwise
+# using the SOFTWARE, you agree to be bound by the terms of that
+# LICENSE.
+
+doc docs: xolint.rst html
+
+#
+# The contents of xolint.rst is generated based on xolint.pl, since we
+# really want this to be self-documenting. But readthedocs.org needs this
+# data to be _in_ repo. So we generate this file on command only, and
+# the developer needs to commit any changes.
+#
+
+xolint.rst: ${top_srcdir}/xolint/xolint.pl
+ perl ${top_srcdir}/xolint/xolint.pl -D > ${top_srcdir}/doc/xolint.rst
+
+SPHINX = python3 -msphinx
+
+html sphinx sphinx-html:
+ ${SPHINX} -M html ${srcdir} . -N -E
+
+singlehtml:
+ ${SPHINX} -M singlehtml ${srcdir} . -N -E
Property changes on: vendor/Juniper/libxo/1.3.0/doc/Makefile.am
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+FreeBSD=%H
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+text/plain
\ No newline at end of property
Index: vendor/Juniper/libxo/1.3.0/doc/api.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/api.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/api.rst (revision 354426)
@@ -0,0 +1,1620 @@
+.. index:: API
+
+The libxo API
+=============
+
+This section gives details about the functions in libxo, how to call
+them, and the actions they perform.
+
+.. index:: Handles
+.. _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`.
+
+.. index:: xo_create
+
+xo_create
+~~~~~~~~~
+
+.. c:function:: xo_handle_t *xo_create (xo_style_t style, xo_xof_flags_t flags)
+
+ The `xo_create` function allocates a new handle which can be passed
+ to further libxo function calls. The `xo_handle_t` structure is
+ opaque.
+
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
+ :return: New libxo handle
+ :rtype: xo_handle_t \*
+
+ ::
+
+ EXAMPLE:
+ xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN | XOF_PRETTY);
+ ....
+ xo_emit_h(xop, "testing\n");
+
+ See also :ref:`output-styles` and :ref:`flags`.
+
+.. index:: xo_create_to_file
+.. index:: XOF_CLOSE_FP
+
+xo_create_to_file
+~~~~~~~~~~~~~~~~~
+
+.. c:function::
+ xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, unsigned flags)
+
+ The `xo_create_to_file` function is aconvenience function is
+ provided for situations when output should be written to a different
+ file, rather than the default of standard output.
+
+ The `XOF_CLOSE_FP` flag can be set on the returned handle to trigger a
+ call to fclose() for the FILE pointer when the handle is destroyed,
+ avoiding the need for the caller to perform this task.
+
+ :param fp: FILE to use as base for this handle
+ :type fp: FILE *
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
+ :return: New libxo handle
+ :rtype: xo_handle_t \*
+
+.. index:: xo_set_writer
+.. index:: xo_write_func_t
+.. index:: xo_close_func_t
+.. index:: xo_flush_func_t
+
+xo_set_writer
+~~~~~~~~~~~~~
+
+.. c:function::
+ 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)
+
+ The `xo_set_writer` function allows custom functions which can
+ tailor how libxo writes data. The `opaque` argument is recorded and
+ passed back to the functions, allowing the function to acquire
+ context information. The *write_func* function writes data to the
+ output stream. The *close_func* function can release this opaque
+ data and any other resources as needed. The *flush_func* function
+ is called to flush buffered data associated with the opaque object.
+
+ :param xop: Handle to modify (or NULL for default handle)
+ :type xop: xo_handle_t *
+ :param opaque: Pointer to opaque data passed to the given functions
+ :type opaque: void *
+ :param xo_write_func_t write_func: New write function
+ :param xo_close_func_t close_func: New close function
+ :param xo_flush_func_t flush_func: New flush function
+ :returns: void
+
+.. index:: xo_get_style
+
+xo_get_style
+~~~~~~~~~~~~
+
+.. c:function:: xo_style_t xo_get_style(xo_handle_t *xop)
+
+ Use the `xo_get_style` function to find the current output style for
+ a given handle. To use the default handle, pass a `NULL` handle.
+
+ :param xop: Handle to interrogate (or NULL for default handle)
+ :type xop: xo_handle_t *
+ :returns: Output style (XO_STYLE\_*)
+ :rtype: xo_style_t
+
+ ::
+
+ EXAMPLE::
+ style = xo_get_style(NULL);
+
+.. index:: XO_STYLE_TEXT
+.. index:: XO_STYLE_XML
+.. index:: XO_STYLE_JSON
+.. index:: XO_STYLE_HTML
+
+.. _output-styles:
+
+Output Styles (XO_STYLE\_\*)
+++++++++++++++++++++++++++++
+
+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
+ =============== =========================
+
+The "XML", "JSON", and "HTML" output styles all use the UTF-8
+character encoding. "TEXT" using locale-based encoding.
+
+.. index:: xo_set_style
+
+xo_set_style
+~~~~~~~~~~~~
+
+.. c:function:: void xo_set_style(xo_handle_t *xop, xo_style_t style)
+
+ The `xo_set_style` function is used to change the output style
+ setting for a handle. To use the default handle, pass a `NULL`
+ handle.
+
+ :param xop: Handle to modify
+ :type xop: xo_handle_t *
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :returns: void
+
+ ::
+
+ EXAMPLE:
+ xo_set_style(NULL, XO_STYLE_XML);
+
+.. index:: xo_set_style_name
+
+xo_set_style_name
+~~~~~~~~~~~~~~~~~
+
+.. c:function:: int xo_set_style_name (xo_handle_t *xop, const char *style)
+
+ The `xo_set_style_name` function can be used to set the style based
+ on a name encoded as a string: The name can be any of the supported
+ styles: "text", "xml", "json", or "html".
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param style: Text name of the style
+ :type style: const char \*
+ :returns: zero for success, non-zero for error
+ :rtype: int
+
+ ::
+
+ EXAMPLE:
+ xo_set_style_name(NULL, "html");
+
+.. index:: xo_set_flags
+
+xo_set_flags
+~~~~~~~~~~~~
+
+.. c:function:: void xo_set_flags(xo_handle_t *xop, xo_xof_flags_t flags)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param xo_xof_flags_t flags: Flags to add for the handle
+ :returns: void
+
+ Use the `xo_set_flags` function to turn on flags for a given libxo
+ handle. To use the default handle, pass a `NULL` handle.
+
+ ::
+
+ EXAMPLE:
+ xo_set_flags(NULL, XOF_PRETTY | XOF_WARN);
+
+.. index:: Flags; XOF_*
+.. index:: XOF_CLOSE_FP
+.. index:: XOF_COLOR
+.. index:: XOF_COLOR_ALLOWED
+.. index:: XOF_DTRT
+.. index:: XOF_INFO
+.. index:: XOF_KEYS
+.. index:: XOF_NO_ENV
+.. index:: XOF_NO_HUMANIZE
+.. index:: XOF_PRETTY
+.. index:: XOF_UNDERSCORES
+.. index:: XOF_UNITS
+.. index:: XOF_WARN
+.. index:: XOF_WARN_XML
+.. index:: XOF_XPATH
+.. index:: XOF_COLUMNS
+.. index:: XOF_FLUSH
+
+.. _flags:
+
+Flags (XOF\_\*)
++++++++++++++++
+
+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 :ref:`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 :ref:`field-information` 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
+
+.. index:: xo_clear_flags
+
+xo_clear_flags
+++++++++++++++
+
+.. c:function:: void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param xo_xof_flags_t flags: Flags to clear for the handle
+ :returns: void
+
+ Use the `xo_clear_flags` function to turn off the given flags in a
+ specific handle. To use the default handle, pass a `NULL` handle.
+
+.. index:: xo_set_options
+
+xo_set_options
+++++++++++++++
+
+.. c:function:: int xo_set_options (xo_handle_t *xop, const char *input)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param input: string containing options to set
+ :type input: const char *
+ :returns: zero for success, non-zero for error
+ :rtype: int
+
+ The `xo_set_options` function accepts a comma-separated list of
+ output styles and modifier flags and enables them for a specific
+ handle. The options are identical to those listed in
+ :ref:`options`. To use the default handle, pass a `NULL` handle.
+
+.. index:: xo_destroy
+
+xo_destroy
+++++++++++
+
+.. c:function:: void xo_destroy(xo_handle_t *xop)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: void
+
+ 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.
+
+.. index:: xo_emit
+
+Emitting Content (xo_emit)
+--------------------------
+
+The functions in this section are used to emit output.
+
+The "fmt" argument is a string containing field descriptors as
+specified in :ref:`format-strings`. The use of a handle is optional and
+`NULL` can be passed to access the internal "default" handle. See
+:ref:`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`.
+
+.. 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: xo_ssize_t
+
+.. 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: xo_ssize_t
+
+.. 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: xo_ssize_t
+
+.. index:: xo_emit_field
+
+Single Field Emitting Functions (xo_emit_field)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The functions in this section can also make output, but only make a
+single field at a time. 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.
+
+.. 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 *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :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: xo_ssize_t
+
+ ::
+
+ EXAMPLE::
+ xo_emit_field("T", "Host name is ", NULL, NULL);
+ xo_emit_field("V", "host-name", NULL, NULL, host-name);
+
+.. 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 \*
+ :param rolmod: A comma-separated list of field roles and field modifiers
+ :type rolmod: const char *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :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: xo_ssize_t
+
+.. 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 \*
+ :param rolmod: A comma-separated list of field roles and field modifiers
+ :type rolmod: const char *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :param efmt: Encoding format string
+ :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: xo_ssize_t
+
+.. index:: xo_attr
+.. _xo_attr:
+
+Attributes (xo_attr)
+~~~~~~~~~~~~~~~~~~~~
+
+The functions in this section emit an XML attribute with the given name
+and value. This only affects the XML output style.
+
+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`.
+
+All attributes recorded via `xo_attr` are 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.
+
+.. 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: xo_ssize_t
+
+ ::
+
+ 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
+
+
+.. 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 \*
+
+ The `xo_attr_h` function follows the conventions of `xo_attr` but
+ adds an explicit libxo handle.
+
+.. 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.
+
+.. index:: xo_flush
+
+Flushing Output (xo_flush)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: xo_ssize_t xo_flush (void)
+
+ :returns: -1 for error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ libxo buffers data, both for performance and consistency, but also
+ to allow for the proper function of various advanced features. At
+ various times, the caller may wish to flush any data buffered within
+ the library. The `xo_flush` call is used for this.
+
+ Calling `xo_flush` also triggers the flush function associated with
+ the handle. For the default handle, this is equivalent to
+ "fflush(stdio);".
+
+.. c:function:: xo_ssize_t xo_flush_h (xo_handle_t *xop)
+
+ :param xop: Handle for flush (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: -1 for error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_flush_h` function follows the conventions of `xo_flush`,
+ but adds an explicit libxo handle.
+
+.. index:: xo_finish
+.. index:: xo_finish_atexit
+.. index:: atexit
+
+Finishing Output (xo_finish)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the program is ready to exit or close a handle, a call to
+`xo_finish` or `xo_finish_h` is required. This flushes any buffered
+data, closes open libxo constructs, and completes any pending
+operations.
+
+Calling this function is vital to the proper operation of libxo,
+especially for the non-TEXT output styles.
+
+.. c:function:: xo_ssize_t xo_finish (void)
+
+ :returns: -1 on error, or the number of bytes flushed
+ :rtype: xo_ssize_t
+
+.. c:function:: xo_ssize_t xo_finish_h (xo_handle_t *xop)
+
+ :param xop: Handle for finish (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: -1 on error, or the number of bytes flushed
+ :rtype: xo_ssize_t
+
+.. c:function:: void xo_finish_atexit (void)
+
+ The `xo_finish_atexit` function is suitable for use with
+ :manpage:`atexit(3)` to ensure that `xo_finish` is called
+ on the default handle when the application exits.
+
+.. index:: UTF-8
+.. index:: xo_open_container
+.. index:: xo_close_container
+
+Emitting Hierarchy
+------------------
+
+libxo represents two types of hierarchy: containers and lists. A
+container appears once under a given parent where a list consists of
+instances that can appear multiple times. A container is used to hold
+related fields and to give the data organization and scope.
+
+.. index:: YANG
+
+.. admonition:: YANG Terminology
+
+ libxo uses terminology from YANG (:RFC:`7950`), the data modeling
+ language for NETCONF: container, list, leaf, and leaf-list.
+
+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.
+
+.. index:: Containers
+
+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 and organize 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. To close a level, use the
+xo_close_container() or xo_close_container_h() functions.
+
+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.
+
+.. c:function:: xo_ssize_t xo_open_container (const char *name)
+
+ :param name: Name of the container
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ 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.
+
+.. c:function:: xo_ssize_t xo_open_container_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_container_h` function adds a `handle` parameter.
+
+.. c:function:: xo_ssize_t xo_close_container (const char *name)
+
+ :param name: Name of the container
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+.. c:function:: xo_ssize_t xo_close_container_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_container_h` function adds a `handle` parameter.
+
+Use the :index:`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 to record an XPath value when the
+:index:`XOF_XPATH` flag is set.
+
+::
+
+ 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");
+ TEXT:
+ my-host.example.org
+ XML:
+
+
+ my-host.example.org
+
+
+ JSON:
+ "top" : {
+ "system" : {
+ "host-name": "my-host.example.org"
+ }
+ }
+ HTML:
+
my-host.example.org
+
+.. index:: xo_open_instance
+.. index:: xo_close_instance
+.. index:: xo_open_list
+.. index:: xo_close_list
+
+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.
+
+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("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.
+
+Opening Lists
++++++++++++++
+
+.. c:function:: xo_ssize_t xo_open_list (const char *name)
+
+ :param name: Name of the list
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_list` function open a list of instances.
+
+.. c:function:: xo_ssize_t xo_open_list_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+Closing Lists
++++++++++++++
+
+.. c:function:: xo_ssize_t xo_close_list (const char *name)
+
+ :param name: Name of the list
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_list` function closes a list of instances.
+
+.. c:function:: xo_ssize_t xo_close_list_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_container_h` function adds a `handle` parameter.
+
+Opening Instances
++++++++++++++++++
+
+.. c:function:: xo_ssize_t xo_open_instance (const char *name)
+
+ :param name: Name of the instance (same as the list name)
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_instance` function open a single instance.
+
+.. c:function:: xo_ssize_t xo_open_instance_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_instance_h` function adds a `handle` parameter.
+
+Closing Instances
++++++++++++++++++
+
+.. c:function:: xo_ssize_t xo_close_instance (const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_instance` function closes an open instance.
+
+.. c:function:: xo_ssize_t xo_close_instance_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_instance_h` function adds a `handle` parameter.
+
+ ::
+
+ 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",
+ }
+ ]
+
+Markers
+~~~~~~~
+
+Markers are used to protect and restore the state of open hierarchy
+constructs (containers, lists, or instances). 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::
+
+ EXAMPLE:
+ for (i = 0; fish[i]; i++) {
+ xo_open_instance("fish");
+ xo_open_marker("fish-guts");
+ dump_fish_details(i);
+ xo_close_marker("fish-guts");
+ }
+
+.. c:function:: xo_ssize_t xo_open_marker(const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_marker` function records the current state of open tags
+ in order for `xo_close_marker` to close them at some later point.
+
+.. c:function:: xo_ssize_t xo_open_marker_h(const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_marker_h` function adds a `handle` parameter.
+
+.. c:function:: xo_ssize_t xo_close_marker(const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_marker` function closes any open containers, lists, or
+ instances as needed to return to the state recorded when
+ `xo_open_marker` was called with the matching name.
+
+.. c:function:: xo_ssize_t xo_close_marker(const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_marker_h` function adds a `handle` parameter.
+
+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);
+
+.. index:: 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_d("top");
+ ...
+ xo_close_container_d();
+
+This also works for lists and instances::
+
+ xo_open_list_d("item");
+ for (...) {
+ xo_open_instance_d("item");
+ xo_emit(...);
+ xo_close_instance_d();
+ }
+ xo_close_list_d();
+
+.. index:: XOF_WARN
+
+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.
+
+Support Functions
+-----------------
+
+.. index:: xo_parse_args
+.. _xo_parse_args:
+
+Parsing Command-line Arguments (xo_parse_args)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: int xo_parse_args (int argc, char **argv)
+
+ :param int argc: Number of arguments
+ :param argv: Array of argument strings
+ :return: -1 on error, or the number of remaining arguments
+ :rtype: int
+
+ 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 is 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 :ref:`options` for a
+ description of valid arguments.
+
+.. index:: xo_set_program
+
+xo_set_program
+~~~~~~~~~~~~~~
+
+.. c:function:: void xo_set_program (const char *name)
+
+ :param name: Name to use as the program name
+ :type name: const char *
+ :returns: void
+
+ The `xo_set_program` function sets the 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::
+
+ EXAMPLE:
+ 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.
+
+.. index:: xo_set_version
+
+xo_set_version
+~~~~~~~~~~~~~~
+
+.. c:function:: void xo_set_version (const char *version)
+
+ :param name: Value to use as the version string
+ :type name: const char *
+ :returns: void
+
+ 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.
+
+.. c:function:: void xo_set_version_h (xo_handle_t *xop, const char *version)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_set_version` function adds a `handle` parameter.
+
+.. index:: --libxo
+.. index:: XOF_INFO
+.. index:: xo_info_t
+
+.. _field-information:
+
+Field Information (xo_info_t)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+
+.. c:function:: void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+ :param infop: Array of information structures
+ :type infop: xo_info_t *
+ :returns: void
+
+.. index:: xo_set_allocator
+.. index:: xo_realloc_func_t
+.. index:: xo_free_func_t
+
+Memory Allocation
+~~~~~~~~~~~~~~~~~
+
+The `xo_set_allocator` function allows libxo to be used in
+environments where the standard :manpage:`realloc(3)` and
+:manpage:`free(3)` functions are not appropriate.
+
+.. c:function:: void xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func)
+
+ :param xo_realloc_func_t realloc_func: Allocation function
+ :param xo_free_func_t free_func: Free function
+
+ *realloc_func* should expect the same arguments as
+ :manpage:`realloc(3)` and return a pointer to memory following the
+ same convention. *free_func* will receive the same argument as
+ :manpage:`free(3)` and should release it, as appropriate for the
+ environment.
+
+By default, the standard :manpage:`realloc(3)` and :manpage:`free(3)`
+functions are used.
+
+.. index:: --libxo
+
+.. _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`" command-line option preferable in most situations.
+
+.. index:: xo_warn
+.. index:: xo_err
+.. index:: xo_errx
+.. index:: xo_message
+
+Errors, Warnings, and Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many programs make use of the standard library functions
+:manpage:`err(3)` and :manpage:`warn(3)` 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);
+
+.. index:: xo_error
+
+xo_error
+~~~~~~~~
+
+.. c:function:: void xo_error (const char *fmt, ...)
+
+ :param fmt: Format string
+ :type fmt: const char *
+ :returns: void
+
+ 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" }
+
+.. index:: xo_no_setlocale
+.. index:: Locale
+
+xo_no_setlocale
+~~~~~~~~~~~~~~~
+
+.. c:function:: void xo_no_setlocale (void)
+
+ 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.
+
+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.
+
+.. _Enterprise IDs:
+ 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
+:ref:`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.
+
+.. _syslog-details:
+
+Priority, Facility, and Flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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. :manpage:`login(1)`)
+ LOG_AUTHPRIV As LOG_AUTH, but logged to a privileged file
+ LOG_CRON The cron daemon: :manpage:`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 :manpage:`ipfw(4)`
+ LOG_SYSLOG Messages generated internally by :manpage:`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 logging behaviors:
+
+ ============ ====================================================
+ Flag Description
+ ============ ====================================================
+ LOG_CONS If syslogd fails, attempt to write to /dev/console
+ LOG_NDELAY Open the connection to :manpage:`syslogd(8)` immediately
+ LOG_PERROR Write the message also to standard error output
+ LOG_PID Log the process id with each message
+ ============ ====================================================
+
+.. index:: xo_syslog
+
+xo_syslog
+~~~~~~~~~
+
+.. c:function:: void xo_syslog (int pri, const char *name, const char *fmt, ...)
+
+ :param int pri: syslog priority
+ :param name: Name of the syslog event
+ :type name: const char *
+ :param fmt: Format string, followed by arguments
+ :type fmt: const char *
+ :returns: void
+
+ 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
+~~~~~~~~~~~~~~~~~
+
+.. index:: xo_vsyslog
+
+xo_vsyslog
+++++++++++
+
+.. c:function:: void xo_vsyslog (int pri, const char *name, const char *fmt, va_list vap)
+
+ :param int pri: syslog priority
+ :param name: Name of the syslog event
+ :type name: const char *
+ :param fmt: Format string
+ :type fmt: const char *
+ :param va_list vap: Variadic argument list
+ :returns: void
+
+ xo_vsyslog is identical in function to xo_syslog, but takes the set of
+ arguments using a va_list::
+
+ EXAMPLE:
+ 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);
+ }
+
+.. index:: xo_open_log
+
+xo_open_log
++++++++++++
+
+.. c:function:: void xo_open_log (const char *ident, int logopt, int facility)
+
+ :param indent:
+ :type indent: const char *
+ :param int logopt: Bit field containing logging options
+ :param int facility:
+ :returns: void
+
+ xo_open_log functions similar to :manpage:`openlog(3)`, allowing
+ customization of the program name, the log facility number, and the
+ additional option flags described in :ref:`syslog-details`.
+
+.. index:: xo_close_log
+
+xo_close_log
+++++++++++++
+
+.. c:function:: void xo_close_log (void)
+
+ The `xo_close_log` function is similar to :manpage:`closelog(3)`,
+ closing the log file and releasing any associated resources.
+
+.. index:: xo_set_logmask
+
+xo_set_logmask
+++++++++++++++
+
+.. c:function:: int xo_set_logmask (int maskpri)
+
+ :param int maskpri: the log priority mask
+ :returns: The previous log priority mask
+
+ The `xo_set_logmask` function is similar to :manpage:`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::
+
+ EXAMPLE:
+ setlogmask(LOG_UPTO(LOG_WARN));
+
+.. index:: xo_set_syslog_enterprise_id
+
+xo_set_syslog_enterprise_id
++++++++++++++++++++++++++++
+
+.. c:function:: void xo_set_syslog_enterprise_id (unsigned short eid)
+
+ 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.
+
+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.
+
+.. index:: CBOR
+
+libxo source contains an encoder for Concise Binary Object
+Representation, aka CBOR (:RFC:`7049`), which can be used as an
+example for the API for other encoders.
+
+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.
Index: vendor/Juniper/libxo/1.3.0/doc/conf.py
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/conf.py (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/conf.py (revision 354426)
@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# JuniperStory documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 10 10:18:55 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import subprocess
+
+#
+# Instead of hardcoding the version number here, we read it from the
+# project's configure script
+#
+vers_cmd = "grep AC_INIT ../configure.ac | awk '{ print substr($2, 2, length($2) - 3);}'"
+version = subprocess.check_output(vers_cmd, shell=True).decode("utf-8")
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'libxo'
+copyright = '2017-2019, Juniper Networks Inc'
+author = 'Phil Shafer'
+default_role = 'code'
+primary_domain = 'c'
+smart_quotes = False
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+#version = 'develop'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+html_theme_options = {
+ "sidebarwidth": 320,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+alabaster_html_sidebars = {
+ '**': [
+ 'about.html',
+ 'navigation.html',
+ 'relations.html', # needs 'show_related': True theme option to display
+ 'searchbox.html',
+ 'donate.html',
+ ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'libxo-manual'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'libxo.tex', 'libxo Documentation',
+ 'Phil Shafer', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'libxo', 'libxo Documentation',
+ [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'libxo', 'libxo Documentation',
+ author, 'libxo', 'A Library for Generating Text, XML, JSON, and HTML Output',
+ 'Miscellaneous'),
+]
+
+
+
Property changes on: vendor/Juniper/libxo/1.3.0/doc/conf.py
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:keywords
## -0,0 +1 ##
+FreeBSD=%H
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+text/plain
\ No newline at end of property
Index: vendor/Juniper/libxo/1.3.0/doc/encoders.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/encoders.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/encoders.rst (revision 354426)
@@ -0,0 +1,269 @@
+.. index:: encoder
+
+Encoders
+========
+
+This section gives an overview of encoders, details on the encoders
+that ship with libxo, and documentation for developers of future
+encoders.
+
+Overview
+--------
+
+The libxo library contains software to generate four "built-in"
+formats: text, XML, JSON, and HTML. These formats are common and
+useful, but there are other common and useful formats that users will
+want, and including them all in the libxo software would be difficult
+and cumbersome.
+
+To allow support for additional encodings, libxo includes a
+"pluggable" extension mechanism for dynamically loading new encoders.
+libxo-based applications can automatically use any installed encoder.
+
+Use the "encoder=XXX" option to access encoders. The following
+example uses the "cbor" encoder, saving the output into a file::
+
+ df --libxo encoder=cbor > df-output.cbor
+
+Encoders can support specific options that can be accessed by
+following the encoder name with a colon (':') and one of more options,
+separated by a plus sign "+"::
+
+ df --libxo encoder=csv:path=filesystem+leaf=name+no-header
+
+This example instructs libxo to load the "csv" encoder and pass the
+following options::
+
+ path=filesystem
+ leaf=name
+ no-header
+
+Each of these option is interpreted by the encoder, and all such
+options names and semantics are specific to the particular encoder.
+Refer to the intended encoder for documentation on its options.
+
+.. _csv_encoder:
+
+CSV - Comma Separated Values
+----------------------------
+
+libxo ships with a custom encoder for "CSV" files, a common format for
+comma separated values. The output of the CSV encoder can be loaded
+directly into spreadsheets or similar applications.
+
+A standard for CSV files is provided in :RFC:`4180`, but since the
+format predates that standard by decades, there are many minor
+differences in CSV file consumers and their expectations. The CSV
+encoder has a number of options to tailor output to those
+expectations.
+
+Consider the following XML::
+
+ % list-items --libxo xml,pretty
+
+
+
+ GRO-000-415
+ gum
+ 1412
+ 54
+ 10
+
+
+ HRD-000-212
+ rope
+ 85
+ 4
+ 2
+
+
+ HRD-000-517
+ ladder
+ 0
+ 2
+ 1
+
+
+
+
+This output is a list of `instances` (named "item"), each containing a
+set of `leafs` ("sku", "name", etc).
+
+The CSV encoder will emit the leaf values in this output as `fields`
+inside a CSV `record`, which is a line containing a set of
+comma-separated values::
+
+ % list-items --libxo encoder=csv
+ sku,name,sold,in-stock,on-order
+ GRO-000-415,gum,1412,54,10
+ HRD-000-212,rope,85,4,2
+ HRD-000-517,ladder,0,2,1
+
+Be aware that since the CSV encoder looks for data instances, when
+used with :ref:`xo`, the `--instance` option will be needed::
+
+ % xo --libxo encoder=csv --instance foo 'The {:product} is {:status}\n' stereo "in route"
+ product,status
+ stereo,in route
+
+.. _csv_path:
+
+The `path` Option
+~~~~~~~~~~~~~~~~~
+
+By default, the CSV encoder will attempt to emit any list instance
+generated by the application. In some cases, this may be
+unacceptable, and a specific list may be desired.
+
+Use the "path" option to limit the processing of output to a specific
+hierarchy. The path should be one or more names of containers or
+lists.
+
+For example, if the "list-items" application generates other lists,
+the user can give "path=top/data/item" as a path::
+
+ % list-items --libxo encoder=csv:path=top/data/item
+ sku,name,sold,in-stock,on-order
+ GRO-000-415,gum,1412,54,10
+ HRD-000-212,rope,85,4,2
+ HRD-000-517,ladder,0,2,1
+
+Paths are "relative", meaning they need not be a complete set
+of names to the list. This means that "path=item" may be sufficient
+for the above example.
+
+.. _csv_leafs:
+
+The `leafs` Option
+~~~~~~~~~~~~~~~~~~
+
+The CSV encoding requires that all lines of output have the same
+number of fields with the same order. In contrast, XML and JSON allow
+any order (though libxo forces key leafs to appear before other
+leafs).
+
+To maintain a consistent set of fields inside the CSV file, the same
+set of leafs must be selected from each list item. By default, the
+CSV encoder records the set of leafs that appear in the first list
+instance it processes, and extract only those leafs from future
+instances. If the first instance is missing a leaf that is desired by
+the consumer, the "leaf" option can be used to ensure that an empty
+value is recorded for instances that lack a particular leaf.
+
+The "leafs" option can also be used to exclude leafs, limiting the
+output to only those leafs provided.
+
+In addition, the order of the output fields follows the order in which
+the leafs are listed. "leafs=one.two" and "leafs=two.one" give
+distinct output.
+
+So the "leafs" option can be used to expand, limit, and order the set
+of leafs.
+
+The value of the leafs option should be one or more leaf names,
+separated by a period (".")::
+
+ % list-items --libxo encoder=csv:leafs=sku.on-order
+ sku,on-order
+ GRO-000-415,10
+ HRD-000-212,2
+ HRD-000-517,1
+ % list-items -libxo encoder=csv:leafs=on-order.sku
+ on-order,sku
+ 10,GRO-000-415
+ 2,HRD-000-212
+ 1,HRD-000-517
+
+Note that since libxo uses terminology from YANG (:RFC:`7950`), the
+data modeling language for NETCONF (:RFC:`6241`), which uses "leafs"
+as the plural form of "leaf". libxo follows that convention.
+
+.. _csv_no_header:
+
+The `no-header` Option
+~~~~~~~~~~~~~~~~~~~~~~
+
+CSV files typical begin with a line that defines the fields included
+in that file, in an attempt to make the contents self-defining::
+
+ sku,name,sold,in-stock,on-order
+ GRO-000-415,gum,1412,54,10
+ HRD-000-212,rope,85,4,2
+ HRD-000-517,ladder,0,2,1
+
+There is no reliable mechanism for determining whether this header
+line is included, so the consumer must make an assumption.
+
+The csv encoder defaults to producing the header line, but the
+"no-header" option can be included to avoid the header line.
+
+.. _csv_no_quotes:
+
+The `no-quotes` Option
+~~~~~~~~~~~~~~~~~~~~~~
+
+:RFC:`4180` specifies that fields containing spaces should be quoted, but
+many CSV consumers do not handle quotes. The "no-quotes" option
+instruct the CSV encoder to avoid the use of quotes.
+
+.. _csv_dos:
+
+The `dos` Option
+~~~~~~~~~~~~~~~~
+
+:RFC:`4180` defines the end-of-line marker as a carriage return
+followed by a newline. This `CRLF` convention dates from the distant
+past, but its use was anchored in the 1980s by the `DOS` operating
+system.
+
+The CSV encoder defaults to using the standard Unix end-of-line
+marker, a simple newline. Use the "dos" option to use the `CRLF`
+convention.
+
+The Encoder API
+---------------
+
+The encoder API consists of three distinct phases:
+
+- loading the encoder
+- initializing the encoder
+- feeding operations to the encoder
+
+To load the encoder, libxo will open a shared library named:
+
+ ${prefix}/lib/libxo/encoder/${name}.enc
+
+This file is typically a symbolic link to a dynamic library, suitable
+for `dlopen`(). libxo looks for a symbol called
+`xo_encoder_library_init` inside that library and calls it with the
+arguments defined in the header file "xo_encoder.h". This function
+should look as follows::
+
+ int
+ xo_encoder_library_init (XO_ENCODER_INIT_ARGS)
+ {
+ arg->xei_version = XO_ENCODER_VERSION;
+ arg->xei_handler = test_handler;
+
+ return 0;
+ }
+
+Several features here allow for future compatibility: the macro
+XO_ENCODER_INIT_ARGS allows the arguments to this function change over
+time, and the XO_ENCODER_VERSION allows the library to tell libxo
+which version of the API it was compiled with.
+
+The function places in xei_handler should be have the signature::
+
+ static int
+ test_handler (XO_ENCODER_HANDLER_ARGS)
+ {
+ ...
+
+This function will be called with the "op" codes defined in
+"xo_encoder.h". Each op code represents a distinct event in the libxo
+processing model. For example OP_OPEN_CONTAINER tells the encoder
+that a new container has been opened, and the encoder can behave in an
+appropriate manner.
+
+
Index: vendor/Juniper/libxo/1.3.0/doc/faq.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/faq.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/faq.rst (revision 354426)
@@ -0,0 +1,208 @@
+
+FAQs
+====
+
+This section contains the set of questions that users typically ask,
+along with answers that might be helpful.
+
+General
+-------
+
+Can you share the history of libxo?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In 2001, we added an XML API to the JUNOS operating system, which is
+built on top of FreeBSD_. Eventually this API became standardized as
+the NETCONF API (:RFC:`6241`). As part of this effort, we modified many
+FreeBSD utilities to emit XML, typically via a "-X" switch. The
+results were mixed. The cost of maintaining this code, updating it,
+and carrying it were non-trivial, and contributed to our expense (and
+the associated delay) with upgrading the version of FreeBSD on which
+each release of JUNOS is based.
+
+.. _FreeBSD: https://www.freebsd.org
+
+A recent (2014) effort within JUNOS aims at removing our modifications
+to the underlying FreeBSD code as a means of reducing the expense and
+delay in tracking HEAD. JUNOS is structured to have system components
+generate XML that is rendered by the CLI (think: login shell) into
+human-readable text. This allows the API to use the same plumbing as
+the CLI, and ensures that all components emit XML, and that it is
+emitted with knowledge of the consumer of that XML, yielding an API
+that have no incremental cost or feature delay.
+
+libxo is an effort to mix the best aspects of the JUNOS strategy into
+FreeBSD in a seemless way, allowing commands to make printf-like
+output calls with a single code path.
+
+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.
+
+.. index:: XOF_UNDERSCORES
+
+.. _good-field-names:
+
+What makes a good field name?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make useful, consistent field names, follow these guidelines:
+
+Use lower case, even for TLAs
+ Lower case is more civilized. Even TLAs should be lower case
+ to avoid scenarios where the differences between "XPath" and
+ "Xpath" drive your users crazy. Using "xpath" is simpler and better.
+
+Use hyphens, not underscores
+ Use of hyphens is traditional in XML, and the XOF_UNDERSCORES
+ flag can be used to generate underscores in JSON, if desired.
+ But the raw field name should use hyphens.
+
+Use full words
+ Don't abbreviate especially when the abbreviation is not obvious or
+ not widely used. Use "data-size", not "dsz" or "dsize". Use
+ "interface" instead of "ifname", "if-name", "iface", "if", or "intf".
+
+Use -
+ Using the form - or -- helps in
+ making consistent, useful names, avoiding the situation where one app
+ uses "sent-packet" and another "packets-sent" and another
+ "packets-we-have-sent". The can be dropped when it is
+ obvious, as can obvious words in the classification.
+ Use "receive-after-window-packets" instead of
+ "received-packets-of-data-after-window".
+
+Reuse existing field names
+ Nothing's worse than writing expressions like::
+
+ if ($src1/process[pid == $pid]/name ==
+ $src2/proc-table/proc-list
+ /prc-entry[prcss-id == $pid]/proc-name) {
+ ...
+ }
+
+ Find someone else who is expressing similar data and follow their
+ 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". Consistency rocks!
+
+Use containment as scoping
+ In the previous example, all the names are prefixed with "proc-",
+ which is redundant given that they are nested under the process table.
+
+Think about your users
+ Have empathy for your users, choosing clear and useful fields that
+ contain clear and useful data. You may need to augment the display
+ content with xo_attr() calls (:ref:`xo_attr`) or "{e:}"
+ fields (:ref:`encoding-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 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.
+
+Be consistent, uniform, unsurprising, and predictable
+ Think of your field vocabulary as an API. You want it useful,
+ expressive, meaningful, direct, and obvious. You want the client
+ application's programmer to move between without the need to
+ understand a variety of opinions on how fields are named. They
+ should see the system as a single cohesive whole, not a sack of
+ cats.
+
+Field names constitute the means by which client programmers interact
+with our system. By choosing wise names now, you are making their
+lives better.
+
+After using `xolint` to find errors in your field descriptors, use
+"`xolint -V`" to spell check your field names and to help you 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 is no difference, use only one of the field names. If there is
+a difference, change the names to make that difference more obvious.
+
+What does this message mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: xolint.rst
Index: vendor/Juniper/libxo/1.3.0/doc/field-formatting.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/field-formatting.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/field-formatting.rst (revision 354426)
@@ -0,0 +1,370 @@
+
+.. index:: Field Formatting
+
+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
+ ===== ============= ====================
+
+.. index:: UTF-8
+.. index:: Locale
+
+.. _utf-8:
+
+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");
+
+ ======== ================== ===============================
+ Format Argument Type Argument Contents
+ ======== ================== ===============================
+ %s const char \* UTF-8 string
+ %S const char \* UTF-8 string (alias for '%ls')
+ %ls const wchar_t \* Wide character UNICODE string
+ %hs const char * locale-based string
+ ======== ================== ===============================
+
+.. admonition:: "Long", not "locale"
+
+ The "*l*" in "%ls" is for "*long*", following the convention of "%ld".
+ It is not "*locale*", a common mis-mnemonic. "%S" is equivalent to
+ "%ls".
+
+For example, the following 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
+
.
+
+.. index:: errno
+
+"%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.
+
+.. index:: printf-like
+
+Argument Validation
+~~~~~~~~~~~~~~~~~~~
+
+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
+ ================== ========================
+
+.. index:: performance
+.. index:: XOEF_RETAIN
+
+.. _retain:
+
+Retaining Parsed Format Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+
+
In stock
+
:
+
+
144
+
+
+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
Index: vendor/Juniper/libxo/1.3.0/doc/field-modifiers.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/field-modifiers.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/field-modifiers.rst (revision 354426)
@@ -0,0 +1,353 @@
+
+.. index:: Field Modifiers
+.. _field-modifiers:
+
+Field Modifiers
+~~~~~~~~~~~~~~~
+
+Field modifiers are flags which modify the way content emitted for
+particular output styles:
+
+ === =============== ===================================================
+ M Name Description
+ === =============== ===================================================
+ a argument The content appears as a 'const char \*' argument
+ c colon A colon (":") is appended after the label
+ d display Only emit field for display styles (text/HTML)
+ e encoding Only emit for encoding styles (XML/JSON)
+ g gettext Call gettext on field's render content
+ h humanize (hn) Format large numbers in human-readable style
+ \ hn-space Humanize: Place space between numeric and unit
+ \ hn-decimal Humanize: Add a decimal digit, if number < 10
+ \ hn-1000 Humanize: Use 1000 as divisor instead of 1024
+ 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
+ p plural Gettext: Use comma-separated plural form
+ q quotes Quote the field when using JSON style
+ t trim Trim leading and trailing whitespace
+ w white A blank (" ") is appended after the label
+ === =============== ===================================================
+
+Roles and modifiers can also use more verbose names, when preceded by
+a comma. For example, the modifier string "Lwc" (or "L,white,colon")
+means the field has a label role (text that describes the next field)
+and should be followed by a colon ('c') and a space ('w'). The
+modifier string "Vkq" (or ":key,quote") means the field has a value
+role (the default role), that it is a key for the current instance,
+and that the value should be quoted when encoded for JSON.
+
+.. index:: Field Modifiers; Argument
+.. _argument-modifier:
+
+The Argument Modifier ({a:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Argument
+
+The argument modifier indicates that the content of the field
+descriptor will be placed as a UTF-8 string (const char \*) argument
+within the xo_emit parameters::
+
+ EXAMPLE:
+ xo_emit("{La:} {a:}\n", "Label text", "label", "value");
+ TEXT:
+ Label text value
+ JSON:
+ "label": "value"
+ XML:
+
+
+The argument modifier allows field names for value fields to be passed
+on the stack, avoiding the need to build a field descriptor using
+snprintf. For many field roles, the argument modifier is not needed,
+since those roles have specific mechanisms for arguments, such as
+"{C:fg-%s}".
+
+.. index:: Field Modifiers; Colon
+.. _colon-modifier:
+
+The Colon Modifier ({c:})
++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Colon
+
+The colon modifier appends a single colon to the data value::
+
+ EXAMPLE:
+ xo_emit("{Lc:Name}{:name}\n", "phil");
+ TEXT:
+ Name:phil
+
+The colon modifier is only used for the TEXT and HTML output
+styles. It is commonly combined with the space modifier ('{w:}').
+It is purely a convenience feature.
+
+.. index:: Field Modifiers; Display
+.. _display-modifier:
+
+The Display Modifier ({d:})
++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Display
+
+The display modifier indicated the field should only be generated for
+the display output styles, TEXT and HTML::
+
+ EXAMPLE:
+ xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
+ TEXT:
+ Name: phil 1
+ XML:
+ 1
+
+The display modifier is the opposite of the encoding modifier, and
+they are often used to give to distinct views of the underlying data.
+
+.. index:: Field Modifiers; Encoding
+.. _encoding-modifier:
+
+The Encoding Modifier ({e:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Encoding
+
+The display modifier indicated the field should only be generated for
+the display output styles, TEXT and HTML::
+
+ EXAMPLE:
+ xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
+ TEXT:
+ Name: phil
+ XML:
+ phil1
+
+The encoding modifier is the opposite of the display modifier, and
+they are often used to give to distinct views of the underlying data.
+
+.. index:: Field Modifiers; Gettext
+.. _gettext-modifier:
+
+The Gettext Modifier ({g:})
++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Gettext
+.. index:: gettext
+
+The gettext modifier is used to translate individual fields using the
+gettext domain (typically set using the "`{G:}`" role) and current
+language settings. Once libxo renders the field value, it is passed
+to gettext(3), where it is used as a key to find the native language
+translation.
+
+In the following example, the strings "State" and "full" are passed
+to gettext() to find locale-based translated strings::
+
+ xo_emit("{Lgwc:State}{g:state}\n", "full");
+
+See :ref:`gettext-role`, :ref:`plural-modifier`, and
+:ref:`i18n` for additional details.
+
+.. index:: Field Modifiers; Humanize
+.. _humanize-modifier:
+
+The Humanize Modifier ({h:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Humanize
+
+The humanize modifier is used to render large numbers as in a
+human-readable format. While numbers like "44470272" are completely
+readable to computers and savants, humans will generally find "44M"
+more meaningful.
+
+"hn" can be used as an alias for "humanize".
+
+The humanize modifier only affects display styles (TEXT and HMTL).
+The "`no-humanize`" option (See :ref:`options`) will block
+the function of the humanize modifier.
+
+There are a number of modifiers that affect details of humanization.
+These are only available in as full names, not single characters. The
+"`hn-space`" modifier places a space between the number and any
+multiplier symbol, such as "M" or "K" (ex: "44 K"). The
+"`hn-decimal`" modifier will add a decimal point and a single tenths
+digit when the number is less than 10 (ex: "4.4K"). The "`hn-1000`"
+modifier will use 1000 as divisor instead of 1024, following the
+JEDEC-standard instead of the more natural binary powers-of-two
+tradition::
+
+ EXAMPLE:
+ xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
+ "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
+ "{h,hn-decimal:remaining/%u}\n",
+ input, output, errors, capacity, remaining);
+ TEXT:
+ 21, 57 K, 96M, 44M, 1.2G
+
+In the HTML style, the original numeric value is rendered in the
+"data-number" attribute on the
element::
+
+
96M
+
+.. index:: Field Modifiers; Key
+.. _key-modifier:
+
+The Key Modifier ({k:})
++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Key
+
+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");
+
+.. index:: XOF_XPATH
+
+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.
+
+.. index:: Field Modifiers; Leaf-List
+.. _leaf-list:
+
+The Leaf-List Modifier ({l:})
++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Leaf-List
+
+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.
+
+.. index:: Field Modifiers; No-Quotes
+.. _no-quotes-modifier:
+
+The No-Quotes Modifier ({n:})
++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; No-Quotes
+
+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
+
+.. index:: Field Modifiers; Plural
+.. _plural-modifier:
+
+The Plural Modifier ({p:})
+++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Plural
+.. index:: gettext
+
+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 :ref:`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.
+
+.. index:: Field Modifiers; Quotes
+.. _quotes-modifier:
+
+The Quotes Modifier ({q:})
+++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Quotes
+
+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
+
+.. index:: Field Modifiers; Trim
+.. _trim-modifier:
+
+The Trim Modifier ({t:})
+++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Trim
+
+The trim modifier removes any leading or trailing whitespace from
+the value::
+
+ EXAMPLE:
+ xo_emit("{t:description}", " some input ");
+ JSON:
+ "description": "some input"
+
+.. index:: Field Modifiers; White Space
+.. _white-space-modifier:
+
+The White Space Modifier ({w:})
++++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; White Space
+
+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.
Index: vendor/Juniper/libxo/1.3.0/doc/field-roles.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/field-roles.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/field-roles.rst (revision 354426)
@@ -0,0 +1,312 @@
+
+.. index:: Field Roles
+.. _field-roles:
+
+Field Roles
+~~~~~~~~~~~
+
+Field roles are optional, and indicate the role and formatting of the
+content. The roles are listed below; only one role is permitted:
+
+ === ============== =================================================
+ R Name Description
+ === ============== =================================================
+ C color Field has color and effect controls
+ D decoration Field is non-text (e.g., colon, comma)
+ E error Field is an error message
+ G gettext Call gettext(3) on the format string
+ L label Field is text that prefixes a value
+ N note Field is text that follows a value
+ P padding Field is spaces needed for vertical alignment
+ T title Field is a title value for headings
+ U units Field is the units for the previous value field
+ V value Field is the name of field (the default)
+ W warning Field is a warning message
+ [ start-anchor Begin a section of anchored variable-width text
+ ] stop-anchor End a section of anchored variable-width text
+ === ============== =================================================
+
+::
+
+ EXAMPLE:
+ xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n",
+ free_blocks);
+
+When a role is not provided, the "*value*" role is used as the default.
+
+Roles and modifiers can also use more verbose names, when preceded by
+a comma::
+
+ EXAMPLE:
+ xo_emit("{,label:Free}{,decoration::}{,padding: }"
+ "{,value:free/%u} {,units:Blocks}\n",
+ free_blocks);
+
+.. index:: Field Roles; Color
+.. _color-role:
+
+The Color Role ({C:})
++++++++++++++++++++++
+
+Colors and effects control how text values are displayed; they are
+used for display styles (TEXT and HTML)::
+
+ xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
+
+Colors and effects remain in effect until modified by other "C"-role
+fields::
+
+ xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
+
+If the content is empty, the "*reset*" action is performed::
+
+ xo_emit("{C:both,underline}{:value}{C:}\n", value);
+
+The content should be a comma-separated list of zero or more colors or
+display effects::
+
+ xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n");
+
+The color content can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+if preceded by a slash ("/"):
+
+ xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
+ need_underline ? "underline" : "", value);
+
+Color names are prefixed with either "fg-" or "bg-" to change the
+foreground and background colors, respectively::
+
+ xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
+ fg_color, bg_color, cost);
+
+The following table lists the supported effects:
+
+ =============== =================================================
+ Name Description
+ =============== =================================================
+ bg-XXXXX Change background color
+ bold Start bold text effect
+ fg-XXXXX Change foreground color
+ inverse Start inverse (aka reverse) text effect
+ no-bold Stop bold text effect
+ no-inverse Stop inverse (aka reverse) text effect
+ no-underline Stop underline text effect
+ normal Reset effects (only)
+ reset Reset colors and effects (restore defaults)
+ underline Start underline text effect
+ =============== =================================================
+
+The following color names are supported:
+
+ ========= ============================================
+ Name Description
+ ========= ============================================
+ black
+ blue
+ cyan
+ default Default color for foreground or background
+ green
+ magenta
+ red
+ white
+ yellow
+ ========= ============================================
+
+When using colors, the developer should remember that users will
+change the foreground and background colors of terminal session
+according to their own tastes, so assuming that "blue" looks nice is
+never safe, and is a constant annoyance to your dear author. In
+addition, a significant percentage of users (1 in 12) will be color
+blind. Depending on color to convey critical information is not a
+good idea. Color should enhance output, but should not be used as the
+sole means of encoding information.
+
+.. index:: Field Roles; Decoration
+.. _decoration-role:
+
+The Decoration Role ({D:})
+++++++++++++++++++++++++++
+
+Decorations are typically punctuation marks such as colons,
+semi-colons, and commas used to decorate the text and make it simpler
+for human readers. By marking these distinctly, HTML usage scenarios
+can use CSS to direct their display parameters::
+
+ xo_emit("{D:((}{:name}{D:))}\n", name);
+
+.. index:: Field Roles; Gettext
+.. _gettext-role:
+
+The Gettext Role ({G:})
++++++++++++++++++++++++
+
+libxo supports internationalization (i18n) through its use of
+gettext(3). Use the "{G:}" role to request that the remaining part of
+the format string, following the "{G:}" field, be handled using
+gettext().
+
+Since gettext() uses the string as the key into the message catalog,
+libxo uses a simplified version of the format string that removes
+unimportant field formatting and modifiers, stopping minor formatting
+changes from impacting the expensive translation process. A developer
+change such as changing "/%06d" to "/%08d" should not force hand
+inspection of all .po files.
+
+The simplified version can be generated for a single message using the
+"`xopo -s $text`" command, or an entire .pot can be translated using
+the "`xopo -f $input -o $output`" command.
+
+ xo_emit("{G:}Invalid token\n");
+
+The {G:} role allows a domain name to be set. gettext calls will
+continue to use that domain name until the current format string
+processing is complete, enabling a library function to emit strings
+using it's own catalog. The domain name can be either static as the
+content of the field, or a format can be used to get the domain name
+from the arguments.
+
+ xo_emit("{G:libc}Service unavailable in restricted mode\n");
+
+See :ref:`i18n` for additional details.
+
+.. index:: Field Roles; Label
+.. _label-role:
+
+The Label Role ({L:})
++++++++++++++++++++++
+
+Labels are text that appears before a value::
+
+ xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
+
+.. index:: Field Roles; Note
+.. _note-role:
+
+The Note Role ({N:})
+++++++++++++++++++++
+
+Notes are text that appears after a value::
+
+ xo_emit("{:cost/%u} {N:per year}\n", cost);
+
+.. index:: Field Roles; Padding
+.. _padding-role:
+
+The Padding Role ({P:})
++++++++++++++++++++++++
+
+Padding represents whitespace used before and between fields.
+
+The padding content can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+if preceded by a slash ("/")::
+
+ xo_emit("{P: }{Lwc:Cost}{:cost/%u}\n", cost);
+ xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
+
+.. index:: Field Roles; Title
+.. _title-role:
+
+The Title Role ({T:})
++++++++++++++++++++++
+
+Title are heading or column headers that are meant to be displayed to
+the user. The title can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+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.
+
+.. index:: Field Roles; Units
+.. index:: XOF_UNITS
+.. _units-role:
+
+The Units Role ({U:})
++++++++++++++++++++++
+
+Units are the dimension by which values are measured, such as degrees,
+miles, bytes, and decibels. The units field carries this information
+for the previous value field::
+
+ xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
+
+Note that the sense of the 'w' modifier is reversed for units;
+a blank is added before the contents, rather than after it.
+
+When the XOF_UNITS flag is set, units are rendered in XML as the
+"units" attribute::
+
+ 50
+
+Units can also be rendered in HTML as the "data-units" attribute::
+
+
50
+
+.. index:: Field Roles; Value
+.. _value-role:
+
+The Value Role ({V:} and {:})
++++++++++++++++++++++++++++++
+
+The value role is used to represent the a data value that is
+interesting for the non-display output styles (XML and JSON). Value
+is the default role; if no other role designation is given, the field
+is a value. The field name must appear within the field descriptor,
+followed by one or two format descriptors. The first format
+descriptor is used for display styles (TEXT and HTML), while the
+second one is used for encoding styles (XML and JSON). If no second
+format is given, the encoding format defaults to the first format,
+with any minimum width removed. If no first format is given, both
+format descriptors default to "%s"::
+
+ xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
+ length, width, height);
+ xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n,
+ author, poem, year);
+
+.. index:: Field Roles; Anchor
+.. _anchor-role:
+
+The Anchor Roles ({[:} and {]:})
+++++++++++++++++++++++++++++++++
+
+The anchor roles allow a set of strings by be padded as a group,
+but still be visible to xo_emit as distinct fields. Either the start
+or stop anchor can give a field width and it can be either directly in
+the descriptor or passed as an argument. Any fields between the start
+and stop anchor are padded to meet the minimum width given.
+
+To give a width directly, encode it as the content of the anchor tag::
+
+ xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
+
+To pass a width as an argument, use "%d" as the format, which must
+appear after the "/". Note that only "%d" is supported for widths.
+Using any other value could ruin your day::
+
+ xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
+
+If the width is negative, padding will be added on the right, suitable
+for left justification. Otherwise the padding will be added to the
+left of the fields between the start and stop anchors, suitable for
+right justification. If the width is zero, nothing happens. If the
+number of columns of output between the start and stop anchors is less
+than the absolute value of the given width, nothing happens.
+
+.. index:: XOF_WARN
+
+Widths over 8k are considered probable errors and not supported. If
+XOF_WARN is set, a warning will be generated.
Index: vendor/Juniper/libxo/1.3.0/doc/index.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/index.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/index.rst (revision 354426)
@@ -0,0 +1,54 @@
+.. #
+ # Copyright (c) 2014, Juniper Networks, Inc.
+ # All rights reserved.
+ # This SOFTWARE is licensed under the LICENSE provided in the
+ # ../Copyright file. By downloading, installing, copying, or
+ # using the SOFTWARE, you agree to be bound by the terms of that
+ # LICENSE.
+ # Phil Shafer, July 2014
+ #
+
+.. default-role:: code
+
+libxo - A Library for Generating Text, XML, JSON, and HTML Output
+===================================================================
+
+The libxo library allows an application to generate text, XML, JSON,
+and HTML output, suitable for both command line use and for web
+applications. The application decides at run time which output style
+should be produced. By using libxo, a single source code path can
+emit multiple styles of output using command line options to select
+the style, along with optional behaviors. libxo includes support for
+multiple output streams, pluralization, color, syslog,
+:manpage:`humanized(3)` output, internationalization, and UTF-8. The
+library aims to minimize the cost of migrating code to libxo.
+
+libxo ships as part of FreeBSD.
+
+.. toctree::
+ :maxdepth: 3
+ :caption: Documentation Contents:
+
+ intro
+ getting
+ formatting
+ options
+ format-strings
+ field-roles
+ field-modifiers
+ field-formatting
+ api
+ encoders
+ xo
+ xolint
+ xohtml
+ xopo
+ faq
+ howto
+ example
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
Index: vendor/Juniper/libxo/1.3.0/doc/options.rst
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/options.rst (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/options.rst (revision 354426)
@@ -0,0 +1,164 @@
+
+.. index:: --libxo
+.. index:: Options
+
+.. _options:
+
+Command-line Arguments
+======================
+
+libxo uses command line options to trigger rendering behavior. There
+are multiple conventions for passing options, all using the
+"`--libxo`" option::
+
+ --libxo
+ --libxo=
+ --libxo:
+
+The *brief-options* is a series of single letter abbrevations, where
+the *options* is a comma-separated list of words. Both provide access
+to identical functionality. 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 :ref:`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 :ref:`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
+ :ref:`humanize-modifier` 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 (see :ref:`retain`
+ for details).
+- "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)
+ ======== =============================================
+
+.. index:: Colors
+
+.. _color-mapping:
+
+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 plus signs ("+")::
+
+ --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 plus signs ("+")::
+
+ --libxo colors=++++yellow/yellow
Index: vendor/Juniper/libxo/1.3.0/doc/top-link.html.in
===================================================================
--- vendor/Juniper/libxo/1.3.0/doc/top-link.html.in (nonexistent)
+++ vendor/Juniper/libxo/1.3.0/doc/top-link.html.in (revision 354426)
@@ -0,0 +1,9 @@
+
+
+
+
+
+
+