diff --git a/contrib/libxo/.gitignore b/contrib/libxo/.gitignore index 8d70b6cc1550..f4ace8fe0a81 100644 --- a/contrib/libxo/.gitignore +++ b/contrib/libxo/.gitignore @@ -1,46 +1,32 @@ -# Object files -*.o - -# Libraries -*.lib -*.a - -# Shared objects (inc. Windows DLLs) -*.dll -*.so -*.so.* -*.dylib - -# Executables -*.exe -*.app - -*~ -*.orig - +tag.sh +Makefile.in aclocal.m4 ar-lib autom4te.cache -build +bin +build* compile +configure config.guess -config.h.in config.sub depcomp +doc/Makefile.in +info* install-sh ltmain.sh -missing m4 - -Makefile.in -configure -.DS_Store - -xoconfig.h.in -xo_config.h.in - -.gdbinit -.gdbinit.local -xtest -xtest.dSYM -tests/w +missing +patches* +doc/Makefile.in +encoder/Makefile.in +encoder/cbor/Makefile.in +encoder/test/Makefile.in +libxo/Makefile.in +tests/Makefile.in +tests/core/Makefile.in +tests/gettext/Makefile.in +tests/xo/Makefile.in +xo/Makefile.in +xohtml/Makefile.in +xolint/Makefile.in +xopo/Makefile.in diff --git a/contrib/libxo/.svnignore b/contrib/libxo/.svnignore deleted file mode 100644 index 8327c93fdd15..000000000000 --- a/contrib/libxo/.svnignore +++ /dev/null @@ -1,18 +0,0 @@ -Makefile.in -aclocal.m4 -ar-lib -autom4te.cache -bin* -build* -compile -configure -config.guess -config.sub -depcomp -doc/Makefile.in -info* -install-sh -ltmain.sh -m4 -missing -patches* diff --git a/contrib/libxo/Makefile.am b/contrib/libxo/Makefile.am index 8a524738858b..617e3b1af871 100644 --- a/contrib/libxo/Makefile.am +++ b/contrib/libxo/Makefile.am @@ -1,144 +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 +SUBDIRS = bin 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 diff --git a/contrib/libxo/configure.ac b/contrib/libxo/configure.ac index e28db9396082..2f5681d4276f 100644 --- a/contrib/libxo/configure.ac +++ b/contrib/libxo/configure.ac @@ -1,500 +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.4.0], [phil@juniper.net]) +AC_PREREQ([2.69]) +AC_INIT([libxo],[1.6.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` + HAVE_GCC=`${CC} --version 2>&1 | grep -i GCC` if test "${HAVE_GCC}" != ""; then HAVE_GCC=yes + AC_DEFINE([HAVE_GCC], [1], [Using real gcc]) 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 + bin/Makefile 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} ]) diff --git a/contrib/libxo/doc/Makefile.am b/contrib/libxo/doc/Makefile.am index eb9ce3646537..dcd155e95f23 100644 --- a/contrib/libxo/doc/Makefile.am +++ b/contrib/libxo/doc/Makefile.am @@ -1,29 +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 +doc docs: xolint-errors.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 +xolint-errors.rst: ${top_srcdir}/xolint/xolint.pl + perl ${top_srcdir}/xolint/xolint.pl -D > ${top_srcdir}/doc/xolint-errors.rst SPHINX = python3 -msphinx html sphinx sphinx-html: ${SPHINX} -M html ${srcdir} . -N -E singlehtml: ${SPHINX} -M singlehtml ${srcdir} . -N -E diff --git a/contrib/libxo/doc/api.rst b/contrib/libxo/doc/api.rst index 94358489f075..8a9b7bb5cefe 100644 --- a/contrib/libxo/doc/api.rst +++ b/contrib/libxo/doc/api.rst @@ -1,1679 +1,1702 @@ .. 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 +The functions in this section are used to emit output. They use a +`format` 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`. +string, since an inappropriate or missing argument 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, ...) +The functions in this section emit formatted output similar to +`xo_emit` but where `xo_emit` uses a single string argument containing +the description for multiple fields, `xo_emit_field` emits a single +field using multiple ar- guments to contain the field description. +`xo_emit_field_h` adds an ex- plicit handle to use instead of the +default handle, while `xo_emit_field_hv` accepts a va_list for +additional flexibility. + +The arguments `rolmod`, `content`, `fmt`, and `efmt` are detailed in +:ref:`field-formatting`. Using distinct arguments allows callers to +pass the field description in pieces, rather than having to use +something like `snprintf` to build the format string required by +`xo_emit`. The arguments are each NUL-terminated strings. The `rolmod` +argument contains the `role` and `modifier` portions of the field +description, the `content` argument contains the `content` portion, and +the `fmt` and `efmt` contain the `field-format` and `encoding-format` por- +tions, respectively. + +As with `xo_emit`, the `fmt` and `efmt` values are both optional, +since the `field-format` string defaults to "%s", and the +`encoding-format`'s default value is derived from the `field-format` +per :ref:`field-formatting`. However, care must be taken to avoid +using a value directly as the format, since characters like '{', '%', +and '}' will be interpreted as formatting directives, and may cause +xo_emit_field to dereference arbitrary values off the stack, leading +to bugs, core files, and gnashing of teeth. + +.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *content, 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 + :param content: The "content" portion of the field description string + :type content: const char * + :param fmt: Contents 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", title, NULL, NULL, NULL); xo_emit_field("T", "Host name is ", NULL, NULL); xo_emit_field("V", "host-name", NULL, NULL, host-name); + xo_emit_field(",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u", + "gum", 1412); .. 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 .. index:: xo_error_h .. index:: xo_error_hv .. index:: xo_errorn .. index:: xo_errorn_h .. index:: xo_errorn_hv xo_error ~~~~~~~~ .. c:function:: void xo_error (const char *fmt, ...) :param fmt: Format string :type fmt: const char * :returns: void .. c:function:: void xo_error_h (xo_handle_t *xop, const char *fmt, ...) :param xop: libxo handle pointer :type xop: xo_handle_t * :param fmt: Format string :type fmt: const char * :returns: void .. c:function:: void xo_error_hv (xo_handle_t *xop, const char *fmt, va_list vap) :param xop: libxo handle pointer :type xop: xo_handle_t * :param fmt: Format string :type fmt: const char * :param vap: variadic arguments :type xop: va_list :returns: void .. c:function:: void xo_errorn (const char *fmt, ...) :param fmt: Format string :type fmt: const char * :returns: void .. c:function:: void xo_errorn_h (xo_handle_t *xop, const char *fmt, ...) :param xop: libxo handle pointer :type xop: xo_handle_t * :param fmt: Format string :type fmt: const char * :returns: void .. c:function:: void xo_errorn_hv (xo_handle_t *xop, int need_newline, const char *fmt, va_list vap) :param xop: libxo handle pointer :type xop: xo_handle_t * :param need_newline: boolean indicating need for trailing newline :type need_newline: int :param fmt: Format string :type fmt: const char * :param vap: variadic arguments :type xop: va_list :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" } The `xo_error_h` and `xo_error_hv` add a handle object and a variadic-ized parameter to the signature, respectively. The `xo_errorn` function supplies a newline at the end the error message if the format string does not include one. The `xo_errorn_h` and `xo_errorn_hv` functions add a handle object and a variadic-ized parameter to the signature, respectively. The `xo_errorn_hv` function also adds a boolean to indicate the need for a trailing newline. .. 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. diff --git a/contrib/libxo/doc/faq.rst b/contrib/libxo/doc/faq.rst index 087ef710d0ec..5232a7271681 100644 --- a/contrib/libxo/doc/faq.rst +++ b/contrib/libxo/doc/faq.rst @@ -1,208 +1,211 @@ 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 +.. toctree:: + :maxdepth: 2 + + xolint-errors.rst diff --git a/contrib/libxo/doc/field-formatting.rst b/contrib/libxo/doc/field-formatting.rst index b182fcee999c..1a4a29af6e64 100644 --- a/contrib/libxo/doc/field-formatting.rst +++ b/contrib/libxo/doc/field-formatting.rst @@ -1,370 +1,371 @@ .. index:: Field Formatting +.. _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
diff --git a/contrib/libxo/doc/field-roles.rst b/contrib/libxo/doc/field-roles.rst index 4de810c64658..3499aea81aba 100644 --- a/contrib/libxo/doc/field-roles.rst +++ b/contrib/libxo/doc/field-roles.rst @@ -1,312 +1,317 @@ .. 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); +If a label needs to include a slash, it must be escaped using two +backslashes, one for the C compiler and one for libxo:: + + xo_emit("{Lc:Low\\/warn level}{:level/%s}\n", level); + .. 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. diff --git a/contrib/libxo/doc/xolint.rst b/contrib/libxo/doc/xolint-errors.rst similarity index 100% copy from contrib/libxo/doc/xolint.rst copy to contrib/libxo/doc/xolint-errors.rst diff --git a/contrib/libxo/doc/xolint.rst b/contrib/libxo/doc/xolint.rst index c3e518b9cddf..739fa18558f7 100644 --- a/contrib/libxo/doc/xolint.rst +++ b/contrib/libxo/doc/xolint.rst @@ -1,444 +1,40 @@ -'A percent sign appearing in text is a literal' -+++++++++++++++++++++++++++++++++++++++++++++++ - -The message "A percent sign appearing in text is a literal" can be caused by code like: - -:: - - xo_emit("cost: %d", cost); - -This code should be replaced with code like: - -:: - - xo_emit("{L:cost}: {:cost/%d}", cost); - -This can be a bit surprising and could be a field that was not -properly converted to a libxo-style format string. - - -'Unknown long name for role/modifier' -+++++++++++++++++++++++++++++++++++++ - -The message "Unknown long name for role/modifier" can be caused by code like: - -:: - - xo_emit("{,humanization:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{,humanize:value}", value); - -The hn-* modifiers (hn-decimal, hn-space, hn-1000) -are only valid for fields with the {h:} modifier. - - -'Last character before field definition is a field type' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Last character before field definition is a field type" can be caused by code like: -A common typo: - -:: - - xo_emit("{T:Min} T{:Max}"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:Min} {T:Max}"); - -Twiddling the "{" and the field role is a common typo. - - -'Encoding format uses different number of arguments' -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Encoding format uses different number of arguments" can be caused by code like: - -:: - - xo_emit("{:name/%6.6s %%04d/%s}", name, number); - -This code should be replaced with code like: - -:: - - xo_emit("{:name/%6.6s %04d/%s-%d}", name, number); - -Both format should consume the same number of arguments off the stack - - -'Only one field role can be used' -+++++++++++++++++++++++++++++++++ - -The message "Only one field role can be used" can be caused by code like: - -:: - - xo_emit("{LT:Max}"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:Max}"); - -'Potential missing slash after C, D, N, L, or T with format' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like: - -:: - - xo_emit("{T:%6.6s}\n", "Max"); - -This code should be replaced with code like: - -:: - - xo_emit("{T:/%6.6s}\n", "Max"); - -The "%6.6s" will be a literal, not a field format. While -it's possibly valid, it's likely a missing "/". - - -'An encoding format cannot be given (roles: DNLT)' -++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like: - -:: - - xo_emit("{T:Max//%s}", "Max"); - -Fields with the C, D, N, L, and T roles are not emitted in -the 'encoding' style (JSON, XML), so an encoding format -would make no sense. - - -'Format cannot be given when content is present (roles: CDLN)' -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like: - -:: - - xo_emit("{N:Max/%6.6s}", "Max"); - -Fields with the C, D, L, or N roles can't have both -static literal content ("{L:Label}") and a -format ("{L:/%s}"). -This error will also occur when the content has a backslash -in it, like "{N:Type of I/O}"; backslashes should be escaped, -like "{N:Type of I\\/O}". Note the double backslash, one for -handling 'C' strings, and one for libxo. - - -'Field has color without fg- or bg- (role: C)' -++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has color without fg- or bg- (role: C)" can be caused by code like: - -:: - - xo_emit("{C:green}{:foo}{C:}", x); - -This code should be replaced with code like: - -:: - - xo_emit("{C:fg-green}{:foo}{C:}", x); - -Colors must be prefixed by either "fg-" or "bg-". - - -'Field has invalid color or effect (role: C)' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has invalid color or effect (role: C)" can be caused by code like: - -:: - - xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x); - -This code should be replaced with code like: - -:: - - xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x); - -The list of colors and effects are limited. The -set of colors includes default, black, red, green, -yellow, blue, magenta, cyan, and white, which must -be prefixed by either "fg-" or "bg-". Effects are -limited to bold, no-bold, underline, no-underline, -inverse, no-inverse, normal, and reset. Values must -be separated by commas. - - -'Field has humanize modifier but no format string' -++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has humanize modifier but no format string" can be caused by code like: - -:: - - xo_emit("{h:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{h:value/%d}", value); - -Humanization is only value for numbers, which are not -likely to use the default format ("%s"). - - -'Field has hn-* modifier but not 'h' modifier' -++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like: - -:: - - xo_emit("{,hn-1000:value}", value); - -This code should be replaced with code like: - -:: - - xo_emit("{h,hn-1000:value}", value); - -The hn-* modifiers (hn-decimal, hn-space, hn-1000) -are only valid for fields with the {h:} modifier. - - -'Value field must have a name (as content)")' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field must have a name (as content)")" can be caused by code like: - -:: - - xo_emit("{:/%s}", "value"); - -This code should be replaced with code like: - -:: - - xo_emit("{:tag-name/%s}", "value"); - -The field name is used for XML and JSON encodings. These -tags names are static and must appear directly in the -field descriptor. - - -'Use hyphens, not underscores, for value field name' -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Use hyphens, not underscores, for value field name" can be caused by code like: - -:: - - xo_emit("{:no_under_scores}", "bad"); - -This code should be replaced with code like: - -:: - - xo_emit("{:no-under-scores}", "bad"); - -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. - - -'Value field name cannot start with digit' -++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name cannot start with digit" can be caused by code like: - -:: - - xo_emit("{:10-gig/}"); - -This code should be replaced with code like: - -:: - - xo_emit("{:ten-gig/}"); - -XML element names cannot start with a digit. - - -'Value field name should be lower case' -+++++++++++++++++++++++++++++++++++++++ - -The message "Value field name should be lower case" can be caused by code like: - -:: - - xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON"); - -This code should be replaced with code like: - -:: - - xo_emit("{:why-are-you-shouting}", "no reason"); - -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. Lower case rules the seas. - - -'Value field name should be longer than two characters' -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name should be longer than two characters" can be caused by code like: - -:: - - xo_emit("{:x}", "mumble"); - -This code should be replaced with code like: - -:: - - xo_emit("{:something-meaningful}", "mumble"); - -Field names should be descriptive, and it's hard to -be descriptive in less than two characters. Consider -your users and try to make something more useful. -Note that this error often occurs when the field type -is placed after the colon ("{:T/%20s}"), instead of before -it ("{T:/20s}"). - - -'Value field name contains invalid character' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "Value field name contains invalid character" can be caused by code like: - -:: - - xo_emit("{:cost-in-$$/%u}", 15); - -This code should be replaced with code like: - -:: - - xo_emit("{:cost-in-dollars/%u}", 15); - -An invalid character is often a sign of a typo, like "{:]}" -instead of "{]:}". Field names are restricted to lower-case -characters, digits, and hyphens. - - -'decoration field contains invalid character' -+++++++++++++++++++++++++++++++++++++++++++++ - -The message "decoration field contains invalid character" can be caused by code like: - -:: - - xo_emit("{D:not good}"); - -This code should be replaced with code like: - -:: - - xo_emit("{D:((}{:good}{D:))}", "yes"); - -This is minor, but fields should use proper roles. Decoration -fields are meant to hold punctuation and other characters used -to decorate the content, typically to make it more readable -to human readers. - - -'Anchor content should be decimal width' -++++++++++++++++++++++++++++++++++++++++ - -The message "Anchor content should be decimal width" can be caused by code like: - -:: - - xo_emit("{[:mumble}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:32}"); - -Anchors need an integer value to specify the width of -the set of anchored fields. The value can be positive -(for left padding/right justification) or negative (for -right padding/left justification) and can appear in -either the start or stop anchor field descriptor. - - -'Anchor format should be "%d"' -++++++++++++++++++++++++++++++ - -The message "Anchor format should be "%d"" can be caused by code like: - -:: - - xo_emit("{[:/%s}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:/%d}"); - -Anchors only grok integer values, and if the value is not static, -if must be in an 'int' argument, represented by the "%d" format. -Anything else is an error. - - -'Anchor cannot have both format and encoding format")' -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The message "Anchor cannot have both format and encoding format")" can be caused by code like: - -:: - - xo_emit("{[:32/%d}"); - -This code should be replaced with code like: - -:: - - xo_emit("{[:32}"); - -Anchors can have a static value or argument for the width, -but cannot have both. - - -'Max width only valid for strings' -++++++++++++++++++++++++++++++++++ - -The message "Max width only valid for strings" can be caused by code like: - -:: - - xo_emit("{:tag/%2.4.6d}", 55); - -This code should be replaced with code like: - -:: - - xo_emit("{:tag/%2.6d}", 55); - -libxo allows a true 'max width' in addition to the traditional -printf-style 'max number of bytes to use for input'. But this -is supported only for string values, since it makes no sense -for non-strings. This error may occur from a typo, -like "{:tag/%6..6d}" where only one period should be used. +====== +xolint +====== + +`xolint` is a tool for reporting common mistakes in format strings +in source code that invokes `xo_emit`. It allows these errors +to be diagnosed at build time, rather than waiting until runtime. + +`xolint` takes the one or more C files as arguments, and reports +and errors, warning, or informational messages as needed: + + ============ =================================================== + Option Meaning + ============ =================================================== + -c Invoke 'cpp' against the input file + -C Flags that are passed to 'cpp + -d Enable debug output + -D Generate documentation for all xolint messages + -I Generate info table code + -p Print the offending lines after the message + -V Print vocabulary of all field names + -X Extract samples from xolint, suitable for testing + ============ =================================================== + +The output message will contain the source filename and line number, the +class of the message, the message, and, if -p is given, the +line that contains the error:: + + % xolint.pl -t xolint.c + xolint.c: 16: error: anchor format should be "%d" + 16 xo_emit("{[:/%s}"); + +The "-I" option will generate a table of `xo_info_t`_ structures, +suitable for inclusion in source code. + +.. _xo_info_t: :ref:`field-information` + +The "-V" option does not report errors, but prints a complete list of +all field names, sorted alphabetically. The output can help spot +inconsistencies and spelling errors. diff --git a/contrib/libxo/libxo/Makefile.am b/contrib/libxo/libxo/Makefile.am index a4d94acae19f..9f17527e68ec 100644 --- a/contrib/libxo/libxo/Makefile.am +++ b/contrib/libxo/libxo/Makefile.am @@ -1,95 +1,96 @@ # # 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. if LIBXO_WARNINGS_HIGH LIBXO_WARNINGS = HIGH endif if HAVE_GCC GCC_WARNINGS = yes endif include ${top_srcdir}/warnings.mk libxoincdir = ${includedir}/libxo AM_CFLAGS = \ -I${top_srcdir} \ ${WARNINGS} \ ${GETTEXT_CFLAGS} AM_CFLAGS += \ -DXO_ENCODERDIR=\"${XO_ENCODERDIR}\" lib_LTLIBRARIES = libxo.la LIBS = \ ${GETTEXT_LIBS} libxoinc_HEADERS = \ xo.h \ xo_encoder.h noinst_HEADERS = \ xo_buf.h \ xo_explicit.h \ xo_humanize.h \ xo_wcwidth.h libxo_la_SOURCES = \ libxo.c \ xo_encoder.c \ xo_syslog.c man3_files = \ libxo.3 \ xo_attr.3 \ xo_create.3 \ xo_emit.3 \ xo_emit_err.3 \ xo_err.3 \ xo_error.3 \ xo_finish.3 \ xo_flush.3 \ xo_message.3 \ xo_no_setlocale.3 \ xo_open_container.3 \ xo_open_list.3 \ xo_open_marker.3 \ xo_parse_args.3 \ xo_set_allocator.3 \ xo_set_flags.3 \ xo_set_info.3 \ xo_set_options.3 \ xo_set_style.3 \ xo_set_syslog_enterprise_id.3 \ xo_set_version.3 \ xo_set_writer.3 \ xo_syslog.3 man5_files = \ xo_format.5 man7_files = \ + libxo-csv.7 \ xo_options.7 man_MANS = ${man3_files} ${man5_files} ${man7_files} EXTRA_DIST = \ ${man_MANS} call-graph: ${RM} libxo.o ${MAKE} CC="clang -Xclang -analyze -Xclang \ -analyzer-checker=debug.ViewCallGraph" libxo.o install-data-hook: for file in ${man3_files}; do \ cat ../libxo/add.man >> ${DESTDIR}${man3dir}/$$file ; done for file in ${man5_files}; do \ cat ../libxo/add.man >> ${DESTDIR}${man5dir}/$$file ; done for file in ${man7_files}; do \ cat ../libxo/add.man >> ${DESTDIR}${man7dir}/$$file ; done diff --git a/contrib/libxo/libxo/gen-wide.sh b/contrib/libxo/libxo/gen-wide.sh old mode 100755 new mode 100644 diff --git a/contrib/libxo/libxo/libxo-csv.7 b/contrib/libxo/libxo/libxo-csv.7 new file mode 100644 index 000000000000..6e043820a010 --- /dev/null +++ b/contrib/libxo/libxo/libxo-csv.7 @@ -0,0 +1,274 @@ +.\" # +.\" # Copyright (c) 2021, 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, May 2021 +.\" +.Dd May 13, 2021 +.Dt LIBXO-CSV 7 +.Os +.Sh NAME +.Nm --libxo encoder=csv[+options] +.Nd a CVS encoder for libxo\-based commands +.Sh DESCRIPTION +The +.Nm libxo +library supports a "pluggable" encoder mechanism, and ships with an +encoder for CSV (comma separated values) files. The encoder allows +paths and fields to be selected out of the output contents: +.Bd -literal -offset indent + % df --libxo @csv + name,total-blocks,used-blocks,available-blocks,used-percent,mounted-on + zroot/ROOT/default,3825984331,29376725,3796607605,1,/ + devfs,1,1,0,100,/dev + zroot/usr/home,3808301289,11693684,3796607605,0,/usr/home + zroot/var/audit,3796607806,201,3796607605,0,/var/audit + ... + % df --libxo @csv+leafs=name.used-percent + name,used-percent + zroot/ROOT/default,1 + devfs,100 + zroot/usr/home,0 + zroot/var/audit,0 + ... + % df --libxo @csv+leafs=available-blocks+no-header / + 3796607605 +.Ed + 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. +.Pp +To allow support for additional encodings, libxo includes a +"pluggable" extension mechanism for dynamically loading new encoders. +.Nm libxo -based +applications can automatically use any installed encoder. +.Pp +Use the "encoder=XXX" option to access encoders. The following +example uses the "cbor" encoder, saving the output into a file: +.Bd -literal -offset indent + df --libxo encoder=cbor > df-output.cbor +.Ed +.Pp +Encoders can support specific options that can be accessed by +following the encoder name with a colon (':') or a plus sign ('+') and +one of more options, separated by the same character: +.Bd -literal -offset indent + df --libxo encoder=csv+path=filesystem+leaf=name+no-header + df --libxo encoder=csv:path=filesystem:leaf=name:no-header +.Ed +.Pp +These examples instructs libxo to load the "csv" encoder and pass the +following options: +.Bd -literal -offset indent + path=filesystem + leaf=name + no-header +.Ed +.Pp +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. +.Pp +The string "@" can be used in place of the string "encoder=". +.Bd -literal -offset indent + df --libxo @csv:no-header +.Ed +.Sh The CSV (Comma Separated Values) Encoder +.Nm 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. +.Pp +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. +.Pp +Consider the following XML: +.Bd -literal -offset indent + % 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 + + + +.Ed +.Pp +This output is a list of `instances` (named "item"), each containing a +set of `leafs` ("sku", "name", etc). +.Pp +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: +.Bd -literal -offset indent + % 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 +.Ed +.Pp +Be aware that since the CSV encoder looks for data instances, when +used with +.Nm xo , +the `--instance` option will be needed: +.Bd -literal -offset indent + % xo --libxo encoder=csv --instance foo 'The {:product} is {:status}\n' stereo "in route" + product,status + stereo,in route +.Ed +.Sh 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. +.Pp +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. +.Pp +For example, if the "list-items" application generates other lists, +the user can give "path=top/data/item" as a path: +.Bd -literal -offset indent + % 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 +.Ed +.Pp +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. +.Sh 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). +.Pp +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. +.Pp +The "leafs" option can also be used to exclude leafs, limiting the +output to only those leafs provided. +.Pp +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. +.Pp +So the "leafs" option can be used to expand, limit, and order the set +of leafs. +.Pp +The value of the leafs option should be one or more leaf names, +separated by a period ("."): +.Bd -literal -offset indent + % 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 +.Ed +.Pp +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. +.Sh 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: +.Bd -literal -offset indent + 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 +.Ed +.Pp +There is no reliable mechanism for determining whether this header +line is included, so the consumer must make an assumption. +.Pp +The csv encoder defaults to producing the header line, but the +"no-header" option can be included to avoid the header line. +.Sh 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. +.Sh 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. +.Pp +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. +.Sh Option Handling +The handling of command-line options is complex, since there are three +hierarchies in use, but the rules are: +.Bl -bullet +.It +commas separate +.Nm libxo +options +.Bd -literal -ofset indent + \-\-libxo json,pretty,warn +.Ed +.It +pluses separate encoder options +.Bd -literal -ofset indent +\-\-libxo @csv+dos+no-header,warn +.Ed +.It +periods separate tag names +.Bd -literal -ofset indent +\-\-libxo @csv+leafs=name.used.free+dos,warn +.El +.Sh SEE ALSO +.Xr libxo 3 , +.Xr xo_options 7 +.Sh HISTORY +The +.Nm libxo +library first appeared in +.Fx 11.0 . +The CSV encoder first appeared in +.Fx 13.0 . +.Sh AUTHORS +.Nm libxo +was written by +.An Phil Shafer Aq Mt phil@freebsd.org . + diff --git a/contrib/libxo/libxo/libxo.3 b/contrib/libxo/libxo/libxo.3 index f07962036e07..95c0059865b8 100644 --- a/contrib/libxo/libxo/libxo.3 +++ b/contrib/libxo/libxo/libxo.3 @@ -1,323 +1,414 @@ .\" # .\" # 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 .\" .Dd December 8, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm libxo .Nd library for emitting text, XML, JSON, or HTML output .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Sh DESCRIPTION The functions defined in .Nm are used to generate a choice of .Em TEXT , .Em XML , .Em JSON , or .Em HTML output. A common set of functions are used, with command line switches passed to the library to control the details of the output. .Pp Most commands emit text output aimed at humans. It is designed to be parsed and understood by a user. Humans are gifted at extracting details and pattern matching. Often programmers need to extract information from this human-oriented output. Programmers use tools like .Xr grep 1 , .Xr awk 1 , and regular expressions to ferret out the pieces of information they need. Such solutions are fragile and require updates when output contents change or evolve, requiring testing and validation. .Pp Modern tool developers favor encoding schemes like XML and JSON, which allow trivial parsing and extraction of data. Such formats are simple, well understood, hierarchical, easily parsed, and often integrate easier with common tools and environments. .Pp In addition, modern reality means that more output ends up in web browsers than in terminals, making HTML output valuable. .Pp .Nm allows a single set of function calls in source code to generate traditional text output, as well as XML and JSON formatted data. HTML can also be generated; "
" elements surround the traditional text output, with attributes that detail how to render the data. .Pp There are four encoding styles supported by .Nm : .Bl -bullet .It TEXT output can be display on a terminal session, allowing compatibility with traditional command line usage. .It XML output is suitable for tools like XPath and protocols like NETCONF. .It JSON output can be used for RESTful APIs and integration with languages like Javascript and Python. .It HTML can be matched with a small CSS file to permit rendering in any HTML5 browser. .El .Pp In general, XML and JSON are suitable for encoding data, while TEXT is suited for terminal output and HTML is suited for display in a web browser (see .Xr xohtml 1 ). .Pp +.Nm libxo +uses command line options to trigger rendering behavior. +The following options are recognised: +.Pp +.Bl -tag -width "--libxo" +.It +\-\^\-libxo +.It +\-\^\-libxo= +.It +\-\^\-libxo: +.El +.Pp +Options is a comma-separated list of tokens that correspond to output +styles, flags, or features: +.Pp +.Bl -tag -width "12345678" +.It Sy "Token Action" +.It Dv dtrt +Enable "Do The Right Thing" mode +.It Dv html +Emit HTML output +.It Dv indent=xx +Set the indentation level +.It Dv info +Add info attributes (HTML) +.It Dv json +Emit JSON output +.It Dv keys +Emit the key attribute for keys (XML) +.It Dv log-gettext +Log (via stderr) each +.Xr gettext 3 +string lookup +.It Dv log-syslog +Log (via stderr) each syslog message (via +.Xr xo_syslog 3 ) +.It Dv no-humanize +Ignore the {h:} modifier (TEXT, HTML) +.It Dv no-locale +Do not initialize the locale setting +.It Dv no-retain +Prevent retaining formatting information +.It Dv no-top +Do not emit a top set of braces (JSON) +.It Dv not-first +Pretend the 1st output item was not 1st (JSON) +.It Dv pretty +Emit pretty-printed output +.It Dv retain +Force retaining formatting information +.It Dv text +Emit TEXT output +.It Dv underscores +Replace XML-friendly "-"s with JSON friendly "_"s e +.It Dv units +Add the 'units' (XML) or 'data-units (HTML) attribute +.It Dv warn +Emit warnings when libxo detects bad calls +.It Dv warn-xml +Emit warnings in XML +.It Dv xml +Emit XML output +.It Dv xpath +Add XPath expressions (HTML) +.El +.Pp +The +.Dq brief-options +are single letter commands, designed for those with +too little patience to use real tokens. +No comma separator is used. +.Bl -column "i" +.It Sy "Token Action" +.It "H " "Enable HTML output (XO_STYLE_HTML)" +.It "I " "Enable info output (XOF_INFO)" +.It "i " "Indent by " +.It "J " "Enable JSON output (XO_STYLE_JSON)" +.It "P " "Enable pretty-printed output (XOF_PRETTY)" +.It "T " "Enable text output (XO_STYLE_TEXT)" +.It "W " "Enable warnings (XOF_WARN)" +.It "X " "Enable XML output (XO_STYLE_XML)" +.It "x " "Enable XPath data (XOF_XPATH)" +.El +.Pp +Refer to +.Xr xo_options 7 +for additional option information. +.Pp The .Nm library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced. The application calls a function .Xr xo_emit 3 to product output that is described in a format string. A .Dq field descriptor tells .Nm what the field is and what it means. Each field descriptor is placed in braces with a printf-like format string: .Bd -literal -offset indent xo_emit(" {:lines/%7ju} {:words/%7ju} " "{:characters/%7ju}{d:filename/%s}\\n", linect, wordct, charct, file); .Ed .Pp Each field can have a role, with the 'value' role being the default, and the role tells .Nm how and when to render that field, as well as a .Xr printf 3 Ns -like format string. .Pp Output can then be generated in various style, using the "--libxo" option. .Sh DEFAULT HANDLE Handles give an abstraction for .Nm that encapsulates the state of a stream of output. Handles have the data type "xo_handle_t" and are opaque to the caller. .Pp The library has a default handle that is automatically initialized. By default, this handle will send text style output to standard output. The .Xr xo_set_style 3 and .Xr xo_set_flags 3 functions can be used to change this behavior. .Pp Many .Nm functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed .Dv NULL to access the default handle. .Pp For the typical command that is generating output on standard output, there is no need to create an explicit handle, but they are available when needed, e.g., for daemons that generate multiple streams of output. .Sh FUNCTION OVERVIEW The .Nm library includes the following functions: .Bl -tag -width "xo_close_container_hd" .It Sy "Function Description" .It Fn xo_attr .It Fn xo_attr_h .It Fn xo_attr_hv Allows the caller to emit XML attributes with the next open element. .It Fn xo_create .It Fn xo_create_to_file Allow the caller to create a new handle. Note that .Nm has a default handle that allows the caller to avoid use of an explicitly created handle. Only callers writing to files other than .Dv stdout would need to call .Fn xo_create . .It Fn xo_destroy Frees any resources associated with the handle, including the handle itself. .It Fn xo_emit .It Fn xo_emit_h .It Fn xo_emit_hv Emit formatted output. The .Fa fmt string controls the conversion of the remaining arguments into formatted output. See .Xr xo_format 5 for details. .It Fn xo_emit_warn .It Fn xo_emit_warnx .It Fn xo_emit_warn_c .It Fn xo_emit_warn_hc .It Fn xo_emit_err .It Fn xo_emit_errc .It Fn xo_emit_errx These functions are mildly compatible with their standard libc namesakes, but use the format string defined in .Xr xo_format 5 . While there is an increased cost for converting the strings, the output provided can be richer and more useful. See also .Xr xo_err 3 .It Fn xo_warn .It Fn xo_warnx .It Fn xo_warn_c .It Fn xo_warn_hc .It Fn xo_err .It Fn xo_errc .It Fn xo_errx .It Fn xo_message .It Fn xo_message_c .It Fn xo_message_hc .It Fn xo_message_hcv These functions are meant to be compatible with their standard libc namesakes. .It Fn xo_finish .It Fn xo_finish_h Flush output, close open construct, and complete any pending operations. .It Fn xo_flush .It Fn xo_flush_h Allow the caller to flush any pending output for a handle. .It Fn xo_no_setlocale Direct .Nm to avoid initializing the locale. This function should be called before any other .Nm function is called. .It Fn xo_open_container .It Fn xo_open_container_h .It Fn xo_open_container_hd .It Fn xo_open_container_d .It Fn xo_close_container .It Fn xo_close_container_h .It Fn xo_close_container_hd .It Fn xo_close_container_d Containers a singleton levels of hierarchy, typically used to organize related content. .It Fn xo_open_list_h .It Fn xo_open_list .It Fn xo_open_list_hd .It Fn xo_open_list_d .It Fn xo_open_instance_h .It Fn xo_open_instance .It Fn xo_open_instance_hd .It Fn xo_open_instance_d .It Fn xo_close_instance_h .It Fn xo_close_instance .It Fn xo_close_instance_hd .It Fn xo_close_instance_d .It Fn xo_close_list_h .It Fn xo_close_list .It Fn xo_close_list_hd .It Fn xo_close_list_d Lists are levels of hierarchy that can appear multiple times within the same parent. Two calls are needed to encapsulate them, one for the list and one for each instance of that list. Typically .Fn xo_open_list and .Fn xo_close_list are called outside a for-loop, where .Fn xo_open_instance it called at the top of the loop, and .Fn xo_close_instance is called at the bottom of the loop. .It Fn xo_parse_args Inspects command line arguments for directions to .Nm . This function should be called before .Va argv is inspected by the application. .It Fn xo_set_allocator Instructs .Nm to use an alternative memory allocator and deallocator. .It Fn xo_set_flags .It Fn xo_clear_flags Change the flags set for a handle. .It Fn xo_set_info Provides additional information about elements for use with HTML rendering. .It Fn xo_set_options Changes formatting options used by handle. .It Fn xo_set_style .It Fn xo_set_style_name Changes the output style used by a handle. .It Fn xo_set_writer Instructs .Nm to use an alternative set of low-level output functions. .El .Sh SEE ALSO +.Xr libxo-csv 7, .Xr xo 1 , .Xr xolint 1 , .Xr xo_attr 3 , .Xr xo_create 3 , .Xr xo_emit 3 , .Xr xo_emit_err 3 , .Xr xo_err 3 , .Xr xo_finish 3 , .Xr xo_flush 3 , .Xr xo_no_setlocale 3 , .Xr xo_open_container 3 , .Xr xo_open_list 3 , +.Xr xo_options 7, .Xr xo_parse_args 3 , .Xr xo_set_allocator 3 , .Xr xo_set_flags 3 , .Xr xo_set_info 3 , .Xr xo_set_options 3 , .Xr xo_set_style 3 , .Xr xo_set_writer 3 , .Xr xo_format 5 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/libxo.c b/contrib/libxo/libxo/libxo.c index ea64feb82747..916a111f5af2 100644 --- a/contrib/libxo/libxo/libxo.c +++ b/contrib/libxo/libxo/libxo.c @@ -1,8518 +1,8544 @@ /* * Copyright (c) 2014-2019, 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. * Phil Shafer, July 2014 * * This is the implementation of libxo, the formatting library that * generates multiple styles of output from a single code path. * Command line utilities can have their normal text output while * automation tools can see XML or JSON output, and web tools can use * HTML output that encodes the text output annotated with additional * information. Specialized encoders can be built that allow custom * encoding including binary ones like CBOR, thrift, protobufs, etc. * * Full documentation is available in ./doc/libxo.txt or online at: * http://juniper.github.io/libxo/libxo-manual.html * * For first time readers, the core bits of code to start looking at are: * - xo_do_emit() -- parse and emit a set of fields * - xo_do_emit_fields -- the central function of the library * - xo_do_format_field() -- handles formatting a single field * - xo_transiton() -- the state machine that keeps things sane * and of course the "xo_handle_t" data structure, which carries all * configuration and state. */ #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include "xo_config.h" #include "xo.h" #include "xo_encoder.h" #include "xo_buf.h" #include "xo_explicit.h" /* * We ask wcwidth() to do an impossible job, really. It's supposed to * need to tell us the number of columns consumed to display a unicode * character. It returns that number without any sort of context, but * we know they are characters whose glyph differs based on placement * (end of word, middle of word, etc) and many that affect characters * previously emitted. Without content, it can't hope to tell us. * But it's the only standard tool we've got, so we use it. We would * use wcswidth() but it typically just loops through adding the results * of wcwidth() calls in an entirely unhelpful way. * * Even then, there are many poor implementations (macosx), so we have * to carry our own. We could have configure.ac test this (with * something like 'assert(wcwidth(0x200d) == 0)'), but it would have * to run a binary, which breaks cross-compilation. Hmm... I could * run this test at init time and make a warning for our dear user. * * Anyhow, it remains a best-effort sort of thing. And it's all made * more hopeless because we assume the display code doing the rendering is * playing by the same rules we are. If it display 0x200d as a square * box or a funky question mark, the output will be hosed. */ #ifdef LIBXO_WCWIDTH #include "xo_wcwidth.h" #else /* LIBXO_WCWIDTH */ #define xo_wcwidth(_x) wcwidth(_x) #endif /* LIBXO_WCWIDTH */ #ifdef HAVE_STDIO_EXT_H #include #endif /* HAVE_STDIO_EXT_H */ /* * humanize_number is a great function, unless you don't have it. So * we carry one in our pocket. */ #ifdef HAVE_HUMANIZE_NUMBER #include #define xo_humanize_number humanize_number #else /* HAVE_HUMANIZE_NUMBER */ #include "xo_humanize.h" #endif /* HAVE_HUMANIZE_NUMBER */ #ifdef HAVE_GETTEXT #include #endif /* HAVE_GETTEXT */ /* Rather lame that we can't count on these... */ #ifndef FALSE #define FALSE 0 #endif #ifndef TRUE #define TRUE 1 #endif /* * Three styles of specifying thread-local variables are supported. * configure.ac has the brains to run each possibility through the * compiler and see what works; we are left to define the THREAD_LOCAL * macro to the right value. Most toolchains (clang, gcc) use * "before", but some (borland) use "after" and I've heard of some * (ms) that use __declspec. Any others out there? */ #define THREAD_LOCAL_before 1 #define THREAD_LOCAL_after 2 #define THREAD_LOCAL_declspec 3 #ifndef HAVE_THREAD_LOCAL #define THREAD_LOCAL(_x) _x #elif HAVE_THREAD_LOCAL == THREAD_LOCAL_before #define THREAD_LOCAL(_x) __thread _x #elif HAVE_THREAD_LOCAL == THREAD_LOCAL_after #define THREAD_LOCAL(_x) _x __thread #elif HAVE_THREAD_LOCAL == THREAD_LOCAL_declspec #define THREAD_LOCAL(_x) __declspec(_x) #else #error unknown thread-local setting #endif /* HAVE_THREADS_H */ const char xo_version[] = LIBXO_VERSION; const char xo_version_extra[] = LIBXO_VERSION_EXTRA; static const char xo_default_format[] = "%s"; #ifndef UNUSED #define UNUSED __attribute__ ((__unused__)) #endif /* UNUSED */ #define XO_INDENT_BY 2 /* Amount to indent when pretty printing */ #define XO_DEPTH 128 /* Default stack depth */ #define XO_MAX_ANCHOR_WIDTH (8*1024) /* Anything wider is just silly */ #define XO_FAILURE_NAME "failure" /* Flags for the stack frame */ typedef unsigned xo_xsf_flags_t; /* XSF_* flags */ #define XSF_NOT_FIRST (1<<0) /* Not the first element */ #define XSF_LIST (1<<1) /* Frame is a list */ #define XSF_INSTANCE (1<<2) /* Frame is an instance */ #define XSF_DTRT (1<<3) /* Save the name for DTRT mode */ #define XSF_CONTENT (1<<4) /* Some content has been emitted */ #define XSF_EMIT (1<<5) /* Some field has been emitted */ #define XSF_EMIT_KEY (1<<6) /* A key has been emitted */ #define XSF_EMIT_LEAF_LIST (1<<7) /* A leaf-list field has been emitted */ /* These are the flags we propagate between markers and their parents */ #define XSF_MARKER_FLAGS \ (XSF_NOT_FIRST | XSF_CONTENT | XSF_EMIT | XSF_EMIT_KEY | XSF_EMIT_LEAF_LIST ) /* * Turn the transition between two states into a number suitable for * a "switch" statement. */ #define XSS_TRANSITION(_old, _new) ((_old) << 8 | (_new)) /* * xo_stack_t: As we open and close containers and levels, we * create a stack of frames to track them. This is needed for * XOF_WARN and XOF_XPATH. */ typedef struct xo_stack_s { xo_xsf_flags_t xs_flags; /* Flags for this frame */ xo_state_t xs_state; /* State for this stack frame */ char *xs_name; /* Name (for XPath value) */ char *xs_keys; /* XPath predicate for any key fields */ } xo_stack_t; /* * libxo supports colors and effects, for those who like them. * XO_COL_* ("colors") refers to fancy ansi codes, while X__EFF_* * ("effects") are bits since we need to maintain state. */ typedef uint8_t xo_color_t; #define XO_COL_DEFAULT 0 #define XO_COL_BLACK 1 #define XO_COL_RED 2 #define XO_COL_GREEN 3 #define XO_COL_YELLOW 4 #define XO_COL_BLUE 5 #define XO_COL_MAGENTA 6 #define XO_COL_CYAN 7 #define XO_COL_WHITE 8 #define XO_NUM_COLORS 9 /* * Yes, there's no blink. We're civilized. We like users. Blink * isn't something one does to someone you like. Friends don't let * friends use blink. On friends. You know what I mean. Blink is * like, well, it's like bursting into show tunes at a funeral. It's * just not done. Not something anyone wants. And on those rare * instances where it might actually be appropriate, it's still wrong, * since it's likely done by the wrong person for the wrong reason. * Just like blink. And if I implemented blink, I'd be like a funeral * director who adds "Would you like us to burst into show tunes?" on * the list of questions asked while making funeral arrangements. * It's formalizing wrongness in the wrong way. And we're just too * civilized to do that. Hhhmph! */ #define XO_EFF_RESET (1<<0) #define XO_EFF_NORMAL (1<<1) #define XO_EFF_BOLD (1<<2) #define XO_EFF_UNDERLINE (1<<3) #define XO_EFF_INVERSE (1<<4) #define XO_EFF_CLEAR_BITS XO_EFF_RESET /* Reset gets reset, surprisingly */ typedef uint8_t xo_effect_t; typedef struct xo_colors_s { xo_effect_t xoc_effects; /* Current effect set */ xo_color_t xoc_col_fg; /* Foreground color */ xo_color_t xoc_col_bg; /* Background color */ } xo_colors_t; /* * xo_handle_t: this is the principle data structure for libxo. * It's used as a store for state, options, content, and all manor * of other information. */ struct xo_handle_s { xo_xof_flags_t xo_flags; /* Flags (XOF_*) from the user*/ xo_xof_flags_t xo_iflags; /* Internal flags (XOIF_*) */ xo_style_t xo_style; /* XO_STYLE_* value */ unsigned short xo_indent; /* Indent level (if pretty) */ unsigned short xo_indent_by; /* Indent amount (tab stop) */ xo_write_func_t xo_write; /* Write callback */ xo_close_func_t xo_close; /* Close callback */ xo_flush_func_t xo_flush; /* Flush callback */ xo_formatter_t xo_formatter; /* Custom formating function */ xo_checkpointer_t xo_checkpointer; /* Custom formating support function */ void *xo_opaque; /* Opaque data for write function */ xo_buffer_t xo_data; /* Output data */ xo_buffer_t xo_fmt; /* Work area for building format strings */ xo_buffer_t xo_attrs; /* Work area for building XML attributes */ xo_buffer_t xo_predicate; /* Work area for building XPath predicates */ xo_stack_t *xo_stack; /* Stack pointer */ int xo_depth; /* Depth of stack */ int xo_stack_size; /* Size of the stack */ xo_info_t *xo_info; /* Info fields for all elements */ int xo_info_count; /* Number of info entries */ va_list xo_vap; /* Variable arguments (stdargs) */ char *xo_leading_xpath; /* A leading XPath expression */ mbstate_t xo_mbstate; /* Multi-byte character conversion state */ ssize_t xo_anchor_offset; /* Start of anchored text */ ssize_t xo_anchor_columns; /* Number of columns since the start anchor */ ssize_t xo_anchor_min_width; /* Desired width of anchored text */ ssize_t xo_units_offset; /* Start of units insertion point */ ssize_t xo_columns; /* Columns emitted during this xo_emit call */ #ifndef LIBXO_TEXT_ONLY xo_color_t xo_color_map_fg[XO_NUM_COLORS]; /* Foreground color mappings */ xo_color_t xo_color_map_bg[XO_NUM_COLORS]; /* Background color mappings */ #endif /* LIBXO_TEXT_ONLY */ xo_colors_t xo_colors; /* Current color and effect values */ xo_buffer_t xo_color_buf; /* HTML: buffer of colors and effects */ char *xo_version; /* Version string */ int xo_errno; /* Saved errno for "%m" */ char *xo_gt_domain; /* Gettext domain, suitable for dgettext(3) */ xo_encoder_func_t xo_encoder; /* Encoding function */ void *xo_private; /* Private data for external encoders */ }; /* Flag operations */ #define XOF_BIT_ISSET(_flag, _bit) (((_flag) & (_bit)) ? 1 : 0) #define XOF_BIT_SET(_flag, _bit) do { (_flag) |= (_bit); } while (0) #define XOF_BIT_CLEAR(_flag, _bit) do { (_flag) &= ~(_bit); } while (0) #define XOF_ISSET(_xop, _bit) XOF_BIT_ISSET(_xop->xo_flags, _bit) #define XOF_SET(_xop, _bit) XOF_BIT_SET(_xop->xo_flags, _bit) #define XOF_CLEAR(_xop, _bit) XOF_BIT_CLEAR(_xop->xo_flags, _bit) #define XOIF_ISSET(_xop, _bit) XOF_BIT_ISSET(_xop->xo_iflags, _bit) #define XOIF_SET(_xop, _bit) XOF_BIT_SET(_xop->xo_iflags, _bit) #define XOIF_CLEAR(_xop, _bit) XOF_BIT_CLEAR(_xop->xo_iflags, _bit) /* Internal flags */ #define XOIF_REORDER XOF_BIT(0) /* Reordering fields; record field info */ #define XOIF_DIV_OPEN XOF_BIT(1) /* A
is open */ #define XOIF_TOP_EMITTED XOF_BIT(2) /* The top JSON braces have been emitted */ #define XOIF_ANCHOR XOF_BIT(3) /* An anchor is in place */ #define XOIF_UNITS_PENDING XOF_BIT(4) /* We have a units-insertion pending */ #define XOIF_INIT_IN_PROGRESS XOF_BIT(5) /* Init of handle is in progress */ #define XOIF_MADE_OUTPUT XOF_BIT(6) /* Have already made output */ /* * Normal printf has width and precision, which for strings operate as * min and max number of columns. But this depends on the idea that * one byte means one column, which UTF-8 and multi-byte characters * pitches on its ear. It may take 40 bytes of data to populate 14 * columns, but we can't go off looking at 40 bytes of data without the * caller's permission for fear/knowledge that we'll generate core files. * * So we make three values, distinguishing between "max column" and * "number of bytes that we will inspect inspect safely" We call the * later "size", and make the format "%[[].[[].]]s". * * Under the "first do no harm" theory, we default "max" to "size". * This is a reasonable assumption for folks that don't grok the * MBS/WCS/UTF-8 world, and while it will be annoying, it will never * be evil. * * For example, xo_emit("{:tag/%-14.14s}", buf) will make 14 * columns of output, but will never look at more than 14 bytes of the * input buffer. This is mostly compatible with printf and caller's * expectations. * * In contrast xo_emit("{:tag/%-14..14s}", buf) will look at however * many bytes (or until a NUL is seen) are needed to fill 14 columns * of output. xo_emit("{:tag/%-14.*.14s}", xx, buf) will look at up * to xx bytes (or until a NUL is seen) in order to fill 14 columns * of output. * * It's fairly amazing how a good idea (handle all languages of the * world) blows such a big hole in the bottom of the fairly weak boat * that is C string handling. The simplicity and completenesss are * sunk in ways we haven't even begun to understand. */ #define XF_WIDTH_MIN 0 /* Minimal width */ #define XF_WIDTH_SIZE 1 /* Maximum number of bytes to examine */ #define XF_WIDTH_MAX 2 /* Maximum width */ #define XF_WIDTH_NUM 3 /* Numeric fields in printf (min.size.max) */ /* Input and output string encodings */ #define XF_ENC_WIDE 1 /* Wide characters (wchar_t) */ #define XF_ENC_UTF8 2 /* UTF-8 */ #define XF_ENC_LOCALE 3 /* Current locale */ /* * A place to parse printf-style format flags for each field */ typedef struct xo_format_s { unsigned char xf_fc; /* Format character */ unsigned char xf_enc; /* Encoding of the string (XF_ENC_*) */ unsigned char xf_skip; /* Skip this field */ unsigned char xf_lflag; /* 'l' (long) */ unsigned char xf_hflag;; /* 'h' (half) */ unsigned char xf_jflag; /* 'j' (intmax_t) */ unsigned char xf_tflag; /* 't' (ptrdiff_t) */ unsigned char xf_zflag; /* 'z' (size_t) */ unsigned char xf_qflag; /* 'q' (quad_t) */ unsigned char xf_seen_minus; /* Seen a minus */ int xf_leading_zero; /* Seen a leading zero (zero fill) */ unsigned xf_dots; /* Seen one or more '.'s */ int xf_width[XF_WIDTH_NUM]; /* Width/precision/size numeric fields */ unsigned xf_stars; /* Seen one or more '*'s */ unsigned char xf_star[XF_WIDTH_NUM]; /* Seen one or more '*'s */ } xo_format_t; /* * This structure represents the parsed field information, suitable for * processing by xo_do_emit and anything else that needs to parse fields. * Note that all pointers point to the main format string. * * XXX This is a first step toward compilable or cachable format * strings. We can also cache the results of dgettext when no format * is used, assuming the 'p' modifier has _not_ been set. */ typedef struct xo_field_info_s { xo_xff_flags_t xfi_flags; /* Flags for this field */ unsigned xfi_ftype; /* Field type, as character (e.g. 'V') */ const char *xfi_start; /* Start of field in the format string */ const char *xfi_content; /* Field's content */ const char *xfi_format; /* Field's Format */ const char *xfi_encoding; /* Field's encoding format */ const char *xfi_next; /* Next character in format string */ ssize_t xfi_len; /* Length of field */ ssize_t xfi_clen; /* Content length */ ssize_t xfi_flen; /* Format length */ ssize_t xfi_elen; /* Encoding length */ unsigned xfi_fnum; /* Field number (if used; 0 otherwise) */ unsigned xfi_renum; /* Reordered number (0 == no renumbering) */ } xo_field_info_t; /* * We keep a 'default' handle to allow callers to avoid having to * allocate one. Passing NULL to any of our functions will use * this default handle. Most functions have a variant that doesn't * require a handle at all, since most output is to stdout, which * the default handle handles handily. */ static THREAD_LOCAL(xo_handle_t) xo_default_handle; static THREAD_LOCAL(int) xo_default_inited; static int xo_locale_inited; static const char *xo_program; /* * To allow libxo to be used in diverse environment, we allow the * caller to give callbacks for memory allocation. */ xo_realloc_func_t xo_realloc = realloc; xo_free_func_t xo_free = free; /* Forward declarations */ static ssize_t xo_transition (xo_handle_t *xop, xo_xof_flags_t flags, const char *name, xo_state_t new_state); static int xo_set_options_simple (xo_handle_t *xop, const char *input); static int xo_color_find (const char *str); static void xo_buf_append_div (xo_handle_t *xop, const char *class, xo_xff_flags_t flags, const char *name, ssize_t nlen, const char *value, ssize_t vlen, const char *fmt, ssize_t flen, const char *encoding, ssize_t elen); static void xo_anchor_clear (xo_handle_t *xop); /* * xo_style is used to retrieve the current style. When we're built * for "text only" mode, we use this function to drive the removal * of most of the code in libxo. We return a constant and the compiler * happily removes the non-text code that is not longer executed. This * trims our code nicely without needing to trampel perfectly readable * code with ifdefs. */ static inline xo_style_t xo_style (xo_handle_t *xop UNUSED) { #ifdef LIBXO_TEXT_ONLY return XO_STYLE_TEXT; #else /* LIBXO_TEXT_ONLY */ return xop->xo_style; #endif /* LIBXO_TEXT_ONLY */ } /* * Allow the compiler to optimize out non-text-only code while * still compiling it. */ static inline int xo_text_only (void) { #ifdef LIBXO_TEXT_ONLY return TRUE; #else /* LIBXO_TEXT_ONLY */ return FALSE; #endif /* LIBXO_TEXT_ONLY */ } /* * Callback to write data to a FILE pointer */ static xo_ssize_t xo_write_to_file (void *opaque, const char *data) { FILE *fp = (FILE *) opaque; return fprintf(fp, "%s", data); } /* * Callback to close a file */ static void xo_close_file (void *opaque) { FILE *fp = (FILE *) opaque; fclose(fp); } /* * Callback to flush a FILE pointer */ static int xo_flush_file (void *opaque) { FILE *fp = (FILE *) opaque; return fflush(fp); } /* * Use a rotating stock of buffers to make a printable string */ #define XO_NUMBUFS 8 #define XO_SMBUFSZ 128 static const char * xo_printable (const char *str) { static THREAD_LOCAL(char) bufset[XO_NUMBUFS][XO_SMBUFSZ]; static THREAD_LOCAL(int) bufnum = 0; if (str == NULL) return ""; if (++bufnum == XO_NUMBUFS) bufnum = 0; char *res = bufset[bufnum], *cp, *ep; for (cp = res, ep = res + XO_SMBUFSZ - 1; *str && cp < ep; cp++, str++) { if (*str == '\n') { *cp++ = '\\'; *cp = 'n'; } else if (*str == '\r') { *cp++ = '\\'; *cp = 'r'; } else if (*str == '\"') { *cp++ = '\\'; *cp = '"'; } else *cp = *str; } *cp = '\0'; return res; } static int xo_depth_check (xo_handle_t *xop, int depth) { xo_stack_t *xsp; if (depth >= xop->xo_stack_size) { depth += XO_DEPTH; /* Extra room */ xsp = xo_realloc(xop->xo_stack, sizeof(xop->xo_stack[0]) * depth); if (xsp == NULL) { xo_failure(xop, "xo_depth_check: out of memory (%d)", depth); return -1; } int count = depth - xop->xo_stack_size; bzero(xsp + xop->xo_stack_size, count * sizeof(*xsp)); xop->xo_stack_size = depth; xop->xo_stack = xsp; } return 0; } void xo_no_setlocale (void) { xo_locale_inited = 1; /* Skip initialization */ } /* * For XML, the first character of a tag cannot be numeric, but people * will likely not notice. So we people-proof them by forcing a leading * underscore if they use invalid tags. Note that this doesn't cover * all broken tags, just this fairly specific case. */ static const char * xo_xml_leader_len (xo_handle_t *xop, const char *name, xo_ssize_t nlen) { if (name == NULL || isalpha(name[0]) || name[0] == '_') return ""; xo_failure(xop, "invalid XML tag name: '%.*s'", nlen, name); return "_"; } static const char * xo_xml_leader (xo_handle_t *xop, const char *name) { return xo_xml_leader_len(xop, name, strlen(name)); } /* * We need to decide if stdout is line buffered (_IOLBF). Lacking a * standard way to decide this (e.g. getlinebuf()), we have configure * look to find __flbf, which glibc supported. If not, we'll rely on * isatty, with the assumption that terminals are the only thing * that's line buffered. We _could_ test for "steam._flags & _IOLBF", * which is all __flbf does, but that's even tackier. Like a * bedazzled Elvis outfit on an ugly lap dog sort of tacky. Not * something we're willing to do. */ static int xo_is_line_buffered (FILE *stream) { #if HAVE___FLBF if (__flbf(stream)) return 1; #else /* HAVE___FLBF */ if (isatty(fileno(stream))) return 1; #endif /* HAVE___FLBF */ return 0; } /* * Initialize an xo_handle_t, using both static defaults and * the global settings from the LIBXO_OPTIONS environment * variable. */ static void xo_init_handle (xo_handle_t *xop) { xop->xo_opaque = stdout; xop->xo_write = xo_write_to_file; xop->xo_flush = xo_flush_file; if (xo_is_line_buffered(stdout)) XOF_SET(xop, XOF_FLUSH_LINE); /* * We need to initialize the locale, which isn't really pretty. * Libraries should depend on their caller to set up the * environment. But we really can't count on the caller to do * this, because well, they won't. Trust me. */ if (!xo_locale_inited) { xo_locale_inited = 1; /* Only do this once */ #ifdef __FreeBSD__ /* Who does The Right Thing */ const char *cp = ""; #else /* __FreeBSD__ */ const char *cp = getenv("LC_ALL"); if (cp == NULL) cp = getenv("LC_CTYPE"); if (cp == NULL) cp = getenv("LANG"); if (cp == NULL) cp = "C"; /* Default for C programs */ #endif /* __FreeBSD__ */ (void) setlocale(LC_CTYPE, cp); } /* * Initialize only the xo_buffers we know we'll need; the others * can be allocated as needed. */ xo_buf_init(&xop->xo_data); xo_buf_init(&xop->xo_fmt); if (XOIF_ISSET(xop, XOIF_INIT_IN_PROGRESS)) return; XOIF_SET(xop, XOIF_INIT_IN_PROGRESS); xop->xo_indent_by = XO_INDENT_BY; xo_depth_check(xop, XO_DEPTH); XOIF_CLEAR(xop, XOIF_INIT_IN_PROGRESS); } /* * Initialize the default handle. */ static void xo_default_init (void) { xo_handle_t *xop = &xo_default_handle; xo_init_handle(xop); #if !defined(NO_LIBXO_OPTIONS) if (!XOF_ISSET(xop, XOF_NO_ENV)) { char *env = getenv("LIBXO_OPTIONS"); if (env) xo_set_options_simple(xop, env); } #endif /* NO_LIBXO_OPTIONS */ xo_default_inited = 1; } /* * Cheap convenience function to return either the argument, or * the internal handle, after it has been initialized. The usage * is: * xop = xo_default(xop); */ static xo_handle_t * xo_default (xo_handle_t *xop) { if (xop == NULL) { if (xo_default_inited == 0) xo_default_init(); xop = &xo_default_handle; } return xop; } /* * Return the number of spaces we should be indenting. If * we are pretty-printing, this is indent * indent_by. */ static int xo_indent (xo_handle_t *xop) { int rc = 0; xop = xo_default(xop); if (XOF_ISSET(xop, XOF_PRETTY)) { rc = xop->xo_indent * xop->xo_indent_by; if (XOIF_ISSET(xop, XOIF_TOP_EMITTED)) rc += xop->xo_indent_by; } return (rc > 0) ? rc : 0; } static void xo_buf_indent (xo_handle_t *xop, int indent) { xo_buffer_t *xbp = &xop->xo_data; if (indent <= 0) indent = xo_indent(xop); if (!xo_buf_has_room(xbp, indent)) return; memset(xbp->xb_curp, ' ', indent); xbp->xb_curp += indent; } static char xo_xml_amp[] = "&"; static char xo_xml_lt[] = "<"; static char xo_xml_gt[] = ">"; static char xo_xml_quot[] = """; static ssize_t xo_escape_xml (xo_buffer_t *xbp, ssize_t len, xo_xff_flags_t flags) { ssize_t slen; ssize_t delta = 0; char *cp, *ep, *ip; const char *sp; int attr = XOF_BIT_ISSET(flags, XFF_ATTR); for (cp = xbp->xb_curp, ep = cp + len; cp < ep; cp++) { /* We're subtracting 2: 1 for the NUL, 1 for the char we replace */ if (*cp == '<') delta += sizeof(xo_xml_lt) - 2; else if (*cp == '>') delta += sizeof(xo_xml_gt) - 2; else if (*cp == '&') delta += sizeof(xo_xml_amp) - 2; else if (attr && *cp == '"') delta += sizeof(xo_xml_quot) - 2; } if (delta == 0) /* Nothing to escape; bail */ return len; if (!xo_buf_has_room(xbp, delta)) /* No room; bail, but don't append */ return 0; ep = xbp->xb_curp; cp = ep + len; ip = cp + delta; do { cp -= 1; ip -= 1; if (*cp == '<') sp = xo_xml_lt; else if (*cp == '>') sp = xo_xml_gt; else if (*cp == '&') sp = xo_xml_amp; else if (attr && *cp == '"') sp = xo_xml_quot; else { *ip = *cp; continue; } slen = strlen(sp); ip -= slen - 1; memcpy(ip, sp, slen); } while (cp > ep && cp != ip); return len + delta; } static ssize_t xo_escape_json (xo_buffer_t *xbp, ssize_t len, xo_xff_flags_t flags UNUSED) { ssize_t delta = 0; char *cp, *ep, *ip; for (cp = xbp->xb_curp, ep = cp + len; cp < ep; cp++) { if (*cp == '\\' || *cp == '"') delta += 1; else if (*cp == '\n' || *cp == '\r') delta += 1; } if (delta == 0) /* Nothing to escape; bail */ return len; if (!xo_buf_has_room(xbp, delta)) /* No room; bail, but don't append */ return 0; ep = xbp->xb_curp; cp = ep + len; ip = cp + delta; do { cp -= 1; ip -= 1; if (*cp == '\\' || *cp == '"') { *ip-- = *cp; *ip = '\\'; } else if (*cp == '\n') { *ip-- = 'n'; *ip = '\\'; } else if (*cp == '\r') { *ip-- = 'r'; *ip = '\\'; } else { *ip = *cp; } } while (cp > ep && cp != ip); return len + delta; } /* * PARAM-VALUE = UTF-8-STRING ; characters '"', '\' and * ; ']' MUST be escaped. */ static ssize_t xo_escape_sdparams (xo_buffer_t *xbp, ssize_t len, xo_xff_flags_t flags UNUSED) { ssize_t delta = 0; char *cp, *ep, *ip; for (cp = xbp->xb_curp, ep = cp + len; cp < ep; cp++) { if (*cp == '\\' || *cp == '"' || *cp == ']') delta += 1; } if (delta == 0) /* Nothing to escape; bail */ return len; if (!xo_buf_has_room(xbp, delta)) /* No room; bail, but don't append */ return 0; ep = xbp->xb_curp; cp = ep + len; ip = cp + delta; do { cp -= 1; ip -= 1; if (*cp == '\\' || *cp == '"' || *cp == ']') { *ip-- = *cp; *ip = '\\'; } else { *ip = *cp; } } while (cp > ep && cp != ip); return len + delta; } static void xo_buf_escape (xo_handle_t *xop, xo_buffer_t *xbp, const char *str, ssize_t len, xo_xff_flags_t flags) { if (!xo_buf_has_room(xbp, len)) return; memcpy(xbp->xb_curp, str, len); switch (xo_style(xop)) { case XO_STYLE_XML: case XO_STYLE_HTML: len = xo_escape_xml(xbp, len, flags); break; case XO_STYLE_JSON: len = xo_escape_json(xbp, len, flags); break; case XO_STYLE_SDPARAMS: len = xo_escape_sdparams(xbp, len, flags); break; } xbp->xb_curp += len; } /* * Write the current contents of the data buffer using the handle's * xo_write function. */ static ssize_t xo_write (xo_handle_t *xop) { ssize_t rc = 0; xo_buffer_t *xbp = &xop->xo_data; if (xbp->xb_curp != xbp->xb_bufp) { xo_buf_append(xbp, "", 1); /* Append ending NUL */ xo_anchor_clear(xop); if (xop->xo_write) rc = xop->xo_write(xop->xo_opaque, xbp->xb_bufp); xbp->xb_curp = xbp->xb_bufp; } /* Turn off the flags that don't survive across writes */ XOIF_CLEAR(xop, XOIF_UNITS_PENDING); return rc; } /* * Format arguments into our buffer. If a custom formatter has been set, * we use that to do the work; otherwise we vsnprintf(). */ static ssize_t xo_vsnprintf (xo_handle_t *xop, xo_buffer_t *xbp, const char *fmt, va_list vap) { va_list va_local; ssize_t rc; ssize_t left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); va_copy(va_local, vap); if (xop->xo_formatter) rc = xop->xo_formatter(xop, xbp->xb_curp, left, fmt, va_local); else rc = vsnprintf(xbp->xb_curp, left, fmt, va_local); if (rc >= left) { if (!xo_buf_has_room(xbp, rc)) { va_end(va_local); return -1; } /* * After we call vsnprintf(), the stage of vap is not defined. * We need to copy it before we pass. Then we have to do our * own logic below to move it along. This is because the * implementation can have va_list be a pointer (bsd) or a * structure (macosx) or anything in between. */ va_end(va_local); /* Reset vap to the start */ va_copy(va_local, vap); left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); if (xop->xo_formatter) rc = xop->xo_formatter(xop, xbp->xb_curp, left, fmt, va_local); else rc = vsnprintf(xbp->xb_curp, left, fmt, va_local); } va_end(va_local); return rc; } /* * Print some data through the handle. */ static ssize_t xo_printf_v (xo_handle_t *xop, const char *fmt, va_list vap) { xo_buffer_t *xbp = &xop->xo_data; ssize_t left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); ssize_t rc; va_list va_local; va_copy(va_local, vap); rc = vsnprintf(xbp->xb_curp, left, fmt, va_local); if (rc >= left) { if (!xo_buf_has_room(xbp, rc)) { va_end(va_local); return -1; } va_end(va_local); /* Reset vap to the start */ va_copy(va_local, vap); left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); rc = vsnprintf(xbp->xb_curp, left, fmt, va_local); } va_end(va_local); if (rc > 0) xbp->xb_curp += rc; return rc; } static ssize_t xo_printf (xo_handle_t *xop, const char *fmt, ...) { ssize_t rc; va_list vap; va_start(vap, fmt); rc = xo_printf_v(xop, fmt, vap); va_end(vap); return rc; } /* * These next few function are make The Essential UTF-8 Ginsu Knife. * Identify an input and output character, and convert it. */ static uint8_t xo_utf8_data_bits[5] = { 0, 0x7f, 0x1f, 0x0f, 0x07 }; static uint8_t xo_utf8_len_bits[5] = { 0, 0x00, 0xc0, 0xe0, 0xf0 }; /* * If the byte has a high-bit set, it's UTF-8, not ASCII. */ static int xo_is_utf8 (char ch) { return (ch & 0x80); } /* * Look at the high bits of the first byte to determine the length * of the UTF-8 character. */ static inline ssize_t xo_utf8_to_wc_len (const char *buf) { uint8_t bval = (uint8_t) *buf; ssize_t len; if ((bval & 0x80) == 0x0) len = 1; else if ((bval & 0xe0) == 0xc0) len = 2; else if ((bval & 0xf0) == 0xe0) len = 3; else if ((bval & 0xf8) == 0xf0) len = 4; else len = -1; return len; } static ssize_t xo_buf_utf8_len (xo_handle_t *xop, const char *buf, ssize_t bufsiz) { unsigned b = (unsigned char) *buf; ssize_t len, i; len = xo_utf8_to_wc_len(buf); if (len < 0) { xo_failure(xop, "invalid UTF-8 data: %02hhx", b); return -1; } if (len > bufsiz) { xo_failure(xop, "invalid UTF-8 data (short): %02hhx (%d/%d)", b, len, bufsiz); return -1; } for (i = 2; i < len; i++) { b = (unsigned char ) buf[i]; if ((b & 0xc0) != 0x80) { xo_failure(xop, "invalid UTF-8 data (byte %d): %x", i, b); return -1; } } return len; } /* * Build a wide character from the input buffer; the number of * bits we pull off the first character is dependent on the length, * but we put 6 bits off all other bytes. */ static inline wchar_t xo_utf8_char (const char *buf, ssize_t len) { /* Most common case: singleton byte */ if (len == 1) return (unsigned char) buf[0]; ssize_t i; wchar_t wc; const unsigned char *cp = (const unsigned char *) buf; wc = *cp & xo_utf8_data_bits[len]; for (i = 1; i < len; i++) { wc <<= 6; /* Low six bits have data */ wc |= cp[i] & 0x3f; if ((cp[i] & 0xc0) != 0x80) return (wchar_t) -1; } return wc; } /* * Determine the number of bytes needed to encode a wide character. */ static ssize_t xo_utf8_emit_len (wchar_t wc) { ssize_t len; if ((wc & ((1 << 7) - 1)) == wc) /* Simple case */ len = 1; else if ((wc & ((1 << 11) - 1)) == wc) len = 2; else if ((wc & ((1 << 16) - 1)) == wc) len = 3; else if ((wc & ((1 << 21) - 1)) == wc) len = 4; else len = -1; /* Invalid */ return len; } /* * Emit one wide character into the given buffer */ static void xo_utf8_emit_char (char *buf, ssize_t len, wchar_t wc) { ssize_t i; if (len == 1) { /* Simple case */ buf[0] = wc & 0x7f; return; } /* Start with the low bits and insert them, six bits at a time */ for (i = len - 1; i >= 0; i--) { buf[i] = 0x80 | (wc & 0x3f); wc >>= 6; /* Drop the low six bits */ } /* Finish off the first byte with the length bits */ buf[0] &= xo_utf8_data_bits[len]; /* Clear out the length bits */ buf[0] |= xo_utf8_len_bits[len]; /* Drop in new length bits */ } /* * Append a single UTF-8 character to a buffer, converting it to locale * encoding. Returns the number of columns consumed by that character, * as best we can determine it. */ static ssize_t xo_buf_append_locale_from_utf8 (xo_handle_t *xop, xo_buffer_t *xbp, const char *ibuf, ssize_t ilen) { wchar_t wc; ssize_t len; /* * Build our wide character from the input buffer; the number of * bits we pull off the first character is dependent on the length, * but we put 6 bits off all other bytes. */ wc = xo_utf8_char(ibuf, ilen); if (wc == (wchar_t) -1) { xo_failure(xop, "invalid UTF-8 byte sequence"); return 0; } if (XOF_ISSET(xop, XOF_NO_LOCALE)) { if (!xo_buf_has_room(xbp, ilen)) return 0; memcpy(xbp->xb_curp, ibuf, ilen); xbp->xb_curp += ilen; } else { if (!xo_buf_has_room(xbp, MB_LEN_MAX + 1)) return 0; bzero(&xop->xo_mbstate, sizeof(xop->xo_mbstate)); len = wcrtomb(xbp->xb_curp, wc, &xop->xo_mbstate); if (len <= 0) { xo_failure(xop, "could not convert wide char: %lx", (unsigned long) wc); return 0; } xbp->xb_curp += len; } return xo_wcwidth(wc); } /* * Append a UTF-8 string to a buffer, converting it into locale encoding */ static void xo_buf_append_locale (xo_handle_t *xop, xo_buffer_t *xbp, const char *cp, ssize_t len) { const char *sp = cp, *ep = cp + len; ssize_t save_off = xbp->xb_bufp - xbp->xb_curp; ssize_t slen; int cols = 0; for ( ; cp < ep; cp++) { if (!xo_is_utf8(*cp)) { cols += 1; continue; } /* * We're looking at a non-ascii UTF-8 character. * First we copy the previous data. * Then we need find the length and validate it. * Then we turn it into a wide string. * Then we turn it into a localized string. * Then we repeat. Isn't i18n fun? */ if (sp != cp) xo_buf_append(xbp, sp, cp - sp); /* Append previous data */ slen = xo_buf_utf8_len(xop, cp, ep - cp); if (slen <= 0) { /* Bad data; back it all out */ xbp->xb_curp = xbp->xb_bufp + save_off; return; } cols += xo_buf_append_locale_from_utf8(xop, xbp, cp, slen); /* Next time through, we'll start at the next character */ cp += slen - 1; sp = cp + 1; } /* Update column values */ if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += cols; /* Before we fall into the basic logic below, we need reset len */ len = ep - sp; if (len != 0) /* Append trailing data */ xo_buf_append(xbp, sp, len); } /* * Append the given string to the given buffer, without escaping or * character set conversion. This is the straight copy to the data * buffer with no fanciness. */ static void xo_data_append (xo_handle_t *xop, const char *str, ssize_t len) { xo_buf_append(&xop->xo_data, str, len); } /* * Append the given string to the given buffer */ static void xo_data_escape (xo_handle_t *xop, const char *str, ssize_t len) { xo_buf_escape(xop, &xop->xo_data, str, len, 0); } #ifdef LIBXO_NO_RETAIN /* * Empty implementations of the retain logic */ void xo_retain_clear_all (void) { return; } void xo_retain_clear (const char *fmt UNUSED) { return; } static void xo_retain_add (const char *fmt UNUSED, xo_field_info_t *fields UNUSED, unsigned num_fields UNUSED) { return; } static int xo_retain_find (const char *fmt UNUSED, xo_field_info_t **valp UNUSED, unsigned *nump UNUSED) { return -1; } #else /* !LIBXO_NO_RETAIN */ /* * Retain: We retain parsed field definitions to enhance performance, * especially inside loops. We depend on the caller treating the format * strings as immutable, so that we can retain pointers into them. We * hold the pointers in a hash table, so allow quick access. Retained * information is retained until xo_retain_clear is called. */ /* * xo_retain_entry_t holds information about one retained set of * parsed fields. */ typedef struct xo_retain_entry_s { struct xo_retain_entry_s *xre_next; /* Pointer to next (older) entry */ unsigned long xre_hits; /* Number of times we've hit */ const char *xre_format; /* Pointer to format string */ unsigned xre_num_fields; /* Number of fields saved */ xo_field_info_t *xre_fields; /* Pointer to fields */ } xo_retain_entry_t; /* * xo_retain_t holds a complete set of parsed fields as a hash table. */ #ifndef XO_RETAIN_SIZE #define XO_RETAIN_SIZE 6 #endif /* XO_RETAIN_SIZE */ #define RETAIN_HASH_SIZE (1<> 4) & (((1 << 24) - 1))); val = (val ^ 61) ^ (val >> 16); val = val + (val << 3); val = val ^ (val >> 4); val = val * 0x3a8f05c5; /* My large prime number */ val = val ^ (val >> 15); val &= RETAIN_HASH_SIZE - 1; return val; } /* * Walk all buckets, clearing all retained entries */ void xo_retain_clear_all (void) { int i; xo_retain_entry_t *xrep, *next; for (i = 0; i < RETAIN_HASH_SIZE; i++) { for (xrep = xo_retain.xr_bucket[i]; xrep; xrep = next) { next = xrep->xre_next; xo_free(xrep); } xo_retain.xr_bucket[i] = NULL; } xo_retain_count = 0; } /* * Walk all buckets, clearing all retained entries */ void xo_retain_clear (const char *fmt) { xo_retain_entry_t **xrepp; unsigned hash = xo_retain_hash(fmt); for (xrepp = &xo_retain.xr_bucket[hash]; *xrepp; xrepp = &(*xrepp)->xre_next) { if ((*xrepp)->xre_format == fmt) { *xrepp = (*xrepp)->xre_next; xo_retain_count -= 1; return; } } } /* * Search the hash for an entry matching 'fmt'; return it's fields. */ static int xo_retain_find (const char *fmt, xo_field_info_t **valp, unsigned *nump) { if (xo_retain_count == 0) return -1; unsigned hash = xo_retain_hash(fmt); xo_retain_entry_t *xrep; for (xrep = xo_retain.xr_bucket[hash]; xrep != NULL; xrep = xrep->xre_next) { if (xrep->xre_format == fmt) { *valp = xrep->xre_fields; *nump = xrep->xre_num_fields; xrep->xre_hits += 1; return 0; } } return -1; } static void xo_retain_add (const char *fmt, xo_field_info_t *fields, unsigned num_fields) { unsigned hash = xo_retain_hash(fmt); xo_retain_entry_t *xrep; ssize_t sz = sizeof(*xrep) + (num_fields + 1) * sizeof(*fields); xo_field_info_t *xfip; xrep = xo_realloc(NULL, sz); if (xrep == NULL) return; xfip = (xo_field_info_t *) &xrep[1]; memcpy(xfip, fields, num_fields * sizeof(*fields)); bzero(xrep, sizeof(*xrep)); xrep->xre_format = fmt; xrep->xre_fields = xfip; xrep->xre_num_fields = num_fields; /* Record the field info in the retain bucket */ xrep->xre_next = xo_retain.xr_bucket[hash]; xo_retain.xr_bucket[hash] = xrep; xo_retain_count += 1; } #endif /* !LIBXO_NO_RETAIN */ /* * Generate a warning. Normally, this is a text message written to * standard error. If the XOF_WARN_XML flag is set, then we generate * XMLified content on standard output. */ static void xo_warn_hcv (xo_handle_t *xop, int code, int check_warn, const char *fmt, va_list vap) { xop = xo_default(xop); if (check_warn && !XOF_ISSET(xop, XOF_WARN)) return; if (fmt == NULL) return; ssize_t len = strlen(fmt); ssize_t plen = xo_program ? strlen(xo_program) : 0; char *newfmt = alloca(len + 1 + plen + 2); /* NUL, and ": " */ if (plen) { memcpy(newfmt, xo_program, plen); newfmt[plen++] = ':'; newfmt[plen++] = ' '; } memcpy(newfmt + plen, fmt, len); newfmt[len + plen] = '\0'; if (XOF_ISSET(xop, XOF_WARN_XML)) { static char err_open[] = ""; static char err_close[] = ""; static char msg_open[] = ""; static char msg_close[] = ""; xo_buffer_t *xbp = &xop->xo_data; xo_buf_append(xbp, err_open, sizeof(err_open) - 1); xo_buf_append(xbp, msg_open, sizeof(msg_open) - 1); va_list va_local; va_copy(va_local, vap); ssize_t left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); ssize_t rc = vsnprintf(xbp->xb_curp, left, newfmt, vap); if (rc >= left) { if (!xo_buf_has_room(xbp, rc)) { va_end(va_local); return; } va_end(vap); /* Reset vap to the start */ va_copy(vap, va_local); left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); rc = vsnprintf(xbp->xb_curp, left, fmt, vap); } va_end(va_local); rc = xo_escape_xml(xbp, rc, 1); xbp->xb_curp += rc; xo_buf_append(xbp, msg_close, sizeof(msg_close) - 1); xo_buf_append(xbp, err_close, sizeof(err_close) - 1); if (code >= 0) { const char *msg = strerror(code); if (msg) { xo_buf_append(xbp, ": ", 2); xo_buf_append(xbp, msg, strlen(msg)); } } xo_buf_append(xbp, "\n", 1); /* Append newline and NUL to string */ (void) xo_write(xop); } else { vfprintf(stderr, newfmt, vap); if (code >= 0) { const char *msg = strerror(code); if (msg) fprintf(stderr, ": %s", msg); } fprintf(stderr, "\n"); } } void xo_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_warn_hcv(xop, code, 0, fmt, vap); va_end(vap); } void xo_warn_c (int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, code, 0, fmt, vap); va_end(vap); } void xo_warn (const char *fmt, ...) { int code = errno; va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, code, 0, fmt, vap); va_end(vap); } void xo_warnx (const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, -1, 0, fmt, vap); va_end(vap); } void xo_err (int eval, const char *fmt, ...) { int code = errno; va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, code, 0, fmt, vap); va_end(vap); xo_finish(); exit(eval); } void xo_errx (int eval, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, -1, 0, fmt, vap); va_end(vap); xo_finish(); exit(eval); } void xo_errc (int eval, int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_warn_hcv(NULL, code, 0, fmt, vap); va_end(vap); xo_finish(); exit(eval); } /* * Generate a warning. Normally, this is a text message written to * standard error. If the XOF_WARN_XML flag is set, then we generate * XMLified content on standard output. */ void xo_message_hcv (xo_handle_t *xop, int code, const char *fmt, va_list vap) { static char msg_open[] = ""; static char msg_close[] = ""; xo_buffer_t *xbp; ssize_t rc; va_list va_local; xop = xo_default(xop); if (fmt == NULL || *fmt == '\0') return; int need_nl = (fmt[strlen(fmt) - 1] != '\n'); switch (xo_style(xop)) { case XO_STYLE_XML: xbp = &xop->xo_data; if (XOF_ISSET(xop, XOF_PRETTY)) xo_buf_indent(xop, xop->xo_indent_by); xo_buf_append(xbp, msg_open, sizeof(msg_open) - 1); va_copy(va_local, vap); ssize_t left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); rc = vsnprintf(xbp->xb_curp, left, fmt, vap); if (rc >= left) { if (!xo_buf_has_room(xbp, rc)) { va_end(va_local); return; } va_end(vap); /* Reset vap to the start */ va_copy(vap, va_local); left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); rc = vsnprintf(xbp->xb_curp, left, fmt, vap); } va_end(va_local); rc = xo_escape_xml(xbp, rc, 0); xbp->xb_curp += rc; if (need_nl && code > 0) { const char *msg = strerror(code); if (msg) { xo_buf_append(xbp, ": ", 2); xo_buf_append(xbp, msg, strlen(msg)); } } if (need_nl) xo_buf_append(xbp, "\n", 1); /* Append newline and NUL to string */ xo_buf_append(xbp, msg_close, sizeof(msg_close) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_buf_append(xbp, "\n", 1); /* Append newline and NUL to string */ (void) xo_write(xop); break; case XO_STYLE_HTML: { char buf[BUFSIZ], *bp = buf, *cp; ssize_t bufsiz = sizeof(buf); ssize_t rc2; va_copy(va_local, vap); rc = vsnprintf(bp, bufsiz, fmt, va_local); if (rc > bufsiz) { bufsiz = rc + BUFSIZ; bp = alloca(bufsiz); va_end(va_local); va_copy(va_local, vap); rc = vsnprintf(bp, bufsiz, fmt, va_local); } va_end(va_local); cp = bp + rc; if (need_nl) { rc2 = snprintf(cp, bufsiz - rc, "%s%s\n", (code > 0) ? ": " : "", (code > 0) ? strerror(code) : ""); if (rc2 > 0) rc += rc2; } xo_buf_append_div(xop, "message", 0, NULL, 0, bp, rc, NULL, 0, NULL, 0); } break; case XO_STYLE_JSON: case XO_STYLE_SDPARAMS: case XO_STYLE_ENCODER: /* No means of representing messages */ return; case XO_STYLE_TEXT: rc = xo_printf_v(xop, fmt, vap); /* * XXX need to handle UTF-8 widths */ if (rc > 0) { if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += rc; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += rc; } if (need_nl && code > 0) { const char *msg = strerror(code); if (msg) { xo_printf(xop, ": %s", msg); } } if (need_nl) xo_printf(xop, "\n"); break; } switch (xo_style(xop)) { case XO_STYLE_HTML: if (XOIF_ISSET(xop, XOIF_DIV_OPEN)) { static char div_close[] = "
"; XOIF_CLEAR(xop, XOIF_DIV_OPEN); xo_data_append(xop, div_close, sizeof(div_close) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); } break; } (void) xo_flush_h(xop); } void xo_message_hc (xo_handle_t *xop, int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_message_hcv(xop, code, fmt, vap); va_end(vap); } void xo_message_c (int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_message_hcv(NULL, code, fmt, vap); va_end(vap); } void xo_message_e (const char *fmt, ...) { int code = errno; va_list vap; va_start(vap, fmt); xo_message_hcv(NULL, code, fmt, vap); va_end(vap); } void xo_message (const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_message_hcv(NULL, 0, fmt, vap); va_end(vap); } void xo_failure (xo_handle_t *xop, const char *fmt, ...) { if (!XOF_ISSET(xop, XOF_WARN)) return; va_list vap; va_start(vap, fmt); xo_warn_hcv(xop, -1, 1, fmt, vap); va_end(vap); } /** * Create a handle for use by later libxo functions. * * Note: normal use of libxo does not require a distinct handle, since * the default handle (used when NULL is passed) generates text on stdout. * * @param style Style of output desired (XO_STYLE_* value) * @param flags Set of XOF_* flags in use with this handle * @return Newly allocated handle * @see xo_destroy */ xo_handle_t * xo_create (xo_style_t style, xo_xof_flags_t flags) { xo_handle_t *xop = xo_realloc(NULL, sizeof(*xop)); if (xop) { bzero(xop, sizeof(*xop)); xop->xo_style = style; XOF_SET(xop, flags); xo_init_handle(xop); xop->xo_style = style; /* Reset style (see LIBXO_OPTIONS) */ } return xop; } /** * Create a handle that will write to the given file. Use * the XOF_CLOSE_FP flag to have the file closed on xo_destroy(). * * @param fp FILE pointer to use * @param style Style of output desired (XO_STYLE_* value) * @param flags Set of XOF_* flags to use with this handle * @return Newly allocated handle * @see xo_destroy */ xo_handle_t * xo_create_to_file (FILE *fp, xo_style_t style, xo_xof_flags_t flags) { xo_handle_t *xop = xo_create(style, flags); if (xop) { xop->xo_opaque = fp; xop->xo_write = xo_write_to_file; xop->xo_close = xo_close_file; xop->xo_flush = xo_flush_file; } return xop; } /** * Set the default handler to output to a file. * * @param xop libxo handle * @param fp FILE pointer to use * @return 0 on success, non-zero on failure */ int xo_set_file_h (xo_handle_t *xop, FILE *fp) { xop = xo_default(xop); if (fp == NULL) { xo_failure(xop, "xo_set_file: NULL fp"); return -1; } xop->xo_opaque = fp; xop->xo_write = xo_write_to_file; xop->xo_close = xo_close_file; xop->xo_flush = xo_flush_file; return 0; } /** * Set the default handler to output to a file. * * @param fp FILE pointer to use * @return 0 on success, non-zero on failure */ int xo_set_file (FILE *fp) { return xo_set_file_h(NULL, fp); } /** * Release any resources held by the handle. * * @param xop XO handle to alter (or NULL for default handle) */ void xo_destroy (xo_handle_t *xop_arg) { xo_handle_t *xop = xo_default(xop_arg); xo_flush_h(xop); if (xop->xo_close && XOF_ISSET(xop, XOF_CLOSE_FP)) xop->xo_close(xop->xo_opaque); xo_free(xop->xo_stack); xo_buf_cleanup(&xop->xo_data); xo_buf_cleanup(&xop->xo_fmt); xo_buf_cleanup(&xop->xo_predicate); xo_buf_cleanup(&xop->xo_attrs); xo_buf_cleanup(&xop->xo_color_buf); if (xop->xo_version) xo_free(xop->xo_version); if (xop_arg == NULL) { bzero(&xo_default_handle, sizeof(xo_default_handle)); xo_default_inited = 0; } else xo_free(xop); } /** * Record a new output style to use for the given handle (or default if * handle is NULL). This output style will be used for any future output. * * @param xop XO handle to alter (or NULL for default handle) * @param style new output style (XO_STYLE_*) */ void xo_set_style (xo_handle_t *xop, xo_style_t style) { xop = xo_default(xop); xop->xo_style = style; } /** * Return the current style of a handle * * @param xop XO handle to access * @return The handle's current style */ xo_style_t xo_get_style (xo_handle_t *xop) { xop = xo_default(xop); return xo_style(xop); } /** * Return the XO_STYLE_* value matching a given name * * @param name String name of a style * @return XO_STYLE_* value */ static int xo_name_to_style (const char *name) { if (xo_streq(name, "xml")) return XO_STYLE_XML; else if (xo_streq(name, "json")) return XO_STYLE_JSON; else if (xo_streq(name, "encoder")) return XO_STYLE_ENCODER; else if (xo_streq(name, "text")) return XO_STYLE_TEXT; else if (xo_streq(name, "html")) return XO_STYLE_HTML; else if (xo_streq(name, "sdparams")) return XO_STYLE_SDPARAMS; return -1; } /* * Indicate if the style is an "encoding" one as opposed to a "display" one. */ static int xo_style_is_encoding (xo_handle_t *xop) { if (xo_style(xop) == XO_STYLE_JSON || xo_style(xop) == XO_STYLE_XML || xo_style(xop) == XO_STYLE_SDPARAMS || xo_style(xop) == XO_STYLE_ENCODER) return 1; return 0; } /* Simple name-value mapping */ typedef struct xo_mapping_s { xo_xff_flags_t xm_value; /* Flag value */ const char *xm_name; /* String name */ } xo_mapping_t; static xo_xff_flags_t xo_name_lookup (xo_mapping_t *map, const char *value, ssize_t len) { if (len == 0) return 0; if (len < 0) len = strlen(value); while (isspace((int) *value)) { value += 1; len -= 1; } while (isspace((int) value[len])) len -= 1; if (*value == '\0') return 0; for ( ; map->xm_name; map++) if (strncmp(map->xm_name, value, len) == 0) return map->xm_value; return 0; } #ifdef NOT_NEEDED_YET static const char * xo_value_lookup (xo_mapping_t *map, xo_xff_flags_t value) { if (value == 0) return NULL; for ( ; map->xm_name; map++) if (map->xm_value == value) return map->xm_name; return NULL; } #endif /* NOT_NEEDED_YET */ static xo_mapping_t xo_xof_names[] = { { XOF_COLOR_ALLOWED, "color" }, { XOF_COLOR, "color-force" }, { XOF_COLUMNS, "columns" }, { XOF_DTRT, "dtrt" }, { XOF_FLUSH, "flush" }, { XOF_FLUSH_LINE, "flush-line" }, { XOF_IGNORE_CLOSE, "ignore-close" }, { XOF_INFO, "info" }, { XOF_KEYS, "keys" }, { XOF_LOG_GETTEXT, "log-gettext" }, { XOF_LOG_SYSLOG, "log-syslog" }, { XOF_NO_HUMANIZE, "no-humanize" }, { XOF_NO_LOCALE, "no-locale" }, { XOF_RETAIN_NONE, "no-retain" }, { XOF_NO_TOP, "no-top" }, { XOF_NOT_FIRST, "not-first" }, { XOF_PRETTY, "pretty" }, { XOF_RETAIN_ALL, "retain" }, { XOF_UNDERSCORES, "underscores" }, { XOF_UNITS, "units" }, { XOF_WARN, "warn" }, { XOF_WARN_XML, "warn-xml" }, { XOF_XPATH, "xpath" }, { 0, NULL } }; /* Options available via the environment variable ($LIBXO_OPTIONS) */ static xo_mapping_t xo_xof_simple_names[] = { { XOF_COLOR_ALLOWED, "color" }, { XOF_FLUSH, "flush" }, { XOF_FLUSH_LINE, "flush-line" }, { XOF_NO_HUMANIZE, "no-humanize" }, { XOF_NO_LOCALE, "no-locale" }, { XOF_RETAIN_NONE, "no-retain" }, { XOF_PRETTY, "pretty" }, { XOF_RETAIN_ALL, "retain" }, { XOF_UNDERSCORES, "underscores" }, { XOF_WARN, "warn" }, { 0, NULL } }; /* * Convert string name to XOF_* flag value. * Not all are useful. Or safe. Or sane. */ static unsigned xo_name_to_flag (const char *name) { return (unsigned) xo_name_lookup(xo_xof_names, name, -1); } /** * Set the style of an libxo handle based on a string name * * @param xop XO handle * @param name String value of name * @return 0 on success, non-zero on failure */ int xo_set_style_name (xo_handle_t *xop, const char *name) { if (name == NULL) return -1; int style = xo_name_to_style(name); if (style < 0) return -1; xo_set_style(xop, style); return 0; } /* * Fill in the color map, based on the input string; currently unimplemented * Look for something like "colors=red/blue+green/yellow" as fg/bg pairs. */ static void xo_set_color_map (xo_handle_t *xop, char *value) { if (xo_text_only()) return; char *cp, *ep, *vp, *np; ssize_t len = value ? strlen(value) + 1 : 0; int num = 1, fg, bg; for (cp = value, ep = cp + len - 1; cp && *cp && cp < ep; cp = np) { np = strchr(cp, '+'); if (np) *np++ = '\0'; vp = strchr(cp, '/'); if (vp) *vp++ = '\0'; fg = *cp ? xo_color_find(cp) : -1; bg = (vp && *vp) ? xo_color_find(vp) : -1; #ifndef LIBXO_TEXT_ONLY xop->xo_color_map_fg[num] = (fg < 0) ? num : fg; xop->xo_color_map_bg[num] = (bg < 0) ? num : bg; #endif /* LIBXO_TEXT_ONLY */ if (++num > XO_NUM_COLORS) break; } /* If no color initialization happened, then we don't need the map */ if (num > 1) XOF_SET(xop, XOF_COLOR_MAP); else XOF_CLEAR(xop, XOF_COLOR_MAP); #ifndef LIBXO_TEXT_ONLY /* Fill in the rest of the colors with the defaults */ for ( ; num < XO_NUM_COLORS; num++) xop->xo_color_map_fg[num] = xop->xo_color_map_bg[num] = num; #endif /* LIBXO_TEXT_ONLY */ } static int xo_set_options_simple (xo_handle_t *xop, const char *input) { xo_xof_flags_t new_flag; char *cp, *ep, *vp, *np, *bp; ssize_t len = strlen(input) + 1; bp = alloca(len); memcpy(bp, input, len); for (cp = bp, ep = cp + len - 1; cp && cp < ep; cp = np) { np = strchr(cp, ','); if (np) *np++ = '\0'; vp = strchr(cp, '='); if (vp) *vp++ = '\0'; if (xo_streq("colors", cp)) { xo_set_color_map(xop, vp); continue; } new_flag = xo_name_lookup(xo_xof_simple_names, cp, -1); if (new_flag != 0) { XOF_SET(xop, new_flag); } else if (xo_streq(cp, "no-color")) { XOF_CLEAR(xop, XOF_COLOR_ALLOWED); } else { xo_failure(xop, "unknown simple option: %s", cp); return -1; } } return 0; } /** * Set the options for a handle using a string of options * passed in. The input is a comma-separated set of names * and optional values: "xml,pretty,indent=4" * * @param xop XO handle * @param input Comma-separated set of option values * @return 0 on success, non-zero on failure */ int xo_set_options (xo_handle_t *xop, const char *input) { char *cp, *ep, *vp, *np, *bp; int style = -1, new_style, rc = 0; ssize_t len; xo_xof_flags_t new_flag; if (input == NULL) return 0; xop = xo_default(xop); #ifdef LIBXO_COLOR_ON_BY_DEFAULT /* If the installer used --enable-color-on-by-default, then we allow it */ XOF_SET(xop, XOF_COLOR_ALLOWED); #endif /* LIBXO_COLOR_ON_BY_DEFAULT */ /* * We support a simpler, old-school style of giving option * also, using a single character for each option. It's * ideal for lazy people, such as myself. */ if (*input == ':') { ssize_t sz; for (input++ ; *input; input++) { switch (*input) { case 'c': XOF_SET(xop, XOF_COLOR_ALLOWED); break; case 'f': XOF_SET(xop, XOF_FLUSH); break; case 'F': XOF_SET(xop, XOF_FLUSH_LINE); break; case 'g': XOF_SET(xop, XOF_LOG_GETTEXT); break; case 'H': xop->xo_style = XO_STYLE_HTML; break; case 'I': XOF_SET(xop, XOF_INFO); break; case 'i': sz = strspn(input + 1, "0123456789"); if (sz > 0) { xop->xo_indent_by = atoi(input + 1); input += sz - 1; /* Skip value */ } break; case 'J': xop->xo_style = XO_STYLE_JSON; break; case 'k': XOF_SET(xop, XOF_KEYS); break; case 'n': XOF_SET(xop, XOF_NO_HUMANIZE); break; case 'P': XOF_SET(xop, XOF_PRETTY); break; case 'T': xop->xo_style = XO_STYLE_TEXT; break; case 'U': XOF_SET(xop, XOF_UNITS); break; case 'u': XOF_SET(xop, XOF_UNDERSCORES); break; case 'W': XOF_SET(xop, XOF_WARN); break; case 'X': xop->xo_style = XO_STYLE_XML; break; case 'x': XOF_SET(xop, XOF_XPATH); break; } } return 0; } len = strlen(input) + 1; bp = alloca(len); memcpy(bp, input, len); for (cp = bp, ep = cp + len - 1; cp && cp < ep; cp = np) { np = strchr(cp, ','); if (np) *np++ = '\0'; /* * "@foo" is a shorthand for "encoder=foo". This is driven * chiefly by a desire to make pluggable encoders not appear * so distinct from built-in encoders. */ if (*cp == '@') { vp = cp + 1; if (*vp == '\0') xo_failure(xop, "missing value for encoder option"); else { rc = xo_encoder_init(xop, vp); if (rc) xo_warnx("error initializing encoder: %s", vp); } continue; } vp = strchr(cp, '='); if (vp) *vp++ = '\0'; if (xo_streq("colors", cp)) { xo_set_color_map(xop, vp); continue; } /* * For options, we don't allow "encoder" since we want to * handle it explicitly below as "encoder=xxx". */ new_style = xo_name_to_style(cp); if (new_style >= 0 && new_style != XO_STYLE_ENCODER) { if (style >= 0) xo_warnx("ignoring multiple styles: '%s'", cp); else style = new_style; } else { new_flag = xo_name_to_flag(cp); if (new_flag != 0) XOF_SET(xop, new_flag); else if (xo_streq(cp, "no-color")) XOF_CLEAR(xop, XOF_COLOR_ALLOWED); else if (xo_streq(cp, "indent")) { if (vp) xop->xo_indent_by = atoi(vp); else xo_failure(xop, "missing value for indent option"); } else if (xo_streq(cp, "encoder")) { if (vp == NULL) xo_failure(xop, "missing value for encoder option"); else { rc = xo_encoder_init(xop, vp); if (rc) xo_warnx("error initializing encoder: %s", vp); } } else { xo_warnx("unknown libxo option value: '%s'", cp); rc = -1; } } } if (style > 0) xop->xo_style= style; return rc; } /** * Set one or more flags for a given handle (or default if handle is NULL). * These flags will affect future output. * * @param xop XO handle to alter (or NULL for default handle) * @param flags Flags to be set (XOF_*) */ void xo_set_flags (xo_handle_t *xop, xo_xof_flags_t flags) { xop = xo_default(xop); XOF_SET(xop, flags); } /** * Accessor to return the current set of flags for a handle * @param xop XO handle * @return Current set of flags */ xo_xof_flags_t xo_get_flags (xo_handle_t *xop) { xop = xo_default(xop); return xop->xo_flags; } /** * strndup with a twist: len < 0 means len = strlen(str) */ static char * xo_strndup (const char *str, ssize_t len) { if (len < 0) len = strlen(str); char *cp = xo_realloc(NULL, len + 1); if (cp) { memcpy(cp, str, len); cp[len] = '\0'; } return cp; } /** * Record a leading prefix for the XPath we generate. This allows the * generated data to be placed within an XML hierarchy but still have * accurate XPath expressions. * * @param xop XO handle to alter (or NULL for default handle) * @param path The XPath expression */ void xo_set_leading_xpath (xo_handle_t *xop, const char *path) { xop = xo_default(xop); if (xop->xo_leading_xpath) { xo_free(xop->xo_leading_xpath); xop->xo_leading_xpath = NULL; } if (path == NULL) return; xop->xo_leading_xpath = xo_strndup(path, -1); } /** * Record the info data for a set of tags * * @param xop XO handle to alter (or NULL for default handle) * @param info Info data (xo_info_t) to be recorded (or NULL) (MUST BE SORTED) * @pararm count Number of entries in info (or -1 to count them ourselves) */ void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count) { xop = xo_default(xop); if (count < 0 && infop) { xo_info_t *xip; for (xip = infop, count = 0; xip->xi_name; xip++, count++) continue; } xop->xo_info = infop; xop->xo_info_count = count; } /** * Set the formatter callback for a handle. The callback should * return a newly formatting contents of a formatting instruction, * meaning the bits inside the braces. */ void xo_set_formatter (xo_handle_t *xop, xo_formatter_t func, xo_checkpointer_t cfunc) { xop = xo_default(xop); xop->xo_formatter = func; xop->xo_checkpointer = cfunc; } /** * Clear one or more flags for a given handle (or default if handle is NULL). * These flags will affect future output. * * @param xop XO handle to alter (or NULL for default handle) * @param flags Flags to be cleared (XOF_*) */ void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags) { xop = xo_default(xop); XOF_CLEAR(xop, flags); } static const char * xo_state_name (xo_state_t state) { static const char *names[] = { "init", "open_container", "close_container", "open_list", "close_list", "open_instance", "close_instance", "open_leaf_list", "close_leaf_list", "discarding", "marker", "emit", "emit_leaf_list", "finish", NULL }; if (state < (sizeof(names) / sizeof(names[0]))) return names[state]; return "unknown"; } static void xo_line_ensure_open (xo_handle_t *xop, xo_xff_flags_t flags UNUSED) { static char div_open[] = "
"; static char div_open_blank[] = "
"; if (XOF_ISSET(xop, XOF_CONTINUATION)) { XOF_CLEAR(xop, XOF_CONTINUATION); XOIF_SET(xop, XOIF_DIV_OPEN); return; } if (XOIF_ISSET(xop, XOIF_DIV_OPEN)) return; if (xo_style(xop) != XO_STYLE_HTML) return; XOIF_SET(xop, XOIF_DIV_OPEN); if (flags & XFF_BLANK_LINE) xo_data_append(xop, div_open_blank, sizeof(div_open_blank) - 1); else xo_data_append(xop, div_open, sizeof(div_open) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); } static void xo_line_close (xo_handle_t *xop) { static char div_close[] = "
"; switch (xo_style(xop)) { case XO_STYLE_HTML: if (!XOIF_ISSET(xop, XOIF_DIV_OPEN)) xo_line_ensure_open(xop, 0); XOIF_CLEAR(xop, XOIF_DIV_OPEN); xo_data_append(xop, div_close, sizeof(div_close) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); break; case XO_STYLE_TEXT: xo_data_append(xop, "\n", 1); break; } } static int xo_info_compare (const void *key, const void *data) { const char *name = key; const xo_info_t *xip = data; return strcmp(name, xip->xi_name); } static xo_info_t * xo_info_find (xo_handle_t *xop, const char *name, ssize_t nlen) { xo_info_t *xip; char *cp = alloca(nlen + 1); /* Need local copy for NUL termination */ memcpy(cp, name, nlen); cp[nlen] = '\0'; xip = bsearch(cp, xop->xo_info, xop->xo_info_count, sizeof(xop->xo_info[0]), xo_info_compare); return xip; } #define CONVERT(_have, _need) (((_have) << 8) | (_need)) /* * Check to see that the conversion is safe and sane. */ static int xo_check_conversion (xo_handle_t *xop, int have_enc, int need_enc) { switch (CONVERT(have_enc, need_enc)) { case CONVERT(XF_ENC_UTF8, XF_ENC_UTF8): case CONVERT(XF_ENC_UTF8, XF_ENC_LOCALE): case CONVERT(XF_ENC_WIDE, XF_ENC_UTF8): case CONVERT(XF_ENC_WIDE, XF_ENC_LOCALE): case CONVERT(XF_ENC_LOCALE, XF_ENC_LOCALE): case CONVERT(XF_ENC_LOCALE, XF_ENC_UTF8): return 0; default: xo_failure(xop, "invalid conversion (%c:%c)", have_enc, need_enc); return 1; } } static int xo_format_string_direct (xo_handle_t *xop, xo_buffer_t *xbp, xo_xff_flags_t flags, const wchar_t *wcp, const char *cp, ssize_t len, int max, int need_enc, int have_enc) { int cols = 0; wchar_t wc = 0; ssize_t ilen, olen; ssize_t width; int attr = XOF_BIT_ISSET(flags, XFF_ATTR); const char *sp; if (len > 0 && !xo_buf_has_room(xbp, len)) return 0; for (;;) { if (len == 0) break; if (cp) { if (*cp == '\0') break; if ((flags & XFF_UNESCAPE) && (*cp == '\\' || *cp == '%')) { cp += 1; len -= 1; if (len == 0 || *cp == '\0') break; } } if (wcp && *wcp == L'\0') break; ilen = 0; switch (have_enc) { case XF_ENC_WIDE: /* Wide character */ wc = *wcp++; ilen = 1; break; case XF_ENC_UTF8: /* UTF-8 */ ilen = xo_utf8_to_wc_len(cp); if (ilen < 0) { xo_failure(xop, "invalid UTF-8 character: %02hhx", *cp); return -1; /* Can't continue; we can't find the end */ } if (len > 0 && len < ilen) { len = 0; /* Break out of the loop */ continue; } wc = xo_utf8_char(cp, ilen); if (wc == (wchar_t) -1) { xo_failure(xop, "invalid UTF-8 character: %02hhx/%d", *cp, ilen); return -1; /* Can't continue; we can't find the end */ } cp += ilen; break; case XF_ENC_LOCALE: /* Native locale */ ilen = (len > 0) ? len : MB_LEN_MAX; ilen = mbrtowc(&wc, cp, ilen, &xop->xo_mbstate); if (ilen < 0) { /* Invalid data; skip */ xo_failure(xop, "invalid mbs char: %02hhx", *cp); wc = L'?'; ilen = 1; } if (ilen == 0) { /* Hit a wide NUL character */ len = 0; continue; } cp += ilen; break; } /* Reduce len, but not below zero */ if (len > 0) { len -= ilen; if (len < 0) len = 0; } /* * Find the width-in-columns of this character, which must be done * in wide characters, since we lack a mbswidth() function. If * it doesn't fit */ width = xo_wcwidth(wc); if (width < 0) width = iswcntrl(wc) ? 0 : 1; if (xo_style(xop) == XO_STYLE_TEXT || xo_style(xop) == XO_STYLE_HTML) { if (max > 0 && cols + width > max) break; } switch (need_enc) { case XF_ENC_UTF8: /* Output in UTF-8 needs to be escaped, based on the style */ switch (xo_style(xop)) { case XO_STYLE_XML: case XO_STYLE_HTML: if (wc == '<') sp = xo_xml_lt; else if (wc == '>') sp = xo_xml_gt; else if (wc == '&') sp = xo_xml_amp; else if (attr && wc == '"') sp = xo_xml_quot; else break; ssize_t slen = strlen(sp); if (!xo_buf_has_room(xbp, slen - 1)) return -1; memcpy(xbp->xb_curp, sp, slen); xbp->xb_curp += slen; goto done_with_encoding; /* Need multi-level 'break' */ case XO_STYLE_JSON: if (wc != '\\' && wc != '"' && wc != '\n' && wc != '\r') break; if (!xo_buf_has_room(xbp, 2)) return -1; *xbp->xb_curp++ = '\\'; if (wc == '\n') wc = 'n'; else if (wc == '\r') wc = 'r'; else wc = wc & 0x7f; *xbp->xb_curp++ = wc; goto done_with_encoding; case XO_STYLE_SDPARAMS: if (wc != '\\' && wc != '"' && wc != ']') break; if (!xo_buf_has_room(xbp, 2)) return -1; *xbp->xb_curp++ = '\\'; wc = wc & 0x7f; *xbp->xb_curp++ = wc; goto done_with_encoding; } olen = xo_utf8_emit_len(wc); if (olen < 0) { xo_failure(xop, "ignoring bad length"); continue; } if (!xo_buf_has_room(xbp, olen)) return -1; xo_utf8_emit_char(xbp->xb_curp, olen, wc); xbp->xb_curp += olen; break; case XF_ENC_LOCALE: if (!xo_buf_has_room(xbp, MB_LEN_MAX + 1)) return -1; olen = wcrtomb(xbp->xb_curp, wc, &xop->xo_mbstate); if (olen <= 0) { xo_failure(xop, "could not convert wide char: %lx", (unsigned long) wc); width = 1; *xbp->xb_curp++ = '?'; } else xbp->xb_curp += olen; break; } done_with_encoding: cols += width; } return cols; } static int xo_needed_encoding (xo_handle_t *xop) { if (XOF_ISSET(xop, XOF_UTF8)) /* Check the override flag */ return XF_ENC_UTF8; if (xo_style(xop) == XO_STYLE_TEXT) /* Text means locale */ return XF_ENC_LOCALE; return XF_ENC_UTF8; /* Otherwise, we love UTF-8 */ } static ssize_t xo_format_string (xo_handle_t *xop, xo_buffer_t *xbp, xo_xff_flags_t flags, xo_format_t *xfp) { static char null[] = "(null)"; static char null_no_quotes[] = "null"; char *cp = NULL; wchar_t *wcp = NULL; ssize_t len; ssize_t cols = 0, rc = 0; ssize_t off = xbp->xb_curp - xbp->xb_bufp, off2; int need_enc = xo_needed_encoding(xop); if (xo_check_conversion(xop, xfp->xf_enc, need_enc)) return 0; len = xfp->xf_width[XF_WIDTH_SIZE]; if (xfp->xf_fc == 'm') { cp = strerror(xop->xo_errno); if (len < 0) len = cp ? strlen(cp) : 0; goto normal_string; } else if (xfp->xf_enc == XF_ENC_WIDE) { wcp = va_arg(xop->xo_vap, wchar_t *); if (xfp->xf_skip) return 0; /* * Dont' deref NULL; use the traditional "(null)" instead * of the more accurate "who's been a naughty boy, then?". */ if (wcp == NULL) { cp = null; len = sizeof(null) - 1; } } else { cp = va_arg(xop->xo_vap, char *); /* UTF-8 or native */ normal_string: if (xfp->xf_skip) return 0; /* Echo "Dont' deref NULL" logic */ if (cp == NULL) { if ((flags & XFF_NOQUOTE) && xo_style_is_encoding(xop)) { cp = null_no_quotes; len = sizeof(null_no_quotes) - 1; } else { cp = null; len = sizeof(null) - 1; } } /* * Optimize the most common case, which is "%s". We just * need to copy the complete string to the output buffer. */ if (xfp->xf_enc == need_enc && xfp->xf_width[XF_WIDTH_MIN] < 0 && xfp->xf_width[XF_WIDTH_SIZE] < 0 && xfp->xf_width[XF_WIDTH_MAX] < 0 && !(XOIF_ISSET(xop, XOIF_ANCHOR) || XOF_ISSET(xop, XOF_COLUMNS))) { len = strlen(cp); xo_buf_escape(xop, xbp, cp, len, flags); /* * Our caller expects xb_curp left untouched, so we have * to reset it and return the number of bytes written to * the buffer. */ off2 = xbp->xb_curp - xbp->xb_bufp; rc = off2 - off; xbp->xb_curp = xbp->xb_bufp + off; return rc; } } cols = xo_format_string_direct(xop, xbp, flags, wcp, cp, len, xfp->xf_width[XF_WIDTH_MAX], need_enc, xfp->xf_enc); if (cols < 0) goto bail; /* * xo_buf_append* will move xb_curp, so we save/restore it. */ off2 = xbp->xb_curp - xbp->xb_bufp; rc = off2 - off; xbp->xb_curp = xbp->xb_bufp + off; if (cols < xfp->xf_width[XF_WIDTH_MIN]) { /* * Find the number of columns needed to display the string. * If we have the original wide string, we just call wcswidth, * but if we did the work ourselves, then we need to do it. */ int delta = xfp->xf_width[XF_WIDTH_MIN] - cols; if (!xo_buf_has_room(xbp, xfp->xf_width[XF_WIDTH_MIN])) goto bail; /* * If seen_minus, then pad on the right; otherwise move it so * we can pad on the left. */ if (xfp->xf_seen_minus) { cp = xbp->xb_curp + rc; } else { cp = xbp->xb_curp; memmove(xbp->xb_curp + delta, xbp->xb_curp, rc); } /* Set the padding */ memset(cp, (xfp->xf_leading_zero > 0) ? '0' : ' ', delta); rc += delta; cols += delta; } if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += cols; return rc; bail: xbp->xb_curp = xbp->xb_bufp + off; return 0; } /* * Look backwards in a buffer to find a numeric value */ static int xo_buf_find_last_number (xo_buffer_t *xbp, ssize_t start_offset) { int rc = 0; /* Fail with zero */ int digit = 1; char *sp = xbp->xb_bufp; char *cp = sp + start_offset; while (--cp >= sp) if (isdigit((int) *cp)) break; for ( ; cp >= sp; cp--) { if (!isdigit((int) *cp)) break; rc += (*cp - '0') * digit; digit *= 10; } return rc; } static ssize_t xo_count_utf8_cols (const char *str, ssize_t len) { ssize_t tlen; wchar_t wc; ssize_t cols = 0; const char *ep = str + len; while (str < ep) { tlen = xo_utf8_to_wc_len(str); if (tlen < 0) /* Broken input is very bad */ return cols; wc = xo_utf8_char(str, tlen); if (wc == (wchar_t) -1) return cols; /* We only print printable characters */ if (iswprint((wint_t) wc)) { /* * Find the width-in-columns of this character, which must be done * in wide characters, since we lack a mbswidth() function. */ ssize_t width = xo_wcwidth(wc); if (width < 0) width = iswcntrl(wc) ? 0 : 1; cols += width; } str += tlen; } return cols; } #ifdef HAVE_GETTEXT static inline const char * xo_dgettext (xo_handle_t *xop, const char *str) { const char *domainname = xop->xo_gt_domain; const char *res; res = dgettext(domainname, str); if (XOF_ISSET(xop, XOF_LOG_GETTEXT)) fprintf(stderr, "xo: gettext: %s%s%smsgid \"%s\" returns \"%s\"\n", domainname ? "domain \"" : "", xo_printable(domainname), domainname ? "\", " : "", xo_printable(str), xo_printable(res)); return res; } static inline const char * xo_dngettext (xo_handle_t *xop, const char *sing, const char *plural, unsigned long int n) { const char *domainname = xop->xo_gt_domain; const char *res; res = dngettext(domainname, sing, plural, n); if (XOF_ISSET(xop, XOF_LOG_GETTEXT)) fprintf(stderr, "xo: gettext: %s%s%s" "msgid \"%s\", msgid_plural \"%s\" (%lu) returns \"%s\"\n", domainname ? "domain \"" : "", xo_printable(domainname), domainname ? "\", " : "", xo_printable(sing), xo_printable(plural), n, xo_printable(res)); return res; } #else /* HAVE_GETTEXT */ static inline const char * xo_dgettext (xo_handle_t *xop UNUSED, const char *str) { return str; } static inline const char * xo_dngettext (xo_handle_t *xop UNUSED, const char *singular, const char *plural, unsigned long int n) { return (n == 1) ? singular : plural; } #endif /* HAVE_GETTEXT */ /* * This is really _re_formatting, since the normal format code has * generated a beautiful string into xo_data, starting at * start_offset. We need to see if it's plural, which means * comma-separated options, or singular. Then we make the appropriate * call to d[n]gettext() to get the locale-based version. Note that * both input and output of gettext() this should be UTF-8. */ static ssize_t xo_format_gettext (xo_handle_t *xop, xo_xff_flags_t flags, ssize_t start_offset, ssize_t cols, int need_enc) { xo_buffer_t *xbp = &xop->xo_data; if (!xo_buf_has_room(xbp, 1)) return cols; xbp->xb_curp[0] = '\0'; /* NUL-terminate the input string */ char *cp = xbp->xb_bufp + start_offset; ssize_t len = xbp->xb_curp - cp; const char *newstr = NULL; /* * The plural flag asks us to look backwards at the last numeric * value rendered and disect the string into two pieces. */ if (flags & XFF_GT_PLURAL) { int n = xo_buf_find_last_number(xbp, start_offset); char *two = memchr(cp, (int) ',', len); if (two == NULL) { xo_failure(xop, "no comma in plural gettext field: '%s'", cp); return cols; } if (two == cp) { xo_failure(xop, "nothing before comma in plural gettext " "field: '%s'", cp); return cols; } if (two == xbp->xb_curp) { xo_failure(xop, "nothing after comma in plural gettext " "field: '%s'", cp); return cols; } *two++ = '\0'; if (flags & XFF_GT_FIELD) { newstr = xo_dngettext(xop, cp, two, n); } else { /* Don't do a gettext() look up, just get the plural form */ newstr = (n == 1) ? cp : two; } /* * If we returned the first string, optimize a bit by * backing up over comma */ if (newstr == cp) { xbp->xb_curp = two - 1; /* One for comma */ /* * If the caller wanted UTF8, we're done; nothing changed, * but we need to count the columns used. */ if (need_enc == XF_ENC_UTF8) return xo_count_utf8_cols(cp, xbp->xb_curp - cp); } } else { /* The simple case (singular) */ newstr = xo_dgettext(xop, cp); if (newstr == cp) { /* If the caller wanted UTF8, we're done; nothing changed */ if (need_enc == XF_ENC_UTF8) return cols; } } /* * Since the new string string might be in gettext's buffer or * in the buffer (as the plural form), we make a copy. */ ssize_t nlen = strlen(newstr); char *newcopy = alloca(nlen + 1); memcpy(newcopy, newstr, nlen + 1); xbp->xb_curp = xbp->xb_bufp + start_offset; /* Reset the buffer */ return xo_format_string_direct(xop, xbp, flags, NULL, newcopy, nlen, 0, need_enc, XF_ENC_UTF8); } static void xo_data_append_content (xo_handle_t *xop, const char *str, ssize_t len, xo_xff_flags_t flags) { int cols; int need_enc = xo_needed_encoding(xop); ssize_t start_offset = xo_buf_offset(&xop->xo_data); cols = xo_format_string_direct(xop, &xop->xo_data, XFF_UNESCAPE | flags, NULL, str, len, -1, need_enc, XF_ENC_UTF8); if (flags & XFF_GT_FLAGS) cols = xo_format_gettext(xop, flags, start_offset, cols, need_enc); if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += cols; } /** * Bump one of the 'width' values in a format strings (e.g. "%40.50.60s"). * @param xfp Formatting instructions * @param digit Single digit (0-9) of input */ static void xo_bump_width (xo_format_t *xfp, int digit) { int *ip = &xfp->xf_width[xfp->xf_dots]; *ip = ((*ip > 0) ? *ip : 0) * 10 + digit; } static ssize_t xo_trim_ws (xo_buffer_t *xbp, ssize_t len) { char *cp, *sp, *ep; ssize_t delta; /* First trim leading space */ for (cp = sp = xbp->xb_curp, ep = cp + len; cp < ep; cp++) { if (*cp != ' ') break; } delta = cp - sp; if (delta) { len -= delta; memmove(sp, cp, len); } /* Then trim off the end */ for (cp = xbp->xb_curp, sp = ep = cp + len; cp < ep; ep--) { if (ep[-1] != ' ') break; } delta = sp - ep; if (delta) { len -= delta; cp[len] = '\0'; } return len; } /* * Interface to format a single field. The arguments are in xo_vap, * and the format is in 'fmt'. If 'xbp' is null, we use xop->xo_data; * this is the most common case. */ static ssize_t xo_do_format_field (xo_handle_t *xop, xo_buffer_t *xbp, const char *fmt, ssize_t flen, xo_xff_flags_t flags) { xo_format_t xf; const char *cp, *ep, *sp, *xp = NULL; ssize_t rc, cols; int style = (flags & XFF_XML) ? XO_STYLE_XML : xo_style(xop); unsigned make_output = !(flags & XFF_NO_OUTPUT) ? 1 : 0; int need_enc = xo_needed_encoding(xop); int real_need_enc = need_enc; ssize_t old_cols = xop->xo_columns; /* The gettext interface is UTF-8, so we'll need that for now */ if (flags & XFF_GT_FIELD) need_enc = XF_ENC_UTF8; if (xbp == NULL) xbp = &xop->xo_data; ssize_t start_offset = xo_buf_offset(xbp); for (cp = fmt, ep = fmt + flen; cp < ep; cp++) { /* * Since we're starting a new field, save the starting offset. * We'll need this later for field-related operations. */ if (*cp != '%') { add_one: if (xp == NULL) xp = cp; if (*cp == '\\' && cp[1] != '\0') cp += 1; continue; } else if (cp + 1 < ep && cp[1] == '%') { cp += 1; goto add_one; } if (xp) { if (make_output) { cols = xo_format_string_direct(xop, xbp, flags | XFF_UNESCAPE, NULL, xp, cp - xp, -1, need_enc, XF_ENC_UTF8); if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += cols; } xp = NULL; } bzero(&xf, sizeof(xf)); xf.xf_leading_zero = -1; xf.xf_width[0] = xf.xf_width[1] = xf.xf_width[2] = -1; /* * "%@" starts an XO-specific set of flags: * @X@ - XML-only field; ignored if style isn't XML */ if (cp[1] == '@') { for (cp += 2; cp < ep; cp++) { if (*cp == '@') { break; } if (*cp == '*') { /* * '*' means there's a "%*.*s" value in vap that * we want to ignore */ if (!XOF_ISSET(xop, XOF_NO_VA_ARG)) va_arg(xop->xo_vap, int); } } } /* Hidden fields are only visible to JSON and XML */ if (XOF_ISSET(xop, XFF_ENCODE_ONLY)) { if (style != XO_STYLE_XML && !xo_style_is_encoding(xop)) xf.xf_skip = 1; } else if (XOF_ISSET(xop, XFF_DISPLAY_ONLY)) { if (style != XO_STYLE_TEXT && xo_style(xop) != XO_STYLE_HTML) xf.xf_skip = 1; } if (!make_output) xf.xf_skip = 1; /* * Looking at one piece of a format; find the end and * call snprintf. Then advance xo_vap on our own. * * Note that 'n', 'v', and '$' are not supported. */ sp = cp; /* Save start pointer */ for (cp += 1; cp < ep; cp++) { if (*cp == 'l') xf.xf_lflag += 1; else if (*cp == 'h') xf.xf_hflag += 1; else if (*cp == 'j') xf.xf_jflag += 1; else if (*cp == 't') xf.xf_tflag += 1; else if (*cp == 'z') xf.xf_zflag += 1; else if (*cp == 'q') xf.xf_qflag += 1; else if (*cp == '.') { if (++xf.xf_dots >= XF_WIDTH_NUM) { xo_failure(xop, "Too many dots in format: '%s'", fmt); return -1; } } else if (*cp == '-') xf.xf_seen_minus = 1; else if (isdigit((int) *cp)) { if (xf.xf_leading_zero < 0) xf.xf_leading_zero = (*cp == '0'); xo_bump_width(&xf, *cp - '0'); } else if (*cp == '*') { xf.xf_stars += 1; xf.xf_star[xf.xf_dots] = 1; } else if (strchr("diouxXDOUeEfFgGaAcCsSpm", *cp) != NULL) break; else if (*cp == 'n' || *cp == 'v') { xo_failure(xop, "unsupported format: '%s'", fmt); return -1; } } if (cp == ep) xo_failure(xop, "field format missing format character: %s", fmt); xf.xf_fc = *cp; if (!XOF_ISSET(xop, XOF_NO_VA_ARG)) { if (*cp == 's' || *cp == 'S') { /* Handle "%*.*.*s" */ int s; for (s = 0; s < XF_WIDTH_NUM; s++) { if (xf.xf_star[s]) { xf.xf_width[s] = va_arg(xop->xo_vap, int); /* Normalize a negative width value */ if (xf.xf_width[s] < 0) { if (s == 0) { xf.xf_width[0] = -xf.xf_width[0]; xf.xf_seen_minus = 1; } else xf.xf_width[s] = -1; /* Ignore negative values */ } } } } } /* If no max is given, it defaults to size */ if (xf.xf_width[XF_WIDTH_MAX] < 0 && xf.xf_width[XF_WIDTH_SIZE] >= 0) xf.xf_width[XF_WIDTH_MAX] = xf.xf_width[XF_WIDTH_SIZE]; if (xf.xf_fc == 'D' || xf.xf_fc == 'O' || xf.xf_fc == 'U') xf.xf_lflag = 1; if (!xf.xf_skip) { xo_buffer_t *fbp = &xop->xo_fmt; ssize_t len = cp - sp + 1; if (!xo_buf_has_room(fbp, len + 1)) return -1; char *newfmt = fbp->xb_curp; memcpy(newfmt, sp, len); newfmt[0] = '%'; /* If we skipped over a "%@...@s" format */ newfmt[len] = '\0'; /* * Bad news: our strings are UTF-8, but the stock printf * functions won't handle field widths for wide characters * correctly. So we have to handle this ourselves. */ if (xop->xo_formatter == NULL && (xf.xf_fc == 's' || xf.xf_fc == 'S' || xf.xf_fc == 'm')) { xf.xf_enc = (xf.xf_fc == 'm') ? XF_ENC_UTF8 : (xf.xf_lflag || (xf.xf_fc == 'S')) ? XF_ENC_WIDE : xf.xf_hflag ? XF_ENC_LOCALE : XF_ENC_UTF8; rc = xo_format_string(xop, xbp, flags, &xf); if ((flags & XFF_TRIM_WS) && xo_style_is_encoding(xop)) rc = xo_trim_ws(xbp, rc); } else { ssize_t columns = rc = xo_vsnprintf(xop, xbp, newfmt, xop->xo_vap); if (rc > 0) { /* * For XML and HTML, we need "&<>" processing; for JSON, * it's quotes. Text gets nothing. */ switch (style) { case XO_STYLE_XML: if (flags & XFF_TRIM_WS) columns = rc = xo_trim_ws(xbp, rc); /* FALLTHRU */ case XO_STYLE_HTML: rc = xo_escape_xml(xbp, rc, (flags & XFF_ATTR)); break; case XO_STYLE_JSON: if (flags & XFF_TRIM_WS) columns = rc = xo_trim_ws(xbp, rc); rc = xo_escape_json(xbp, rc, 0); break; case XO_STYLE_SDPARAMS: if (flags & XFF_TRIM_WS) columns = rc = xo_trim_ws(xbp, rc); rc = xo_escape_sdparams(xbp, rc, 0); break; case XO_STYLE_ENCODER: if (flags & XFF_TRIM_WS) columns = rc = xo_trim_ws(xbp, rc); break; } /* * We can assume all the non-%s data we've * added is ASCII, so the columns and bytes are the * same. xo_format_string handles all the fancy * string conversions and updates xo_anchor_columns * accordingly. */ if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += columns; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += columns; } } if (rc > 0) xbp->xb_curp += rc; } /* * Now for the tricky part: we need to move the argument pointer * along by the amount needed. */ if (!XOF_ISSET(xop, XOF_NO_VA_ARG)) { if (xf.xf_fc == 's' ||xf.xf_fc == 'S') { /* * The 'S' and 's' formats are normally handled in * xo_format_string, but if we skipped it, then we * need to pop it. */ if (xf.xf_skip) va_arg(xop->xo_vap, char *); } else if (xf.xf_fc == 'm') { /* Nothing on the stack for "%m" */ } else { int s; for (s = 0; s < XF_WIDTH_NUM; s++) { if (xf.xf_star[s]) va_arg(xop->xo_vap, int); } if (strchr("diouxXDOU", xf.xf_fc) != NULL) { if (xf.xf_hflag > 1) { va_arg(xop->xo_vap, int); } else if (xf.xf_hflag > 0) { va_arg(xop->xo_vap, int); } else if (xf.xf_lflag > 1) { va_arg(xop->xo_vap, unsigned long long); } else if (xf.xf_lflag > 0) { va_arg(xop->xo_vap, unsigned long); } else if (xf.xf_jflag > 0) { va_arg(xop->xo_vap, intmax_t); } else if (xf.xf_tflag > 0) { va_arg(xop->xo_vap, ptrdiff_t); } else if (xf.xf_zflag > 0) { va_arg(xop->xo_vap, size_t); } else if (xf.xf_qflag > 0) { va_arg(xop->xo_vap, quad_t); } else { va_arg(xop->xo_vap, int); } } else if (strchr("eEfFgGaA", xf.xf_fc) != NULL) if (xf.xf_lflag) va_arg(xop->xo_vap, long double); else va_arg(xop->xo_vap, double); else if (xf.xf_fc == 'C' || (xf.xf_fc == 'c' && xf.xf_lflag)) va_arg(xop->xo_vap, wint_t); else if (xf.xf_fc == 'c') va_arg(xop->xo_vap, int); else if (xf.xf_fc == 'p') va_arg(xop->xo_vap, void *); } } } if (xp) { if (make_output) { cols = xo_format_string_direct(xop, xbp, flags | XFF_UNESCAPE, NULL, xp, cp - xp, -1, need_enc, XF_ENC_UTF8); if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += cols; } xp = NULL; } if (flags & XFF_GT_FLAGS) { /* * Handle gettext()ing the field by looking up the value * and then copying it in, while converting to locale, if * needed. */ ssize_t new_cols = xo_format_gettext(xop, flags, start_offset, old_cols, real_need_enc); if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += new_cols - old_cols; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += new_cols - old_cols; } return 0; } /* * Remove any numeric precision/width format from the format string by * inserting the "%" after the [0-9]+, returning the substring. */ static char * xo_fix_encoding (xo_handle_t *xop UNUSED, char *encoding) { char *cp = encoding; if (cp[0] != '%' || !isdigit((int) cp[1])) return encoding; for (cp += 2; *cp; cp++) { if (!isdigit((int) *cp)) break; } *--cp = '%'; /* Back off and insert the '%' */ return cp; } static void xo_color_append_html (xo_handle_t *xop) { /* * If the color buffer has content, we add it now. It's already * prebuilt and ready, since we want to add it to every
. */ if (!xo_buf_is_empty(&xop->xo_color_buf)) { xo_buffer_t *xbp = &xop->xo_color_buf; xo_data_append(xop, xbp->xb_bufp, xbp->xb_curp - xbp->xb_bufp); } } /* * A wrapper for humanize_number that autoscales, since the * HN_AUTOSCALE flag scales as needed based on the size of * the output buffer, not the size of the value. I also * wish HN_DECIMAL was more imperative, without the <10 * test. But the boat only goes where we want when we hold * the rudder, so xo_humanize fixes part of the problem. */ static ssize_t xo_humanize (char *buf, ssize_t len, uint64_t value, int flags) { int scale = 0; if (value) { uint64_t left = value; if (flags & HN_DIVISOR_1000) { for ( ; left; scale++) left /= 1000; } else { for ( ; left; scale++) left /= 1024; } scale -= 1; } return xo_humanize_number(buf, len, value, "", scale, flags); } /* * This is an area where we can save information from the handle for * later restoration. We need to know what data was rendered to know * what needs cleaned up. */ typedef struct xo_humanize_save_s { ssize_t xhs_offset; /* Saved xo_offset */ ssize_t xhs_columns; /* Saved xo_columns */ ssize_t xhs_anchor_columns; /* Saved xo_anchor_columns */ } xo_humanize_save_t; /* * Format a "humanized" value for a numeric, meaning something nice * like "44M" instead of "44470272". We autoscale, choosing the * most appropriate value for K/M/G/T/P/E based on the value given. */ static void xo_format_humanize (xo_handle_t *xop, xo_buffer_t *xbp, xo_humanize_save_t *savep, xo_xff_flags_t flags) { if (XOF_ISSET(xop, XOF_NO_HUMANIZE)) return; ssize_t end_offset = xbp->xb_curp - xbp->xb_bufp; if (end_offset == savep->xhs_offset) /* Huh? Nothing to render */ return; /* * We have a string that's allegedly a number. We want to * humanize it, which means turning it back into a number * and calling xo_humanize_number on it. */ uint64_t value; char *ep; xo_buf_append(xbp, "", 1); /* NUL-terminate it */ value = strtoull(xbp->xb_bufp + savep->xhs_offset, &ep, 0); if (!(value == ULLONG_MAX && errno == ERANGE) && (ep != xbp->xb_bufp + savep->xhs_offset)) { /* * There are few values where humanize_number needs * more bytes than the original value. I've used * 10 as a rectal number to cover those scenarios. */ if (xo_buf_has_room(xbp, 10)) { xbp->xb_curp = xbp->xb_bufp + savep->xhs_offset; ssize_t rc; ssize_t left = (xbp->xb_bufp + xbp->xb_size) - xbp->xb_curp; int hn_flags = HN_NOSPACE; /* On by default */ if (flags & XFF_HN_SPACE) hn_flags &= ~HN_NOSPACE; if (flags & XFF_HN_DECIMAL) hn_flags |= HN_DECIMAL; if (flags & XFF_HN_1000) hn_flags |= HN_DIVISOR_1000; rc = xo_humanize(xbp->xb_curp, left, value, hn_flags); if (rc > 0) { xbp->xb_curp += rc; xop->xo_columns = savep->xhs_columns + rc; xop->xo_anchor_columns = savep->xhs_anchor_columns + rc; } } } } /* * Convenience function that either append a fixed value (if one is * given) or formats a field using a format string. If it's * encode_only, then we can't skip formatting the field, since it may * be pulling arguments off the stack. */ static inline void xo_simple_field (xo_handle_t *xop, unsigned encode_only, const char *value, ssize_t vlen, const char *fmt, ssize_t flen, xo_xff_flags_t flags) { if (encode_only) flags |= XFF_NO_OUTPUT; if (vlen == 0) xo_do_format_field(xop, NULL, fmt, flen, flags); else if (!encode_only) xo_data_append_content(xop, value, vlen, flags); } /* * Html mode: append a
to the output buffer contain a field * along with all the supporting information indicated by the flags. */ static void xo_buf_append_div (xo_handle_t *xop, const char *class, xo_xff_flags_t flags, const char *name, ssize_t nlen, const char *value, ssize_t vlen, const char *fmt, ssize_t flen, const char *encoding, ssize_t elen) { static char div_start[] = "
"; static char div_close[] = "
"; /* The encoding format defaults to the normal format */ if (encoding == NULL && fmt != NULL) { char *enc = alloca(flen + 1); memcpy(enc, fmt, flen); enc[flen] = '\0'; encoding = xo_fix_encoding(xop, enc); elen = strlen(encoding); } /* * To build our XPath predicate, we need to save the va_list before * we format our data, and then restore it before we format the * xpath expression. * Display-only keys implies that we've got an encode-only key * elsewhere, so we don't use them from making predicates. */ int need_predidate = (name && (flags & XFF_KEY) && !(flags & XFF_DISPLAY_ONLY) && XOF_ISSET(xop, XOF_XPATH)) ? 1 : 0; if (need_predidate) { va_list va_local; va_copy(va_local, xop->xo_vap); if (xop->xo_checkpointer) xop->xo_checkpointer(xop, xop->xo_vap, 0); /* * Build an XPath predicate expression to match this key. * We use the format buffer. */ xo_buffer_t *pbp = &xop->xo_predicate; pbp->xb_curp = pbp->xb_bufp; /* Restart buffer */ xo_buf_append(pbp, "[", 1); xo_buf_escape(xop, pbp, name, nlen, 0); if (XOF_ISSET(xop, XOF_PRETTY)) xo_buf_append(pbp, " = '", 4); else xo_buf_append(pbp, "='", 2); xo_xff_flags_t pflags = flags | XFF_XML | XFF_ATTR; pflags &= ~(XFF_NO_OUTPUT | XFF_ENCODE_ONLY); xo_do_format_field(xop, pbp, encoding, elen, pflags); xo_buf_append(pbp, "']", 2); /* Now we record this predicate expression in the stack */ xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; ssize_t olen = xsp->xs_keys ? strlen(xsp->xs_keys) : 0; ssize_t dlen = pbp->xb_curp - pbp->xb_bufp; char *cp = xo_realloc(xsp->xs_keys, olen + dlen + 1); if (cp) { memcpy(cp + olen, pbp->xb_bufp, dlen); cp[olen + dlen] = '\0'; xsp->xs_keys = cp; } /* Now we reset the xo_vap as if we were never here */ va_end(xop->xo_vap); va_copy(xop->xo_vap, va_local); va_end(va_local); if (xop->xo_checkpointer) xop->xo_checkpointer(xop, xop->xo_vap, 1); } if (flags & XFF_ENCODE_ONLY) { /* * Even if this is encode-only, we need to go through the * work of formatting it to make sure the args are cleared * from xo_vap. This is not true when vlen is zero, since * that means our "value" isn't on the stack. */ xo_simple_field(xop, TRUE, NULL, 0, encoding, elen, flags); return; } xo_line_ensure_open(xop, 0); if (XOF_ISSET(xop, XOF_PRETTY)) xo_buf_indent(xop, xop->xo_indent_by); xo_data_append(xop, div_start, sizeof(div_start) - 1); xo_data_append(xop, class, strlen(class)); /* * If the color buffer has content, we add it now. It's already * prebuilt and ready, since we want to add it to every
. */ if (!xo_buf_is_empty(&xop->xo_color_buf)) { xo_buffer_t *xbp = &xop->xo_color_buf; xo_data_append(xop, xbp->xb_bufp, xbp->xb_curp - xbp->xb_bufp); } if (name) { xo_data_append(xop, div_tag, sizeof(div_tag) - 1); xo_data_escape(xop, name, nlen); /* * Save the offset at which we'd place units. See xo_format_units. */ if (XOF_ISSET(xop, XOF_UNITS)) { XOIF_SET(xop, XOIF_UNITS_PENDING); /* * Note: We need the '+1' here because we know we've not * added the closing quote. We add one, knowing the quote * will be added shortly. */ xop->xo_units_offset = xop->xo_data.xb_curp -xop->xo_data.xb_bufp + 1; } if (XOF_ISSET(xop, XOF_XPATH)) { int i; xo_stack_t *xsp; xo_data_append(xop, div_xpath, sizeof(div_xpath) - 1); if (xop->xo_leading_xpath) xo_data_append(xop, xop->xo_leading_xpath, strlen(xop->xo_leading_xpath)); for (i = 0; i <= xop->xo_depth; i++) { xsp = &xop->xo_stack[i]; if (xsp->xs_name == NULL) continue; /* * XSS_OPEN_LIST and XSS_OPEN_LEAF_LIST stack frames * are directly under XSS_OPEN_INSTANCE frames so we * don't need to put these in our XPath expressions. */ if (xsp->xs_state == XSS_OPEN_LIST || xsp->xs_state == XSS_OPEN_LEAF_LIST) continue; xo_data_append(xop, "/", 1); xo_data_escape(xop, xsp->xs_name, strlen(xsp->xs_name)); if (xsp->xs_keys) { /* Don't show keys for the key field */ if (i != xop->xo_depth || !(flags & XFF_KEY)) xo_data_append(xop, xsp->xs_keys, strlen(xsp->xs_keys)); } } xo_data_append(xop, "/", 1); xo_data_escape(xop, name, nlen); } if (XOF_ISSET(xop, XOF_INFO) && xop->xo_info) { static char in_type[] = "\" data-type=\""; static char in_help[] = "\" data-help=\""; xo_info_t *xip = xo_info_find(xop, name, nlen); if (xip) { if (xip->xi_type) { xo_data_append(xop, in_type, sizeof(in_type) - 1); xo_data_escape(xop, xip->xi_type, strlen(xip->xi_type)); } if (xip->xi_help) { xo_data_append(xop, in_help, sizeof(in_help) - 1); xo_data_escape(xop, xip->xi_help, strlen(xip->xi_help)); } } } if ((flags & XFF_KEY) && XOF_ISSET(xop, XOF_KEYS)) xo_data_append(xop, div_key, sizeof(div_key) - 1); } xo_buffer_t *xbp = &xop->xo_data; ssize_t base_offset = xbp->xb_curp - xbp->xb_bufp; xo_data_append(xop, div_end, sizeof(div_end) - 1); xo_humanize_save_t save; /* Save values for humanizing logic */ save.xhs_offset = xbp->xb_curp - xbp->xb_bufp; save.xhs_columns = xop->xo_columns; save.xhs_anchor_columns = xop->xo_anchor_columns; xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); if (flags & XFF_HUMANIZE) { /* * Unlike text style, we want to retain the original value and * stuff it into the "data-number" attribute. */ static const char div_number[] = "\" data-number=\""; ssize_t div_len = sizeof(div_number) - 1; ssize_t end_offset = xbp->xb_curp - xbp->xb_bufp; ssize_t olen = end_offset - save.xhs_offset; char *cp = alloca(olen + 1); memcpy(cp, xbp->xb_bufp + save.xhs_offset, olen); cp[olen] = '\0'; xo_format_humanize(xop, xbp, &save, flags); if (xo_buf_has_room(xbp, div_len + olen)) { ssize_t new_offset = xbp->xb_curp - xbp->xb_bufp; /* Move the humanized string off to the left */ memmove(xbp->xb_bufp + base_offset + div_len + olen, xbp->xb_bufp + base_offset, new_offset - base_offset); /* Copy the data_number attribute name */ memcpy(xbp->xb_bufp + base_offset, div_number, div_len); /* Copy the original long value */ memcpy(xbp->xb_bufp + base_offset + div_len, cp, olen); xbp->xb_curp += div_len + olen; } } xo_data_append(xop, div_close, sizeof(div_close) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); } static void xo_format_text (xo_handle_t *xop, const char *str, ssize_t len) { switch (xo_style(xop)) { case XO_STYLE_TEXT: xo_buf_append_locale(xop, &xop->xo_data, str, len); break; case XO_STYLE_HTML: xo_buf_append_div(xop, "text", 0, NULL, 0, str, len, NULL, 0, NULL, 0); break; } } static void xo_format_title (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { const char *fmt = xfip->xfi_format; ssize_t flen = xfip->xfi_flen; xo_xff_flags_t flags = xfip->xfi_flags; static char div_open[] = "
"; static char div_close[] = "
"; if (flen == 0) { fmt = "%s"; flen = 2; } switch (xo_style(xop)) { case XO_STYLE_XML: case XO_STYLE_JSON: case XO_STYLE_SDPARAMS: case XO_STYLE_ENCODER: /* * Even though we don't care about text, we need to do * enough parsing work to skip over the right bits of xo_vap. */ xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); return; } xo_buffer_t *xbp = &xop->xo_data; ssize_t start = xbp->xb_curp - xbp->xb_bufp; ssize_t left = xbp->xb_size - start; ssize_t rc; if (xo_style(xop) == XO_STYLE_HTML) { xo_line_ensure_open(xop, 0); if (XOF_ISSET(xop, XOF_PRETTY)) xo_buf_indent(xop, xop->xo_indent_by); xo_buf_append(&xop->xo_data, div_open, sizeof(div_open) - 1); xo_color_append_html(xop); xo_buf_append(&xop->xo_data, div_middle, sizeof(div_middle) - 1); } start = xbp->xb_curp - xbp->xb_bufp; /* Reset start */ if (vlen) { char *newfmt = alloca(flen + 1); memcpy(newfmt, fmt, flen); newfmt[flen] = '\0'; /* If len is non-zero, the format string apply to the name */ char *newstr = alloca(vlen + 1); memcpy(newstr, value, vlen); newstr[vlen] = '\0'; if (newstr[vlen - 1] == 's') { char *bp; rc = snprintf(NULL, 0, newfmt, newstr); if (rc > 0) { /* * We have to do this the hard way, since we might need * the columns. */ bp = alloca(rc + 1); rc = snprintf(bp, rc + 1, newfmt, newstr); xo_data_append_content(xop, bp, rc, flags); } goto move_along; } else { rc = snprintf(xbp->xb_curp, left, newfmt, newstr); if (rc >= left) { if (!xo_buf_has_room(xbp, rc)) return; left = xbp->xb_size - (xbp->xb_curp - xbp->xb_bufp); rc = snprintf(xbp->xb_curp, left, newfmt, newstr); } if (rc > 0) { if (XOF_ISSET(xop, XOF_COLUMNS)) xop->xo_columns += rc; if (XOIF_ISSET(xop, XOIF_ANCHOR)) xop->xo_anchor_columns += rc; } } } else { xo_do_format_field(xop, NULL, fmt, flen, flags); /* xo_do_format_field moved curp, so we need to reset it */ rc = xbp->xb_curp - (xbp->xb_bufp + start); xbp->xb_curp = xbp->xb_bufp + start; } /* If we're styling HTML, then we need to escape it */ if (xo_style(xop) == XO_STYLE_HTML) { rc = xo_escape_xml(xbp, rc, 0); } if (rc > 0) xbp->xb_curp += rc; move_along: if (xo_style(xop) == XO_STYLE_HTML) { xo_data_append(xop, div_close, sizeof(div_close) - 1); if (XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); } } /* * strspn() with a string length */ static ssize_t xo_strnspn (const char *str, size_t len, const char *accept) { ssize_t i; const char *cp, *ep; for (i = 0, cp = str, ep = str + len; cp < ep && *cp != '\0'; i++, cp++) { if (strchr(accept, *cp) == NULL) break; } return i; } /* * Decide if a format string should be considered "numeric", * in the sense that the number does not need to be quoted. * This means that it consists only of a single numeric field * with nothing exotic or "interesting". This means that * static values are never considered numeric. */ static int xo_format_is_numeric (const char *fmt, ssize_t flen) { if (flen <= 0 || *fmt++ != '%') /* Must start with '%' */ return FALSE; flen -= 1; /* Handle leading flags; don't want "#" since JSON can't handle hex */ ssize_t spn = xo_strnspn(fmt, flen, "0123456789.*+ -"); if (spn >= flen) return FALSE; fmt += spn; /* Move along the input string */ flen -= spn; /* Handle the length modifiers */ spn = xo_strnspn(fmt, flen, "hljtqz"); if (spn >= flen) return FALSE; fmt += spn; /* Move along the input string */ flen -= spn; if (flen != 1) /* Should only be one character left */ return FALSE; return (strchr("diouDOUeEfFgG", *fmt) == NULL) ? FALSE : TRUE; } /* * Update the stack flags using the object flags, allowing callers * to monkey with the stack flags without even knowing they exist. */ static void xo_stack_set_flags (xo_handle_t *xop) { if (XOF_ISSET(xop, XOF_NOT_FIRST)) { xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; xsp->xs_flags |= XSF_NOT_FIRST; XOF_CLEAR(xop, XOF_NOT_FIRST); } } static void xo_format_prep (xo_handle_t *xop, xo_xff_flags_t flags) { if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) { xo_data_append(xop, ",", 1); if (!(flags & XFF_LEAF_LIST) && XOF_ISSET(xop, XOF_PRETTY)) xo_data_append(xop, "\n", 1); } else xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; } #if 0 /* Useful debugging function */ void xo_arg (xo_handle_t *xop); void xo_arg (xo_handle_t *xop) { xop = xo_default(xop); fprintf(stderr, "0x%x", va_arg(xop->xo_vap, unsigned)); } #endif /* 0 */ static void xo_format_value (xo_handle_t *xop, const char *name, ssize_t nlen, const char *value, ssize_t vlen, const char *fmt, ssize_t flen, const char *encoding, ssize_t elen, xo_xff_flags_t flags) { int pretty = XOF_ISSET(xop, XOF_PRETTY); int quote; /* * Before we emit a value, we need to know that the frame is ready. */ xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; if (flags & XFF_LEAF_LIST) { /* * Check if we've already started to emit normal leafs * or if we're not in a leaf list. */ if ((xsp->xs_flags & (XSF_EMIT | XSF_EMIT_KEY)) || !(xsp->xs_flags & XSF_EMIT_LEAF_LIST)) { char nbuf[nlen + 1]; memcpy(nbuf, name, nlen); nbuf[nlen] = '\0'; ssize_t rc = xo_transition(xop, 0, nbuf, XSS_EMIT_LEAF_LIST); if (rc < 0) flags |= XFF_DISPLAY_ONLY | XFF_ENCODE_ONLY; else xop->xo_stack[xop->xo_depth].xs_flags |= XSF_EMIT_LEAF_LIST; } xsp = &xop->xo_stack[xop->xo_depth]; if (xsp->xs_name) { name = xsp->xs_name; nlen = strlen(name); } } else if (flags & XFF_KEY) { /* Emitting a 'k' (key) field */ if ((xsp->xs_flags & XSF_EMIT) && !(flags & XFF_DISPLAY_ONLY)) { xo_failure(xop, "key field emitted after normal value field: '%.*s'", nlen, name); } else if (!(xsp->xs_flags & XSF_EMIT_KEY)) { char nbuf[nlen + 1]; memcpy(nbuf, name, nlen); nbuf[nlen] = '\0'; ssize_t rc = xo_transition(xop, 0, nbuf, XSS_EMIT); if (rc < 0) flags |= XFF_DISPLAY_ONLY | XFF_ENCODE_ONLY; else xop->xo_stack[xop->xo_depth].xs_flags |= XSF_EMIT_KEY; xsp = &xop->xo_stack[xop->xo_depth]; xsp->xs_flags |= XSF_EMIT_KEY; } } else { /* Emitting a normal value field */ if ((xsp->xs_flags & XSF_EMIT_LEAF_LIST) || !(xsp->xs_flags & XSF_EMIT)) { char nbuf[nlen + 1]; memcpy(nbuf, name, nlen); nbuf[nlen] = '\0'; ssize_t rc = xo_transition(xop, 0, nbuf, XSS_EMIT); if (rc < 0) flags |= XFF_DISPLAY_ONLY | XFF_ENCODE_ONLY; else xop->xo_stack[xop->xo_depth].xs_flags |= XSF_EMIT; xsp = &xop->xo_stack[xop->xo_depth]; xsp->xs_flags |= XSF_EMIT; } } xo_buffer_t *xbp = &xop->xo_data; xo_humanize_save_t save; /* Save values for humanizing logic */ const char *leader = xo_xml_leader_len(xop, name, nlen); switch (xo_style(xop)) { case XO_STYLE_TEXT: if (flags & XFF_ENCODE_ONLY) flags |= XFF_NO_OUTPUT; save.xhs_offset = xbp->xb_curp - xbp->xb_bufp; save.xhs_columns = xop->xo_columns; save.xhs_anchor_columns = xop->xo_anchor_columns; xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); if (flags & XFF_HUMANIZE) xo_format_humanize(xop, xbp, &save, flags); break; case XO_STYLE_HTML: if (flags & XFF_ENCODE_ONLY) flags |= XFF_NO_OUTPUT; xo_buf_append_div(xop, "data", flags, name, nlen, value, vlen, fmt, flen, encoding, elen); break; case XO_STYLE_XML: /* * Even though we're not making output, we still need to * let the formatting code handle the va_arg popping. */ if (flags & XFF_DISPLAY_ONLY) { xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); break; } if (encoding) { fmt = encoding; flen = elen; } else { char *enc = alloca(flen + 1); memcpy(enc, fmt, flen); enc[flen] = '\0'; fmt = xo_fix_encoding(xop, enc); flen = strlen(fmt); } if (nlen == 0) { static char missing[] = "missing-field-name"; xo_failure(xop, "missing field name: %s", fmt); name = missing; nlen = sizeof(missing) - 1; } if (pretty) xo_buf_indent(xop, -1); xo_data_append(xop, "<", 1); if (*leader) xo_data_append(xop, leader, 1); xo_data_escape(xop, name, nlen); if (xop->xo_attrs.xb_curp != xop->xo_attrs.xb_bufp) { xo_data_append(xop, xop->xo_attrs.xb_bufp, xop->xo_attrs.xb_curp - xop->xo_attrs.xb_bufp); xop->xo_attrs.xb_curp = xop->xo_attrs.xb_bufp; } /* * We indicate 'key' fields using the 'key' attribute. While * this is really committing the crime of mixing meta-data with * data, it's often useful. Especially when format meta-data is * difficult to come by. */ if ((flags & XFF_KEY) && XOF_ISSET(xop, XOF_KEYS)) { static char attr[] = " key=\"key\""; xo_data_append(xop, attr, sizeof(attr) - 1); } /* * Save the offset at which we'd place units. See xo_format_units. */ if (XOF_ISSET(xop, XOF_UNITS)) { XOIF_SET(xop, XOIF_UNITS_PENDING); xop->xo_units_offset = xop->xo_data.xb_curp -xop->xo_data.xb_bufp; } xo_data_append(xop, ">", 1); xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); xo_data_append(xop, "", 1); if (pretty) xo_data_append(xop, "\n", 1); break; case XO_STYLE_JSON: if (flags & XFF_DISPLAY_ONLY) { xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); break; } if (encoding) { fmt = encoding; flen = elen; } else { char *enc = alloca(flen + 1); memcpy(enc, fmt, flen); enc[flen] = '\0'; fmt = xo_fix_encoding(xop, enc); flen = strlen(fmt); } xo_stack_set_flags(xop); int first = (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) ? 0 : 1; xo_format_prep(xop, flags); if (flags & XFF_QUOTE) quote = 1; else if (flags & XFF_NOQUOTE) quote = 0; else if (vlen != 0) quote = 1; else if (flen == 0) { quote = 0; fmt = "true"; /* JSON encodes empty tags as a boolean true */ flen = 4; } else if (xo_format_is_numeric(fmt, flen)) quote = 0; else quote = 1; if (nlen == 0) { static char missing[] = "missing-field-name"; xo_failure(xop, "missing field name: %s", fmt); name = missing; nlen = sizeof(missing) - 1; } if (flags & XFF_LEAF_LIST) { if (!first && pretty) xo_data_append(xop, "\n", 1); if (pretty) xo_buf_indent(xop, -1); } else { if (pretty) xo_buf_indent(xop, -1); xo_data_append(xop, "\"", 1); xbp = &xop->xo_data; ssize_t off = xbp->xb_curp - xbp->xb_bufp; xo_data_escape(xop, name, nlen); if (XOF_ISSET(xop, XOF_UNDERSCORES)) { ssize_t coff = xbp->xb_curp - xbp->xb_bufp; for ( ; off < coff; off++) if (xbp->xb_bufp[off] == '-') xbp->xb_bufp[off] = '_'; } xo_data_append(xop, "\":", 2); if (pretty) xo_data_append(xop, " ", 1); } if (quote) xo_data_append(xop, "\"", 1); xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); if (quote) xo_data_append(xop, "\"", 1); break; case XO_STYLE_SDPARAMS: if (flags & XFF_DISPLAY_ONLY) { xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); break; } if (encoding) { fmt = encoding; flen = elen; } else { char *enc = alloca(flen + 1); memcpy(enc, fmt, flen); enc[flen] = '\0'; fmt = xo_fix_encoding(xop, enc); flen = strlen(fmt); } if (nlen == 0) { static char missing[] = "missing-field-name"; xo_failure(xop, "missing field name: %s", fmt); name = missing; nlen = sizeof(missing) - 1; } xo_data_escape(xop, name, nlen); xo_data_append(xop, "=\"", 2); xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); xo_data_append(xop, "\" ", 2); break; case XO_STYLE_ENCODER: if (flags & XFF_DISPLAY_ONLY) { xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); break; } if (flags & XFF_QUOTE) quote = 1; else if (flags & XFF_NOQUOTE) quote = 0; else if (flen == 0) { quote = 0; fmt = "true"; /* JSON encodes empty tags as a boolean true */ flen = 4; } else if (strchr("diouxXDOUeEfFgGaAcCp", fmt[flen - 1]) == NULL) quote = 1; else quote = 0; if (encoding) { fmt = encoding; flen = elen; } else { char *enc = alloca(flen + 1); memcpy(enc, fmt, flen); enc[flen] = '\0'; fmt = xo_fix_encoding(xop, enc); flen = strlen(fmt); } if (nlen == 0) { static char missing[] = "missing-field-name"; xo_failure(xop, "missing field name: %s", fmt); name = missing; nlen = sizeof(missing) - 1; } ssize_t name_offset = xo_buf_offset(&xop->xo_data); xo_data_append(xop, name, nlen); xo_data_append(xop, "", 1); ssize_t value_offset = xo_buf_offset(&xop->xo_data); xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); xo_data_append(xop, "", 1); xo_encoder_handle(xop, quote ? XO_OP_STRING : XO_OP_CONTENT, xo_buf_data(&xop->xo_data, name_offset), xo_buf_data(&xop->xo_data, value_offset), flags); xo_buf_reset(&xop->xo_data); break; } } static void xo_set_gettext_domain (xo_handle_t *xop, xo_field_info_t *xfip, const char *str, ssize_t len) { const char *fmt = xfip->xfi_format; ssize_t flen = xfip->xfi_flen; /* Start by discarding previous domain */ if (xop->xo_gt_domain) { xo_free(xop->xo_gt_domain); xop->xo_gt_domain = NULL; } /* An empty {G:} means no domainname */ if (len == 0 && flen == 0) return; ssize_t start_offset = -1; if (len == 0 && flen != 0) { /* Need to do format the data to get the domainname from args */ start_offset = xop->xo_data.xb_curp - xop->xo_data.xb_bufp; xo_do_format_field(xop, NULL, fmt, flen, 0); ssize_t end_offset = xop->xo_data.xb_curp - xop->xo_data.xb_bufp; len = end_offset - start_offset; str = xop->xo_data.xb_bufp + start_offset; } xop->xo_gt_domain = xo_strndup(str, len); /* Reset the current buffer point to avoid emitting the name as output */ if (start_offset >= 0) xop->xo_data.xb_curp = xop->xo_data.xb_bufp + start_offset; } static void xo_format_content (xo_handle_t *xop, const char *class_name, const char *tag_name, const char *value, ssize_t vlen, const char *fmt, ssize_t flen, xo_xff_flags_t flags) { switch (xo_style(xop)) { case XO_STYLE_TEXT: xo_simple_field(xop, FALSE, value, vlen, fmt, flen, flags); break; case XO_STYLE_HTML: xo_buf_append_div(xop, class_name, flags, NULL, 0, value, vlen, fmt, flen, NULL, 0); break; case XO_STYLE_XML: case XO_STYLE_JSON: case XO_STYLE_SDPARAMS: if (tag_name) { xo_open_container_h(xop, tag_name); xo_format_value(xop, "message", 7, value, vlen, fmt, flen, NULL, 0, flags); xo_close_container_h(xop, tag_name); } else { /* * Even though we don't care about labels, we need to do * enough parsing work to skip over the right bits of xo_vap. */ xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); } break; case XO_STYLE_ENCODER: xo_simple_field(xop, TRUE, value, vlen, fmt, flen, flags); break; } } static const char *xo_color_names[] = { "default", /* XO_COL_DEFAULT */ "black", /* XO_COL_BLACK */ "red", /* XO_CLOR_RED */ "green", /* XO_COL_GREEN */ "yellow", /* XO_COL_YELLOW */ "blue", /* XO_COL_BLUE */ "magenta", /* XO_COL_MAGENTA */ "cyan", /* XO_COL_CYAN */ "white", /* XO_COL_WHITE */ NULL }; static int xo_color_find (const char *str) { int i; for (i = 0; xo_color_names[i]; i++) { if (xo_streq(xo_color_names[i], str)) return i; } return -1; } static const char *xo_effect_names[] = { "reset", /* XO_EFF_RESET */ "normal", /* XO_EFF_NORMAL */ "bold", /* XO_EFF_BOLD */ "underline", /* XO_EFF_UNDERLINE */ "inverse", /* XO_EFF_INVERSE */ NULL }; static const char *xo_effect_on_codes[] = { "0", /* XO_EFF_RESET */ "0", /* XO_EFF_NORMAL */ "1", /* XO_EFF_BOLD */ "4", /* XO_EFF_UNDERLINE */ "7", /* XO_EFF_INVERSE */ NULL }; #if 0 /* * See comment below re: joy of terminal standards. These can * be use by just adding: * + if (newp->xoc_effects & bit) * code = xo_effect_on_codes[i]; * + else * + code = xo_effect_off_codes[i]; * in xo_color_handle_text. */ static const char *xo_effect_off_codes[] = { "0", /* XO_EFF_RESET */ "0", /* XO_EFF_NORMAL */ "21", /* XO_EFF_BOLD */ "24", /* XO_EFF_UNDERLINE */ "27", /* XO_EFF_INVERSE */ NULL }; #endif /* 0 */ static int xo_effect_find (const char *str) { int i; for (i = 0; xo_effect_names[i]; i++) { if (xo_streq(xo_effect_names[i], str)) return i; } return -1; } static void xo_colors_parse (xo_handle_t *xop, xo_colors_t *xocp, char *str) { if (xo_text_only()) return; char *cp, *ep, *np, *xp; ssize_t len = strlen(str); int rc; /* * Possible tokens: colors, bg-colors, effects, no-effects, "reset". */ for (cp = str, ep = cp + len - 1; cp && cp < ep; cp = np) { /* Trim leading whitespace */ while (isspace((int) *cp)) cp += 1; np = strchr(cp, ','); if (np) *np++ = '\0'; /* Trim trailing whitespace */ xp = cp + strlen(cp) - 1; while (isspace(*xp) && xp > cp) *xp-- = '\0'; if (cp[0] == 'f' && cp[1] == 'g' && cp[2] == '-') { rc = xo_color_find(cp + 3); if (rc < 0) goto unknown; xocp->xoc_col_fg = rc; } else if (cp[0] == 'b' && cp[1] == 'g' && cp[2] == '-') { rc = xo_color_find(cp + 3); if (rc < 0) goto unknown; xocp->xoc_col_bg = rc; } else if (cp[0] == 'n' && cp[1] == 'o' && cp[2] == '-') { rc = xo_effect_find(cp + 3); if (rc < 0) goto unknown; xocp->xoc_effects &= ~(1 << rc); } else { rc = xo_effect_find(cp); if (rc < 0) goto unknown; xocp->xoc_effects |= 1 << rc; switch (1 << rc) { case XO_EFF_RESET: xocp->xoc_col_fg = xocp->xoc_col_bg = 0; /* Note: not "|=" since we want to wipe out the old value */ xocp->xoc_effects = XO_EFF_RESET; break; case XO_EFF_NORMAL: xocp->xoc_effects &= ~(XO_EFF_BOLD | XO_EFF_UNDERLINE | XO_EFF_INVERSE | XO_EFF_NORMAL); break; } } continue; unknown: if (XOF_ISSET(xop, XOF_WARN)) xo_failure(xop, "unknown color/effect string detected: '%s'", cp); } } static inline int xo_colors_enabled (xo_handle_t *xop UNUSED) { #ifdef LIBXO_TEXT_ONLY return 0; #else /* LIBXO_TEXT_ONLY */ return XOF_ISSET(xop, XOF_COLOR); #endif /* LIBXO_TEXT_ONLY */ } /* * If the color map is in use (--libxo colors=xxxx), then update * the incoming foreground and background colors from the map. */ static void xo_colors_update (xo_handle_t *xop UNUSED, xo_colors_t *newp UNUSED) { #ifndef LIBXO_TEXT_ONLY xo_color_t fg = newp->xoc_col_fg; if (XOF_ISSET(xop, XOF_COLOR_MAP) && fg < XO_NUM_COLORS) fg = xop->xo_color_map_fg[fg]; /* Fetch from color map */ newp->xoc_col_fg = fg; xo_color_t bg = newp->xoc_col_bg; if (XOF_ISSET(xop, XOF_COLOR_MAP) && bg < XO_NUM_COLORS) bg = xop->xo_color_map_bg[bg]; /* Fetch from color map */ newp->xoc_col_bg = bg; #endif /* LIBXO_TEXT_ONLY */ } static void xo_colors_handle_text (xo_handle_t *xop, xo_colors_t *newp) { char buf[BUFSIZ]; char *cp = buf, *ep = buf + sizeof(buf); unsigned i, bit; xo_colors_t *oldp = &xop->xo_colors; const char *code = NULL; /* * Start the buffer with an escape. We don't want to add the '[' * now, since we let xo_effect_text_add unconditionally add the ';'. * We'll replace the first ';' with a '[' when we're done. */ *cp++ = 0x1b; /* Escape */ /* * Terminals were designed back in the age before "certainty" was * invented, when standards were more what you'd call "guidelines" * than actual rules. Anyway we can't depend on them to operate * correctly. So when display attributes are changed, we punt, * reseting them all and turning back on the ones we want to keep. * Longer, but should be completely reliable. Savvy? */ if (oldp->xoc_effects != (newp->xoc_effects & oldp->xoc_effects)) { newp->xoc_effects |= XO_EFF_RESET; oldp->xoc_effects = 0; } for (i = 0, bit = 1; xo_effect_names[i]; i++, bit <<= 1) { if ((newp->xoc_effects & bit) == (oldp->xoc_effects & bit)) continue; code = xo_effect_on_codes[i]; cp += snprintf(cp, ep - cp, ";%s", code); if (cp >= ep) return; /* Should not occur */ if (bit == XO_EFF_RESET) { /* Mark up the old value so we can detect current values as new */ oldp->xoc_effects = 0; oldp->xoc_col_fg = oldp->xoc_col_bg = XO_COL_DEFAULT; } } xo_color_t fg = newp->xoc_col_fg; if (fg != oldp->xoc_col_fg) { cp += snprintf(cp, ep - cp, ";3%u", (fg != XO_COL_DEFAULT) ? fg - 1 : 9); } xo_color_t bg = newp->xoc_col_bg; if (bg != oldp->xoc_col_bg) { cp += snprintf(cp, ep - cp, ";4%u", (bg != XO_COL_DEFAULT) ? bg - 1 : 9); } if (cp - buf != 1 && cp < ep - 3) { buf[1] = '['; /* Overwrite leading ';' */ *cp++ = 'm'; *cp = '\0'; xo_buf_append(&xop->xo_data, buf, cp - buf); } } static void xo_colors_handle_html (xo_handle_t *xop, xo_colors_t *newp) { xo_colors_t *oldp = &xop->xo_colors; /* * HTML colors are mostly trivial: fill in xo_color_buf with * a set of class tags representing the colors and effects. */ /* If nothing changed, then do nothing */ if (oldp->xoc_effects == newp->xoc_effects && oldp->xoc_col_fg == newp->xoc_col_fg && oldp->xoc_col_bg == newp->xoc_col_bg) return; unsigned i, bit; xo_buffer_t *xbp = &xop->xo_color_buf; xo_buf_reset(xbp); /* We rebuild content after each change */ for (i = 0, bit = 1; xo_effect_names[i]; i++, bit <<= 1) { if (!(newp->xoc_effects & bit)) continue; xo_buf_append_str(xbp, " effect-"); xo_buf_append_str(xbp, xo_effect_names[i]); } const char *fg = NULL; const char *bg = NULL; if (newp->xoc_col_fg != XO_COL_DEFAULT) fg = xo_color_names[newp->xoc_col_fg]; if (newp->xoc_col_bg != XO_COL_DEFAULT) bg = xo_color_names[newp->xoc_col_bg]; if (newp->xoc_effects & XO_EFF_INVERSE) { const char *tmp = fg; fg = bg; bg = tmp; if (fg == NULL) fg = "inverse"; if (bg == NULL) bg = "inverse"; } if (fg) { xo_buf_append_str(xbp, " color-fg-"); xo_buf_append_str(xbp, fg); } if (bg) { xo_buf_append_str(xbp, " color-bg-"); xo_buf_append_str(xbp, bg); } } static void xo_format_colors (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { const char *fmt = xfip->xfi_format; ssize_t flen = xfip->xfi_flen; xo_buffer_t xb; /* If the string is static and we've in an encoding style, bail */ if (vlen != 0 && xo_style_is_encoding(xop)) return; xo_buf_init(&xb); if (vlen) xo_buf_append(&xb, value, vlen); else if (flen) xo_do_format_field(xop, &xb, fmt, flen, 0); else xo_buf_append(&xb, "reset", 6); /* Default if empty */ if (xo_colors_enabled(xop)) { switch (xo_style(xop)) { case XO_STYLE_TEXT: case XO_STYLE_HTML: xo_buf_append(&xb, "", 1); xo_colors_t xoc = xop->xo_colors; xo_colors_parse(xop, &xoc, xb.xb_bufp); xo_colors_update(xop, &xoc); if (xo_style(xop) == XO_STYLE_TEXT) { /* * Text mode means emitting the colors as ANSI character * codes. This will allow people who like colors to have * colors. The issue is, of course conflicting with the * user's perfectly reasonable color scheme. Which leads * to the hell of LSCOLORS, where even app need to have * customization hooks for adjusting colors. Instead we * provide a simpler-but-still-annoying answer where one * can map colors to other colors. */ xo_colors_handle_text(xop, &xoc); xoc.xoc_effects &= ~XO_EFF_RESET; /* After handling it */ } else { /* * HTML output is wrapped in divs, so the color information * must appear in every div until cleared. Most pathetic. * Most unavoidable. */ xoc.xoc_effects &= ~XO_EFF_RESET; /* Before handling effects */ xo_colors_handle_html(xop, &xoc); } xop->xo_colors = xoc; break; case XO_STYLE_XML: case XO_STYLE_JSON: case XO_STYLE_SDPARAMS: case XO_STYLE_ENCODER: /* * Nothing to do; we did all that work just to clear the stack of * formatting arguments. */ break; } } xo_buf_cleanup(&xb); } static void xo_format_units (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { const char *fmt = xfip->xfi_format; ssize_t flen = xfip->xfi_flen; xo_xff_flags_t flags = xfip->xfi_flags; static char units_start_xml[] = " units=\""; static char units_start_html[] = " data-units=\""; if (!XOIF_ISSET(xop, XOIF_UNITS_PENDING)) { xo_format_content(xop, "units", NULL, value, vlen, fmt, flen, flags); return; } xo_buffer_t *xbp = &xop->xo_data; ssize_t start = xop->xo_units_offset; ssize_t stop = xbp->xb_curp - xbp->xb_bufp; if (xo_style(xop) == XO_STYLE_XML) xo_buf_append(xbp, units_start_xml, sizeof(units_start_xml) - 1); else if (xo_style(xop) == XO_STYLE_HTML) xo_buf_append(xbp, units_start_html, sizeof(units_start_html) - 1); else return; if (vlen) xo_data_escape(xop, value, vlen); else xo_do_format_field(xop, NULL, fmt, flen, flags); xo_buf_append(xbp, "\"", 1); ssize_t now = xbp->xb_curp - xbp->xb_bufp; ssize_t delta = now - stop; if (delta <= 0) { /* Strange; no output to move */ xbp->xb_curp = xbp->xb_bufp + stop; /* Reset buffer to prior state */ return; } /* * Now we're in it alright. We've need to insert the unit value * we just created into the right spot. We make a local copy, * move it and then insert our copy. We know there's room in the * buffer, since we're just moving this around. */ char *buf = alloca(delta); memcpy(buf, xbp->xb_bufp + stop, delta); memmove(xbp->xb_bufp + start + delta, xbp->xb_bufp + start, stop - start); memmove(xbp->xb_bufp + start, buf, delta); } static ssize_t xo_find_width (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { const char *fmt = xfip->xfi_format; ssize_t flen = xfip->xfi_flen; long width = 0; char *bp; char *cp; if (vlen) { bp = alloca(vlen + 1); /* Make local NUL-terminated copy of value */ memcpy(bp, value, vlen); bp[vlen] = '\0'; width = strtol(bp, &cp, 0); if (width == LONG_MIN || width == LONG_MAX || bp == cp || *cp != '\0') { width = 0; xo_failure(xop, "invalid width for anchor: '%s'", bp); } } else if (flen) { /* * We really expect the format for width to be "{:/%d}" or * "{:/%u}", so if that's the case, we just grab our width off * the argument list. But we need to avoid optimized logic if * there's a custom formatter. */ if (xop->xo_formatter == NULL && flen == 2 && strncmp("%d", fmt, flen) == 0) { if (!XOF_ISSET(xop, XOF_NO_VA_ARG)) width = va_arg(xop->xo_vap, int); } else if (xop->xo_formatter == NULL && flen == 2 && strncmp("%u", fmt, flen) == 0) { if (!XOF_ISSET(xop, XOF_NO_VA_ARG)) width = va_arg(xop->xo_vap, unsigned); } else { /* * So we have a format and it's not a simple one like * "{:/%d}". That means we need to format the field, * extract the value from the formatted output, and then * discard that output. */ int anchor_was_set = FALSE; xo_buffer_t *xbp = &xop->xo_data; ssize_t start_offset = xo_buf_offset(xbp); bp = xo_buf_cur(xbp); /* Save start of the string */ cp = NULL; if (XOIF_ISSET(xop, XOIF_ANCHOR)) { XOIF_CLEAR(xop, XOIF_ANCHOR); anchor_was_set = TRUE; } ssize_t rc = xo_do_format_field(xop, xbp, fmt, flen, 0); if (rc >= 0) { xo_buf_append(xbp, "", 1); /* Append a NUL */ width = strtol(bp, &cp, 0); if (width == LONG_MIN || width == LONG_MAX || bp == cp || *cp != '\0') { width = 0; xo_failure(xop, "invalid width for anchor: '%s'", bp); } } /* Reset the cur pointer to where we found it */ xbp->xb_curp = xbp->xb_bufp + start_offset; if (anchor_was_set) XOIF_SET(xop, XOIF_ANCHOR); } } return width; } static void xo_anchor_clear (xo_handle_t *xop) { XOIF_CLEAR(xop, XOIF_ANCHOR); xop->xo_anchor_offset = 0; xop->xo_anchor_columns = 0; xop->xo_anchor_min_width = 0; } /* * An anchor is a marker used to delay field width implications. * Imagine the format string "{[:10}{min:%d}/{cur:%d}/{max:%d}{:]}". * We are looking for output like " 1/4/5" * * To make this work, we record the anchor and then return to * format it when the end anchor tag is seen. */ static void xo_anchor_start (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { if (XOIF_ISSET(xop, XOIF_ANCHOR)) xo_failure(xop, "the anchor already recording is discarded"); XOIF_SET(xop, XOIF_ANCHOR); xo_buffer_t *xbp = &xop->xo_data; xop->xo_anchor_offset = xbp->xb_curp - xbp->xb_bufp; xop->xo_anchor_columns = 0; /* * Now we find the width, if possible. If it's not there, * we'll get it on the end anchor. */ xop->xo_anchor_min_width = xo_find_width(xop, xfip, value, vlen); } static void xo_anchor_stop (xo_handle_t *xop, xo_field_info_t *xfip, const char *value, ssize_t vlen) { if (!XOIF_ISSET(xop, XOIF_ANCHOR)) { xo_failure(xop, "no start anchor"); return; } XOIF_CLEAR(xop, XOIF_UNITS_PENDING); ssize_t width = xo_find_width(xop, xfip, value, vlen); if (width == 0) width = xop->xo_anchor_min_width; if (width == 0) /* No width given; nothing to do */ goto done; xo_buffer_t *xbp = &xop->xo_data; ssize_t start = xop->xo_anchor_offset; ssize_t stop = xbp->xb_curp - xbp->xb_bufp; ssize_t abswidth = (width > 0) ? width : -width; ssize_t blen = abswidth - xop->xo_anchor_columns; if (blen <= 0) /* Already over width */ goto done; if (abswidth > XO_MAX_ANCHOR_WIDTH) { xo_failure(xop, "width over %u are not supported", XO_MAX_ANCHOR_WIDTH); goto done; } /* Make a suitable padding field and emit it */ char *buf = alloca(blen); memset(buf, ' ', blen); xo_format_content(xop, "padding", NULL, buf, blen, NULL, 0, 0); if (width < 0) /* Already left justified */ goto done; ssize_t now = xbp->xb_curp - xbp->xb_bufp; ssize_t delta = now - stop; if (delta <= 0) /* Strange; no output to move */ goto done; /* * Now we're in it alright. We've need to insert the padding data * we just created (which might be an HTML
or text) before * the formatted data. We make a local copy, move it and then * insert our copy. We know there's room in the buffer, since * we're just moving this around. */ if (delta > blen) buf = alloca(delta); /* Expand buffer if needed */ memcpy(buf, xbp->xb_bufp + stop, delta); memmove(xbp->xb_bufp + start + delta, xbp->xb_bufp + start, stop - start); memmove(xbp->xb_bufp + start, buf, delta); done: xo_anchor_clear(xop); } static const char * xo_class_name (int ftype) { switch (ftype) { case 'D': return "decoration"; case 'E': return "error"; case 'L': return "label"; case 'N': return "note"; case 'P': return "padding"; case 'W': return "warning"; } return NULL; } static const char * xo_tag_name (int ftype) { switch (ftype) { case 'E': return "__error"; case 'W': return "__warning"; } return NULL; } static int xo_role_wants_default_format (int ftype) { switch (ftype) { /* These roles can be completely empty and/or without formatting */ case 'C': case 'G': case '[': case ']': return 0; } return 1; } static xo_mapping_t xo_role_names[] = { { 'C', "color" }, { 'D', "decoration" }, { 'E', "error" }, { 'L', "label" }, { 'N', "note" }, { 'P', "padding" }, { 'T', "title" }, { 'U', "units" }, { 'V', "value" }, { 'W', "warning" }, { '[', "start-anchor" }, { ']', "stop-anchor" }, { 0, NULL } }; #define XO_ROLE_EBRACE '{' /* Escaped braces */ #define XO_ROLE_TEXT '+' #define XO_ROLE_NEWLINE '\n' static xo_mapping_t xo_modifier_names[] = { { XFF_ARGUMENT, "argument" }, { XFF_COLON, "colon" }, { XFF_COMMA, "comma" }, { XFF_DISPLAY_ONLY, "display" }, { XFF_ENCODE_ONLY, "encoding" }, { XFF_GT_FIELD, "gettext" }, { XFF_HUMANIZE, "humanize" }, { XFF_HUMANIZE, "hn" }, { XFF_HN_SPACE, "hn-space" }, { XFF_HN_DECIMAL, "hn-decimal" }, { XFF_HN_1000, "hn-1000" }, { XFF_KEY, "key" }, { XFF_LEAF_LIST, "leaf-list" }, { XFF_LEAF_LIST, "list" }, { XFF_NOQUOTE, "no-quotes" }, { XFF_NOQUOTE, "no-quote" }, { XFF_GT_PLURAL, "plural" }, { XFF_QUOTE, "quotes" }, { XFF_QUOTE, "quote" }, { XFF_TRIM_WS, "trim" }, { XFF_WS, "white" }, { 0, NULL } }; #ifdef NOT_NEEDED_YET static xo_mapping_t xo_modifier_short_names[] = { { XFF_COLON, "c" }, { XFF_DISPLAY_ONLY, "d" }, { XFF_ENCODE_ONLY, "e" }, { XFF_GT_FIELD, "g" }, { XFF_HUMANIZE, "h" }, { XFF_KEY, "k" }, { XFF_LEAF_LIST, "l" }, { XFF_NOQUOTE, "n" }, { XFF_GT_PLURAL, "p" }, { XFF_QUOTE, "q" }, { XFF_TRIM_WS, "t" }, { XFF_WS, "w" }, { 0, NULL } }; #endif /* NOT_NEEDED_YET */ static int xo_count_fields (xo_handle_t *xop UNUSED, const char *fmt) { int rc = 1; const char *cp; for (cp = fmt; *cp; cp++) if (*cp == '{' || *cp == '\n') rc += 1; return rc * 2 + 1; } /* * The field format is: * '{' modifiers ':' content [ '/' print-fmt [ '/' encode-fmt ]] '}' * Roles are optional and include the following field types: * 'D': decoration; something non-text and non-data (colons, commmas) * 'E': error message * 'G': gettext() the entire string; optional domainname as content * 'L': label; text preceding data * 'N': note; text following data * 'P': padding; whitespace * 'T': Title, where 'content' is a column title * 'U': Units, where 'content' is the unit label * 'V': value, where 'content' is the name of the field (the default) * 'W': warning message * '[': start a section of anchored text * ']': end a section of anchored text * The following modifiers are also supported: * 'a': content is provided via argument (const char *), not descriptor * 'c': flag: emit a colon after the label * 'd': field is only emitted for display styles (text and html) * 'e': field is only emitted for encoding styles (xml and json) * 'g': gettext() the field * 'h': humanize a numeric value (only for display styles) * 'k': this field is a key, suitable for XPath predicates * 'l': a leaf-list, a simple list of values * 'n': no quotes around this field * 'p': the field has plural gettext semantics (ngettext) * 'q': add quotes around this field * 't': trim whitespace around the value * 'w': emit a blank after the label * The print-fmt and encode-fmt strings is the printf-style formating * for this data. JSON and XML will use the encoding-fmt, if present. * If the encode-fmt is not provided, it defaults to the print-fmt. * If the print-fmt is not provided, it defaults to 's'. */ static const char * xo_parse_roles (xo_handle_t *xop, const char *fmt, const char *basep, xo_field_info_t *xfip) { const char *sp; unsigned ftype = 0; xo_xff_flags_t flags = 0; uint8_t fnum = 0; for (sp = basep; sp && *sp; sp++) { if (*sp == ':' || *sp == '/' || *sp == '}') break; if (*sp == '\\') { if (sp[1] == '\0') { xo_failure(xop, "backslash at the end of string"); return NULL; } /* Anything backslashed is ignored */ sp += 1; continue; } if (*sp == ',') { const char *np; for (np = ++sp; *np; np++) if (*np == ':' || *np == '/' || *np == '}' || *np == ',') break; ssize_t slen = np - sp; if (slen > 0) { xo_xff_flags_t value; value = xo_name_lookup(xo_role_names, sp, slen); if (value) ftype = value; else { value = xo_name_lookup(xo_modifier_names, sp, slen); if (value) flags |= value; else xo_failure(xop, "unknown keyword ignored: '%.*s'", slen, sp); } } sp = np - 1; continue; } switch (*sp) { case 'C': case 'D': case 'E': case 'G': case 'L': case 'N': case 'P': case 'T': case 'U': case 'V': case 'W': case '[': case ']': if (ftype != 0) { xo_failure(xop, "field descriptor uses multiple types: '%s'", xo_printable(fmt)); return NULL; } ftype = *sp; break; case '0': case '1': case '2': case '3': case '4': case '5': case '6': case '7': case '8': case '9': fnum = (fnum * 10) + (*sp - '0'); break; case 'a': flags |= XFF_ARGUMENT; break; case 'c': flags |= XFF_COLON; break; case 'd': flags |= XFF_DISPLAY_ONLY; break; case 'e': flags |= XFF_ENCODE_ONLY; break; case 'g': flags |= XFF_GT_FIELD; break; case 'h': flags |= XFF_HUMANIZE; break; case 'k': flags |= XFF_KEY; break; case 'l': flags |= XFF_LEAF_LIST; break; case 'n': flags |= XFF_NOQUOTE; break; case 'p': flags |= XFF_GT_PLURAL; break; case 'q': flags |= XFF_QUOTE; break; case 't': flags |= XFF_TRIM_WS; break; case 'w': flags |= XFF_WS; break; default: xo_failure(xop, "field descriptor uses unknown modifier: '%s'", xo_printable(fmt)); /* * No good answer here; a bad format will likely * mean a core file. We just return and hope * the caller notices there's no output, and while * that seems, well, bad, there's nothing better. */ return NULL; } if (ftype == 'N' || ftype == 'U') { if (flags & XFF_COLON) { xo_failure(xop, "colon modifier on 'N' or 'U' field ignored: " "'%s'", xo_printable(fmt)); flags &= ~XFF_COLON; } } } xfip->xfi_flags = flags; xfip->xfi_ftype = ftype ?: 'V'; xfip->xfi_fnum = fnum; return sp; } /* * Number any remaining fields that need numbers. Note that some * field types (text, newline, escaped braces) never get numbers. */ static void xo_gettext_finish_numbering_fields (xo_handle_t *xop UNUSED, const char *fmt UNUSED, xo_field_info_t *fields) { xo_field_info_t *xfip; unsigned fnum, max_fields; uint64_t bits = 0; const uint64_t one = 1; /* Avoid "1ULL" */ /* First make a list of add the explicitly used bits */ for (xfip = fields, fnum = 0; xfip->xfi_ftype; xfip++) { switch (xfip->xfi_ftype) { case XO_ROLE_NEWLINE: /* Don't get numbered */ case XO_ROLE_TEXT: case XO_ROLE_EBRACE: case 'G': continue; } fnum += 1; if (fnum >= 63) break; if (xfip->xfi_fnum) bits |= one << xfip->xfi_fnum; } max_fields = fnum; for (xfip = fields, fnum = 0; xfip->xfi_ftype; xfip++) { switch (xfip->xfi_ftype) { case XO_ROLE_NEWLINE: /* Don't get numbered */ case XO_ROLE_TEXT: case XO_ROLE_EBRACE: case 'G': continue; } if (xfip->xfi_fnum != 0) continue; /* Find the next unassigned field */ for (fnum++; bits & (one << fnum); fnum++) continue; if (fnum > max_fields) break; xfip->xfi_fnum = fnum; /* Mark the field number */ bits |= one << fnum; /* Mark it used */ } } /* * The format string uses field numbers, so we need to whiffle through it * and make sure everything's sane and lovely. */ static int xo_parse_field_numbers (xo_handle_t *xop, const char *fmt, xo_field_info_t *fields, unsigned num_fields) { xo_field_info_t *xfip; unsigned field, fnum; uint64_t bits = 0; const uint64_t one = 1; /* Avoid 1ULL */ for (xfip = fields, field = 0; field < num_fields; xfip++, field++) { /* Fields default to 1:1 with natural position */ if (xfip->xfi_fnum == 0) xfip->xfi_fnum = field + 1; else if (xfip->xfi_fnum > num_fields) { xo_failure(xop, "field number exceeds number of fields: '%s'", fmt); return -1; } fnum = xfip->xfi_fnum - 1; /* Move to zero origin */ if (fnum < 64) { /* Only test what fits */ if (bits & (one << fnum)) { xo_failure(xop, "field number %u reused: '%s'", xfip->xfi_fnum, fmt); return -1; } bits |= one << fnum; } } return 0; } static int xo_parse_fields (xo_handle_t *xop, xo_field_info_t *fields, unsigned num_fields, const char *fmt) { const char *cp, *sp, *ep, *basep; unsigned field = 0; xo_field_info_t *xfip = fields; unsigned seen_fnum = 0; for (cp = fmt; *cp && field < num_fields; field++, xfip++) { xfip->xfi_start = cp; if (*cp == '\n') { xfip->xfi_ftype = XO_ROLE_NEWLINE; xfip->xfi_len = 1; cp += 1; continue; } if (*cp != '{') { /* Normal text */ for (sp = cp; *sp; sp++) { if (*sp == '{' || *sp == '\n') break; } xfip->xfi_ftype = XO_ROLE_TEXT; xfip->xfi_content = cp; xfip->xfi_clen = sp - cp; xfip->xfi_next = sp; cp = sp; continue; } if (cp[1] == '{') { /* Start of {{escaped braces}} */ xfip->xfi_start = cp + 1; /* Start at second brace */ xfip->xfi_ftype = XO_ROLE_EBRACE; cp += 2; /* Skip over _both_ characters */ for (sp = cp; *sp; sp++) { if (*sp == '}' && sp[1] == '}') break; } if (*sp == '\0') { xo_failure(xop, "missing closing '}}': '%s'", xo_printable(fmt)); return -1; } xfip->xfi_len = sp - xfip->xfi_start + 1; /* Move along the string, but don't run off the end */ if (*sp == '}' && sp[1] == '}') /* Paranoid; must be true */ sp += 2; cp = sp; xfip->xfi_next = cp; continue; } /* We are looking at the start of a field definition */ xfip->xfi_start = basep = cp + 1; const char *format = NULL; ssize_t flen = 0; /* Looking at roles and modifiers */ sp = xo_parse_roles(xop, fmt, basep, xfip); if (sp == NULL) { /* xo_failure has already been called */ return -1; } if (xfip->xfi_fnum) seen_fnum = 1; /* Looking at content */ if (*sp == ':') { for (ep = ++sp; *sp; sp++) { if (*sp == '}' || *sp == '/') break; if (*sp == '\\') { if (sp[1] == '\0') { xo_failure(xop, "backslash at the end of string"); return -1; } sp += 1; continue; } } if (ep != sp) { xfip->xfi_clen = sp - ep; xfip->xfi_content = ep; } } else { xo_failure(xop, "missing content (':'): '%s'", xo_printable(fmt)); return -1; } /* Looking at main (display) format */ if (*sp == '/') { for (ep = ++sp; *sp; sp++) { if (*sp == '}' || *sp == '/') break; if (*sp == '\\') { if (sp[1] == '\0') { xo_failure(xop, "backslash at the end of string"); return -1; } sp += 1; continue; } } flen = sp - ep; format = ep; } /* Looking at encoding format */ if (*sp == '/') { for (ep = ++sp; *sp; sp++) { if (*sp == '}') break; } xfip->xfi_encoding = ep; xfip->xfi_elen = sp - ep; } if (*sp != '}') { xo_failure(xop, "missing closing '}': %s", xo_printable(fmt)); return -1; } xfip->xfi_len = sp - xfip->xfi_start; xfip->xfi_next = ++sp; /* If we have content, then we have a default format */ if (xfip->xfi_clen || format || (xfip->xfi_flags & XFF_ARGUMENT)) { if (format) { xfip->xfi_format = format; xfip->xfi_flen = flen; } else if (xo_role_wants_default_format(xfip->xfi_ftype)) { xfip->xfi_format = xo_default_format; xfip->xfi_flen = 2; } } cp = sp; } int rc = 0; /* * If we saw a field number on at least one field, then we need * to enforce some rules and/or guidelines. */ if (seen_fnum) rc = xo_parse_field_numbers(xop, fmt, fields, field); return rc; } /* * We are passed a pointer to a format string just past the "{G:}" * field. We build a simplified version of the format string. */ static int xo_gettext_simplify_format (xo_handle_t *xop UNUSED, xo_buffer_t *xbp, xo_field_info_t *fields, int this_field, const char *fmt UNUSED, xo_simplify_field_func_t field_cb) { unsigned ftype; xo_xff_flags_t flags; int field = this_field + 1; xo_field_info_t *xfip; char ch; for (xfip = &fields[field]; xfip->xfi_ftype; xfip++, field++) { ftype = xfip->xfi_ftype; flags = xfip->xfi_flags; if ((flags & XFF_GT_FIELD) && xfip->xfi_content && ftype != 'V') { if (field_cb) field_cb(xfip->xfi_content, xfip->xfi_clen, (flags & XFF_GT_PLURAL) ? 1 : 0); } switch (ftype) { case 'G': /* Ignore gettext roles */ break; case XO_ROLE_NEWLINE: xo_buf_append(xbp, "\n", 1); break; case XO_ROLE_EBRACE: xo_buf_append(xbp, "{", 1); xo_buf_append(xbp, xfip->xfi_content, xfip->xfi_clen); xo_buf_append(xbp, "}", 1); break; case XO_ROLE_TEXT: xo_buf_append(xbp, xfip->xfi_content, xfip->xfi_clen); break; default: xo_buf_append(xbp, "{", 1); if (ftype != 'V') { ch = ftype; xo_buf_append(xbp, &ch, 1); } unsigned fnum = xfip->xfi_fnum ?: 0; if (fnum) { char num[12]; /* Field numbers are origin 1, not 0, following printf(3) */ snprintf(num, sizeof(num), "%u", fnum); xo_buf_append(xbp, num, strlen(num)); } xo_buf_append(xbp, ":", 1); xo_buf_append(xbp, xfip->xfi_content, xfip->xfi_clen); xo_buf_append(xbp, "}", 1); } } xo_buf_append(xbp, "", 1); return 0; } void xo_dump_fields (xo_field_info_t *); /* Fake prototype for debug function */ void xo_dump_fields (xo_field_info_t *fields) { xo_field_info_t *xfip; for (xfip = fields; xfip->xfi_ftype; xfip++) { printf("%lu(%u): %lx [%c/%u] [%.*s] [%.*s] [%.*s]\n", (unsigned long) (xfip - fields), xfip->xfi_fnum, (unsigned long) xfip->xfi_flags, isprint((int) xfip->xfi_ftype) ? xfip->xfi_ftype : ' ', xfip->xfi_ftype, (int) xfip->xfi_clen, xfip->xfi_content ?: "", (int) xfip->xfi_flen, xfip->xfi_format ?: "", (int) xfip->xfi_elen, xfip->xfi_encoding ?: ""); } } #ifdef HAVE_GETTEXT /* * Find the field that matches the given field number */ static xo_field_info_t * xo_gettext_find_field (xo_field_info_t *fields, unsigned fnum) { xo_field_info_t *xfip; for (xfip = fields; xfip->xfi_ftype; xfip++) if (xfip->xfi_fnum == fnum) return xfip; return NULL; } /* * At this point, we need to consider if the fields have been reordered, * such as "The {:adjective} {:noun}" to "La {:noun} {:adjective}". * * We need to rewrite the new_fields using the old fields order, * so that we can render the message using the arguments as they * appear on the stack. It's a lot of work, but we don't really * want to (eventually) fall into the standard printf code which * means using the arguments straight (and in order) from the * varargs we were originally passed. */ static void xo_gettext_rewrite_fields (xo_handle_t *xop UNUSED, xo_field_info_t *fields, unsigned max_fields) { xo_field_info_t tmp[max_fields]; bzero(tmp, max_fields * sizeof(tmp[0])); unsigned fnum = 0; xo_field_info_t *newp, *outp, *zp; for (newp = fields, outp = tmp; newp->xfi_ftype; newp++, outp++) { switch (newp->xfi_ftype) { case XO_ROLE_NEWLINE: /* Don't get numbered */ case XO_ROLE_TEXT: case XO_ROLE_EBRACE: case 'G': *outp = *newp; outp->xfi_renum = 0; continue; } zp = xo_gettext_find_field(fields, ++fnum); if (zp == NULL) { /* Should not occur */ *outp = *newp; outp->xfi_renum = 0; continue; } *outp = *zp; outp->xfi_renum = newp->xfi_fnum; } memcpy(fields, tmp, max_fields * sizeof(tmp[0])); } /* * We've got two lists of fields, the old list from the original * format string and the new one from the parsed gettext reply. The * new list has the localized words, where the old list has the * formatting information. We need to combine them into a single list * (the new list). * * If the list needs to be reordered, then we've got more serious work * to do. */ static int xo_gettext_combine_formats (xo_handle_t *xop, const char *fmt UNUSED, const char *gtfmt, xo_field_info_t *old_fields, xo_field_info_t *new_fields, unsigned new_max_fields, int *reorderedp) { int reordered = 0; xo_field_info_t *newp, *oldp, *startp = old_fields; xo_gettext_finish_numbering_fields(xop, fmt, old_fields); for (newp = new_fields; newp->xfi_ftype; newp++) { switch (newp->xfi_ftype) { case XO_ROLE_NEWLINE: case XO_ROLE_TEXT: case XO_ROLE_EBRACE: continue; case 'V': for (oldp = startp; oldp->xfi_ftype; oldp++) { if (oldp->xfi_ftype != 'V') continue; if (newp->xfi_clen != oldp->xfi_clen || strncmp(newp->xfi_content, oldp->xfi_content, oldp->xfi_clen) != 0) { reordered = 1; continue; } startp = oldp + 1; break; } /* Didn't find it on the first pass (starting from start) */ if (oldp->xfi_ftype == 0) { for (oldp = old_fields; oldp < startp; oldp++) { if (oldp->xfi_ftype != 'V') continue; if (newp->xfi_clen != oldp->xfi_clen) continue; if (strncmp(newp->xfi_content, oldp->xfi_content, oldp->xfi_clen) != 0) continue; reordered = 1; break; } if (oldp == startp) { /* Field not found */ xo_failure(xop, "post-gettext format can't find field " "'%.*s' in format '%s'", newp->xfi_clen, newp->xfi_content, xo_printable(gtfmt)); return -1; } } break; default: /* * Other fields don't have names for us to use, so if * the types aren't the same, then we'll have to assume * the original field is a match. */ for (oldp = startp; oldp->xfi_ftype; oldp++) { if (oldp->xfi_ftype == 'V') /* Can't go past these */ break; if (oldp->xfi_ftype == newp->xfi_ftype) goto copy_it; /* Assumably we have a match */ } continue; } /* * Found a match; copy over appropriate fields */ copy_it: newp->xfi_flags = oldp->xfi_flags; newp->xfi_fnum = oldp->xfi_fnum; newp->xfi_format = oldp->xfi_format; newp->xfi_flen = oldp->xfi_flen; newp->xfi_encoding = oldp->xfi_encoding; newp->xfi_elen = oldp->xfi_elen; } *reorderedp = reordered; if (reordered) { xo_gettext_finish_numbering_fields(xop, fmt, new_fields); xo_gettext_rewrite_fields(xop, new_fields, new_max_fields); } return 0; } /* * We don't want to make gettext() calls here with a complete format * string, since that means changing a flag would mean a * labor-intensive re-translation expense. Instead we build a * simplified form with a reduced level of detail, perform a lookup on * that string and then re-insert the formating info. * * So something like: * xo_emit("{G:}close {:fd/%ld} returned {g:error/%m} {:test/%6.6s}\n", ...) * would have a lookup string of: * "close {:fd} returned {:error} {:test}\n" * * We also need to handling reordering of fields, where the gettext() * reply string uses fields in a different order than the original * format string: * "cluse-a {:fd} retoorned {:test}. Bork {:error} Bork. Bork.\n" * If we have to reorder fields within the message, then things get * complicated. See xo_gettext_rewrite_fields. * * Summary: i18n aighn't cheap. */ static const char * xo_gettext_build_format (xo_handle_t *xop, xo_field_info_t *fields, int this_field, const char *fmt, char **new_fmtp) { if (xo_style_is_encoding(xop)) goto bail; xo_buffer_t xb; xo_buf_init(&xb); if (xo_gettext_simplify_format(xop, &xb, fields, this_field, fmt, NULL)) goto bail2; const char *gtfmt = xo_dgettext(xop, xb.xb_bufp); if (gtfmt == NULL || gtfmt == fmt || xo_streq(gtfmt, fmt)) goto bail2; char *new_fmt = xo_strndup(gtfmt, -1); if (new_fmt == NULL) goto bail2; xo_buf_cleanup(&xb); *new_fmtp = new_fmt; return new_fmt; bail2: xo_buf_cleanup(&xb); bail: *new_fmtp = NULL; return fmt; } static void xo_gettext_rebuild_content (xo_handle_t *xop, xo_field_info_t *fields, ssize_t *fstart, unsigned min_fstart, ssize_t *fend, unsigned max_fend) { xo_field_info_t *xfip; char *buf; ssize_t base = fstart[min_fstart]; ssize_t blen = fend[max_fend] - base; xo_buffer_t *xbp = &xop->xo_data; if (blen == 0) return; buf = xo_realloc(NULL, blen); if (buf == NULL) return; memcpy(buf, xbp->xb_bufp + fstart[min_fstart], blen); /* Copy our data */ unsigned field = min_fstart, len, fnum; ssize_t soff, doff = base; xo_field_info_t *zp; /* * Be aware there are two competing views of "field number": we * want the user to thing in terms of "The {1:size}" where {G:}, * newlines, escaped braces, and text don't have numbers. But is * also the internal view, where we have an array of * xo_field_info_t and every field have an index. fnum, fstart[] * and fend[] are the latter, but xfi_renum is the former. */ for (xfip = fields + field; xfip->xfi_ftype; xfip++, field++) { fnum = field; if (xfip->xfi_renum) { zp = xo_gettext_find_field(fields, xfip->xfi_renum); fnum = zp ? zp - fields : field; } soff = fstart[fnum]; len = fend[fnum] - soff; if (len > 0) { soff -= base; memcpy(xbp->xb_bufp + doff, buf + soff, len); doff += len; } } xo_free(buf); } #else /* HAVE_GETTEXT */ static const char * xo_gettext_build_format (xo_handle_t *xop UNUSED, xo_field_info_t *fields UNUSED, int this_field UNUSED, const char *fmt UNUSED, char **new_fmtp) { *new_fmtp = NULL; return fmt; } static int xo_gettext_combine_formats (xo_handle_t *xop UNUSED, const char *fmt UNUSED, const char *gtfmt UNUSED, xo_field_info_t *old_fields UNUSED, xo_field_info_t *new_fields UNUSED, unsigned new_max_fields UNUSED, int *reorderedp UNUSED) { return -1; } static void xo_gettext_rebuild_content (xo_handle_t *xop UNUSED, xo_field_info_t *fields UNUSED, ssize_t *fstart UNUSED, unsigned min_fstart UNUSED, ssize_t *fend UNUSED, unsigned max_fend UNUSED) { return; } #endif /* HAVE_GETTEXT */ /* * Emit a set of fields. This is really the core of libxo. */ static ssize_t xo_do_emit_fields (xo_handle_t *xop, xo_field_info_t *fields, unsigned max_fields, const char *fmt) { int gettext_inuse = 0; int gettext_changed = 0; int gettext_reordered = 0; unsigned ftype; xo_xff_flags_t flags; xo_field_info_t *new_fields = NULL; xo_field_info_t *xfip; unsigned field; ssize_t rc = 0; int flush = XOF_ISSET(xop, XOF_FLUSH); int flush_line = XOF_ISSET(xop, XOF_FLUSH_LINE); char *new_fmt = NULL; if (XOIF_ISSET(xop, XOIF_REORDER) || xo_style(xop) == XO_STYLE_ENCODER) flush_line = 0; /* * Some overhead for gettext; if the fields in the msgstr returned * by gettext are reordered, then we need to record start and end * for each field. We'll go ahead and render the fields in the * normal order, but later we can then reconstruct the reordered * fields using these fstart/fend values. */ unsigned flimit = max_fields * 2; /* Pessimistic limit */ unsigned min_fstart = flimit - 1; unsigned max_fend = 0; /* Highest recorded fend[] entry */ ssize_t fstart[flimit]; bzero(fstart, flimit * sizeof(fstart[0])); ssize_t fend[flimit]; bzero(fend, flimit * sizeof(fend[0])); for (xfip = fields, field = 0; field < max_fields && xfip->xfi_ftype; xfip++, field++) { ftype = xfip->xfi_ftype; flags = xfip->xfi_flags; /* Record field start offset */ if (gettext_reordered) { fstart[field] = xo_buf_offset(&xop->xo_data); if (min_fstart > field) min_fstart = field; } const char *content = xfip->xfi_content; ssize_t clen = xfip->xfi_clen; if (flags & XFF_ARGUMENT) { /* * Argument flag means the content isn't given in the descriptor, * but as a UTF-8 string ('const char *') argument in xo_vap. */ content = va_arg(xop->xo_vap, char *); clen = content ? strlen(content) : 0; } if (ftype == XO_ROLE_NEWLINE) { xo_line_close(xop); if (flush_line && xo_flush_h(xop) < 0) return -1; goto bottom; } else if (ftype == XO_ROLE_EBRACE) { xo_format_text(xop, xfip->xfi_start, xfip->xfi_len); goto bottom; } else if (ftype == XO_ROLE_TEXT) { /* Normal text */ xo_format_text(xop, xfip->xfi_content, xfip->xfi_clen); goto bottom; } /* * Notes and units need the 'w' flag handled before the content. */ if (ftype == 'N' || ftype == 'U') { if (flags & XFF_WS) { xo_format_content(xop, "padding", NULL, " ", 1, NULL, 0, flags); flags &= ~XFF_WS; /* Prevent later handling of this flag */ } } if (ftype == 'V') xo_format_value(xop, content, clen, NULL, 0, xfip->xfi_format, xfip->xfi_flen, xfip->xfi_encoding, xfip->xfi_elen, flags); else if (ftype == '[') xo_anchor_start(xop, xfip, content, clen); else if (ftype == ']') xo_anchor_stop(xop, xfip, content, clen); else if (ftype == 'C') xo_format_colors(xop, xfip, content, clen); else if (ftype == 'G') { /* * A {G:domain} field; disect the domain name and translate * the remaining portion of the input string. If the user * didn't put the {G:} at the start of the format string, then * assumably they just want us to translate the rest of it. * Since gettext returns strings in a static buffer, we make * a copy in new_fmt. */ xo_set_gettext_domain(xop, xfip, content, clen); if (!gettext_inuse) { /* Only translate once */ gettext_inuse = 1; if (new_fmt) { xo_free(new_fmt); new_fmt = NULL; } xo_gettext_build_format(xop, fields, field, xfip->xfi_next, &new_fmt); if (new_fmt) { gettext_changed = 1; unsigned new_max_fields = xo_count_fields(xop, new_fmt); if (++new_max_fields < max_fields) new_max_fields = max_fields; /* Leave a blank slot at the beginning */ ssize_t sz = (new_max_fields + 1) * sizeof(xo_field_info_t); new_fields = alloca(sz); bzero(new_fields, sz); if (!xo_parse_fields(xop, new_fields + 1, new_max_fields, new_fmt)) { gettext_reordered = 0; if (!xo_gettext_combine_formats(xop, fmt, new_fmt, fields, new_fields + 1, new_max_fields, &gettext_reordered)) { if (gettext_reordered) { if (XOF_ISSET(xop, XOF_LOG_GETTEXT)) xo_failure(xop, "gettext finds reordered " "fields in '%s' and '%s'", xo_printable(fmt), xo_printable(new_fmt)); flush_line = 0; /* Must keep at content */ XOIF_SET(xop, XOIF_REORDER); } field = -1; /* Will be incremented at top of loop */ xfip = new_fields; max_fields = new_max_fields; } } } } continue; } else if (clen || xfip->xfi_format) { const char *class_name = xo_class_name(ftype); if (class_name) xo_format_content(xop, class_name, xo_tag_name(ftype), content, clen, xfip->xfi_format, xfip->xfi_flen, flags); else if (ftype == 'T') xo_format_title(xop, xfip, content, clen); else if (ftype == 'U') xo_format_units(xop, xfip, content, clen); else xo_failure(xop, "unknown field type: '%c'", ftype); } if (flags & XFF_COLON) xo_format_content(xop, "decoration", NULL, ":", 1, NULL, 0, 0); if (flags & XFF_WS) xo_format_content(xop, "padding", NULL, " ", 1, NULL, 0, 0); bottom: /* Record the end-of-field offset */ if (gettext_reordered) { fend[field] = xo_buf_offset(&xop->xo_data); max_fend = field; } } if (gettext_changed && gettext_reordered) { /* Final step: rebuild the content using the rendered fields */ xo_gettext_rebuild_content(xop, new_fields + 1, fstart, min_fstart, fend, max_fend); } XOIF_CLEAR(xop, XOIF_REORDER); /* * If we've got enough data, flush it. */ if (xo_buf_offset(&xop->xo_data) > XO_BUF_HIGH_WATER) flush = 1; /* If we don't have an anchor, write the text out */ if (flush && !XOIF_ISSET(xop, XOIF_ANCHOR)) { if (xo_flush_h(xop) < 0) rc = -1; } if (new_fmt) xo_free(new_fmt); /* * We've carried the gettext domainname inside our handle just for * convenience, but we need to ensure it doesn't survive across * xo_emit calls. */ if (xop->xo_gt_domain) { xo_free(xop->xo_gt_domain); xop->xo_gt_domain = NULL; } return (rc < 0) ? rc : xop->xo_columns; } /* * Parse and emit a set of fields */ static int xo_do_emit (xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt) { xop->xo_columns = 0; /* Always reset it */ xop->xo_errno = errno; /* Save for "%m" */ if (fmt == NULL) return 0; unsigned max_fields; xo_field_info_t *fields = NULL; /* Adjust XOEF_RETAIN based on global flags */ if (XOF_ISSET(xop, XOF_RETAIN_ALL)) flags |= XOEF_RETAIN; if (XOF_ISSET(xop, XOF_RETAIN_NONE)) flags &= ~XOEF_RETAIN; /* * Check for 'retain' flag, telling us to retain the field * information. If we've already saved it, then we can avoid * re-parsing the format string. */ if (!(flags & XOEF_RETAIN) || xo_retain_find(fmt, &fields, &max_fields) != 0 || fields == NULL) { /* Nothing retained; parse the format string */ max_fields = xo_count_fields(xop, fmt); fields = alloca(max_fields * sizeof(fields[0])); bzero(fields, max_fields * sizeof(fields[0])); if (xo_parse_fields(xop, fields, max_fields, fmt)) return -1; /* Warning already displayed */ if (flags & XOEF_RETAIN) { /* Retain the info */ xo_retain_add(fmt, fields, max_fields); } } return xo_do_emit_fields(xop, fields, max_fields, fmt); } /* * Rebuild a format string in a gettext-friendly format. This function * is exposed to tools can perform this function. See xo(1). */ char * xo_simplify_format (xo_handle_t *xop, const char *fmt, int with_numbers, xo_simplify_field_func_t field_cb) { xop = xo_default(xop); xop->xo_columns = 0; /* Always reset it */ xop->xo_errno = errno; /* Save for "%m" */ unsigned max_fields = xo_count_fields(xop, fmt); xo_field_info_t fields[max_fields]; bzero(fields, max_fields * sizeof(fields[0])); if (xo_parse_fields(xop, fields, max_fields, fmt)) return NULL; /* Warning already displayed */ xo_buffer_t xb; xo_buf_init(&xb); if (with_numbers) xo_gettext_finish_numbering_fields(xop, fmt, fields); if (xo_gettext_simplify_format(xop, &xb, fields, -1, fmt, field_cb)) return NULL; return xb.xb_bufp; } xo_ssize_t xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap) { ssize_t rc; xop = xo_default(xop); va_copy(xop->xo_vap, vap); rc = xo_do_emit(xop, 0, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } xo_ssize_t xo_emit_h (xo_handle_t *xop, const char *fmt, ...) { ssize_t rc; xop = xo_default(xop); va_start(xop->xo_vap, fmt); rc = xo_do_emit(xop, 0, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } xo_ssize_t xo_emit (const char *fmt, ...) { xo_handle_t *xop = xo_default(NULL); ssize_t rc; va_start(xop->xo_vap, fmt); rc = xo_do_emit(xop, 0, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } xo_ssize_t xo_emit_hvf (xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt, va_list vap) { ssize_t rc; xop = xo_default(xop); va_copy(xop->xo_vap, vap); rc = xo_do_emit(xop, flags, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } xo_ssize_t xo_emit_hf (xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt, ...) { ssize_t rc; xop = xo_default(xop); va_start(xop->xo_vap, fmt); rc = xo_do_emit(xop, flags, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } xo_ssize_t xo_emit_f (xo_emit_flags_t flags, const char *fmt, ...) { xo_handle_t *xop = xo_default(NULL); ssize_t rc; va_start(xop->xo_vap, fmt); rc = xo_do_emit(xop, flags, fmt); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); return rc; } /* * Emit a single field by providing the info information typically provided * inside the field description (role, modifiers, and formats). This is * a convenience function to avoid callers using snprintf to build field * descriptions. */ 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) { ssize_t rc; xop = xo_default(xop); if (rolmod == NULL) rolmod = "V"; xo_field_info_t xfi; bzero(&xfi, sizeof(xfi)); const char *cp; cp = xo_parse_roles(xop, rolmod, rolmod, &xfi); if (cp == NULL) return -1; xfi.xfi_start = fmt; xfi.xfi_content = contents; xfi.xfi_format = fmt; xfi.xfi_encoding = efmt; xfi.xfi_clen = contents ? strlen(contents) : 0; xfi.xfi_flen = fmt ? strlen(fmt) : 0; xfi.xfi_elen = efmt ? strlen(efmt) : 0; /* If we have content, then we have a default format */ if (contents && fmt == NULL && xo_role_wants_default_format(xfi.xfi_ftype)) { xfi.xfi_format = xo_default_format; xfi.xfi_flen = 2; } va_copy(xop->xo_vap, vap); rc = xo_do_emit_fields(xop, &xfi, 1, fmt ?: contents ?: "field"); va_end(xop->xo_vap); return rc; } xo_ssize_t xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) { ssize_t rc; va_list vap; va_start(vap, efmt); rc = xo_emit_field_hv(xop, rolmod, contents, fmt, efmt, vap); va_end(vap); return rc; } xo_ssize_t xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) { ssize_t rc; va_list vap; va_start(vap, efmt); rc = xo_emit_field_hv(NULL, rolmod, contents, fmt, efmt, vap); va_end(vap); return rc; } xo_ssize_t xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap) { const ssize_t extra = 5; /* space, equals, quote, quote, and nul */ xop = xo_default(xop); ssize_t rc = 0; ssize_t nlen = strlen(name); xo_buffer_t *xbp = &xop->xo_attrs; ssize_t name_offset, value_offset; switch (xo_style(xop)) { case XO_STYLE_XML: if (!xo_buf_has_room(xbp, nlen + extra)) return -1; *xbp->xb_curp++ = ' '; memcpy(xbp->xb_curp, name, nlen); xbp->xb_curp += nlen; *xbp->xb_curp++ = '='; *xbp->xb_curp++ = '"'; rc = xo_vsnprintf(xop, xbp, fmt, vap); if (rc >= 0) { rc = xo_escape_xml(xbp, rc, 1); xbp->xb_curp += rc; } if (!xo_buf_has_room(xbp, 2)) return -1; *xbp->xb_curp++ = '"'; *xbp->xb_curp = '\0'; rc += nlen + extra; break; case XO_STYLE_ENCODER: name_offset = xo_buf_offset(xbp); xo_buf_append(xbp, name, nlen); xo_buf_append(xbp, "", 1); value_offset = xo_buf_offset(xbp); rc = xo_vsnprintf(xop, xbp, fmt, vap); if (rc >= 0) { xbp->xb_curp += rc; *xbp->xb_curp = '\0'; rc = xo_encoder_handle(xop, XO_OP_ATTRIBUTE, xo_buf_data(xbp, name_offset), xo_buf_data(xbp, value_offset), 0); } } return rc; } xo_ssize_t xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...) { ssize_t rc; va_list vap; va_start(vap, fmt); rc = xo_attr_hv(xop, name, fmt, vap); va_end(vap); return rc; } xo_ssize_t xo_attr (const char *name, const char *fmt, ...) { ssize_t rc; va_list vap; va_start(vap, fmt); rc = xo_attr_hv(NULL, name, fmt, vap); va_end(vap); return rc; } static void xo_depth_change (xo_handle_t *xop, const char *name, int delta, int indent, xo_state_t state, xo_xsf_flags_t flags) { if (xo_style(xop) == XO_STYLE_HTML || xo_style(xop) == XO_STYLE_TEXT) indent = 0; if (XOF_ISSET(xop, XOF_DTRT)) flags |= XSF_DTRT; if (delta >= 0) { /* Push operation */ if (xo_depth_check(xop, xop->xo_depth + delta)) return; xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth + delta]; xsp->xs_flags = flags; xsp->xs_state = state; xo_stack_set_flags(xop); if (name == NULL) name = XO_FAILURE_NAME; xsp->xs_name = xo_strndup(name, -1); } else { /* Pop operation */ if (xop->xo_depth == 0) { if (!XOF_ISSET(xop, XOF_IGNORE_CLOSE)) xo_failure(xop, "close with empty stack: '%s'", name); return; } xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; if (XOF_ISSET(xop, XOF_WARN)) { const char *top = xsp->xs_name; if (top != NULL && name != NULL && !xo_streq(name, top)) { xo_failure(xop, "incorrect close: '%s' .vs. '%s'", name, top); return; } if ((xsp->xs_flags & XSF_LIST) != (flags & XSF_LIST)) { xo_failure(xop, "list close on list confict: '%s'", name); return; } if ((xsp->xs_flags & XSF_INSTANCE) != (flags & XSF_INSTANCE)) { xo_failure(xop, "list close on instance confict: '%s'", name); return; } } if (xsp->xs_name) { xo_free(xsp->xs_name); xsp->xs_name = NULL; } if (xsp->xs_keys) { xo_free(xsp->xs_keys); xsp->xs_keys = NULL; } } xop->xo_depth += delta; /* Record new depth */ xop->xo_indent += indent; } void xo_set_depth (xo_handle_t *xop, int depth) { xop = xo_default(xop); if (xo_depth_check(xop, depth)) return; xop->xo_depth += depth; xop->xo_indent += depth; /* * Handling the "top wrapper" for JSON is a bit of a pain. Here * we need to detect that the depth has been changed to set the * "XOIF_TOP_EMITTED" flag correctly. */ if (xop->xo_style == XO_STYLE_JSON && !XOF_ISSET(xop, XOF_NO_TOP) && xop->xo_depth > 0) XOIF_SET(xop, XOIF_TOP_EMITTED); } static xo_xsf_flags_t xo_stack_flags (xo_xof_flags_t xflags) { if (xflags & XOF_DTRT) return XSF_DTRT; return 0; } static void xo_emit_top (xo_handle_t *xop, const char *ppn) { xo_printf(xop, "%*s{%s", xo_indent(xop), "", ppn); XOIF_SET(xop, XOIF_TOP_EMITTED); if (xop->xo_version) { xo_printf(xop, "%*s\"__version\": \"%s\", %s", xo_indent(xop), "", xop->xo_version, ppn); xo_free(xop->xo_version); xop->xo_version = NULL; } } static ssize_t xo_do_open_container (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { ssize_t rc = 0; const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; if (name == NULL) { xo_failure(xop, "NULL passed for container name"); name = XO_FAILURE_NAME; } const char *leader = xo_xml_leader(xop, name); flags |= xop->xo_flags; /* Pick up handle flags */ switch (xo_style(xop)) { case XO_STYLE_XML: rc = xo_printf(xop, "%*s<%s%s", xo_indent(xop), "", leader, name); if (xop->xo_attrs.xb_curp != xop->xo_attrs.xb_bufp) { rc += xop->xo_attrs.xb_curp - xop->xo_attrs.xb_bufp; xo_data_append(xop, xop->xo_attrs.xb_bufp, xop->xo_attrs.xb_curp - xop->xo_attrs.xb_bufp); xop->xo_attrs.xb_curp = xop->xo_attrs.xb_bufp; } rc += xo_printf(xop, ">%s", ppn); break; case XO_STYLE_JSON: xo_stack_set_flags(xop); if (!XOF_ISSET(xop, XOF_NO_TOP) && !XOIF_ISSET(xop, XOIF_TOP_EMITTED)) xo_emit_top(xop, ppn); if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? ",\n" : ", "; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; + /* If we need underscores, make a local copy and doctor it */ + const char *new_name = name; + if (XOF_ISSET(xop, XOF_UNDERSCORES)) { + size_t len = strlen(name); + const char *old_name = name; + char *buf, *cp, *ep; + + buf = alloca(len + 1); + for (cp = buf, ep = buf + len + 1; cp < ep; cp++, old_name++) + *cp = (*old_name == '-') ? '_' : *old_name; + new_name = buf; + } + rc = xo_printf(xop, "%s%*s\"%s\": {%s", - pre_nl, xo_indent(xop), "", name, ppn); + pre_nl, xo_indent(xop), "", new_name, ppn); break; case XO_STYLE_SDPARAMS: break; case XO_STYLE_ENCODER: rc = xo_encoder_handle(xop, XO_OP_OPEN_CONTAINER, name, NULL, flags); break; } xo_depth_change(xop, name, 1, 1, XSS_OPEN_CONTAINER, xo_stack_flags(flags)); return rc; } xo_ssize_t xo_open_container_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { return xo_transition(xop, flags, name, XSS_OPEN_CONTAINER); } xo_ssize_t xo_open_container_h (xo_handle_t *xop, const char *name) { return xo_open_container_hf(xop, 0, name); } xo_ssize_t xo_open_container (const char *name) { return xo_open_container_hf(NULL, 0, name); } xo_ssize_t xo_open_container_hd (xo_handle_t *xop, const char *name) { return xo_open_container_hf(xop, XOF_DTRT, name); } xo_ssize_t xo_open_container_d (const char *name) { return xo_open_container_hf(NULL, XOF_DTRT, name); } static int xo_do_close_container (xo_handle_t *xop, const char *name) { xop = xo_default(xop); ssize_t rc = 0; const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; if (name == NULL) { xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; name = xsp->xs_name; if (name) { ssize_t len = strlen(name) + 1; /* We need to make a local copy; xo_depth_change will free it */ char *cp = alloca(len); memcpy(cp, name, len); name = cp; } else if (!(xsp->xs_flags & XSF_DTRT)) { xo_failure(xop, "missing name without 'dtrt' mode"); name = XO_FAILURE_NAME; } } const char *leader = xo_xml_leader(xop, name); switch (xo_style(xop)) { case XO_STYLE_XML: xo_depth_change(xop, name, -1, -1, XSS_CLOSE_CONTAINER, 0); rc = xo_printf(xop, "%*s%s", xo_indent(xop), "", leader, name, ppn); break; case XO_STYLE_JSON: xo_stack_set_flags(xop); pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; ppn = ""; xo_depth_change(xop, name, -1, -1, XSS_CLOSE_CONTAINER, 0); rc = xo_printf(xop, "%s%*s}%s", pre_nl, xo_indent(xop), "", ppn); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; case XO_STYLE_HTML: case XO_STYLE_TEXT: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_CONTAINER, 0); break; case XO_STYLE_SDPARAMS: break; case XO_STYLE_ENCODER: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_CONTAINER, 0); rc = xo_encoder_handle(xop, XO_OP_CLOSE_CONTAINER, name, NULL, 0); break; } return rc; } xo_ssize_t xo_close_container_h (xo_handle_t *xop, const char *name) { return xo_transition(xop, 0, name, XSS_CLOSE_CONTAINER); } xo_ssize_t xo_close_container (const char *name) { return xo_close_container_h(NULL, name); } xo_ssize_t xo_close_container_hd (xo_handle_t *xop) { return xo_close_container_h(xop, NULL); } xo_ssize_t xo_close_container_d (void) { return xo_close_container_h(NULL, NULL); } static int xo_do_open_list (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { ssize_t rc = 0; int indent = 0; xop = xo_default(xop); const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; switch (xo_style(xop)) { case XO_STYLE_JSON: indent = 1; if (!XOF_ISSET(xop, XOF_NO_TOP) && !XOIF_ISSET(xop, XOIF_TOP_EMITTED)) xo_emit_top(xop, ppn); if (name == NULL) { xo_failure(xop, "NULL passed for list name"); name = XO_FAILURE_NAME; } xo_stack_set_flags(xop); if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? ",\n" : ", "; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; + /* If we need underscores, make a local copy and doctor it */ + const char *new_name = name; + if (XOF_ISSET(xop, XOF_UNDERSCORES)) { + size_t len = strlen(name); + const char *old_name = name; + char *buf, *cp, *ep; + + buf = alloca(len + 1); + for (cp = buf, ep = buf + len + 1; cp < ep; cp++, old_name++) + *cp = (*old_name == '-') ? '_' : *old_name; + new_name = buf; + } + rc = xo_printf(xop, "%s%*s\"%s\": [%s", - pre_nl, xo_indent(xop), "", name, ppn); + pre_nl, xo_indent(xop), "", new_name, ppn); break; case XO_STYLE_ENCODER: rc = xo_encoder_handle(xop, XO_OP_OPEN_LIST, name, NULL, flags); break; } xo_depth_change(xop, name, 1, indent, XSS_OPEN_LIST, XSF_LIST | xo_stack_flags(flags)); return rc; } xo_ssize_t xo_open_list_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { return xo_transition(xop, flags, name, XSS_OPEN_LIST); } xo_ssize_t xo_open_list_h (xo_handle_t *xop, const char *name) { return xo_open_list_hf(xop, 0, name); } xo_ssize_t xo_open_list (const char *name) { return xo_open_list_hf(NULL, 0, name); } xo_ssize_t xo_open_list_hd (xo_handle_t *xop, const char *name) { return xo_open_list_hf(xop, XOF_DTRT, name); } xo_ssize_t xo_open_list_d (const char *name) { return xo_open_list_hf(NULL, XOF_DTRT, name); } static int xo_do_close_list (xo_handle_t *xop, const char *name) { ssize_t rc = 0; const char *pre_nl = ""; if (name == NULL) { xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; name = xsp->xs_name; if (name) { ssize_t len = strlen(name) + 1; /* We need to make a local copy; xo_depth_change will free it */ char *cp = alloca(len); memcpy(cp, name, len); name = cp; } else if (!(xsp->xs_flags & XSF_DTRT)) { xo_failure(xop, "missing name without 'dtrt' mode"); name = XO_FAILURE_NAME; } } switch (xo_style(xop)) { case XO_STYLE_JSON: if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; xo_depth_change(xop, name, -1, -1, XSS_CLOSE_LIST, XSF_LIST); rc = xo_printf(xop, "%s%*s]", pre_nl, xo_indent(xop), ""); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; case XO_STYLE_ENCODER: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_LIST, XSF_LIST); rc = xo_encoder_handle(xop, XO_OP_CLOSE_LIST, name, NULL, 0); break; default: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_LIST, XSF_LIST); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; } return rc; } xo_ssize_t xo_close_list_h (xo_handle_t *xop, const char *name) { return xo_transition(xop, 0, name, XSS_CLOSE_LIST); } xo_ssize_t xo_close_list (const char *name) { return xo_close_list_h(NULL, name); } xo_ssize_t xo_close_list_hd (xo_handle_t *xop) { return xo_close_list_h(xop, NULL); } xo_ssize_t xo_close_list_d (void) { return xo_close_list_h(NULL, NULL); } static int xo_do_open_leaf_list (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { ssize_t rc = 0; int indent = 0; xop = xo_default(xop); const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; switch (xo_style(xop)) { case XO_STYLE_JSON: indent = 1; if (!XOF_ISSET(xop, XOF_NO_TOP)) { if (!XOIF_ISSET(xop, XOIF_TOP_EMITTED)) { xo_printf(xop, "%*s{%s", xo_indent(xop), "", ppn); XOIF_SET(xop, XOIF_TOP_EMITTED); } } if (name == NULL) { xo_failure(xop, "NULL passed for list name"); name = XO_FAILURE_NAME; } xo_stack_set_flags(xop); if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? ",\n" : ", "; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; rc = xo_printf(xop, "%s%*s\"%s\": [%s", pre_nl, xo_indent(xop), "", name, ppn); break; case XO_STYLE_ENCODER: rc = xo_encoder_handle(xop, XO_OP_OPEN_LEAF_LIST, name, NULL, flags); break; } xo_depth_change(xop, name, 1, indent, XSS_OPEN_LEAF_LIST, XSF_LIST | xo_stack_flags(flags)); return rc; } static int xo_do_close_leaf_list (xo_handle_t *xop, const char *name) { ssize_t rc = 0; const char *pre_nl = ""; if (name == NULL) { xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; name = xsp->xs_name; if (name) { ssize_t len = strlen(name) + 1; /* We need to make a local copy; xo_depth_change will free it */ char *cp = alloca(len); memcpy(cp, name, len); name = cp; } else if (!(xsp->xs_flags & XSF_DTRT)) { xo_failure(xop, "missing name without 'dtrt' mode"); name = XO_FAILURE_NAME; } } switch (xo_style(xop)) { case XO_STYLE_JSON: if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; xo_depth_change(xop, name, -1, -1, XSS_CLOSE_LEAF_LIST, XSF_LIST); rc = xo_printf(xop, "%s%*s]", pre_nl, xo_indent(xop), ""); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; case XO_STYLE_ENCODER: rc = xo_encoder_handle(xop, XO_OP_CLOSE_LEAF_LIST, name, NULL, 0); /* FALLTHRU */ default: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_LEAF_LIST, XSF_LIST); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; } return rc; } static int xo_do_open_instance (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { xop = xo_default(xop); ssize_t rc = 0; const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; if (name == NULL) { xo_failure(xop, "NULL passed for instance name"); name = XO_FAILURE_NAME; } const char *leader = xo_xml_leader(xop, name); flags |= xop->xo_flags; switch (xo_style(xop)) { case XO_STYLE_XML: rc = xo_printf(xop, "%*s<%s%s", xo_indent(xop), "", leader, name); if (xop->xo_attrs.xb_curp != xop->xo_attrs.xb_bufp) { rc += xop->xo_attrs.xb_curp - xop->xo_attrs.xb_bufp; xo_data_append(xop, xop->xo_attrs.xb_bufp, xop->xo_attrs.xb_curp - xop->xo_attrs.xb_bufp); xop->xo_attrs.xb_curp = xop->xo_attrs.xb_bufp; } rc += xo_printf(xop, ">%s", ppn); break; case XO_STYLE_JSON: xo_stack_set_flags(xop); if (xop->xo_stack[xop->xo_depth].xs_flags & XSF_NOT_FIRST) pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? ",\n" : ", "; xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; rc = xo_printf(xop, "%s%*s{%s", pre_nl, xo_indent(xop), "", ppn); break; case XO_STYLE_SDPARAMS: break; case XO_STYLE_ENCODER: rc = xo_encoder_handle(xop, XO_OP_OPEN_INSTANCE, name, NULL, flags); break; } xo_depth_change(xop, name, 1, 1, XSS_OPEN_INSTANCE, xo_stack_flags(flags)); return rc; } xo_ssize_t xo_open_instance_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name) { return xo_transition(xop, flags, name, XSS_OPEN_INSTANCE); } xo_ssize_t xo_open_instance_h (xo_handle_t *xop, const char *name) { return xo_open_instance_hf(xop, 0, name); } xo_ssize_t xo_open_instance (const char *name) { return xo_open_instance_hf(NULL, 0, name); } xo_ssize_t xo_open_instance_hd (xo_handle_t *xop, const char *name) { return xo_open_instance_hf(xop, XOF_DTRT, name); } xo_ssize_t xo_open_instance_d (const char *name) { return xo_open_instance_hf(NULL, XOF_DTRT, name); } static int xo_do_close_instance (xo_handle_t *xop, const char *name) { xop = xo_default(xop); ssize_t rc = 0; const char *ppn = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; const char *pre_nl = ""; if (name == NULL) { xo_stack_t *xsp = &xop->xo_stack[xop->xo_depth]; name = xsp->xs_name; if (name) { ssize_t len = strlen(name) + 1; /* We need to make a local copy; xo_depth_change will free it */ char *cp = alloca(len); memcpy(cp, name, len); name = cp; } else if (!(xsp->xs_flags & XSF_DTRT)) { xo_failure(xop, "missing name without 'dtrt' mode"); name = XO_FAILURE_NAME; } } const char *leader = xo_xml_leader(xop, name); switch (xo_style(xop)) { case XO_STYLE_XML: xo_depth_change(xop, name, -1, -1, XSS_CLOSE_INSTANCE, 0); rc = xo_printf(xop, "%*s%s", xo_indent(xop), "", leader, name, ppn); break; case XO_STYLE_JSON: pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; xo_depth_change(xop, name, -1, -1, XSS_CLOSE_INSTANCE, 0); rc = xo_printf(xop, "%s%*s}", pre_nl, xo_indent(xop), ""); xop->xo_stack[xop->xo_depth].xs_flags |= XSF_NOT_FIRST; break; case XO_STYLE_HTML: case XO_STYLE_TEXT: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_INSTANCE, 0); break; case XO_STYLE_SDPARAMS: break; case XO_STYLE_ENCODER: xo_depth_change(xop, name, -1, 0, XSS_CLOSE_INSTANCE, 0); rc = xo_encoder_handle(xop, XO_OP_CLOSE_INSTANCE, name, NULL, 0); break; } return rc; } xo_ssize_t xo_close_instance_h (xo_handle_t *xop, const char *name) { return xo_transition(xop, 0, name, XSS_CLOSE_INSTANCE); } xo_ssize_t xo_close_instance (const char *name) { return xo_close_instance_h(NULL, name); } xo_ssize_t xo_close_instance_hd (xo_handle_t *xop) { return xo_close_instance_h(xop, NULL); } xo_ssize_t xo_close_instance_d (void) { return xo_close_instance_h(NULL, NULL); } static int xo_do_close_all (xo_handle_t *xop, xo_stack_t *limit) { xo_stack_t *xsp; ssize_t rc = 0; xo_xsf_flags_t flags; for (xsp = &xop->xo_stack[xop->xo_depth]; xsp >= limit; xsp--) { switch (xsp->xs_state) { case XSS_INIT: /* Nothing */ rc = 0; break; case XSS_OPEN_CONTAINER: rc = xo_do_close_container(xop, NULL); break; case XSS_OPEN_LIST: rc = xo_do_close_list(xop, NULL); break; case XSS_OPEN_INSTANCE: rc = xo_do_close_instance(xop, NULL); break; case XSS_OPEN_LEAF_LIST: rc = xo_do_close_leaf_list(xop, NULL); break; case XSS_MARKER: flags = xsp->xs_flags & XSF_MARKER_FLAGS; xo_depth_change(xop, xsp->xs_name, -1, 0, XSS_MARKER, 0); xop->xo_stack[xop->xo_depth].xs_flags |= flags; rc = 0; break; } if (rc < 0) xo_failure(xop, "close %d failed: %d", xsp->xs_state, rc); } return 0; } /* * This function is responsible for clearing out whatever is needed * to get to the desired state, if possible. */ static int xo_do_close (xo_handle_t *xop, const char *name, xo_state_t new_state) { xo_stack_t *xsp, *limit = NULL; ssize_t rc; xo_state_t need_state = new_state; if (new_state == XSS_CLOSE_CONTAINER) need_state = XSS_OPEN_CONTAINER; else if (new_state == XSS_CLOSE_LIST) need_state = XSS_OPEN_LIST; else if (new_state == XSS_CLOSE_INSTANCE) need_state = XSS_OPEN_INSTANCE; else if (new_state == XSS_CLOSE_LEAF_LIST) need_state = XSS_OPEN_LEAF_LIST; else if (new_state == XSS_MARKER) need_state = XSS_MARKER; else return 0; /* Unknown or useless new states are ignored */ for (xsp = &xop->xo_stack[xop->xo_depth]; xsp > xop->xo_stack; xsp--) { /* * Marker's normally stop us from going any further, unless * we are popping a marker (new_state == XSS_MARKER). */ if (xsp->xs_state == XSS_MARKER && need_state != XSS_MARKER) { if (name) { xo_failure(xop, "close (xo_%s) fails at marker '%s'; " "not found '%s'", xo_state_name(new_state), xsp->xs_name, name); return 0; } else { limit = xsp; xo_failure(xop, "close stops at marker '%s'", xsp->xs_name); } break; } if (xsp->xs_state != need_state) continue; if (name && xsp->xs_name && !xo_streq(name, xsp->xs_name)) continue; limit = xsp; break; } if (limit == NULL) { xo_failure(xop, "xo_%s can't find match for '%s'", xo_state_name(new_state), name); return 0; } rc = xo_do_close_all(xop, limit); return rc; } /* * We are in a given state and need to transition to the new state. */ static ssize_t xo_transition (xo_handle_t *xop, xo_xof_flags_t flags, const char *name, xo_state_t new_state) { xo_stack_t *xsp; ssize_t rc = 0; int old_state, on_marker; xop = xo_default(xop); xsp = &xop->xo_stack[xop->xo_depth]; old_state = xsp->xs_state; on_marker = (old_state == XSS_MARKER); /* If there's a marker on top of the stack, we need to find a real state */ while (old_state == XSS_MARKER) { if (xsp == xop->xo_stack) break; xsp -= 1; old_state = xsp->xs_state; } /* * At this point, the list of possible states are: * XSS_INIT, XSS_OPEN_CONTAINER, XSS_OPEN_LIST, * XSS_OPEN_INSTANCE, XSS_OPEN_LEAF_LIST, XSS_DISCARDING */ switch (XSS_TRANSITION(old_state, new_state)) { open_container: case XSS_TRANSITION(XSS_INIT, XSS_OPEN_CONTAINER): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_OPEN_CONTAINER): case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_OPEN_CONTAINER): rc = xo_do_open_container(xop, flags, name); break; case XSS_TRANSITION(XSS_OPEN_LIST, XSS_OPEN_CONTAINER): case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_OPEN_CONTAINER): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); if (rc >= 0) goto open_container; break; case XSS_TRANSITION(XSS_INIT, XSS_CLOSE_CONTAINER): /* This is an exception for "xo --close" */ rc = xo_do_close_container(xop, name); break; /*close_container:*/ case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_CLOSE_CONTAINER): case XSS_TRANSITION(XSS_OPEN_LIST, XSS_CLOSE_CONTAINER): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_CLOSE_CONTAINER): if (on_marker) goto marker_prevents_close; rc = xo_do_close(xop, name, new_state); break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_CLOSE_CONTAINER): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); if (rc >= 0) rc = xo_do_close(xop, name, new_state); break; open_list: case XSS_TRANSITION(XSS_INIT, XSS_OPEN_LIST): case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_OPEN_LIST): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_OPEN_LIST): rc = xo_do_open_list(xop, flags, name); break; case XSS_TRANSITION(XSS_OPEN_LIST, XSS_OPEN_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close_list(xop, NULL); if (rc >= 0) goto open_list; break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_OPEN_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); if (rc >= 0) goto open_list; break; /*close_list:*/ case XSS_TRANSITION(XSS_OPEN_LIST, XSS_CLOSE_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close(xop, name, new_state); break; case XSS_TRANSITION(XSS_INIT, XSS_CLOSE_LIST): case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_CLOSE_LIST): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_CLOSE_LIST): case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_CLOSE_LIST): rc = xo_do_close(xop, name, new_state); break; open_instance: case XSS_TRANSITION(XSS_OPEN_LIST, XSS_OPEN_INSTANCE): rc = xo_do_open_instance(xop, flags, name); break; case XSS_TRANSITION(XSS_INIT, XSS_OPEN_INSTANCE): case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_OPEN_INSTANCE): rc = xo_do_open_list(xop, flags, name); if (rc >= 0) goto open_instance; break; case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_OPEN_INSTANCE): if (on_marker) { rc = xo_do_open_list(xop, flags, name); } else { rc = xo_do_close_instance(xop, NULL); } if (rc >= 0) goto open_instance; break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_OPEN_INSTANCE): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); if (rc >= 0) goto open_instance; break; /*close_instance:*/ case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_CLOSE_INSTANCE): if (on_marker) goto marker_prevents_close; rc = xo_do_close_instance(xop, name); break; case XSS_TRANSITION(XSS_INIT, XSS_CLOSE_INSTANCE): /* This one makes no sense; ignore it */ xo_failure(xop, "xo_close_instance ignored when called from " "initial state ('%s')", name ?: "(unknown)"); break; case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_CLOSE_INSTANCE): case XSS_TRANSITION(XSS_OPEN_LIST, XSS_CLOSE_INSTANCE): if (on_marker) goto marker_prevents_close; rc = xo_do_close(xop, name, new_state); break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_CLOSE_INSTANCE): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); if (rc >= 0) rc = xo_do_close(xop, name, new_state); break; open_leaf_list: case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_OPEN_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_OPEN_LEAF_LIST): case XSS_TRANSITION(XSS_INIT, XSS_OPEN_LEAF_LIST): rc = xo_do_open_leaf_list(xop, flags, name); break; case XSS_TRANSITION(XSS_OPEN_LIST, XSS_OPEN_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_OPEN_LEAF_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close_list(xop, NULL); if (rc >= 0) goto open_leaf_list; break; /*close_leaf_list:*/ case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_CLOSE_LEAF_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, name); break; case XSS_TRANSITION(XSS_INIT, XSS_CLOSE_LEAF_LIST): /* Makes no sense; ignore */ xo_failure(xop, "xo_close_leaf_list ignored when called from " "initial state ('%s')", name ?: "(unknown)"); break; case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_CLOSE_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_LIST, XSS_CLOSE_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_CLOSE_LEAF_LIST): if (on_marker) goto marker_prevents_close; rc = xo_do_close(xop, name, new_state); break; /*emit:*/ case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_EMIT): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_EMIT): break; case XSS_TRANSITION(XSS_OPEN_LIST, XSS_EMIT): if (on_marker) goto marker_prevents_close; rc = xo_do_close(xop, NULL, XSS_CLOSE_LIST); break; case XSS_TRANSITION(XSS_INIT, XSS_EMIT): break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_EMIT): if (on_marker) goto marker_prevents_close; rc = xo_do_close_leaf_list(xop, NULL); break; /*emit_leaf_list:*/ case XSS_TRANSITION(XSS_INIT, XSS_EMIT_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_CONTAINER, XSS_EMIT_LEAF_LIST): case XSS_TRANSITION(XSS_OPEN_INSTANCE, XSS_EMIT_LEAF_LIST): rc = xo_do_open_leaf_list(xop, flags, name); break; case XSS_TRANSITION(XSS_OPEN_LEAF_LIST, XSS_EMIT_LEAF_LIST): break; case XSS_TRANSITION(XSS_OPEN_LIST, XSS_EMIT_LEAF_LIST): /* * We need to be backward compatible with the pre-xo_open_leaf_list * API, where both lists and leaf-lists were opened as lists. So * if we find an open list that hasn't had anything written to it, * we'll accept it. */ break; default: xo_failure(xop, "unknown transition: (%u -> %u)", xsp->xs_state, new_state); } /* Handle the flush flag */ if (rc >= 0 && XOF_ISSET(xop, XOF_FLUSH)) if (xo_flush_h(xop) < 0) rc = -1; /* We have now official made output */ XOIF_SET(xop, XOIF_MADE_OUTPUT); return rc; marker_prevents_close: xo_failure(xop, "marker '%s' prevents transition from %s to %s", xop->xo_stack[xop->xo_depth].xs_name, xo_state_name(old_state), xo_state_name(new_state)); return -1; } xo_ssize_t xo_open_marker_h (xo_handle_t *xop, const char *name) { xop = xo_default(xop); xo_depth_change(xop, name, 1, 0, XSS_MARKER, xop->xo_stack[xop->xo_depth].xs_flags & XSF_MARKER_FLAGS); return 0; } xo_ssize_t xo_open_marker (const char *name) { return xo_open_marker_h(NULL, name); } xo_ssize_t xo_close_marker_h (xo_handle_t *xop, const char *name) { xop = xo_default(xop); return xo_do_close(xop, name, XSS_MARKER); } xo_ssize_t xo_close_marker (const char *name) { return xo_close_marker_h(NULL, name); } /* * Record custom output functions into the xo handle, allowing * integration with a variety of output frameworks. */ 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) { xop = xo_default(xop); xop->xo_opaque = opaque; xop->xo_write = write_func; xop->xo_close = close_func; xop->xo_flush = flush_func; } void xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func) { xo_realloc = realloc_func; xo_free = free_func; } xo_ssize_t xo_flush_h (xo_handle_t *xop) { ssize_t rc; xop = xo_default(xop); switch (xo_style(xop)) { case XO_STYLE_ENCODER: xo_encoder_handle(xop, XO_OP_FLUSH, NULL, NULL, 0); } rc = xo_write(xop); if (rc >= 0 && xop->xo_flush) if (xop->xo_flush(xop->xo_opaque) < 0) return -1; return rc; } xo_ssize_t xo_flush (void) { return xo_flush_h(NULL); } xo_ssize_t xo_finish_h (xo_handle_t *xop) { const char *open_if_empty = ""; xop = xo_default(xop); if (!XOF_ISSET(xop, XOF_NO_CLOSE)) xo_do_close_all(xop, xop->xo_stack); switch (xo_style(xop)) { case XO_STYLE_JSON: if (!XOF_ISSET(xop, XOF_NO_TOP)) { const char *pre_nl = XOF_ISSET(xop, XOF_PRETTY) ? "\n" : ""; if (XOIF_ISSET(xop, XOIF_TOP_EMITTED)) XOIF_CLEAR(xop, XOIF_TOP_EMITTED); /* Turn off before output */ else if (!XOIF_ISSET(xop, XOIF_MADE_OUTPUT)) { open_if_empty = "{ "; pre_nl = ""; } xo_printf(xop, "%s%*s%s}\n", pre_nl, xo_indent(xop), "", open_if_empty); } break; case XO_STYLE_ENCODER: xo_encoder_handle(xop, XO_OP_FINISH, NULL, NULL, 0); break; } return xo_flush_h(xop); } xo_ssize_t xo_finish (void) { return xo_finish_h(NULL); } /* * xo_finish_atexit is suitable for atexit() calls, to force clear up * and finalizing output. */ void xo_finish_atexit (void) { (void) xo_finish_h(NULL); } /* * Generate an error message, such as would be displayed on stderr */ void xo_errorn_hv (xo_handle_t *xop, int need_newline, const char *fmt, va_list vap) { xop = xo_default(xop); /* * If the format string doesn't end with a newline, we pop * one on ourselves. */ if (need_newline) { ssize_t len = strlen(fmt); if (len > 0 && fmt[len - 1] != '\n') { char *newfmt = alloca(len + 2); memcpy(newfmt, fmt, len); newfmt[len] = '\n'; newfmt[len + 1] = '\0'; fmt = newfmt; } } switch (xo_style(xop)) { case XO_STYLE_TEXT: vfprintf(stderr, fmt, vap); break; case XO_STYLE_HTML: va_copy(xop->xo_vap, vap); xo_buf_append_div(xop, "error", 0, NULL, 0, NULL, 0, fmt, strlen(fmt), NULL, 0); if (XOIF_ISSET(xop, XOIF_DIV_OPEN)) xo_line_close(xop); xo_write(xop); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); break; case XO_STYLE_XML: case XO_STYLE_JSON: va_copy(xop->xo_vap, vap); xo_open_container_h(xop, "error"); xo_format_value(xop, "message", 7, NULL, 0, fmt, strlen(fmt), NULL, 0, 0); xo_close_container_h(xop, "error"); va_end(xop->xo_vap); bzero(&xop->xo_vap, sizeof(xop->xo_vap)); break; case XO_STYLE_SDPARAMS: case XO_STYLE_ENCODER: break; } } void xo_error_h (xo_handle_t *xop, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_errorn_hv(xop, 0, fmt, vap); va_end(vap); } /* * Generate an error message, such as would be displayed on stderr */ void xo_error (const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_errorn_hv(NULL, 0, fmt, vap); va_end(vap); } void xo_errorn_h (xo_handle_t *xop, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_errorn_hv(xop, 1, fmt, vap); va_end(vap); } /* * Generate an error message, such as would be displayed on stderr */ void xo_errorn (const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_errorn_hv(NULL, 1, fmt, vap); va_end(vap); } /* * Parse any libxo-specific options from the command line, removing them * so the main() argument parsing won't see them. We return the new value * for argc or -1 for error. If an error occurred, the program should * exit. A suitable error message has already been displayed. */ int xo_parse_args (int argc, char **argv) { static char libxo_opt[] = "--libxo"; char *cp; int i, save; /* * If xo_set_program has always been called, we honor that value */ if (xo_program == NULL) { /* Save our program name for xo_err and friends */ xo_program = argv[0]; cp = strrchr(xo_program, '/'); if (cp) xo_program = ++cp; else cp = argv[0]; /* Reset to front of string */ /* * GNU libtool add an annoying ".test" as the program * extension; we remove it. libtool also adds a "lt-" prefix * that we cannot remove. */ size_t len = strlen(xo_program); static const char gnu_ext[] = ".test"; if (len >= sizeof(gnu_ext)) { cp += len + 1 - sizeof(gnu_ext); if (xo_streq(cp, gnu_ext)) *cp = '\0'; } } xo_handle_t *xop = xo_default(NULL); for (save = i = 1; i < argc; i++) { if (argv[i] == NULL || strncmp(argv[i], libxo_opt, sizeof(libxo_opt) - 1) != 0) { if (save != i) argv[save] = argv[i]; save += 1; continue; } cp = argv[i] + sizeof(libxo_opt) - 1; if (*cp == '\0') { cp = argv[++i]; if (cp == NULL) { xo_warnx("missing libxo option"); return -1; } if (xo_set_options(xop, cp) < 0) return -1; } else if (*cp == ':') { if (xo_set_options(xop, cp) < 0) return -1; } else if (*cp == '=') { if (xo_set_options(xop, ++cp) < 0) return -1; } else if (*cp == '-') { cp += 1; if (xo_streq(cp, "check")) { exit(XO_HAS_LIBXO); } else { xo_warnx("unknown libxo option: '%s'", argv[i]); return -1; } } else { xo_warnx("unknown libxo option: '%s'", argv[i]); return -1; } } /* * We only want to do color output on terminals, but we only want * to do this if the user has asked for color. */ if (XOF_ISSET(xop, XOF_COLOR_ALLOWED) && isatty(1)) XOF_SET(xop, XOF_COLOR); argv[save] = NULL; return save; } /* * Debugging function that dumps the current stack of open libxo constructs, * suitable for calling from the debugger. */ void xo_dump_stack (xo_handle_t *xop) { int i; xo_stack_t *xsp; xop = xo_default(xop); fprintf(stderr, "Stack dump:\n"); xsp = xop->xo_stack; for (i = 1, xsp++; i <= xop->xo_depth; i++, xsp++) { fprintf(stderr, " [%d] %s '%s' [%x]\n", i, xo_state_name(xsp->xs_state), xsp->xs_name ?: "--", xsp->xs_flags); } } /* * Record the program name used for error messages */ void xo_set_program (const char *name) { xo_program = name; } void xo_set_version_h (xo_handle_t *xop, const char *version) { xop = xo_default(xop); if (version == NULL || strchr(version, '"') != NULL) return; if (!xo_style_is_encoding(xop)) return; switch (xo_style(xop)) { case XO_STYLE_XML: /* For XML, we record this as an attribute for the first tag */ xo_attr_h(xop, "version", "%s", version); break; case XO_STYLE_JSON: /* * For JSON, we record the version string in our handle, and emit * it in xo_emit_top. */ xop->xo_version = xo_strndup(version, -1); break; case XO_STYLE_ENCODER: xo_encoder_handle(xop, XO_OP_VERSION, NULL, version, 0); break; } } /* * Set the version number for the API content being carried through * the xo handle. */ void xo_set_version (const char *version) { xo_set_version_h(NULL, version); } /* * Generate a warning. Normally, this is a text message written to * standard error. If the XOF_WARN_XML flag is set, then we generate * XMLified content on standard output. */ void xo_emit_warn_hcv (xo_handle_t *xop, int as_warning, int code, const char *fmt, va_list vap) { xop = xo_default(xop); if (fmt == NULL) return; xo_open_marker_h(xop, "xo_emit_warn_hcv"); xo_open_container_h(xop, as_warning ? "__warning" : "__error"); if (xo_program) xo_emit("{wc:program}", xo_program); if (xo_style(xop) == XO_STYLE_XML || xo_style(xop) == XO_STYLE_JSON) { va_list ap; xo_handle_t temp; bzero(&temp, sizeof(temp)); temp.xo_style = XO_STYLE_TEXT; xo_buf_init(&temp.xo_data); xo_depth_check(&temp, XO_DEPTH); va_copy(ap, vap); (void) xo_emit_hv(&temp, fmt, ap); va_end(ap); xo_buffer_t *src = &temp.xo_data; xo_format_value(xop, "message", 7, src->xb_bufp, src->xb_curp - src->xb_bufp, NULL, 0, NULL, 0, 0); xo_free(temp.xo_stack); xo_buf_cleanup(src); } (void) xo_emit_hv(xop, fmt, vap); ssize_t len = strlen(fmt); if (len > 0 && fmt[len - 1] != '\n') { if (code > 0) { const char *msg = strerror(code); if (msg) xo_emit_h(xop, ": {G:strerror}{g:error/%s}", msg); } xo_emit("\n"); } xo_close_marker_h(xop, "xo_emit_warn_hcv"); xo_flush_h(xop); } void xo_emit_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_emit_warn_hcv(xop, 1, code, fmt, vap); va_end(vap); } void xo_emit_warn_c (int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_emit_warn_hcv(NULL, 1, code, fmt, vap); va_end(vap); } void xo_emit_warn (const char *fmt, ...) { int code = errno; va_list vap; va_start(vap, fmt); xo_emit_warn_hcv(NULL, 1, code, fmt, vap); va_end(vap); } void xo_emit_warnx (const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_emit_warn_hcv(NULL, 1, -1, fmt, vap); va_end(vap); } void xo_emit_err_v (int eval, int code, const char *fmt, va_list vap) { xo_emit_warn_hcv(NULL, 0, code, fmt, vap); xo_finish(); exit(eval); } void xo_emit_err (int eval, const char *fmt, ...) { int code = errno; va_list vap; va_start(vap, fmt); xo_emit_err_v(eval, code, fmt, vap); /*NOTREACHED*/ } void xo_emit_errx (int eval, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_emit_err_v(eval, -1, fmt, vap); /* This will exit */ /*NOTREACHED*/ } void xo_emit_errc (int eval, int code, const char *fmt, ...) { va_list vap; va_start(vap, fmt); xo_emit_err_v(eval, code, fmt, vap); /* This will exit */ /*NOTREACHED*/ } /* * Get the opaque private pointer for an xo handle */ void * xo_get_private (xo_handle_t *xop) { xop = xo_default(xop); return xop->xo_private; } /* * Set the opaque private pointer for an xo handle. */ void xo_set_private (xo_handle_t *xop, void *opaque) { xop = xo_default(xop); xop->xo_private = opaque; } /* * Get the encoder function */ xo_encoder_func_t xo_get_encoder (xo_handle_t *xop) { xop = xo_default(xop); return xop->xo_encoder; } /* * Record an encoder callback function in an xo handle. */ void xo_set_encoder (xo_handle_t *xop, xo_encoder_func_t encoder) { xop = xo_default(xop); xop->xo_style = XO_STYLE_ENCODER; xop->xo_encoder = encoder; } /* * The xo(1) utility needs to be able to open and close lists and * instances, but since it's called without "state", we cannot * rely on the state transitions (in xo_transition) to DTRT, so * we have a mechanism for external parties to "force" transitions * that would otherwise be impossible. This is not a general * mechanism, and is really tailored only for xo(1). */ void xo_explicit_transition (xo_handle_t *xop, xo_state_t new_state, const char *name, xo_xof_flags_t flags) { xo_xsf_flags_t xsf_flags; xop = xo_default(xop); switch (new_state) { case XSS_OPEN_LIST: xo_do_open_list(xop, flags, name); break; case XSS_OPEN_INSTANCE: xo_do_open_instance(xop, flags, name); break; case XSS_CLOSE_INSTANCE: xo_depth_change(xop, name, 1, 1, XSS_OPEN_INSTANCE, xo_stack_flags(flags)); xo_stack_set_flags(xop); xo_do_close_instance(xop, name); break; case XSS_CLOSE_LIST: xsf_flags = XOF_ISSET(xop, XOF_NOT_FIRST) ? XSF_NOT_FIRST : 0; xo_depth_change(xop, name, 1, 1, XSS_OPEN_LIST, XSF_LIST | xsf_flags | xo_stack_flags(flags)); xo_do_close_list(xop, name); break; } } diff --git a/contrib/libxo/libxo/xo_create.3 b/contrib/libxo/libxo/xo_create.3 index 03d51764b8ae..ea811c27e5c1 100644 --- a/contrib/libxo/libxo/xo_create.3 +++ b/contrib/libxo/libxo/xo_create.3 @@ -1,77 +1,77 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_create , xo_create_to_file , xo_destroy .Nd create and destroy libxo output handles .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft xo_handle_t * .Fn xo_create "unsigned style" "unsigned flags" .Ft xo_handle_t * .Fn xo_create_to_file "FILE *fp" "unsigned style" "unsigned flags" .Ft void .Fn xo_destroy "xo_handle_t *handle" .Sh DESCRIPTION A .Nm libxo handle can be allocated using the .Fn xo_create function. .Bd -literal -offset indent Example: xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN); .... - xo_emit_h(xop, "testing\n"); + xo_emit_h(xop, "testing\\n"); .Ed .Pp By default, .Nm libxo writes output to standard output. A convenience function is provided for situations when output should be written to a different file. .Pp Use the .Dv XOF_CLOSE_FP flag to trigger a call to .Xr fclose 3 for the .Dv FILE pointer when the handle is destroyed. .Pp The .Fn xo_destroy function releases a handle and any resources it is using. Calling .Fn xo_destroy with a .Dv NULL handle will release any resources associated with the default handle. .Sh SEE ALSO .Xr xo_emit 3 , .Xr xo_set_options 3 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_emit.3 b/contrib/libxo/libxo/xo_emit.3 index 9e3ec85b6765..cbf9d2b11eb4 100644 --- a/contrib/libxo/libxo/xo_emit.3 +++ b/contrib/libxo/libxo/xo_emit.3 @@ -1,114 +1,116 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_emit , xo_emit_h , xo_emit_hv .Nd emit formatted output based on format string and arguments .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft xo_ssize_t .Fn xo_emit "const char *fmt" "..." .Ft xo_ssize_t .Fn xo_emit_h "xo_handle_t *xop" "const char *fmt" "..." .Ft xo_ssize_t .Fn xo_emit_hv "xo_handle_t *xop" "const char *fmt" "va_list vap" .Sh DESCRIPTION The .Fn xo_emit function emits formatted output using the description in a format string along with a set of zero or more arguments, in a style similar to .Xr printf 3 but using a more complex format description string, as described in .Xr xo_format 5 . .Pp .Fn xo_emit uses the default output handle, as described in .Xr libxo 3 , where .Fn xo_emit_h uses an explicit handle. .Fn xo_emit_hv accepts a .Fa va_list for additional flexibility. .Sh EXAMPLES In this example, a set of four values is emitted using the following source code: .Bd -literal -offset indent xo_emit(" {:lines/%7ju} {:words/%7ju} " - "{:characters/%7ju} {d:filename/%s}\n", + "{:characters/%7ju} {d:filename/%s}\\n", linect, wordct, charct, file); .Ed Output can then be generated in various style, using the "--libxo" option: .Bd -literal -offset indent % wc /etc/motd 25 165 1140 /etc/motd % wc --libxo xml,pretty,warn /etc/motd 25 165 1140 /etc/motd % wc --libxo json,pretty,warn /etc/motd { "wc": { "file": [ { "lines": 25, "words": 165, "characters": 1140, "filename": "/etc/motd" } ] } } % wc --libxo html,pretty,warn /etc/motd
25
165
1140
/etc/motd
.Ed .Sh RETURN CODE .Nm returns a negative value on error. If the .Nm XOF_COLUMNS flag has been turned on for the specific handle using .Xr xo_set_flags 3 , then the number of display columns consumed by the output will be returned. .Sh SEE ALSO .Xr xo_open_container 3 , .Xr xo_open_list 3 , +.Xr xo_emit_f 3 , +.Xo xo_emit_field 3 , .Xr xo_format 5 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_emit_f.3 b/contrib/libxo/libxo/xo_emit_f.3 index 7c340175aef6..f8ac013256a8 100644 --- a/contrib/libxo/libxo/xo_emit_f.3 +++ b/contrib/libxo/libxo/xo_emit_f.3 @@ -1,121 +1,121 @@ .\" # .\" # Copyright (c) 2016, 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, April 2016 .\" .Dd April 15, 2016 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_emit_f , xo_emit_hf , xo_emit_hvf .Nd emit formatted output based on format string and arguments .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft xo_ssize_t .Fn xo_emit_f "xo_emit_flags_t flags" "const char *fmt" "..." .Ft xo_ssize_t .Fn xo_emit_hf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "..." .Ft xo_ssize_t .Fn xo_emit_hvf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "va_list vap" .Ft void .Fn xo_retain_clear_all "void" .Ft void .Fn xo_retain_clear "const char *fmt" .Sh DESCRIPTION These functions allow callers to pass a set of flags to .Nm emitting functions. These processing of arguments, except for .Fa flags , is identical to the base functions. See .Xr xo_emit 3 for additional information. .Pp The only currently defined flag is .Dv XOEF_RETAIN . .Nm can retain the parsed internal information related to the given format string, allowing subsequent .Xr xo_emit 3 calls, the retained information is used, avoiding repetitive parsing of the format string. To retain parsed format information, use the .Dv XOEF_RETAIN flag to the .Fn xo_emit_f function. .Pp The format string must be immutable across multiple calls to .Xn 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 .Dv XOEF_RETAIN flag must not be used. .Pp The functions .Fn xo_retain_clear and .Fn 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. .Pp The retained information is kept as thread-specific data. .Pp Use .Fn xo_retain_clear and .Fn xo_retain_clear_all to clear the retained information, clearing the retained information for either a specific format string or all format strings, respectively. These functions are only needed when the calling application wants to clear this information; they are not generally needed. .Sh EXAMPLES .Pp .Bd -literal -offset indent for (i = 0; i < 1000; i++) { xo_open_instance("item"); - xo_emit_f(XOEF_RETAIN, "{:name} {:count/%d}\n", + xo_emit_f(XOEF_RETAIN, "{:name} {:count/%d}\\n", name[i], count[i]); } .Ed .Pp In this example, the caller desires to clear the retained information. .Bd -literal -offset indent - const char *fmt = "{:name} {:count/%d}\n"; + 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); .Ed .Sh RETURN CODE The return values for these functions is identical to those of their traditional counterparts. See .Xr xo_emit 3 for details. .Sh SEE ALSO .Xr xo_emit 3 , .Xr xo_open_container 3 , .Xr xo_open_list 3 , .Xr xo_format 5 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_emit_field.3 b/contrib/libxo/libxo/xo_emit_field.3 new file mode 100644 index 000000000000..4f9636cee8e7 --- /dev/null +++ b/contrib/libxo/libxo/xo_emit_field.3 @@ -0,0 +1,113 @@ +.\" # +.\" # Copyright (c) 2021, 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 +.\" +.Dd December 4, 2014 +.Dt LIBXO 3 +.Os +.Sh NAME +.Nm xo_emit_field +.Nd emit formatted output based on format string and arguments +.Sh LIBRARY +.Lb libxo +.Sh SYNOPSIS +.In libxo/xo.h +.Ft xo_ssize_t +.Fn xo_emit_field "const char *rolmod" "const char *content" "const char *fmt" "const char *efmt" "..." +.Ft xo_ssize_t +.Fn xo_emit_field_h "xo_handle_t *xop" "const char *rolmod" "const char *content" "const char *fmt" const char *efmt" "..." +.Ft xo_ssize_t +.Fn xo_emit_field_hv "xo_handle_t *xop" "const char *rolmod" "const char *content" "const char *fmt" "const char *efmt" "va_list vap" +.Sh DESCRIPTION +The +.Fn xo_emit_field +function emits formatted output similar to +.Xr xo_emit 3 +but where +.Fn xo_emit +uses a single string argument containing the description +for multiple fields, +.Fn xo_emit_field +emits a single field using multiple arguments to contain the +field description. +.Fn xo_emit_field_h +adds an explicit handle to use instead of the default +handle, while +.Fn xo_emit_field_hv +accepts a +.Fa va_list +for additional flexibility. +.Pp +The arguments +.Fa rolmod , +.Fa content , +.Fa fmt , +and +.Fa efmt +are detailed in +.Xr xo_format 5 . +Using distinct arguments allows callers to pass the field description +in pieces, rather than having to use something like +.Xr snprintf 3 +to build the format string required by +.Fn xo_emit . +The arguments are each NUL-terminated strings. The +.Fa rolmod +argument contains the "role" and "modifier" portions of +the field description, the +.Fa content +argument contains the "content" portion, and the +.Fa fmt +and +.Fa efmt +contain the "field-format" and "encoding-format" portions, respectively. +.Pp +As with xo_emit, the +.Fa fmt +and +.Fa efmt +values are both optional, since the field-format string +defaults to "%s", and the encoding-format's default value is +derived from the field-format +per +.Xr xo_format 5 . +However, care must be taken to avoid using a value directly as the +format, since characters like '{', '%', and '}' will be interpreted +as formatting directives, and may cause +.Nm +to dereference arbitrary values off the stack, leading to bugs, +core files, and gnashing of teeth. +.Sh EXAMPLES +In this example, a set of four values is emitted using the following +source code: +.Bd -literal -offset indent + xo_emit_field("T", title, NULL, NULL, NULL); + xo_emit_field("Vt", "max-chaos", NULL, NULL, " very "); + xo_emit_field("V", "min-chaos", "%02d", "%d", 42); + xo_emit_field_h(NULL, ",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u", + "gum", 1412); +.Ed +.Sh RETURN CODE +.Nm +returns a negative value on error. If the +.Nm XOF_COLUMNS +flag has been turned on for the specific handle using +.Xr xo_set_flags 3 , +then the number of display columns consumed by the output will be returned. +.Sh SEE ALSO +.Xr xo_format 5 , +.Xr libxo 3 +.Sh HISTORY +The +.Nm libxo +library first appeared in +.Fx 11.0 . +.Sh AUTHORS +.Nm libxo +was written by +.An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_encoder.c b/contrib/libxo/libxo/xo_encoder.c index 475b6d70fa9d..5d195e06a2a8 100644 --- a/contrib/libxo/libxo/xo_encoder.c +++ b/contrib/libxo/libxo/xo_encoder.c @@ -1,417 +1,444 @@ /* * Copyright (c) 2015, 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. * Phil Shafer, August 2015 */ /** * libxo includes a number of fixed encoding styles. But other * external encoders are need to deal with new encoders. Rather * than expose a swarm of libxo internals, we create a distinct * API, with a simpler API than we use internally. */ #include #include #include #include #include #include #include "xo_config.h" #include "xo.h" #include "xo_encoder.h" #ifdef HAVE_DLFCN_H #include #if !defined(HAVE_DLFUNC) #define dlfunc(_p, _n) dlsym(_p, _n) #endif #else /* HAVE_DLFCN_H */ #define dlopen(_n, _f) NULL /* Fail */ #define dlsym(_p, _n) NULL /* Fail */ #define dlfunc(_p, _n) NULL /* Fail */ #endif /* HAVE_DLFCN_H */ static void xo_encoder_setup (void); /* Forward decl */ /* * Need a simple string collection */ typedef struct xo_string_node_s { TAILQ_ENTRY(xo_string_node_s) xs_link; /* Next string */ char xs_data[0]; /* String data */ } xo_string_node_t; typedef TAILQ_HEAD(xo_string_list_s, xo_string_node_s) xo_string_list_t; static inline void xo_string_list_init (xo_string_list_t *listp) { if (listp->tqh_last == NULL) TAILQ_INIT(listp); } static inline xo_string_node_t * xo_string_add (xo_string_list_t *listp, const char *str) { if (listp == NULL || str == NULL) return NULL; xo_string_list_init(listp); size_t len = strlen(str); xo_string_node_t *xsp; xsp = xo_realloc(NULL, sizeof(*xsp) + len + 1); if (xsp) { memcpy(xsp->xs_data, str, len); xsp->xs_data[len] = '\0'; TAILQ_INSERT_TAIL(listp, xsp, xs_link); } return xsp; } #define XO_STRING_LIST_FOREACH(_xsp, _listp) \ xo_string_list_init(_listp); \ TAILQ_FOREACH(_xsp, _listp, xs_link) static inline void xo_string_list_clean (xo_string_list_t *listp) { xo_string_node_t *xsp; xo_string_list_init(listp); for (;;) { xsp = TAILQ_FIRST(listp); if (xsp == NULL) break; TAILQ_REMOVE(listp, xsp, xs_link); xo_free(xsp); } } static xo_string_list_t xo_encoder_path; void xo_encoder_path_add (const char *path) { xo_encoder_setup(); if (path) xo_string_add(&xo_encoder_path, path); } /* ---------------------------------------------------------------------- */ typedef struct xo_encoder_node_s { TAILQ_ENTRY(xo_encoder_node_s) xe_link; /* Next session */ char *xe_name; /* Name for this encoder */ xo_encoder_func_t xe_handler; /* Callback function */ void *xe_dlhandle; /* dlopen handle */ } xo_encoder_node_t; typedef TAILQ_HEAD(xo_encoder_list_s, xo_encoder_node_s) xo_encoder_list_t; #define XO_ENCODER_LIST_FOREACH(_xep, _listp) \ xo_encoder_list_init(_listp); \ TAILQ_FOREACH(_xep, _listp, xe_link) static xo_encoder_list_t xo_encoders; static void xo_encoder_list_init (xo_encoder_list_t *listp) { if (listp->tqh_last == NULL) TAILQ_INIT(listp); } static xo_encoder_node_t * xo_encoder_list_add (const char *name) { if (name == NULL) return NULL; xo_encoder_node_t *xep = xo_realloc(NULL, sizeof(*xep)); if (xep) { ssize_t len = strlen(name) + 1; xep->xe_name = xo_realloc(NULL, len); if (xep->xe_name == NULL) { xo_free(xep); return NULL; } memcpy(xep->xe_name, name, len); TAILQ_INSERT_TAIL(&xo_encoders, xep, xe_link); } return xep; } void xo_encoders_clean (void) { xo_encoder_node_t *xep; xo_encoder_setup(); for (;;) { xep = TAILQ_FIRST(&xo_encoders); if (xep == NULL) break; TAILQ_REMOVE(&xo_encoders, xep, xe_link); if (xep->xe_dlhandle) dlclose(xep->xe_dlhandle); xo_free(xep); } xo_string_list_clean(&xo_encoder_path); } static void xo_encoder_setup (void) { static int initted; if (!initted) { initted = 1; xo_string_list_init(&xo_encoder_path); xo_encoder_list_init(&xo_encoders); xo_encoder_path_add(XO_ENCODERDIR); } } static xo_encoder_node_t * xo_encoder_find (const char *name) { xo_encoder_node_t *xep; xo_encoder_list_init(&xo_encoders); XO_ENCODER_LIST_FOREACH(xep, &xo_encoders) { if (xo_streq(xep->xe_name, name)) return xep; } return NULL; } +/* + * Return the encoder function for a specific shared library. This is + * really just a means of keeping the annoying gcc verbiage out of the + * main code. And that's only need because gcc breaks dlfunc's + * promise that I can cast it's return value to a function: "The + * precise return type of dlfunc() is unspecified; applications must + * cast it to an appropriate function pointer type." + */ +static xo_encoder_init_func_t +xo_encoder_func (void *dlp) +{ + xo_encoder_init_func_t func; + +#if defined(HAVE_GCC) && __GNUC__ > 8 +#pragma GCC diagnostic push +#pragma GCC diagnostic ignored "-Wcast-function-type" +#endif /* HAVE_GCC */ + + func = (xo_encoder_init_func_t) dlfunc(dlp, XO_ENCODER_INIT_NAME); + +#if defined(HAVE_GCC) && __GNUC__ > 8 +#pragma GCC diagnostic pop /* Restore previous setting */ +#endif /* HAVE_GCC */ + + return func; +} + static xo_encoder_node_t * xo_encoder_discover (const char *name) { void *dlp = NULL; char buf[MAXPATHLEN]; xo_string_node_t *xsp; xo_encoder_node_t *xep = NULL; XO_STRING_LIST_FOREACH(xsp, &xo_encoder_path) { static const char fmt[] = "%s/%s.enc"; char *dir = xsp->xs_data; size_t len = snprintf(buf, sizeof(buf), fmt, dir, name); if (len > sizeof(buf)) /* Should not occur */ continue; dlp = dlopen((const char *) buf, RTLD_NOW); if (dlp) break; } if (dlp) { /* * If the library exists, find the initializer function and * call it. */ xo_encoder_init_func_t func; - func = (xo_encoder_init_func_t) dlfunc(dlp, XO_ENCODER_INIT_NAME); + func = xo_encoder_func(dlp); if (func) { xo_encoder_init_args_t xei; bzero(&xei, sizeof(xei)); xei.xei_version = XO_ENCODER_VERSION; ssize_t rc = func(&xei); if (rc == 0 && xei.xei_handler) { xep = xo_encoder_list_add(name); if (xep) { xep->xe_handler = xei.xei_handler; xep->xe_dlhandle = dlp; } } } if (xep == NULL) dlclose(dlp); } return xep; } void xo_encoder_register (const char *name, xo_encoder_func_t func) { xo_encoder_setup(); xo_encoder_node_t *xep = xo_encoder_find(name); if (xep) /* "We alla-ready got one" */ return; xep = xo_encoder_list_add(name); if (xep) xep->xe_handler = func; } void xo_encoder_unregister (const char *name) { xo_encoder_setup(); xo_encoder_node_t *xep = xo_encoder_find(name); if (xep) { TAILQ_REMOVE(&xo_encoders, xep, xe_link); xo_free(xep); } } int xo_encoder_init (xo_handle_t *xop, const char *name) { xo_encoder_setup(); char opts_char = '\0'; const char *col_opts = strchr(name, ':'); const char *plus_opts = strchr(name, '+'); /* * Find the option-separating character (plus or colon) which * appears first in the options string. */ const char *opts = (col_opts == NULL) ? plus_opts : (plus_opts == NULL) ? col_opts : (plus_opts < col_opts) ? plus_opts : col_opts; if (opts) { opts_char = *opts; /* Make a writable copy of the name */ size_t len = strlen(name); char *copy = alloca(len + 1); memcpy(copy, name, len); copy[len] = '\0'; char *opts_copy = copy + (opts - name); /* Move to ':' */ *opts_copy++ = '\0'; /* Trim it off */ opts = opts_copy; /* Use copy as options */ name = copy; /* Use trimmed copy as name */ } /* Can't have names containing '/' or ':' */ if (strchr(name, '/') != NULL || strchr(name, ':') != NULL) { xo_failure(xop, "invalid encoder name: %s", name); return -1; } /* * First we look on the list of known (registered) encoders. * If we don't find it, we follow the set of paths to find * the encoding library. */ xo_encoder_node_t *xep = xo_encoder_find(name); if (xep == NULL) { xep = xo_encoder_discover(name); if (xep == NULL) { xo_failure(xop, "encoder not founde: %s", name); return -1; } } xo_set_encoder(xop, xep->xe_handler); int rc = xo_encoder_handle(xop, XO_OP_CREATE, name, NULL, 0); if (rc == 0 && opts != NULL) { xo_encoder_op_t op; /* Encoder API is limited, so we're stuck with two different options */ op = (opts_char == '+') ? XO_OP_OPTIONS_PLUS : XO_OP_OPTIONS; rc = xo_encoder_handle(xop, op, name, opts, 0); } return rc; } /* * A couple of function varieties here, to allow for multiple * use cases. This variant is for when the main program knows * its own encoder needs. */ xo_handle_t * xo_encoder_create (const char *name, xo_xof_flags_t flags) { xo_handle_t *xop; xop = xo_create(XO_STYLE_ENCODER, flags); if (xop) { if (xo_encoder_init(xop, name)) { xo_destroy(xop); xop = NULL; } } return xop; } int xo_encoder_handle (xo_handle_t *xop, xo_encoder_op_t op, const char *name, const char *value, xo_xff_flags_t flags) { void *private = xo_get_private(xop); xo_encoder_func_t func = xo_get_encoder(xop); if (func == NULL) return -1; return func(xop, op, name, value, private, flags); } const char * xo_encoder_op_name (xo_encoder_op_t op) { static const char *names[] = { /* 0 */ "unknown", /* 1 */ "create", /* 2 */ "open_container", /* 3 */ "close_container", /* 4 */ "open_list", /* 5 */ "close_list", /* 6 */ "open_leaf_list", /* 7 */ "close_leaf_list", /* 8 */ "open_instance", /* 9 */ "close_instance", /* 10 */ "string", /* 11 */ "content", /* 12 */ "finish", /* 13 */ "flush", /* 14 */ "destroy", /* 15 */ "attr", /* 16 */ "version", /* 17 */ "options", }; if (op > sizeof(names) / sizeof(names[0])) return "unknown"; return names[op]; } diff --git a/contrib/libxo/libxo/xo_format.5 b/contrib/libxo/libxo/xo_format.5 index 5265359866bb..3c7ddc9dd1aa 100644 --- a/contrib/libxo/libxo/xo_format.5 +++ b/contrib/libxo/libxo/xo_format.5 @@ -1,977 +1,984 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_format .Nd content of format descriptors for xo_emit .Sh DESCRIPTION .Pp .Nm libxo uses format strings to control the rendering of data into various output styles, including .Em text , .Em XML , .Em JSON , and .Em HTML . Each format string contains a set of zero or more .Dq "field descriptions" , which describe independent data fields. Each field description contains a set of .Dq modifiers , a .Dq "content string" , and zero, one, or two .Dq "format descriptors" . The modifiers tell .Nm libxo what the field is and how to treat it, while the format descriptors are formatting instructions using .Xr printf 3 Ns -style format strings, telling .Nm libxo how to format the field. The field description is placed inside a set of braces, with a colon .Ql ( \&: ) after the modifiers and a slash .Ql ( \&/ ) before each format descriptors. Text may be intermixed with field descriptions within the format string. .Pp The field description is given as follows: .Bd -literal -offset indent \(aq{\(aq [ role | modifier ]* [\(aq,\(aq long\-names ]* \(aq:\(aq [ content ] [ \(aq/\(aq field\-format [ \(aq/\(aq encoding\-format ]] \(aq}\(aq .Ed .Pp The role describes the function of the field, while the modifiers enable optional behaviors. The contents, field\-format, and encoding\-format are used in varying ways, based on the role. These are described in the following sections. .Pp Braces can be escaped by using double braces, similar to "%%" in .Xr printf 3 . The format string "{{braces}}" would emit "{braces}". .Pp In the following example, three field descriptors appear. The first is a padding field containing three spaces of padding, the second is a label ("In stock"), and the third is a value field ("in\-stock"). The in\-stock field has a "%u" format that will parse the next argument passed to the .Xr xo_emit 3 , function as an unsigned integer. .Bd -literal -offset indent xo_emit("{P: }{Lwc:In stock}{:in\-stock/%u}\\n", 65); .Ed .Pp This single line of code can generate text ("In stock: 65\\n"), XML ("65"), JSON (\(aq"in\-stock": 65\(aq), or HTML (too lengthy to be listed here). .Pp While roles and modifiers typically use single character for brevity, there are alternative names for each which allow more verbose formatting strings. These names must be preceded by a comma, and may follow any single\-character values: .Bd -literal -offset indent xo_emit("{L,white,colon:In stock}{,key:in\-stock/%u}\\n", 65); .Ed .Ss "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: .Bl -column "M" "Name12341234" .It Sy "M" "Name " "Description" .It C "color " "Field is a color or effect" .It D "decoration " "Field is non\-text (e.g. colon, comma)" .It E "error " "Field is an error message" .It L "label " "Field is text that prefixes a value" .It N "note " "Field is text that follows a value" .It P "padding " "Field is spaces needed for vertical alignment" .It T "title " "Field is a title value for headings" .It U "units " "Field is the units for the previous value field" .It V "value " "Field is the name of field (the default)" .It W "warning " "Field is a warning message" .It \&[ "start\-anchor" "Begin a section of anchored variable\-width text" .It \&] "stop\-anchor " "End a section of anchored variable\-width text" .El .Bd -literal -offset indent EXAMPLE: xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\\n", free_blocks); .Ed .Pp When a role is not provided, the "value" role is used as the default. .Pp Roles and modifiers can also use more verbose names, when preceded by a comma: .Bd -literal -offset indent EXAMPLE: xo_emit("{,label:Free}{,decoration::}{,padding: }" "{,value:free/%u} {,units:Blocks}\\n", free_blocks); .Ed .Ss "The Color Role ({C:})" Colors and effects control how text values are displayed; they are used for display styles (TEXT and HTML). .Bd -literal -offset indent xo_emit("{C:bold}{:value}{C:no\-bold}\\n", value); .Ed .Pp Colors and effects remain in effect until modified by other "C"\-role fields. .Bd -literal -offset indent xo_emit("{C:bold}{C:inverse}both{C:no\-bold}only inverse\\n"); .Ed .Pp If the content is empty, the "reset" action is performed. .Bd -literal -offset indent xo_emit("{C:both,underline}{:value}{C:}\\n", value); .Ed .Pp The content should be a comma\-separated list of zero or more colors or display effects. .Bd -literal -offset indent xo_emit("{C:bold,underline,inverse}All three{C:no\-bold,no\-inverse}\\n"); .Ed .Pp 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 ("/"): .Bd -literal -offset indent xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "", need_underline ? "underline" : "", value); .Ed .Pp Color names are prefixed with either "fg\-" or "bg\-" to change the foreground and background colors, respectively. .Bd -literal -offset indent xo_emit("{C:/fg\-%s,bg\-%s}{Lwc:Cost}{:cost/%u}{C:reset}\\n", fg_color, bg_color, cost); .Ed .Pp The following table lists the supported effects: .Bl -column "no\-underline" .It Sy "Name " "Description" .It "bg\-xxxxx " "Change background color" .It "bold " "Start bold text effect" .It "fg\-xxxxx " "Change foreground color" .It "inverse " "Start inverse (aka reverse) text effect" .It "no\-bold " "Stop bold text effect" .It "no\-inverse " "Stop inverse (aka reverse) text effect" .It "no\-underline " "Stop underline text effect" .It "normal " "Reset effects (only)" .It "reset " "Reset colors and effects (restore defaults)" .It "underline " "Start underline text effect" .El .Pp The following color names are supported: .Bl -column "no\-underline" .It Sy "Name" .It black .It blue .It cyan .It default .It green .It magenta .It red .It white .It yellow .El .Ss "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. .Bd -literal -offset indent xo_emit("{D:((}{:name}{D:))}\\n", name); .Ed .Ss "The Gettext Role ({G:})" .Nm libxo supports internationalization (i18n) through its use of .Xr gettext 3 . Use the "{G:}" role to request that the remaining part of the format string, following the "{G:}" field, be handled using .Fn gettext . Since .Fn gettext uses the string as the key into the message catalog, .Nm 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. .Pp The simplified version can be generated for a single message using the "xopo \-s " command, or an entire .pot can be translated using the "xopo \-f \-o " command. .Bd -literal -offset indent xo_emit("{G:}Invalid token\\n"); .Ed .Pp The {G:} role allows a domain name to be set. .Fn 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\(aqs 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. .Bd -literal -offset indent xo_emit("{G:libc}Service unavailable in restricted mode\\n"); .Ed .Ss "The Label Role ({L:})" Labels are text that appears before a value. .Bd -literal -offset indent xo_emit("{Lwc:Cost}{:cost/%u}\\n", cost); .Ed +.Pp +If a label needs to include a slash, it must be escaped using two +backslashes, one for the C compiler and one for +.Nm libxo . +.Bd -literal -offset indent + xo_emit("{Lc:Low\\\\/warn level}{:level/%s}\\n", level); +.Ed .Ss "The Note Role ({N:})" Notes are text that appears after a value. .Bd -literal -offset indent xo_emit("{:cost/%u} {N:per year}\\n", cost); .Ed .Ss "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 ("/"): .Bd -literal -offset indent xo_emit("{P: }{Lwc:Cost}{:cost/%u}\\n", cost); xo_emit("{P:/30s}{Lwc:Cost}{:cost/%u}\\n", "", cost); .Ed .Ss "The Title Role ({T:})" Titles 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 ("/"): .Bd -literal -offset indent xo_emit("{T:Interface Statistics}\\n"); xo_emit("{T:/%20.20s}{T:/%6.6s}\\n", "Item Name", "Cost"); .Ed .Ss "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. .Bd -literal -offset indent xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\\n", miles); .Ed .Pp Note that the sense of the \(aqw\(aq modifier is reversed for units; a blank is added before the contents, rather than after it. .Pp When the .Dv XOF_UNITS flag is set, units are rendered in XML as the .Dq units attribute: .Bd -literal -offset indent 50 .Ed .Pp Units can also be rendered in HTML as the "data\-units" attribute: .Bd -literal -offset indent
50
.Ed .Ss "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". .Bd -literal -offset indent 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); .Ed .Ss "The Anchor Roles ({[:} and {]:})" The anchor roles allow a set of strings by be padded as a group, but still be visible to .Xr xo_emit 3 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. .Pp To give a width directly, encode it as the content of the anchor tag: .Bd -literal -offset indent xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\\n", min, max); .Ed .Pp 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. .Bd -literal -offset indent xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\\n", width, min, max); .Ed .Pp 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. .Pp Widths over 8k are considered probable errors and not supported. If .Dv XOF_WARN is set, a warning will be generated. .Ss "Field Modifiers" Field modifiers are flags which modify the way content emitted for particular output styles: .Bl -column M "Name123456789" .It Sy M "Name " "Description" .It a "argument " "The content appears as a ""const char *"" argument" .It c "colon " "A colon ("":"") is appended after the label" .It d "display " "Only emit field for display styles (text/HTML)" .It e "encoding " "Only emit for encoding styles (XML/JSON)" .It h "humanize (hn) " "Format large numbers in human\-readable style" .It " " "hn\-space " "Humanize: Place space between numeric and unit" .It " " "hn\-decimal " "Humanize: Add a decimal digit, if number < 10" .It " " "hn\-1000 " "Humanize: Use 1000 as divisor instead of 1024" .It k "key " "Field is a key, suitable for XPath predicates" .It l "leaf\-list " "Field is a leaf\-list, a list of leaf values" .It n "no\-quotes " "Do not quote the field when using JSON style" .It q "quotes " "Quote the field when using JSON style" .It t "trim " "Trim leading and trailing whitespace" .It w "white space " "A blank ("" "") is appended after the label" .El .Pp For example, the modifier string "Lwc" means the field has a label role (text that describes the next field) and should be followed by a colon (\(aqc\(aq) and a space (\(aqw\(aq). The modifier string "Vkq" means the field has a value role, that it is a key for the current instance, and that the value should be quoted when encoded for JSON. .Pp 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 (\(aqc\(aq) and a space (\(aqw\(aq). 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. .Ss "The Argument Modifier ({a:})" 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. .Bd -literal -offset indent EXAMPLE: xo_emit("{La:} {a:}\\n", "Label text", "label", "value"); TEXT: Label text value JSON: "label": "value" XML: .Ed .Pp The argument modifier allows field names for value fields to be passed on the stack, avoiding the need to build a field descriptor using .Xr snprintf 1 . For many field roles, the argument modifier is not needed, since those roles have specific mechanisms for arguments, such as "{C:fg\-%s}". .Ss "The Colon Modifier ({c:})" The colon modifier appends a single colon to the data value: .Bd -literal -offset indent EXAMPLE: xo_emit("{Lc:Name}{:name}\\n", "phil"); TEXT: Name:phil .Ed .Pp The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier (\(aq{w:}\(aq). It is purely a convenience feature. .Ss "The Display Modifier ({d:})" The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML. .Bd -literal -offset indent EXAMPLE: xo_emit("{Lcw:Name}{d:name} {:id/%d}\\n", "phil", 1); TEXT: Name: phil 1 XML: 1 .Ed .Pp The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data. .Ss "The Encoding Modifier ({e:})" The encoding modifier indicated the field should only be generated for the encoding output styles, such as JSON and XML. .Bd -literal -offset indent EXAMPLE: xo_emit("{Lcw:Name}{:name} {e:id/%d}\\n", "phil", 1); TEXT: Name: phil XML: phil1 .Ed .Pp The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data. .Ss "The Humanize Modifier ({h:})" 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. .Pp "hn" can be used as an alias for "humanize". .Pp The humanize modifier only affects display styles (TEXT and HMTL). The "no\-humanize" option will block the function of the humanize modifier. .Pp 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. .Bd -literal -offset indent 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 .Ed .Pp In the HTML style, the original numeric value is rendered in the "data\-number" attribute on the
element: .Bd -literal -offset indent
96M
.Ed .Ss "The Gettext Modifier ({g:})" 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 .Xr gettext 3 , where it is used as a key to find the native language translation. .Pp In the following example, the strings "State" and "full" are passed to .Fn gettext to find locale\-based translated strings. .Bd -literal -offset indent xo_emit("{Lgwc:State}{g:state}\\n", "full"); .Ed .Ss "The Key Modifier ({k:})" The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data. .Bd -literal -offset indent 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"); .Ed .Pp Currently the key modifier is only used when generating XPath values for the HTML output style when .Dv XOF_XPATH is set, but other uses are likely in the near future. .Ss "The Leaf\-List Modifier ({l:})" The leaf\-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays. .Bd -literal -offset indent EXAMPLE: xo_open_list("user"); for (i = 0; i < num_users; i++) { xo_emit("Member {l:name}\\n", user[i].u_name); } xo_close_list("user"); XML: phil pallavi JSON: "user": [ "phil", "pallavi" ] .Ed .Ss "The No\-Quotes Modifier ({n:})" The no\-quotes modifier (and its twin, the \(aqquotes\(aq modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string values, but no quotes for numeric, boolean, and null data. .Xr xo_emit 3 applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller. .Bd -literal -offset indent EXAMPLE: const char *bool = is_true ? "true" : "false"; xo_emit("{n:fancy/%s}", bool); JSON: "fancy": true .Ed .Ss "The Plural Modifier ({p:})" 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: .Bd -literal -offset indent xo_emit("{:bytes} {Ngp:byte,bytes}\\n", bytes); .Ed .Pp The plural modifier is meant to work with the gettext modifier ({g:}) but can work independently. .Pp 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. .Pp When used with the gettext modifier, the .Xr 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. .Ss "The Quotes Modifier ({q:})" The quotes modifier (and its twin, the \(aqno-quotes\(aq modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string values, but no quotes for numeric, boolean, and null data. .Xr xo_emit 3 applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller. .Bd -literal -offset indent EXAMPLE: xo_emit("{q:time/%d}", 2014); JSON: "year": "2014" .Ed .Ss "The White Space Modifier ({w:})" The white space modifier appends a single space to the data value: .Bd -literal -offset indent EXAMPLE: xo_emit("{Lw:Name}{:name}\\n", "phil"); TEXT: Name phil .Ed .Pp The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier (\(aq{c:}\(aq). It is purely a convenience feature. .Pp Note that the sense of the \(aqw\(aq modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it. .Ss "Field Formatting" The field format is similar to the format string for .Xr printf 3 . Its use varies based on the role of the field, but generally is used to format the field\(aqs contents. .Pp If the format string is not provided for a value field, it defaults to "%s". .Pp Note a field definition can contain zero or more printf\-style .Dq directives , which are sequences that start with a \(aq%\(aq and end with one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive is matched by one of more arguments to the .Xr xo_emit 3 function. .Pp The format string has the form: .Bd -literal -offset indent \(aq%\(aq format\-modifier * format\-character .Ed .Pp The format\-modifier can be: .Bl -bullet .It a \(aq#\(aq character, indicating the output value should be prefixed with "0x", typically to indicate a base 16 (hex) value. .It a minus sign (\(aq\-\(aq), indicating the output value should be padded on the right instead of the left. .It a leading zero (\(aq0\(aq) indicating the output value should be padded on the left with zeroes instead of spaces (\(aq \(aq). .It one or more digits (\(aq0\(aq \- \(aq9\(aq) 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. .It 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. .Xr xo_emit 3 will never dereference memory beyond the given number of bytes. .It 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. .It one or more \(aqh\(aq characters, indicating shorter input data. .It one or more \(aql\(aq characters, indicating longer input data. .It a \(aqz\(aq character, indicating a \(aqsize_t\(aq argument. .It a \(aqt\(aq character, indicating a \(aqptrdiff_t\(aq argument. .It a \(aq \(aq character, indicating a space should be emitted before positive numbers. .It a \(aq+\(aq character, indicating sign should emitted before any number. .El .Pp Note that \(aqq\(aq, \(aqD\(aq, \(aqO\(aq, and \(aqU\(aq are considered deprecated and will be removed eventually. .Pp The format character is described in the following table: .Bl -column C "Argument Type12" .It Sy "C" "Argument Type " "Format" .It d "int " "base 10 (decimal)" .It i "int " "base 10 (decimal)" .It o "int " "base 8 (octal)" .It u "unsigned " "base 10 (decimal)" .It x "unsigned " "base 16 (hex)" .It X "unsigned long " "base 16 (hex)" .It D "long " "base 10 (decimal)" .It O "unsigned long " "base 8 (octal)" .It U "unsigned long " "base 10 (decimal)" .It e "double " "[\-]d.ddde+\-dd" .It E "double " "[\-]d.dddE+\-dd" .It f "double " "[\-]ddd.ddd" .It F "double " "[\-]ddd.ddd" .It g "double " "as \(aqe\(aq or \(aqf\(aq" .It G "double " "as \(aqE\(aq or \(aqF\(aq" .It a "double " "[\-]0xh.hhhp[+\-]d" .It A "double " "[\-]0Xh.hhhp[+\-]d" .It c "unsigned char " "a character" .It C "wint_t " "a character" .It s "char * " "a UTF\-8 string" .It S "wchar_t * " "a unicode/WCS string" .It p "void * " "\(aq%#lx\(aq" .El .Pp The \(aqh\(aq and \(aql\(aq modifiers affect the size and treatment of the argument: .Bl -column "Mod" "d, i " "o, u, x, X " .It Sy "Mod" "d, i " "o, u, x, X" .It "hh " "signed char " "unsigned char" .It "h " "short " "unsigned short" .It "l " "long " "unsigned long" .It "ll " "long long " "unsigned long long" .It "j " "intmax_t " "uintmax_t" .It "t " "ptrdiff_t " "ptrdiff_t" .It "z " "size_t " "size_t" .It "q " "quad_t " "u_quad_t" .El .Ss "UTF\-8 and Locale Strings" All strings for .Nm libxo must be UTF\-8. .Nm libxo will handle turning them into locale\-based strings for display to the user. .Pp For strings, the \(aqh\(aq and \(aql\(aq modifiers affect the interpretation of the bytes pointed to argument. The default \(aq%s\(aq string is a \(aqchar *\(aq pointer to a string encoded as UTF\-8. Since UTF\-8 is compatible with .Em ASCII data, a normal 7\-bit .Em ASCII string can be used. "%ls" expects a "wchar_t *" pointer to a wide\-character string, encoded as 32\-bit Unicode values. "%hs" expects a "char *" pointer to a multi\-byte string encoded with the current locale, as given by the .Ev LC_CTYPE , .Ev LANG , or .Ev LC_ALL environment variables. The first of this list of variables is used and if none of the variables are set, the locale defaults to .Em UTF\-8 . .Pp .Nm 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. .Bd -literal -offset indent xo_emit("All strings are utf\-8 content {:tag/%ls}", L"except for wide strings"); .Ed .Pp "%S" is equivalent to "%ls". .Pp For example, a function is passed a locale\-base name, a hat size, and a time value. The hat size is formatted in a UTF\-8 (ASCII) string, and the time value is formatted into a wchar_t string. .Bd -literal -offset indent 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); } .Ed .Pp It is important to note that .Xr xo_emit 3 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. .Pp 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. .Xr xo_emit 3 uses the precision as the former, and adds a third value for specifying the maximum number of columns. .Pp In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes are in used in filling those columns. .Bd -literal -offset indent xo_emit("{:name/%3.10.6s}", name); .Ed .Ss "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". .Bd -literal -offset indent 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
.
.Ed .Ss "\(aq%n\(aq is Not Supported" .Nm libxo does not support the \(aq%n\(aq directive. It is a bad idea and we just do not do it. .Ss "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". .Sh EXAMPLE In this example, the value for the number of items in stock is emitted: .Bd -literal -offset indent xo_emit("{P: }{Lwc:In stock}{:in\-stock/%u}\\n", instock); .Ed .Pp This call will generate the following output: .Bd -literal -offset indent TEXT: In stock: 144 XML: 144 JSON: "in\-stock": 144, HTML:
In stock
:
144
.Ed .Pp Clearly HTML wins the verbosity award, and this output does not include .Dv XOF_XPATH or .Dv XOF_INFO data, which would expand the penultimate line to: .Bd -literal -offset indent
144
.Ed .Sh WHAT MAKES A GOOD FIELD NAME? To make useful, consistent field names, follow these guidelines: .Ss "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. .Ss "Use hyphens, not underscores" Use of hyphens is traditional in XML, and the .Dv XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens. .Ss "Use full words" Do not 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". .Ss "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". .Ss "Reuse existing field names" Nothing is worse than writing expressions like: .Bd -literal -offset indent if ($src1/process[pid == $pid]/name == $src2/proc\-table/proc/p[process\-id == $pid]/proc\-name) { ... } .Ed .Pp Find someone else who is expressing similar data and follow their fields and hierarchy. Remember the quote is not .Dq "Consistency is the hobgoblin of little minds" but .Dq "A foolish consistency is the hobgoblin of little minds" . .Ss "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 .Xr xo_attr 3 calls or "{e:}" fields to make the data useful. .Ss "Do not 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 is the difference between errors37 and errors63. .Ss "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\(aqs 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. .Pp Field names constitute the means by which client programmers interact with our system. By choosing wise names now, you are making their lives better. .Pp After using .Xr xolint 1 to find errors in your field descriptors, use .Dq "xolint \-V" to spell check your field names and to detect different names for the same data. .Dq dropped\-short and .Dq 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. .Sh SEE ALSO .Xr libxo 3 , .Xr xolint 1 , .Xr xo_emit 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_open_container.3 b/contrib/libxo/libxo/xo_open_container.3 index 7037974d2c4e..303f3f06fd02 100644 --- a/contrib/libxo/libxo/xo_open_container.3 +++ b/contrib/libxo/libxo/xo_open_container.3 @@ -1,198 +1,198 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_open_container , xo_open_container_h , xo_open_container_hd , xo_open_container_d .Nm xo_close_container , xo_close_container_h , xo_close_container_hd , xo_close_container_d .Nd open (and close) container constructs .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft xo_ssize_t .Fn xo_open_container "const char *name" .Ft xo_ssize_t .Fn xo_open_container_h "xo_handle_t *handle" "const char *name" .Ft xo_ssize_t .Fn xo_open_container_hd "xo_handle_t *handle" "const char *name" .Ft xo_ssize_t .Fn xo_open_container_d "const char *name" .Ft xo_ssize_t .Fn xo_close_container "const char *name" .Ft xo_ssize_t .Fn xo_close_container_h "xo_handle_t *handle" "const char *name" .Ft xo_ssize_t .Fn xo_close_container_hd "xo_handle_t *handle" .Ft xo_ssize_t .Fn xo_close_container_d "void" .Sh DESCRIPTION .Nm libxo represents two types of hierarchy: .Dq containers and .Dq lists . A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope. The container has no value, but serves to contain other nodes. .Pp To open a container, call .Fn xo_open_container or .Fn xo_open_container_h . The former uses the default handle and the latter accepts a specific handle. .Pp To close a level, use the .Fn xo_close_container or .Fn xo_close_container_h functions. .Pp Each open call should have a matching close call. If the .Dv XOF_WARN flag is set and the name given does not match the name of the currently open container, a warning will be generated. .Bd -literal -offset indent -compact Example: xo_open_container("top"); xo_open_container("system"); xo_emit("{:host-name/%s%s%s", hostname, domainname ? "." : "", domainname ?: ""); xo_close_container("system"); xo_close_container("top"); Sample Output: Text: my-host.example.org XML: my-host.example.org JSON: "top" : { "system" : { "host-name": "my-host.example.org" } } HTML:
my-host.example.org
.Ed .Sh EMITTING HIERARCHY To create a container, use the .Fn xo_open_container and .Fn xo_close_container set of functions. The .Fa handle parameter contains a handle such as returned by .Xr xo_create 3 or .Dv NULL to use the default handle. The .Fa name parameter gives the name of the container, encoded in .Em UTF-8 . Since .Em ASCII is a proper subset of .Em UTF-8 , traditional C strings can be used directly. .Pp The close functions with the .Dq _d suffix are used in .Dq "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by .Nm libxo to allow the caller to avoid keeping track of the open container name. .Pp Use the .Dv XOF_WARN flag to generate a warning if the name given on the close does not match the current open container. .Pp For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the .Dv XOF_XPATH flag is set. .Pp .Bd -literal -offset indent -compact EXAMPLE: xo_open_container("system"); - xo_emit("The host name is {:host-name}\n", hn); + xo_emit("The host name is {:host-name}\\n", hn); xo_close_container("system"); XML: foo .Ed .Sh DTRT MODE Some users may find tracking the names of open containers, lists, and instances inconvenient. .Nm libxo offers a .Dq "Do The Right Thing" mode, where .Nm libxo will track the names of open containers, lists, and instances so the close function can be called without a name. To enable .Em DTRT mode, turn on the .Dv XOF_DTRT flag prior to making any other .Nm libxo output. .Bd -literal -offset indent -compact xo_set_flags(NULL, XOF_DTRT); .Ed Each open and close function has a version with the suffix .Dq _d , which will close the open container, list, or instance: .Bd -literal -offset indent -compact xo_open_container("top"); ... xo_close_container_d(); .Ed Note that the .Dv XOF_WARN flag will also cause .Nm 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. .Sh SEE ALSO .Xr xo_emit 3 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_open_list.3 b/contrib/libxo/libxo/xo_open_list.3 index f28c9b63ac35..e61e15939c87 100644 --- a/contrib/libxo/libxo/xo_open_list.3 +++ b/contrib/libxo/libxo/xo_open_list.3 @@ -1,168 +1,168 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_open_list , xo_open_list_h , xo_open_list_hd , xo_open_list_d .Nm xo_open_instance , xo_open_instance_h , xo_open_instance_hd , xo_open_instance_d .Nm xo_close_instance , xo_close_instance_h , xo_close_instance_hd , xo_close_instance_d .Nm xo_close_list , xo_close_list_h , xo_close_list_hd , xo_close_list_d .Nd open and close lists and instances .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft xo_ssize_t .Fn xo_open_list_h "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_open_list "const char *name" .Ft xo_ssize_t .Fn xo_open_list_hd "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_open_list_d "const char *name" .Ft xo_ssize_t .Fn xo_open_instance_h "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_open_instance "const char *name" .Ft xo_ssize_t .Fn xo_open_instance_hd "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_open_instance_d "const char *name" .Ft xo_ssize_t .Fn xo_close_instance_h "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_close_instance "const char *name" .Ft xo_ssize_t .Fn xo_close_instance_hd "xo_handle_t *xop" .Ft xo_ssize_t .Fn xo_close_instance_d "void" .Ft xo_ssize_t .Fn xo_close_list_h "xo_handle_t *xop" "const char *name" .Ft xo_ssize_t .Fn xo_close_list "const char *name" .Ft xo_ssize_t .Fn xo_close_list_hd "xo_handle_t *xop" .Ft xo_ssize_t .Fn xo_close_list_d "void" .Sh DESCRIPTION Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance. .Pp 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. .Pp A list is a 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: .Bd -literal -offset indent -compact 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_emit("{L:Item} '{:name/%s}':\\n", ip->i_title); xo_close_instance("item"); } xo_close_list("item"); .Ed Getting the list and instance calls correct is critical to the proper generation of XML and JSON data. .Pp .Bd -literal -offset indent -compact 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", + 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", } ] .Ed .Pp .Sh LEAF LISTS In contrast to a list of instances, a "leaf list" is list of simple values. To emit a leaf list, call the .Fn xo_emit function using the ""l"" modifier: .Bd -literal -offset indent -compact for (ip = list; ip->i_title; ip++) { - xo_emit("{Lwc:Item}{l:item}\n", ip->i_title); + xo_emit("{Lwc:Item}{l:item}\\n", ip->i_title); } .Ed .Pp The name of the field must match the name of the leaf list. .Pp In JSON, leaf lists are rendered as arrays of values. In XML, they are rendered as multiple leaf elements. .Bd -literal -offset indent -compact JSON: "item": "hammer", "nail" XML: hammer nail .Ed .Sh SEE ALSO .Xr xo_emit 3 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/libxo/xo_parse_args.3 b/contrib/libxo/libxo/xo_parse_args.3 index b014e608a0d3..e631af639e07 100644 --- a/contrib/libxo/libxo/xo_parse_args.3 +++ b/contrib/libxo/libxo/xo_parse_args.3 @@ -1,162 +1,80 @@ .\" # .\" # 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 .\" -.Dd December 4, 2014 +.Dd November 17, 2020 .Dt LIBXO 3 .Os .Sh NAME .Nm xo_parse_args , xo_set_program .Nd detect, parse, and remove arguments for libxo .Sh LIBRARY .Lb libxo .Sh SYNOPSIS .In libxo/xo.h .Ft int .Fn xo_parse_args "int argc" "char **argv" .Ft int .Fn xo_set_program "const char *name" .Sh DESCRIPTION The .Fn xo_parse_args -function is used to process command-line arguments. +function is used to process command-line arguments, which are +described in +.Xr xo_options 7 . .Nm libxo specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned. .Bd -literal -offset indent argc = xo_parse_args(argc, argv); if (argc < 0) exit(EXIT_FAILURE); .Ed .Pp Following the call to .Fn xo_parse_args , the application can process the remaining arguments in a normal manner. .Pp -.Nm libxo -uses command line options to trigger rendering behavior. -The following options are recognised: -.Pp -.Bl -tag -width "--libxo" -.It -\-\^\-libxo -.It -\-\^\-libxo= -.It -\-\^\-libxo: -.El -.Pp -Options is a comma-separated list of tokens that correspond to output -styles, flags, or features: -.Pp -.Bl -tag -width "12345678" -.It Sy "Token Action" -.It Dv dtrt -Enable "Do The Right Thing" mode -.It Dv html -Emit HTML output -.It Dv indent=xx -Set the indentation level -.It Dv info -Add info attributes (HTML) -.It Dv json -Emit JSON output -.It Dv keys -Emit the key attribute for keys (XML) -.It Dv log-gettext -Log (via stderr) each -.Xr gettext 3 -string lookup -.It Dv log-syslog -Log (via stderr) each syslog message (via -.Xr xo_syslog 3 ) -.If Dv no-humanize -Ignore the {h:} modifier (TEXT, HTML) -.It Dv no-locale -Do not initialize the locale setting -.It Dv no-retain -Prevent retaining formatting information -.It Dv no-top -Do not emit a top set of braces (JSON) -.It Dv not-first -Pretend the 1st output item was not 1st (JSON) -.It Dv pretty -Emit pretty-printed output -.It Dv retain -Force retaining formatting information -.It Dv text -Emit TEXT output -.If Dv underscores -Replace XML-friendly "-"s with JSON friendly "_"s e -.It Dv units -Add the 'units' (XML) or 'data-units (HTML) attribute -.It Dv warn -Emit warnings when libxo detects bad calls -.It Dv warn-xml -Emit warnings in XML -.It Dv xml -Emit XML output -.It Dv xpath -Add XPath expressions (HTML) -.El -.Pp -The -.Dq brief-options -are single letter commands, designed for those with -too little patience to use real tokens. -No comma separator is used. -.Bl -column "i" -.It Sy "Token Action" -.It "H " "Enable HTML output (XO_STYLE_HTML)" -.It "I " "Enable info output (XOF_INFO)" -.It "i " "Indent by " -.It "J " "Enable JSON output (XO_STYLE_JSON)" -.It "P " "Enable pretty-printed output (XOF_PRETTY)" -.It "T " "Enable text output (XO_STYLE_TEXT)" -.It "W " "Enable warnings (XOF_WARN)" -.It "X " "Enable XML output (XO_STYLE_XML)" -.It "x " "Enable XPath data (XOF_XPATH)" -.El -.Pp The .Fn xo_set_program function sets name of the program as reported by functions like .Fn xo_failure , .Fn xo_warn , .Fn xo_err , etc. The program name is initialized by .Fn xo_parse_args , but subsequent calls to .Fn xo_set_program can override this value. .Pp Note that the value is not copied, so the memory passed to .Fn xo_set_program (and .Fn xo_parse_args ) must be maintained by the caller. .Pp .Sh SEE ALSO .Xr xo_emit 3 , +.Xr xo_options 7, .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/tests/core/Makefile.am b/contrib/libxo/tests/core/Makefile.am index a1dad2cc96a2..1e7010711757 100644 --- a/contrib/libxo/tests/core/Makefile.am +++ b/contrib/libxo/tests/core/Makefile.am @@ -1,148 +1,156 @@ # # $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. AM_CFLAGS = -I${top_srcdir} -I${top_srcdir}/libxo # Ick: maintained by hand! TEST_CASES = \ test_01.c \ test_02.c \ test_03.c \ test_04.c \ test_05.c \ test_06.c \ test_07.c \ test_08.c \ test_09.c \ test_10.c \ test_11.c \ test_12.c test_01_test_SOURCES = test_01.c test_02_test_SOURCES = test_02.c test_03_test_SOURCES = test_03.c test_04_test_SOURCES = test_04.c test_05_test_SOURCES = test_05.c test_06_test_SOURCES = test_06.c test_07_test_SOURCES = test_07.c test_08_test_SOURCES = test_08.c test_09_test_SOURCES = test_09.c test_10_test_SOURCES = test_10.c test_11_test_SOURCES = test_11.c test_12_test_SOURCES = test_12.c # TEST_CASES := $(shell cd ${srcdir} ; echo *.c ) noinst_PROGRAMS = ${TEST_CASES:.c=.test} LDADD = \ ${top_builddir}/libxo/libxo.la if HAVE_HUMANIZE_NUMBER LDADD += -lutil endif EXTRA_DIST = \ ${TEST_CASES} \ - ${addprefix saved/, ${TEST_CASES:.c=.T.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.T.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.XP.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.XP.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.JP.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.JP.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.HP.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.HP.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.X.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.X.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.J.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.J.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.E.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.E.out}} \ ${addprefix saved/, ${TEST_CASES:.c=.H.err}} \ ${addprefix saved/, ${TEST_CASES:.c=.H.out}} \ ${addprefix saved/, ${TEST_CASES:.c=.HIPx.err}} \ ${addprefix saved/, ${TEST_CASES:.c=.HIPx.out}} \ - ${addprefix saved/, ${TEST_CASES:.c=.E.err}} \ - ${addprefix saved/, ${TEST_CASES:.c=.E.out}} + ${addprefix saved/, ${TEST_CASES:.c=.HP.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.HP.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.J.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.J.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.JP.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.JP.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.JPu.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.JPu.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.T.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.T.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.X.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.X.out}} \ + ${addprefix saved/, ${TEST_CASES:.c=.XP.err}} \ + ${addprefix saved/, ${TEST_CASES:.c=.XP.out}} \ + ${addprefix saved/, test_01.Ecsv1.out} \ + ${addprefix saved/, test_01.Ecsv1.err} \ + ${addprefix saved/, test_01.Ecsv2.out} \ + ${addprefix saved/, test_01.Ecsv2.err} \ + ${addprefix saved/, test_01.Ecsv3.out} \ + ${addprefix saved/, test_01.Ecsv3.err} S2O = | ${SED} '1,/@@/d' all: valgrind: @echo '## Running the regression tests under Valgrind' ${MAKE} CHECKER='valgrind -q' tests #TEST_TRACE = set -x ; TEST_JIG = \ ${CHECKER} ./$$base.test --libxo$$xoopts ${TEST_OPTS} \ > out/$$base.$$fmt.out 2> out/$$base.$$fmt.err ; \ ${DIFF} -Nu ${srcdir}/saved/$$base.$$fmt.out out/$$base.$$fmt.out ${S2O} ; \ ${DIFF} -Nu ${srcdir}/saved/$$base.$$fmt.err out/$$base.$$fmt.err ${S2O} TEST_JIG2 = \ echo "... $$test ... $$fmt ..."; \ xoopts==warn,$$csv ; \ ${TEST_JIG}; true; -TEST_FORMATS = T XP JP HP X J H HIPx +TEST_FORMATS = T XP JP JPu HP X J H HIPx test tests: ${bin_PROGRAMS} @${MKDIR} -p out -@ ${TEST_TRACE} (for test in ${TEST_CASES} ; do \ base=`${BASENAME} $$test .c` ; \ (for fmt in ${TEST_FORMATS}; do \ echo "... $$test ... $$fmt ..."; \ xoopts=:W$$fmt ; \ ${TEST_JIG}; \ true; \ done) ; \ (for fmt in E; do \ echo "... $$test ... $$fmt ..."; \ xoopts==warn,encoder=test ; \ ${TEST_JIG}; \ true; \ done) \ done) -@ (${TEST_TRACE} test=test_01.c; base=test_01; \ ( fmt=Ecsv1; csv=encoder=csv ; \ ${TEST_JIG2} ); \ - ( fmt=Ecsv2; csv=encoder=csv:path=top/data/item:no-header ; \ + ( fmt=Ecsv2; csv=encoder=csv:path=top-level/data/item:no-header ; \ ${TEST_JIG2} ); \ ( fmt=Ecsv3; csv=@csv:path=item:leafs=sku.sold:no-quotes ; \ ${TEST_JIG2} ); \ ) one: -@(test=${TEST_CASE}; data=${TEST_DATA}; ${TEST_ONE} ; true) accept: -@(for test in ${TEST_CASES} ; do \ base=`${BASENAME} $$test .c` ; \ (for fmt in ${TEST_FORMATS} E ; do \ echo "... $$test ... $$fmt ..."; \ ${CP} out/$$base.$$fmt.out ${srcdir}/saved/$$base.$$fmt.out ; \ ${CP} out/$$base.$$fmt.err ${srcdir}/saved/$$base.$$fmt.err ; \ done) \ done) -@(test=test_01.c; base=test_01; for fmt in Ecsv1 Ecsv2 Ecsv3 ; do \ echo "... $$test ... $$fmt ..."; \ ${CP} out/$$base.$$fmt.out ${srcdir}/saved/$$base.$$fmt.out ; \ ${CP} out/$$base.$$fmt.err ${srcdir}/saved/$$base.$$fmt.err ; \ done) .c.test: $(AM_V_CC)$(LTCOMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -o $@ $< CLEANFILES = ${TEST_CASES:.c=.test} CLEANDIRS = out clean-local: rm -rf ${CLEANDIRS} diff --git a/contrib/libxo/tests/core/saved/test_01.E.out b/contrib/libxo/tests/core/saved/test_01.E.out index ba0636345851..506bfa83526f 100644 --- a/contrib/libxo/tests/core/saved/test_01.E.out +++ b/contrib/libxo/tests/core/saved/test_01.E.out @@ -1,202 +1,206 @@ op create: [test] [] [0] -op open_container: [top] [] [0x810] +op open_container: [top-level] [] [0x810] op string: [type] [ethernet] [0] op content: [type] [bridge] [0] op content: [type] [18u] [0] op content: [type] [24] [0] op content: [address] [0x0] [0] op content: [port] [1] [0] op content: [address] [0x0] [0] op content: [port] [1] [0] op content: [address] [0x0] [0] op content: [port] [1] [0] op content: [used-percent] [12] [0] op content: [kve_start] [0xdeadbeef] [0x8] op content: [kve_end] [0xcabb1e] [0x8] op string: [host] [my-box] [0x200000] op string: [domain] [example.com] [0x200000] op string: [host] [my-box] [0x200008] op string: [domain] [example.com] [0x200000] op string: [label] [value] [0x200000] op string: [max-chaos] [very] [0x1000] op content: [min-chaos] [42] [0] op string: [some-chaos] [[42]] [0] +op attr: [test-attr] [attr-value] [0] +op open_leaf_list: [sku] [] [0] +op string: [sku] [gum-000-1412] [0x2010] +op close_leaf_list: [sku] [] [0] op string: [host] [my-box] [0] op string: [domain] [example.com] [0] op attr: [test] [value] [0] op open_container: [data] [] [0x810] op open_list: [item] [] [0] op attr: [test2] [value2] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [GRO-000-415] [0x98] op string: [name] [gum] [0x80] op content: [sold] [1412] [0x20] op content: [in-stock] [54] [0] op content: [on-order] [10] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-212] [0x98] op string: [name] [rope] [0x80] op content: [sold] [85] [0x20] op content: [in-stock] [4] [0] op content: [on-order] [2] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-517] [0x98] op string: [name] [ladder] [0x80] op content: [sold] [0] [0x20] op content: [in-stock] [2] [0] op content: [on-order] [1] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-632] [0x98] op string: [name] [bolt] [0x80] op content: [sold] [4123] [0x20] op content: [in-stock] [144] [0] op content: [on-order] [42] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [GRO-000-2331] [0x98] op string: [name] [water] [0x80] op content: [sold] [17] [0x20] op content: [in-stock] [14] [0] op content: [on-order] [2] [0] op close_instance: [item] [] [0] op close_list: [item] [] [0] op close_container: [data] [] [0] op open_container: [data2] [] [0x810] op open_list: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [GRO-000-415] [0x98] op string: [name] [gum] [0x80] op content: [sold] [1412.0] [0x20] op content: [in-stock] [54] [0] op content: [on-order] [10] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [HRD-000-212] [0x98] op string: [name] [rope] [0x80] op content: [sold] [85.0] [0x20] op content: [in-stock] [4] [0] op content: [on-order] [2] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [HRD-000-517] [0x98] op string: [name] [ladder] [0x80] op content: [sold] [0] [0x20] op content: [in-stock] [2] [0] op content: [on-order] [1] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [HRD-000-632] [0x98] op string: [name] [bolt] [0x80] op content: [sold] [4123.0] [0x20] op content: [in-stock] [144] [0] op content: [on-order] [42] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [GRO-000-2331] [0x98] op string: [name] [water] [0x80] op content: [sold] [17.0] [0x20] op content: [in-stock] [14] [0] op content: [on-order] [2] [0] op close_instance: [item] [] [0] op close_list: [item] [] [0] op close_container: [data2] [] [0] op open_container: [data3] [] [0x810] op open_list: [item] [] [0] op open_instance: [item] [] [0x810] op string: [sku] [GRO-000-533] [0x98] op string: [name] [fish] [0x80] op content: [sold] [1321.0] [0x20] op content: [in-stock] [45] [0] op content: [on-order] [1] [0] op close_instance: [item] [] [0] op close_list: [item] [] [0] op close_container: [data3] [] [0] op open_container: [data4] [] [0x810] op open_list: [item] [] [0] op attr: [test4] [value4] [0] op string: [item] [gum] [0x2000] op attr: [test4] [value4] [0] op string: [item] [rope] [0x2000] op attr: [test4] [value4] [0] op string: [item] [ladder] [0x2000] op attr: [test4] [value4] [0] op string: [item] [bolt] [0x2000] op attr: [test4] [value4] [0] op string: [item] [water] [0x2000] op close_list: [item] [] [0] op close_container: [data4] [] [0] op attr: [test] [value] [0] op open_container: [data] [] [0x810] op open_list: [item] [] [0] op attr: [test2] [value2] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [GRO-000-415] [0x98] op string: [name] [gum] [0x80] op content: [sold] [1412] [0x20] op content: [on-order] [10] [0] op content: [in-stock] [54] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-212] [0x98] op string: [name] [rope] [0x80] op content: [sold] [85] [0x20] op string: [extra] [special] [0] op content: [on-order] [2] [0] op content: [in-stock] [4] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-517] [0x98] op string: [name] [ladder] [0x80] op content: [sold] [0] [0x20] op string: [extra] [special] [0] op content: [on-order] [1] [0] op content: [in-stock] [2] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [HRD-000-632] [0x98] op string: [name] [bolt] [0x80] op content: [sold] [4123] [0x20] op content: [on-order] [42] [0] op content: [in-stock] [144] [0] op close_instance: [item] [] [0] op open_instance: [item] [] [0x810] op attr: [test3] [value3] [0] op string: [sku] [GRO-000-2331] [0x98] op string: [name] [water] [0x80] op content: [sold] [17] [0x20] op string: [extra] [special] [0] op content: [on-order] [2] [0] op content: [in-stock] [14] [0] op close_instance: [item] [] [0] op close_list: [item] [] [0] op close_container: [data] [] [0] op content: [cost] [425] [0] op content: [cost] [455] [0] op string: [mode] [mode] [0x8] op string: [mode_octal] [octal] [0x8] op string: [links] [links] [0x1000] op string: [user] [user] [0x1000] op string: [group] [group] [0x1000] op string: [pre] [that] [0x8] op content: [links] [3] [0x1000] op string: [post] [this] [0x1000] op string: [mode] [/some/file] [0x1000] op content: [mode_octal] [640] [0x8] op content: [links] [1] [0x1000] op string: [user] [user] [0x1000] op string: [group] [group] [0x1000] -op close_container: [top] [] [0] +op close_container: [top-level] [] [0] op finish: [] [] [0] op flush: [] [] [0] diff --git a/contrib/libxo/tests/core/saved/test_01.H.out b/contrib/libxo/tests/core/saved/test_01.H.out index e8ea9fe96e7d..b58816d8617f 100644 --- a/contrib/libxo/tests/core/saved/test_01.H.out +++ b/contrib/libxo/tests/core/saved/test_01.H.out @@ -1,2 +1,3 @@ -
static
ethernet
bridge
18u
24
anchor
0x0
..
1
anchor
0x0
..
1
anchor
0x0
..
1
df
12
%
testing argument modifier
my-box
.
example.com
...
testing argument modifier with encoding to
.
example.com
...
Label text
value
very
42
42 -
Connecting to
my-box
.
example.com
...
Item
Total Sold
In Stock
On Order
SKU
gum
1412
54
10
GRO-000-415
rope
85
4
2
HRD-000-212
ladder
0
2
1
HRD-000-517
bolt
4123
144
42
HRD-000-632
water
17
14
2
GRO-000-2331
Item
'
gum
':
Total sold
:
1412.0
In stock
:
54
On order
:
10
SKU
:
GRO-000-415
Item
'
rope
':
Total sold
:
85.0
In stock
:
4
On order
:
2
SKU
:
HRD-000-212
Item
'
ladder
':
Total sold
:
0
In stock
:
2
On order
:
1
SKU
:
HRD-000-517
Item
'
bolt
':
Total sold
:
4123.0
In stock
:
144
On order
:
42
SKU
:
HRD-000-632
Item
'
water
':
Total sold
:
17.0
In stock
:
14
On order
:
2
SKU
:
GRO-000-2331
Item
'
fish
':
Total sold
:
1321.0
In stock
:
45
On order
:
1
SKU
:
GRO-000-533
Item
:
gum
Item
:
rope
Item
:
ladder
Item
:
bolt
Item
:
water
Item
Total Sold
In Stock
On Order
SKU
gum
1412
10
54
GRO-000-415
rope
85
Extra:
special
2
4
HRD-000-212
ladder
0
Extra:
special
1
2
HRD-000-517
bolt
4123
42
144
HRD-000-632
water
17
Extra:
special
2
14
GRO-000-2331
X
X
X
X
X
X
X
X
X
X
Cost
:
425
X
X
Cost
:
455
links
user
group
3
this
/some/file
1
user
group
\ No newline at end of file +
static
ethernet
bridge
18u
24
anchor
0x0
..
1
anchor
0x0
..
1
anchor
0x0
..
1
df
12
%
testing argument modifier
my-box
.
example.com
...
testing argument modifier with encoding to
.
example.com
...
Label text
value
My Title +
very
42
42 +
gum-1412
Connecting to
my-box
.
example.com
...
Item
Total Sold
In Stock
On Order
SKU
gum
1412
54
10
GRO-000-415
rope
85
4
2
HRD-000-212
ladder
0
2
1
HRD-000-517
bolt
4123
144
42
HRD-000-632
water
17
14
2
GRO-000-2331
Item
'
gum
':
Total sold
:
1412.0
In stock
:
54
On order
:
10
SKU
:
GRO-000-415
Item
'
rope
':
Total sold
:
85.0
In stock
:
4
On order
:
2
SKU
:
HRD-000-212
Item
'
ladder
':
Total sold
:
0
In stock
:
2
On order
:
1
SKU
:
HRD-000-517
Item
'
bolt
':
Total sold
:
4123.0
In stock
:
144
On order
:
42
SKU
:
HRD-000-632
Item
'
water
':
Total sold
:
17.0
In stock
:
14
On order
:
2
SKU
:
GRO-000-2331
Item
'
fish
':
Total sold
:
1321.0
In stock
:
45
On order
:
1
SKU
:
GRO-000-533
Item
:
gum
Item
:
rope
Item
:
ladder
Item
:
bolt
Item
:
water
Item
Total Sold
In Stock
On Order
SKU
gum
1412
10
54
GRO-000-415
rope
85
Extra:
special
2
4
HRD-000-212
ladder
0
Extra:
special
1
2
HRD-000-517
bolt
4123
42
144
HRD-000-632
water
17
Extra:
special
2
14
GRO-000-2331
X
X
X
X
X
X
X
X
X
X
Cost
:
425
X
X
Cost
:
455
links
user
group
3
this
/some/file
1
user
group
\ No newline at end of file diff --git a/contrib/libxo/tests/core/saved/test_01.HIPx.out b/contrib/libxo/tests/core/saved/test_01.HIPx.out index fa5fd8314e7a..da30b72ab7ec 100644 --- a/contrib/libxo/tests/core/saved/test_01.HIPx.out +++ b/contrib/libxo/tests/core/saved/test_01.HIPx.out @@ -1,434 +1,437 @@
static
-
ethernet
+
ethernet
-
bridge
+
bridge
-
18u
+
18u
-
24
+
24
anchor
-
0x0
+
0x0
..
-
1
+
1
anchor
-
0x0
+
0x0
..
-
1
+
1
anchor
-
0x0
+
0x0
..
-
1
+
1
df
-
12
+
12
%
testing argument modifier
-
my-box
+
my-box
.
-
example.com
+
example.com
...
testing argument modifier with encoding to
.
-
example.com
+
example.com
...
Label text
-
value
+
value
-
very
-
42
-
42 +
My Title
+
very
+
42
+
42 +
+
gum-1412
Connecting to
-
my-box
+
my-box
.
-
example.com
+
example.com
...
Item
Total Sold
In Stock
On Order
SKU
-
gum
-
1412
-
54
-
10
-
GRO-000-415
+
gum
+
1412
+
54
+
10
+
GRO-000-415
-
rope
-
85
-
4
-
2
-
HRD-000-212
+
rope
+
85
+
4
+
2
+
HRD-000-212
-
ladder
-
0
-
2
-
1
-
HRD-000-517
+
ladder
+
0
+
2
+
1
+
HRD-000-517
-
bolt
-
4123
-
144
-
42
-
HRD-000-632
+
bolt
+
4123
+
144
+
42
+
HRD-000-632
-
water
-
17
-
14
-
2
-
GRO-000-2331
+
water
+
17
+
14
+
2
+
GRO-000-2331
Item
'
-
gum
+
gum
':
Total sold
:
-
1412.0
+
1412.0
In stock
:
-
54
+
54
On order
:
-
10
+
10
SKU
:
-
GRO-000-415
+
GRO-000-415
Item
'
-
rope
+
rope
':
Total sold
:
-
85.0
+
85.0
In stock
:
-
4
+
4
On order
:
-
2
+
2
SKU
:
-
HRD-000-212
+
HRD-000-212
Item
'
-
ladder
+
ladder
':
Total sold
:
-
0
+
0
In stock
:
-
2
+
2
On order
:
-
1
+
1
SKU
:
-
HRD-000-517
+
HRD-000-517
Item
'
-
bolt
+
bolt
':
Total sold
:
-
4123.0
+
4123.0
In stock
:
-
144
+
144
On order
:
-
42
+
42
SKU
:
-
HRD-000-632
+
HRD-000-632
Item
'
-
water
+
water
':
Total sold
:
-
17.0
+
17.0
In stock
:
-
14
+
14
On order
:
-
2
+
2
SKU
:
-
GRO-000-2331
+
GRO-000-2331
Item
'
-
fish
+
fish
':
Total sold
:
-
1321.0
+
1321.0
In stock
:
-
45
+
45
On order
:
-
1
+
1
SKU
:
-
GRO-000-533
+
GRO-000-533
Item
:
-
gum
+
gum
Item
:
-
rope
+
rope
Item
:
-
ladder
+
ladder
Item
:
-
bolt
+
bolt
Item
:
-
water
+
water
Item
Total Sold
In Stock
On Order
SKU
-
gum
-
1412
-
10
-
54
-
GRO-000-415
+
gum
+
1412
+
10
+
54
+
GRO-000-415
-
rope
-
85
+
rope
+
85
Extra:
-
special
-
2
-
4
-
HRD-000-212
+
special
+
2
+
4
+
HRD-000-212
-
ladder
-
0
+
ladder
+
0
Extra:
-
special
-
1
-
2
-
HRD-000-517
+
special
+
1
+
2
+
HRD-000-517
-
bolt
-
4123
-
42
-
144
-
HRD-000-632
+
bolt
+
4123
+
42
+
144
+
HRD-000-632
-
water
-
17
+
water
+
17
Extra:
-
special
-
2
-
14
-
GRO-000-2331
+
special
+
2
+
14
+
GRO-000-2331
X
X
X
X
X
X
X
X
X
X
Cost
:
-
425
+
425
X
X
Cost
:
-
455
+
455
-
links
+
links
-
user
+
user
-
group
+
group
-
3
-
this
+
3
+
this
-
/some/file
+
/some/file
-
1
+
1
-
user
+
user
-
group
+
group
diff --git a/contrib/libxo/tests/core/saved/test_01.HP.out b/contrib/libxo/tests/core/saved/test_01.HP.out index 9eadb4a1fd23..5a7aed05ac0b 100644 --- a/contrib/libxo/tests/core/saved/test_01.HP.out +++ b/contrib/libxo/tests/core/saved/test_01.HP.out @@ -1,434 +1,437 @@
static
ethernet
bridge
18u
24
anchor
0x0
..
1
anchor
0x0
..
1
anchor
0x0
..
1
df
12
%
testing argument modifier
my-box
.
example.com
...
testing argument modifier with encoding to
.
example.com
...
Label text
value
+
My Title +
very
42
42
+
gum-1412
Connecting to
my-box
.
example.com
...
Item
Total Sold
In Stock
On Order
SKU
gum
1412
54
10
GRO-000-415
rope
85
4
2
HRD-000-212
ladder
0
2
1
HRD-000-517
bolt
4123
144
42
HRD-000-632
water
17
14
2
GRO-000-2331
Item
'
gum
':
Total sold
:
1412.0
In stock
:
54
On order
:
10
SKU
:
GRO-000-415
Item
'
rope
':
Total sold
:
85.0
In stock
:
4
On order
:
2
SKU
:
HRD-000-212
Item
'
ladder
':
Total sold
:
0
In stock
:
2
On order
:
1
SKU
:
HRD-000-517
Item
'
bolt
':
Total sold
:
4123.0
In stock
:
144
On order
:
42
SKU
:
HRD-000-632
Item
'
water
':
Total sold
:
17.0
In stock
:
14
On order
:
2
SKU
:
GRO-000-2331
Item
'
fish
':
Total sold
:
1321.0
In stock
:
45
On order
:
1
SKU
:
GRO-000-533
Item
:
gum
Item
:
rope
Item
:
ladder
Item
:
bolt
Item
:
water
Item
Total Sold
In Stock
On Order
SKU
gum
1412
10
54
GRO-000-415
rope
85
Extra:
special
2
4
HRD-000-212
ladder
0
Extra:
special
1
2
HRD-000-517
bolt
4123
42
144
HRD-000-632
water
17
Extra:
special
2
14
GRO-000-2331
X
X
X
X
X
X
X
X
X
X
Cost
:
425
X
X
Cost
:
455
links
user
group
3
this
/some/file
1
user
group
diff --git a/contrib/libxo/tests/core/saved/test_01.J.out b/contrib/libxo/tests/core/saved/test_01.J.out index 4a3b05f967bf..b8c782677916 100644 --- a/contrib/libxo/tests/core/saved/test_01.J.out +++ b/contrib/libxo/tests/core/saved/test_01.J.out @@ -1 +1 @@ -{"top": {"type":"ethernet","type":"bridge","type":"18u","type":24,"address":"0x0","port":1,"address":"0x0","port":1,"address":"0x0","port":1,"used-percent":12,"kve_start":"0xdeadbeef","kve_end":"0xcabb1e","host":"my-box","domain":"example.com","host":"my-box","domain":"example.com","label":"value","max-chaos":"very","min-chaos":42,"some-chaos":"[42]","host":"my-box","domain":"example.com", "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17,"in-stock":14,"on-order":2}]}, "data2": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412.0,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85.0,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123.0,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17.0,"in-stock":14,"on-order":2}]}, "data3": {"item": [{"sku":"GRO-000-533","name":"fish","sold":1321.0,"in-stock":45,"on-order":1}]}, "data4": {"item": ["gum","rope","ladder","bolt","water"]}, "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"on-order":10,"in-stock":54}, {"sku":"HRD-000-212","name":"rope","sold":85,"extra":"special","on-order":2,"in-stock":4}, {"sku":"HRD-000-517","name":"ladder","sold":0,"extra":"special","on-order":1,"in-stock":2}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"on-order":42,"in-stock":144}, {"sku":"GRO-000-2331","name":"water","sold":17,"extra":"special","on-order":2,"in-stock":14}]},"cost":425,"cost":455,"mode":"mode","mode_octal":"octal","links":"links","user":"user","group":"group","pre":"that","links":3,"post":"this","mode":"/some/file","mode_octal":640,"links":1,"user":"user","group":"group"}} +{"top-level": {"type":"ethernet","type":"bridge","type":"18u","type":24,"address":"0x0","port":1,"address":"0x0","port":1,"address":"0x0","port":1,"used-percent":12,"kve_start":"0xdeadbeef","kve_end":"0xcabb1e","host":"my-box","domain":"example.com","host":"my-box","domain":"example.com","label":"value","max-chaos":"very","min-chaos":42,"some-chaos":"[42]", "sku": ["gum-000-1412"],"host":"my-box","domain":"example.com", "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17,"in-stock":14,"on-order":2}]}, "data2": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412.0,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85.0,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123.0,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17.0,"in-stock":14,"on-order":2}]}, "data3": {"item": [{"sku":"GRO-000-533","name":"fish","sold":1321.0,"in-stock":45,"on-order":1}]}, "data4": {"item": ["gum","rope","ladder","bolt","water"]}, "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"on-order":10,"in-stock":54}, {"sku":"HRD-000-212","name":"rope","sold":85,"extra":"special","on-order":2,"in-stock":4}, {"sku":"HRD-000-517","name":"ladder","sold":0,"extra":"special","on-order":1,"in-stock":2}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"on-order":42,"in-stock":144}, {"sku":"GRO-000-2331","name":"water","sold":17,"extra":"special","on-order":2,"in-stock":14}]},"cost":425,"cost":455,"mode":"mode","mode_octal":"octal","links":"links","user":"user","group":"group","pre":"that","links":3,"post":"this","mode":"/some/file","mode_octal":640,"links":1,"user":"user","group":"group"}} diff --git a/contrib/libxo/tests/core/saved/test_01.JP.out b/contrib/libxo/tests/core/saved/test_01.JP.out index 5c226354c761..71a77cea81df 100644 --- a/contrib/libxo/tests/core/saved/test_01.JP.out +++ b/contrib/libxo/tests/core/saved/test_01.JP.out @@ -1,182 +1,185 @@ { - "top": { + "top-level": { "type": "ethernet", "type": "bridge", "type": "18u", "type": 24, "address": "0x0", "port": 1, "address": "0x0", "port": 1, "address": "0x0", "port": 1, "used-percent": 12, "kve_start": "0xdeadbeef", "kve_end": "0xcabb1e", "host": "my-box", "domain": "example.com", "host": "my-box", "domain": "example.com", "label": "value", "max-chaos": "very", "min-chaos": 42, "some-chaos": "[42]", + "sku": [ + "gum-000-1412" + ], "host": "my-box", "domain": "example.com", "data": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412, "in-stock": 54, "on-order": 10 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85, "in-stock": 4, "on-order": 2 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, "in-stock": 2, "on-order": 1 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123, "in-stock": 144, "on-order": 42 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17, "in-stock": 14, "on-order": 2 } ] }, "data2": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412.0, "in-stock": 54, "on-order": 10 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85.0, "in-stock": 4, "on-order": 2 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, "in-stock": 2, "on-order": 1 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123.0, "in-stock": 144, "on-order": 42 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17.0, "in-stock": 14, "on-order": 2 } ] }, "data3": { "item": [ { "sku": "GRO-000-533", "name": "fish", "sold": 1321.0, "in-stock": 45, "on-order": 1 } ] }, "data4": { "item": [ "gum", "rope", "ladder", "bolt", "water" ] }, "data": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412, "on-order": 10, "in-stock": 54 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85, "extra": "special", "on-order": 2, "in-stock": 4 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, "extra": "special", "on-order": 1, "in-stock": 2 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123, "on-order": 42, "in-stock": 144 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17, "extra": "special", "on-order": 2, "in-stock": 14 } ] }, "cost": 425, "cost": 455, "mode": "mode", "mode_octal": "octal", "links": "links", "user": "user", "group": "group", "pre": "that", "links": 3, "post": "this", "mode": "/some/file", "mode_octal": 640, "links": 1, "user": "user", "group": "group" } } diff --git a/contrib/libxo/tests/core/saved/test_01.JPu.err b/contrib/libxo/tests/core/saved/test_01.JPu.err new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/contrib/libxo/tests/core/saved/test_01.JP.out b/contrib/libxo/tests/core/saved/test_01.JPu.out similarity index 74% copy from contrib/libxo/tests/core/saved/test_01.JP.out copy to contrib/libxo/tests/core/saved/test_01.JPu.out index 5c226354c761..747db16f07a7 100644 --- a/contrib/libxo/tests/core/saved/test_01.JP.out +++ b/contrib/libxo/tests/core/saved/test_01.JPu.out @@ -1,182 +1,185 @@ { - "top": { + "top_level": { "type": "ethernet", "type": "bridge", "type": "18u", "type": 24, "address": "0x0", "port": 1, "address": "0x0", "port": 1, "address": "0x0", "port": 1, - "used-percent": 12, + "used_percent": 12, "kve_start": "0xdeadbeef", "kve_end": "0xcabb1e", "host": "my-box", "domain": "example.com", "host": "my-box", "domain": "example.com", "label": "value", - "max-chaos": "very", - "min-chaos": 42, - "some-chaos": "[42]", + "max_chaos": "very", + "min_chaos": 42, + "some_chaos": "[42]", + "sku": [ + "gum-000-1412" + ], "host": "my-box", "domain": "example.com", "data": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412, - "in-stock": 54, - "on-order": 10 + "in_stock": 54, + "on_order": 10 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85, - "in-stock": 4, - "on-order": 2 + "in_stock": 4, + "on_order": 2 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, - "in-stock": 2, - "on-order": 1 + "in_stock": 2, + "on_order": 1 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123, - "in-stock": 144, - "on-order": 42 + "in_stock": 144, + "on_order": 42 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17, - "in-stock": 14, - "on-order": 2 + "in_stock": 14, + "on_order": 2 } ] }, "data2": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412.0, - "in-stock": 54, - "on-order": 10 + "in_stock": 54, + "on_order": 10 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85.0, - "in-stock": 4, - "on-order": 2 + "in_stock": 4, + "on_order": 2 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, - "in-stock": 2, - "on-order": 1 + "in_stock": 2, + "on_order": 1 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123.0, - "in-stock": 144, - "on-order": 42 + "in_stock": 144, + "on_order": 42 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17.0, - "in-stock": 14, - "on-order": 2 + "in_stock": 14, + "on_order": 2 } ] }, "data3": { "item": [ { "sku": "GRO-000-533", "name": "fish", "sold": 1321.0, - "in-stock": 45, - "on-order": 1 + "in_stock": 45, + "on_order": 1 } ] }, "data4": { "item": [ "gum", "rope", "ladder", "bolt", "water" ] }, "data": { "item": [ { "sku": "GRO-000-415", "name": "gum", "sold": 1412, - "on-order": 10, - "in-stock": 54 + "on_order": 10, + "in_stock": 54 }, { "sku": "HRD-000-212", "name": "rope", "sold": 85, "extra": "special", - "on-order": 2, - "in-stock": 4 + "on_order": 2, + "in_stock": 4 }, { "sku": "HRD-000-517", "name": "ladder", "sold": 0, "extra": "special", - "on-order": 1, - "in-stock": 2 + "on_order": 1, + "in_stock": 2 }, { "sku": "HRD-000-632", "name": "bolt", "sold": 4123, - "on-order": 42, - "in-stock": 144 + "on_order": 42, + "in_stock": 144 }, { "sku": "GRO-000-2331", "name": "water", "sold": 17, "extra": "special", - "on-order": 2, - "in-stock": 14 + "on_order": 2, + "in_stock": 14 } ] }, "cost": 425, "cost": 455, "mode": "mode", "mode_octal": "octal", "links": "links", "user": "user", "group": "group", "pre": "that", "links": 3, "post": "this", "mode": "/some/file", "mode_octal": 640, "links": 1, "user": "user", "group": "group" } } diff --git a/contrib/libxo/tests/core/saved/test_01.T.out b/contrib/libxo/tests/core/saved/test_01.T.out index 0b051da25fa8..89d3157336e2 100644 --- a/contrib/libxo/tests/core/saved/test_01.T.out +++ b/contrib/libxo/tests/core/saved/test_01.T.out @@ -1,66 +1,67 @@ static ethernet bridge 18u 24anchor 0x0..1 anchor 0x0..1 anchor 0x0..1 df 12% testing argument modifier my-box.example.com... testing argument modifier with encoding to .example.com... Label text value +My Title very 4242 -Connecting to my-box.example.com... +gum-1412Connecting to my-box.example.com... Item Total Sold In Stock On Order SKU gum 1412 54 10 GRO-000-415 rope 85 4 2 HRD-000-212 ladder 0 2 1 HRD-000-517 bolt 4123 144 42 HRD-000-632 water 17 14 2 GRO-000-2331 Item 'gum': Total sold: 1412.0 In stock: 54 On order: 10 SKU: GRO-000-415 Item 'rope': Total sold: 85.0 In stock: 4 On order: 2 SKU: HRD-000-212 Item 'ladder': Total sold: 0 In stock: 2 On order: 1 SKU: HRD-000-517 Item 'bolt': Total sold: 4123.0 In stock: 144 On order: 42 SKU: HRD-000-632 Item 'water': Total sold: 17.0 In stock: 14 On order: 2 SKU: GRO-000-2331 Item 'fish': Total sold: 1321.0 In stock: 45 On order: 1 SKU: GRO-000-533 Item: gum Item: rope Item: ladder Item: bolt Item: water Item Total Sold In Stock On Order SKU gum 1412 10 54 GRO-000-415 rope 85Extra: special 2 4 HRD-000-212 ladder 0Extra: special 1 2 HRD-000-517 bolt 4123 42 144 HRD-000-632 water 17Extra: special 2 14 GRO-000-2331 XXXXXXXX X XCost: 425 X XCost: 455 links user group 3 this /some/file 1 user group diff --git a/contrib/libxo/tests/core/saved/test_01.X.out b/contrib/libxo/tests/core/saved/test_01.X.out index 2ba5583fcac1..2f1fa8261702 100644 --- a/contrib/libxo/tests/core/saved/test_01.X.out +++ b/contrib/libxo/tests/core/saved/test_01.X.out @@ -1 +1 @@ -ethernetbridge18u24
0x0
1
0x0
1
0x0
1120xdeadbeef0xcabb1emy-boxexample.commy-boxexample.comvery42[42]my-boxexample.comGRO-000-415gum14125410HRD-000-212rope8542HRD-000-517ladder021HRD-000-632bolt412314442GRO-000-2331water17142GRO-000-415gum1412.05410HRD-000-212rope85.042HRD-000-517ladder021HRD-000-632bolt4123.014442GRO-000-2331water17.0142GRO-000-533fish1321.0451gumropeladderboltwaterGRO-000-415gum14121054HRD-000-212rope85special24HRD-000-517ladder0special12HRD-000-632bolt412342144GRO-000-2331water17special214425455modeoctallinksusergroup
that
3this/some/file6401usergroup \ No newline at end of file +ethernetbridge18u24
0x0
1
0x0
1
0x0
1120xdeadbeef0xcabb1emy-boxexample.commy-boxexample.comvery42[42]gum-000-1412my-boxexample.comGRO-000-415gum14125410HRD-000-212rope8542HRD-000-517ladder021HRD-000-632bolt412314442GRO-000-2331water17142GRO-000-415gum1412.05410HRD-000-212rope85.042HRD-000-517ladder021HRD-000-632bolt4123.014442GRO-000-2331water17.0142GRO-000-533fish1321.0451gumropeladderboltwaterGRO-000-415gum14121054HRD-000-212rope85special24HRD-000-517ladder0special12HRD-000-632bolt412342144GRO-000-2331water17special214425455modeoctallinksusergroup
that
3this/some/file6401usergroup \ No newline at end of file diff --git a/contrib/libxo/tests/core/saved/test_01.XP.out b/contrib/libxo/tests/core/saved/test_01.XP.out index e40055a21369..afa79ada5f81 100644 --- a/contrib/libxo/tests/core/saved/test_01.XP.out +++ b/contrib/libxo/tests/core/saved/test_01.XP.out @@ -1,170 +1,171 @@ - + ethernet bridge 18u 24
0x0
1
0x0
1
0x0
1 12 0xdeadbeef 0xcabb1e my-box example.com my-box example.com very 42 [42] + gum-000-1412 my-box example.com GRO-000-415 gum 1412 54 10 HRD-000-212 rope 85 4 2 HRD-000-517 ladder 0 2 1 HRD-000-632 bolt 4123 144 42 GRO-000-2331 water 17 14 2 GRO-000-415 gum 1412.0 54 10 HRD-000-212 rope 85.0 4 2 HRD-000-517 ladder 0 2 1 HRD-000-632 bolt 4123.0 144 42 GRO-000-2331 water 17.0 14 2 GRO-000-533 fish 1321.0 45 1 gum rope ladder bolt water GRO-000-415 gum 1412 10 54 HRD-000-212 rope 85 special 2 4 HRD-000-517 ladder 0 special 1 2 HRD-000-632 bolt 4123 42 144 GRO-000-2331 water 17 special 2 14 425 455 mode octal links user group 
that
3 this /some/file 640 1 user group - + diff --git a/contrib/libxo/tests/core/saved/test_02.E.out b/contrib/libxo/tests/core/saved/test_02.E.out index e554b30bab34..7550b680d09d 100644 --- a/contrib/libxo/tests/core/saved/test_02.E.out +++ b/contrib/libxo/tests/core/saved/test_02.E.out @@ -1,72 +1,73 @@ op create: [test] [] [0] op open_container: [top] [] [0x40010] op open_container: [data] [] [0x40010] op string: [name] [em0] [0x1080] op string: [flags] [0x8843] [0x18] op string: [name] [em0] [0x1088] op string: [flags] [0x8843] [0x18] op string: [what] [braces] [0] op string: [length] [abcdef] [0] op content: [fd] [-1] [0] op string: [error] [Bad file descriptor] [0] op string: [test] [good] [0] op content: [fd] [-1] [0] op string: [error] [Bad fi] [0] op string: [test] [good] [0] op content: [lines] [20] [0] op content: [words] [30] [0] op content: [characters] [40] [0] op open_leaf_list: [bytes] [] [0] op content: [bytes] [0] [0x2004] op content: [bytes] [1] [0x2004] op content: [bytes] [2] [0x2004] op content: [bytes] [3] [0x2004] op content: [bytes] [4] [0x2004] op close_leaf_list: [bytes] [] [0] +op content: [granularity-lw] [155] [0] op content: [mbuf-current] [10] [0] op content: [mbuf-cache] [20] [0] op content: [mbuf-total] [30] [0] op content: [distance] [50] [0] op string: [location] [Boston] [0] op content: [memory] [64] [0] op content: [total] [640] [0] op content: [memory] [64] [0] op content: [total] [640] [0] op content: [ten] [10] [0] op content: [eleven] [11] [0] op content: [unknown] [1010] [0] op content: [unknown] [1010] [0] op content: [min] [15] [0x20] op content: [cur] [20] [0x20] op content: [max] [125] [0] op content: [min] [15] [0] op content: [cur] [20] [0] op content: [max] [125] [0] op content: [min] [15] [0x20] op content: [cur] [20] [0x20] op content: [max] [125] [0x20] op content: [min] [15] [0] op content: [cur] [20] [0] op content: [max] [125] [0] op content: [val1] [21] [0x8000] op content: [val2] [58368] [0x18000] op content: [val3] [100663296] [0x28000] op content: [val4] [44470272] [0x48000] op content: [val5] [1342172800] [0x28000] op open_list: [flag] [] [0] op string: [flag] [one] [0x2010] op string: [flag] [two] [0x2010] op string: [flag] [three] [0x2010] op close_list: [flag] [] [0] op content: [works] [null] [0x20] op content: [empty-tag] [true] [0x8] op string: [t1] [1000] [0x1010] op string: [t2] [test5000] [0x1010] op string: [t3] [ten-longx] [0x1010] op string: [t4] [xtest] [0x1010] op content: [count] [10] [0] op content: [test] [4] [0] op close_container: [data] [] [0] op close_container: [top] [] [0] op finish: [] [] [0] op flush: [] [] [0] diff --git a/contrib/libxo/tests/core/saved/test_02.H.out b/contrib/libxo/tests/core/saved/test_02.H.out index a3d88030075a..03daf89ff0d2 100644 --- a/contrib/libxo/tests/core/saved/test_02.H.out +++ b/contrib/libxo/tests/core/saved/test_02.H.out @@ -1,10 +1,10 @@
em0
em0
We are
{emit}
{ting}
some
braces
abcdef
abcdef: Bad file descriptor
improper use of profanity; ten yard penalty; first down
length
abcdef
close
-1
returned
Bad file descriptor
good
close
-1
returned
Bad fi
good
improper use of profanity; ten yard penalty; first down -
20
30
40
file
0
bytes
1
byte
2
bytes
3
bytes
4
bytes
10
/
20
/
30
mbufs <&> in use (current/cache/total)
50
from
Boston
64
left out of
640
64
left out of
640
beforeworkingafter:
string
:
10
11
1010
packets here/there/everywhere
1010
packets here/there/everywhere
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
Humanize:
21
,
57 K
,
96M
,
44M
,
1.2G
one
two
three
(null)
1:
1000
2:
test5000
3:
ten-longx
4:
xtest
this is an error
two more errors
this is an warning
two more warnings
V1/V2 packets
:
10
0004
tries
improper use of profanity; ten yard penalty; first down +
20
30
40
file
0
bytes
1
byte
2
bytes
3
bytes
4
bytes
Low/warn granularity
:
155
10
/
20
/
30
mbufs <&> in use (current/cache/total)
50
from
Boston
64
left out of
640
64
left out of
640
beforeworkingafter:
string
:
10
11
1010
packets here/there/everywhere
1010
packets here/there/everywhere
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
Humanize:
21
,
57 K
,
96M
,
44M
,
1.2G
one
two
three
(null)
1:
1000
2:
test5000
3:
ten-longx
4:
xtest
this is an error
two more errors
this is an warning
two more warnings
V1/V2 packets
:
10
0004
tries
improper use of profanity; ten yard penalty; first down
Shut 'er down, Clancey! She's a-pumpin' mud! <>!,"!<>
err message (1)
err message (2)
err message (1)
err message (2)
\ No newline at end of file diff --git a/contrib/libxo/tests/core/saved/test_02.HIPx.out b/contrib/libxo/tests/core/saved/test_02.HIPx.out index 984caa3297fe..6859660f2f09 100644 --- a/contrib/libxo/tests/core/saved/test_02.HIPx.out +++ b/contrib/libxo/tests/core/saved/test_02.HIPx.out @@ -1,242 +1,249 @@
em0
em0
We are
{emit}
{ting}
some
braces
abcdef
abcdef: Bad file descriptor
improper use of profanity; ten yard penalty; first down
length
abcdef
close
-1
returned
Bad file descriptor
good
close
-1
returned
Bad fi
good
improper use of profanity; ten yard penalty; first down
20
30
40
file
0
bytes
1
byte
2
bytes
3
bytes
4
bytes
+
+
Low/warn granularity
+
:
+
+
155
+
+
10
/
20
/
30
mbufs <&> in use (current/cache/total)
50
from
Boston
64
left out of
640
64
left out of
640
beforeworkingafter:
string
:
10
11
1010
packets here/there/everywhere
1010
packets here/there/everywhere
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
Humanize:
21
,
57 K
,
96M
,
44M
,
1.2G
one
two
three
(null)
1:
1000
2:
test5000
3:
ten-longx
4:
xtest
this is an error
two more errors
this is an warning
two more warnings
V1/V2 packets
:
10
0004
tries
improper use of profanity; ten yard penalty; first down
Shut 'er down, Clancey! She's a-pumpin' mud! <>!,"!<>
err message (1)
err message (2)
err message (1)
err message (2)
diff --git a/contrib/libxo/tests/core/saved/test_02.HP.out b/contrib/libxo/tests/core/saved/test_02.HP.out index f2634522dbcb..6bf93277a3b8 100644 --- a/contrib/libxo/tests/core/saved/test_02.HP.out +++ b/contrib/libxo/tests/core/saved/test_02.HP.out @@ -1,242 +1,249 @@
em0
em0
We are
{emit}
{ting}
some
braces
abcdef
abcdef: Bad file descriptor
improper use of profanity; ten yard penalty; first down
length
abcdef
close
-1
returned
Bad file descriptor
good
close
-1
returned
Bad fi
good
improper use of profanity; ten yard penalty; first down
20
30
40
file
0
bytes
1
byte
2
bytes
3
bytes
4
bytes
+
+
Low/warn granularity
+
:
+
+
155
+
+
10
/
20
/
30
mbufs <&> in use (current/cache/total)
50
from
Boston
64
left out of
640
64
left out of
640
beforeworkingafter:
string
:
10
11
1010
packets here/there/everywhere
1010
packets here/there/everywhere
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
(
15
/
20
/
125
)
Humanize:
21
,
57 K
,
96M
,
44M
,
1.2G
one
two
three
(null)
1:
1000
2:
test5000
3:
ten-longx
4:
xtest
this is an error
two more errors
this is an warning
two more warnings
V1/V2 packets
:
10
0004
tries
improper use of profanity; ten yard penalty; first down
Shut 'er down, Clancey! She's a-pumpin' mud! <>!,"!<>
err message (1)
err message (2)
err message (1)
err message (2)
diff --git a/contrib/libxo/tests/core/saved/test_02.J.out b/contrib/libxo/tests/core/saved/test_02.J.out index c34e685b4ac5..5e01fa9a8bd4 100644 --- a/contrib/libxo/tests/core/saved/test_02.J.out +++ b/contrib/libxo/tests/core/saved/test_02.J.out @@ -1 +1 @@ -{"top": {"data": {"name":"em0","flags":"0x8843","name":"em0","flags":"0x8843","what":"braces","length":"abcdef","fd":-1,"error":"Bad file descriptor","test":"good","fd":-1,"error":"Bad fi","test":"good","lines":20,"words":30,"characters":40, "bytes": [0,1,2,3,4],"mbuf-current":10,"mbuf-cache":20,"mbuf-total":30,"distance":50,"location":"Boston","memory":64,"total":640,"memory":64,"total":640,"ten":10,"eleven":11,"unknown":1010,"unknown":1010,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"val1":21,"val2":58368,"val3":100663296,"val4":44470272,"val5":1342172800, "flag": ["one","two","three"],"works":null,"empty-tag":true,"t1":"1000","t2":"test5000","t3":"ten-longx","t4":"xtest", "__error": {"message":"this is an error"}, "__error": {"message":"two more errors"}, "__warning": {"message":"this is an warning"}, "__warning": {"message":"two more warnings"},"count":10,"test":4, "error": {"message":"Shut 'er down, Clancey! She's a-pumpin' mud! <>!,\"!<>\n"}, "error": {"message":"err message (1)"}, "error": {"message":"err message (2)\n"}, "error": {"message":"err message (1)\n"}, "error": {"message":"err message (2)\n"}}}} +{"top": {"data": {"name":"em0","flags":"0x8843","name":"em0","flags":"0x8843","what":"braces","length":"abcdef","fd":-1,"error":"Bad file descriptor","test":"good","fd":-1,"error":"Bad fi","test":"good","lines":20,"words":30,"characters":40, "bytes": [0,1,2,3,4],"granularity-lw":155,"mbuf-current":10,"mbuf-cache":20,"mbuf-total":30,"distance":50,"location":"Boston","memory":64,"total":640,"memory":64,"total":640,"ten":10,"eleven":11,"unknown":1010,"unknown":1010,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"min":15,"cur":20,"max":125,"val1":21,"val2":58368,"val3":100663296,"val4":44470272,"val5":1342172800, "flag": ["one","two","three"],"works":null,"empty-tag":true,"t1":"1000","t2":"test5000","t3":"ten-longx","t4":"xtest", "__error": {"message":"this is an error"}, "__error": {"message":"two more errors"}, "__warning": {"message":"this is an warning"}, "__warning": {"message":"two more warnings"},"count":10,"test":4, "error": {"message":"Shut 'er down, Clancey! She's a-pumpin' mud! <>!,\"!<>\n"}, "error": {"message":"err message (1)"}, "error": {"message":"err message (2)\n"}, "error": {"message":"err message (1)\n"}, "error": {"message":"err message (2)\n"}}}} diff --git a/contrib/libxo/tests/core/saved/test_02.JP.out b/contrib/libxo/tests/core/saved/test_02.JP.out index 1a3b464231bd..ef39233d0062 100644 --- a/contrib/libxo/tests/core/saved/test_02.JP.out +++ b/contrib/libxo/tests/core/saved/test_02.JP.out @@ -1,98 +1,99 @@ { "top": { "data": { "name": "em0", "flags": "0x8843", "name": "em0", "flags": "0x8843", "what": "braces", "length": "abcdef", "fd": -1, "error": "Bad file descriptor", "test": "good", "fd": -1, "error": "Bad fi", "test": "good", "lines": 20, "words": 30, "characters": 40, "bytes": [ 0, 1, 2, 3, 4 ], + "granularity-lw": 155, "mbuf-current": 10, "mbuf-cache": 20, "mbuf-total": 30, "distance": 50, "location": "Boston", "memory": 64, "total": 640, "memory": 64, "total": 640, "ten": 10, "eleven": 11, "unknown": 1010, "unknown": 1010, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "val1": 21, "val2": 58368, "val3": 100663296, "val4": 44470272, "val5": 1342172800, "flag": [ "one", "two", "three" ], "works": null, "empty-tag": true, "t1": "1000", "t2": "test5000", "t3": "ten-longx", "t4": "xtest", "__error": { "message": "this is an error" }, "__error": { "message": "two more errors" }, "__warning": { "message": "this is an warning" }, "__warning": { "message": "two more warnings" }, "count": 10, "test": 4, "error": { "message": "Shut 'er down, Clancey! She's a-pumpin' mud! <>!,\"!<>\n" }, "error": { "message": "err message (1)" }, "error": { "message": "err message (2)\n" }, "error": { "message": "err message (1)\n" }, "error": { "message": "err message (2)\n" } } } } diff --git a/contrib/libxo/tests/core/saved/test_02.JPu.err b/contrib/libxo/tests/core/saved/test_02.JPu.err new file mode 100644 index 000000000000..cedb03e0da31 --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_02.JPu.err @@ -0,0 +1 @@ +test_02: key field emitted after normal value field: 'name' diff --git a/contrib/libxo/tests/core/saved/test_02.JP.out b/contrib/libxo/tests/core/saved/test_02.JPu.out similarity index 93% copy from contrib/libxo/tests/core/saved/test_02.JP.out copy to contrib/libxo/tests/core/saved/test_02.JPu.out index 1a3b464231bd..d0b868a5f8ee 100644 --- a/contrib/libxo/tests/core/saved/test_02.JP.out +++ b/contrib/libxo/tests/core/saved/test_02.JPu.out @@ -1,98 +1,99 @@ { "top": { "data": { "name": "em0", "flags": "0x8843", "name": "em0", "flags": "0x8843", "what": "braces", "length": "abcdef", "fd": -1, "error": "Bad file descriptor", "test": "good", "fd": -1, "error": "Bad fi", "test": "good", "lines": 20, "words": 30, "characters": 40, "bytes": [ 0, 1, 2, 3, 4 ], - "mbuf-current": 10, - "mbuf-cache": 20, - "mbuf-total": 30, + "granularity_lw": 155, + "mbuf_current": 10, + "mbuf_cache": 20, + "mbuf_total": 30, "distance": 50, "location": "Boston", "memory": 64, "total": 640, "memory": 64, "total": 640, "ten": 10, "eleven": 11, "unknown": 1010, "unknown": 1010, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "min": 15, "cur": 20, "max": 125, "val1": 21, "val2": 58368, "val3": 100663296, "val4": 44470272, "val5": 1342172800, "flag": [ "one", "two", "three" ], "works": null, - "empty-tag": true, + "empty_tag": true, "t1": "1000", "t2": "test5000", "t3": "ten-longx", "t4": "xtest", "__error": { "message": "this is an error" }, "__error": { "message": "two more errors" }, "__warning": { "message": "this is an warning" }, "__warning": { "message": "two more warnings" }, "count": 10, "test": 4, "error": { "message": "Shut 'er down, Clancey! She's a-pumpin' mud! <>!,\"!<>\n" }, "error": { "message": "err message (1)" }, "error": { "message": "err message (2)\n" }, "error": { "message": "err message (1)\n" }, "error": { "message": "err message (2)\n" } } } } diff --git a/contrib/libxo/tests/core/saved/test_02.T.out b/contrib/libxo/tests/core/saved/test_02.T.out index 5b22c1615bb2..552e95393ab5 100644 --- a/contrib/libxo/tests/core/saved/test_02.T.out +++ b/contrib/libxo/tests/core/saved/test_02.T.out @@ -1,37 +1,38 @@ em0 em0 We are {emit}{ting} some braces abcdef abcdef: Bad file descriptor improper use of profanity; ten yard penalty; first down length abcdef close -1 returned Bad file descriptor good close -1 returned Bad fi good improper use of profanity; ten yard penalty; first down 20 30 40 file 0 bytes 1 byte 2 bytes 3 bytes 4 bytes +Low/warn granularity: 155 mAh 10/20/30 mbufs <&> in use (current/cache/total) 50 miles from Boston 64k left out of 640kb 64k left out of 640kilobytes beforeworkingafter: string: 1011 1010 packets here/there/everywhere 1010 packets here/there/everywhere ( 15/20/125) ( 15/20/125) (15/20/125 ) (15/20/125 ) Humanize: 21, 57 K, 96M, 44M, 1.2G one two three (null) 1: 1000 2:test5000 3: ten-longx 4:xtest this is an error two more errors this is an warning two more warnings V1/V2 packets: 10 0004 tries improper use of profanity; ten yard penalty; first down diff --git a/contrib/libxo/tests/core/saved/test_02.X.out b/contrib/libxo/tests/core/saved/test_02.X.out index 598480be9946..3c491c3ec81b 100644 --- a/contrib/libxo/tests/core/saved/test_02.X.out +++ b/contrib/libxo/tests/core/saved/test_02.X.out @@ -1,10 +1,10 @@ em00x8843em00x8843bracesabcdef abcdef: Bad file descriptor improper use of profanity; ten yard penalty; first down abcdef-1Bad file descriptorgood-1Bad figoodimproper use of profanity; ten yard penalty; first down -2030400123410203050Boston646406464010111010101015201251520125152012515201252158368100663296444702721342172800onetwothreenull1000test5000ten-longxxtest<__error>this is an error<__error>two more errors<__warning>this is an warning<__warning>two more warnings104improper use of profanity; ten yard penalty; first down +2030400123415510203050Boston646406464010111010101015201251520125152012515201252158368100663296444702721342172800onetwothreenull1000test5000ten-longxxtest<__error>this is an error<__error>two more errors<__warning>this is an warning<__warning>two more warnings104improper use of profanity; ten yard penalty; first down Shut 'er down, Clancey! She's a-pumpin' mud! <>!,"!<> err message (1)err message (2) err message (1) err message (2) \ No newline at end of file diff --git a/contrib/libxo/tests/core/saved/test_02.XP.out b/contrib/libxo/tests/core/saved/test_02.XP.out index 9a0755e01421..c9e85cb46d5b 100644 --- a/contrib/libxo/tests/core/saved/test_02.XP.out +++ b/contrib/libxo/tests/core/saved/test_02.XP.out @@ -1,106 +1,107 @@ em0 0x8843 em0 0x8843 braces abcdef abcdef: Bad file descriptor improper use of profanity; ten yard penalty; first down abcdef -1 Bad file descriptor good -1 Bad fi good improper use of profanity; ten yard penalty; first down 20 30 40 0 1 2 3 4 + 155 10 20 30 50 Boston 64 640 64 640 10 11 1010 1010 15 20 125 15 20 125 15 20 125 15 20 125 21 58368 100663296 44470272 1342172800 one two three null 1000 test5000 ten-longx xtest <__error> this is an error <__error> two more errors <__warning> this is an warning <__warning> two more warnings 10 4 improper use of profanity; ten yard penalty; first down Shut 'er down, Clancey! She's a-pumpin' mud! <>!,"!<> err message (1) err message (2) err message (1) err message (2) diff --git a/contrib/libxo/tests/core/saved/test_03.JPu.err b/contrib/libxo/tests/core/saved/test_03.JPu.err new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/contrib/libxo/tests/core/saved/test_03.JPu.out b/contrib/libxo/tests/core/saved/test_03.JPu.out new file mode 100644 index 000000000000..d0c3ccf45b59 --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_03.JPu.out @@ -0,0 +1,33 @@ +{ + "employees": { + "employee": [ + ], + "extra": "", + "memory": [ + { + "type": "name", + "in_use": 12345, + "memory_use": 54321, + "high_use": "-", + "requests": 32145 + } + ], + "employee": [ + { + "first_name": "Terry", + "last_name": "Jones", + "department": 660 + }, + { + "first_name": "Leslie", + "last_name": "Patterson", + "department": 341 + }, + { + "first_name": "Ashley", + "last_name": "Smith", + "department": 1440 + } + ] + } +} diff --git a/contrib/libxo/tests/core/saved/test_04.JPu.err b/contrib/libxo/tests/core/saved/test_04.JPu.err new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/contrib/libxo/tests/core/saved/test_04.JPu.out b/contrib/libxo/tests/core/saved/test_04.JPu.out new file mode 100644 index 000000000000..b0f802dc03fd --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_04.JPu.out @@ -0,0 +1,21 @@ +{ + "employees": { + "employee": [ + { + "first_name": "Terry", + "last_name": "Jones", + "department": 660 + }, + { + "first_name": "Leslie", + "last_name": "Patterson", + "department": 341 + }, + { + "first_name": "Ashley", + "last_name": "Smith", + "department": 1440 + } + ] + } +} diff --git a/contrib/libxo/tests/core/saved/test_05.JPu.err b/contrib/libxo/tests/core/saved/test_05.JPu.err new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/contrib/libxo/tests/core/saved/test_05.JPu.out b/contrib/libxo/tests/core/saved/test_05.JPu.out new file mode 100644 index 000000000000..9bcbf69df916 --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_05.JPu.out @@ -0,0 +1,91 @@ +{ + "indian_languages": { + "gurmukhi": "ਲਹੌਰ ਪਾਕਿਸਤਾਨੀ ਪੰਜਾਬ ਦੀ ਰਾਜਧਾਨੀ ਹੈ । ਲੋਕ ਗਿਣਤੀ ਦੇ ਨਾਲ ਕਰਾਚੀ ਤੋਂ ਬਾਅਦ ਲਹੌਰ ਦੂਜਾ ਸਭ ਤੋਂ ਵੱਡਾ ਸ਼ਹਿਰ ਹੈ । ਲਹੌਰ ਪਾਕਿਸਤਾਨ ਦਾ ਸਿਆਸੀ, ਰਹਤਲੀ ਤੇ ਪੜ੍ਹਾਈ ਦਾ ਗੜ੍ਹ ਹੈ ਅਤੇ ਇਸ ਲਈ ਇਹਨੂੰ ਪਾਕਿਸਤਾਨ ਦਾ ਦਿਲ ਵੀ ਕਿਹਾ ਜਾਂਦਾ ਹੈ । ਲਹੌਰ ਦਰਿਆ-ਏ-ਰਾਵੀ ਦੇ ਕੰਢੇ ਤੇ ਵਸਦਾ ਹੈ ਤੇ ਇਸਦੀ ਲੋਕ ਗਿਣਤੀ ਇੱਕ ਕਰੋੜ ਦੇ ਨੇੜੇ ਹੈ ।", + "shahmukhi": "لہور پاکستانی پنجاب دا دارالحکومت اے۔ لوک گنتی دے نال کراچی توں بعد لہور دوجا سبھ توں وڈا شہر اے۔ لہور پاکستان دا سیاسی، رہتلی تے پڑھائی دا گڑھ اے تے اس لئی ایھنوں پاکستان دا دل وی کیھا جاندا اے۔ لہور دریاۓ راوی دے کنڈھے تے وسدا اے اسدی لوک گنتی اک کروڑ دے نیڑے اے ۔", + "tranliteration": "lahor pākistān panjāb dā dārul hakūmat ē. lōk giṇtī dē nāḷ karācī tō᷈ bāad lahor dūjā sab tō᷈ vaḍḍā shahr ē. lahor pākistān dā siāsī, rahtalī tē paṛā̀ī dā gā́ṛ ē tē is laī ihnū᷈ pākistān dā dil vī kehā jāndā ē. lahor dariāē rāvī dē kanḍē tē vasdā ē. isdī lōk giṇtī ikk karōṛ dē nēṛē ē." + }, + "employees": { + "wc": [ + "෴ - 0xdf4 - 1", + "ණ - 0xdab - 1", + "් - 0xdca - 0", + "ණ - 0xdab - 1", + "្ - 0x17d2 - 0", + "෴ - 0xdf4 - 1", + "1 - 0x31 - 1", + "͏ - 0x34f - 0", + "2 - 0x32 - 1", + "⃝ - 0x20dd - 0" + ], + "fancy": "1͏2⃝", + "v1": "γιγνώσκειν", + "v2": "ὦ ἄνδρες ᾿Αθηναῖοι", + "v1": "ახლავე გაიაროთ რეგისტრაცია", + "v2": "Unicode-ის მეათე საერთაშორისო", + "width": 55, + "sinhala": "෴ණ්ණ෴", + "width": 4, + "sinhala": "෴", + "width": 1, + "sinhala": "෴ණ්ණ෴෴ණ්ණ෴", + "width": 8, + "not_sinhala": "123456", + "tag": "ර්‍ඝ", + "width": 2, + "employee": [ + { + "first_name": "Jim", + "nic_name": "\"რეგტ\"", + "last_name": "გთხოვთ ახ", + "department": 431, + "percent_time": 90, + "benefits": "full" + }, + { + "first_name": "Terry", + "nic_name": "\"1 2015-06-23T13:47:09.123-0500 worker-host test-program 222 animal-status [animal-status@42 animal="snake" state="loose"] The snake is loose}} +{{test-program: }} +{{The snake is loose}} + +{{<22>1 2015-06-23T13:47:09.123-0500 worker-host test-program 222 animal-consumed [animal-consumed@42 animal="snake" pet="hamster"] My snake ate your hamster}} +{{test-program: }} +{{My snake ate your hamster}} + +{{<29>1 2015-06-23T13:47:09.123-0500 worker-host test-program 222 animal-talk [animal-talk@42 count="1" animal="owl" quote="\"e=m\\c[2\]\""] 1 owl said "e=m\c[2]"}} +{{test-program: }} +{{1 owl said "e=m\c[2]"}} + +{{<165>1 2015-06-23T13:47:09.123-0500 worker-host test-program 222 ID47 [ID47@32473 iut="3" event-source="application" event-id="1011"] An application 1011 log entry}} +{{test-program: }} +{{An application 1011 log entry}} + +{ + "__version": "3.1.4", + "top": { + + } +} diff --git a/contrib/libxo/tests/core/saved/test_12.JPu.err b/contrib/libxo/tests/core/saved/test_12.JPu.err new file mode 100644 index 000000000000..6e563c3c236c --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_12.JPu.err @@ -0,0 +1,4 @@ +test_12: invalid XML tag name: '2by4' +test_12: invalid XML tag name: '4x4' +test_12: invalid XML tag name: '2morrow' +test_12: invalid XML tag name: '2by4' diff --git a/contrib/libxo/tests/core/saved/test_12.JPu.out b/contrib/libxo/tests/core/saved/test_12.JPu.out new file mode 100644 index 000000000000..0095d8dcc59a --- /dev/null +++ b/contrib/libxo/tests/core/saved/test_12.JPu.out @@ -0,0 +1,94 @@ +{ + "top": { + "data": { + "animal": "fish", + "animal": "fish", + "thing": [ + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45" + }, + { + "name": "thing", + "color": "green", + "time": "2:15", + "hand": "left", + "color": "blue", + "time": "3:45", + "2by4": { + "4x4": "truck", + "2morrow": "tomorrow" + } + } + ] + } + } +} diff --git a/contrib/libxo/tests/core/test_01.c b/contrib/libxo/tests/core/test_01.c index aeeb0c9ca67a..8311efbfc87c 100644 --- a/contrib/libxo/tests/core/test_01.c +++ b/contrib/libxo/tests/core/test_01.c @@ -1,256 +1,263 @@ /* * Copyright (c) 2014-2019, 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. * Phil Shafer, July 2014 */ #include #include #include #include #include "xo.h" #include "xo_encoder.h" int main (int argc, char **argv) { static char base_grocery[] = "GRO"; static char base_hardware[] = "HRD"; struct item { const char *i_title; int i_sold; int i_instock; int i_onorder; const char *i_sku_base; int i_sku_num; }; struct item list[] = { { "gum", 1412, 54, 10, base_grocery, 415 }, { "rope", 85, 4, 2, base_hardware, 212 }, { "ladder", 0, 2, 1, base_hardware, 517 }, { "bolt", 4123, 144, 42, base_hardware, 632 }, { "water", 17, 14, 2, base_grocery, 2331 }, { NULL, 0, 0, 0, NULL, 0 } }; struct item list2[] = { { "fish", 1321, 45, 1, base_grocery, 533 }, { NULL, 0, 0, 0, NULL, 0 } }; struct item *ip; 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" }, { XO_INFO_NULL }, }; char name[] = "test_01.test"; /* test trimming of xo_program */ argv[0] = name; argc = xo_parse_args(argc, argv); if (argc < 0) return 1; for (argc = 1; argv[argc]; argc++) { if (xo_streq(argv[argc], "xml")) xo_set_style(NULL, XO_STYLE_XML); else if (xo_streq(argv[argc], "json")) xo_set_style(NULL, XO_STYLE_JSON); else if (xo_streq(argv[argc], "text")) xo_set_style(NULL, XO_STYLE_TEXT); else if (xo_streq(argv[argc], "html")) xo_set_style(NULL, XO_STYLE_HTML); else if (xo_streq(argv[argc], "pretty")) xo_set_flags(NULL, XOF_PRETTY); else if (xo_streq(argv[argc], "xpath")) xo_set_flags(NULL, XOF_XPATH); else if (xo_streq(argv[argc], "info")) xo_set_flags(NULL, XOF_INFO); else if (xo_streq(argv[argc], "error")) { close(-1); xo_err(1, "error detected"); } } xo_set_info(NULL, info, -1); xo_set_flags(NULL, XOF_KEYS); - xo_open_container_h(NULL, "top"); + xo_open_container_h(NULL, "top-level"); xo_emit("static {:type/ethernet} {:type/bridge} {:type/%4du} {:type/%3d}", 18, 24); xo_emit("anchor {[:/%d}{:address/%p}..{:port/%u}{]:}\n", 18, NULL, 1); xo_emit("anchor {[:18}{:address/%p}..{:port/%u}{]:}\n", NULL, 1); xo_emit("anchor {[:/18}{:address/%p}..{:port/%u}{]:}\n", NULL, 1); xo_emit("df {:used-percent/%5.0f}{U:%%}\n", (double) 12); xo_emit("{e:kve_start/%#jx}", (uintmax_t) 0xdeadbeef); xo_emit("{e:kve_end/%#jx}", (uintmax_t) 0xcabb1e); xo_emit("testing argument modifier {a:}.{a:}...\n", "host", "my-box", "domain", "example.com"); xo_emit("testing argument modifier with encoding to {ea:}.{a:}...\n", "host", "my-box", "domain", "example.com"); xo_emit("{La:} {a:}\n", "Label text", "label", "value"); + const char *title = "My Title"; + xo_emit_field("T", title, "%s\n", NULL, NULL); + xo_emit_field("Vt", "max-chaos", NULL, NULL, " very "); xo_emit_field("V", "min-chaos", "%d", NULL, 42); xo_emit_field("V", "some-chaos", "%d\n", "[%d]", 42); + xo_attr("test-attr", "attr-value"); + xo_emit_field_h(NULL, ",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u", + "gum", 1412); + xo_emit("Connecting to {:host}.{:domain}...\n", "my-box", "example.com"); xo_attr("test", "value"); xo_open_container("data"); xo_open_list("item"); xo_attr("test2", "value2"); xo_emit("{T:Item/%-10s}{T:Total Sold/%12s}{T:In Stock/%12s}" "{T:On Order/%12s}{T:SKU/%5s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_attr("test3", "value3"); xo_emit("{keq:sku/%s-%u/%s-000-%u}" "{k:name/%-10s/%s}{n:sold/%12u/%u}{:in-stock/%12u/%u}" "{:on-order/%12u/%u}{qkd:sku/%5s-000-%u/%s-000-%u}\n", ip->i_sku_base, ip->i_sku_num, ip->i_title, ip->i_sold, ip->i_instock, ip->i_onorder, ip->i_sku_base, ip->i_sku_num); xo_close_instance("item"); } xo_close_list("item"); xo_close_container("data"); xo_emit("\n\n"); xo_open_container("data2"); xo_open_list("item"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{keq:sku/%s-%u/%s-000-%u}", ip->i_sku_base, ip->i_sku_num); xo_emit("{L:Item} '{k:name/%s}':\n", ip->i_title); xo_emit("{P: }{L:Total sold}: {n:sold/%u%s}\n", ip->i_sold, ip->i_sold ? ".0" : ""); xo_emit("{P: }{Lcw:In stock}{:in-stock/%u}\n", ip->i_instock); xo_emit("{P: }{Lcw:On order}{:on-order/%u}\n", ip->i_onorder); xo_emit("{P: }{L:SKU}: {qkd:sku/%s-000-%u}\n", ip->i_sku_base, ip->i_sku_num); xo_close_instance("item"); } xo_close_list("item"); xo_close_container("data2"); xo_open_container("data3"); xo_open_list("item"); for (ip = list2; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{keq:sku/%s-%u/%s-000-%u}", ip->i_sku_base, ip->i_sku_num); xo_emit("{L:Item} '{k:name/%s}':\n", ip->i_title); xo_emit("{P: }{L:Total sold}: {n:sold/%u%s}\n", ip->i_sold, ip->i_sold ? ".0" : ""); xo_emit("{P: }{Lcw:In stock}{:in-stock/%u}\n", ip->i_instock); xo_emit("{P: }{Lcw:On order}{:on-order/%u}\n", ip->i_onorder); xo_emit("{P: }{L:SKU}: {qkd:sku/%s-000-%u}\n", ip->i_sku_base, ip->i_sku_num); xo_close_instance("item"); } xo_close_list("item"); xo_close_container("data3"); xo_open_container("data4"); xo_open_list("item"); for (ip = list; ip->i_title; ip++) { xo_attr("test4", "value4"); xo_emit("{Lwc:Item}{l:item}\n", ip->i_title); } xo_close_list("item"); xo_close_container("data4"); xo_attr("test", "value"); xo_open_container("data"); xo_open_list("item"); xo_attr("test2", "value2"); xo_emit("{T:Item/%-10s}{T:Total Sold/%12s}{T:In Stock/%12s}" "{T:On Order/%12s}{T:SKU/%5s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_attr("test3", "value3"); xo_emit("{keq:sku/%s-%u/%s-000-%u}" "{k:name/%-10s/%s}{n:sold/%12u/%u}", ip->i_sku_base, ip->i_sku_num, ip->i_title, ip->i_sold); if (ip->i_onorder < 5) xo_emit("Extra: {:extra}", "special"); if (ip->i_instock & 1) xo_emit("{:in-stock/%12u/%u}", ip->i_instock); xo_emit("{:on-order/%12u/%u}", ip->i_onorder); if (!(ip->i_instock & 1)) xo_emit("{:in-stock/%12u/%u}", ip->i_instock); xo_emit("{qkd:sku/%5s-000-%u/%s-000-%u}\n", ip->i_sku_base, ip->i_sku_num); xo_close_instance("item"); } xo_close_list("item"); xo_close_container("data"); xo_emit("\n\n"); xo_emit("X{P:}X", "epic fail"); xo_emit("X{T:}X", "epic fail"); xo_emit("X{N:}X", "epic fail"); xo_emit("X{L:}X\n", "epic fail"); xo_emit("X{P: }X{Lwc:Cost}{:cost/%u}\n", 425); xo_emit("X{P:/%30s}X{Lwc:Cost}{:cost/%u}\n", "", 455); xo_emit("{e:mode/%s}{e:mode_octal/%s} {t:links/%s} " "{t:user/%s} {t:group/%s} \n", "mode", "octal", "links", "user", "group", "extra1", "extra2", "extra3"); xo_emit("{e:pre/%s}{t:links/%-*u}{t:post/%-*s}\n", "that", 8, 3, 8, "this"); xo_emit("{t:mode/%s}{e:mode_octal/%03o} {t:links/%*u} " "{t:user/%-*s} {t:group/%-*s} \n", "/some/file", (int) 0640, 8, 1, 10, "user", 12, "group"); - xo_close_container_h(NULL, "top"); + xo_close_container_h(NULL, "top-level"); xo_finish(); return 0; } diff --git a/contrib/libxo/tests/core/test_02.c b/contrib/libxo/tests/core/test_02.c index 4ea8c459047c..7591eb177f7a 100644 --- a/contrib/libxo/tests/core/test_02.c +++ b/contrib/libxo/tests/core/test_02.c @@ -1,161 +1,163 @@ /* * Copyright (c) 2014-2019, 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. * Phil Shafer, July 2014 */ #include #include #include #include #include "xo.h" #include "xo_encoder.h" #include "xo_humanize.h" int main (int argc, char **argv) { xo_set_program("test_02"); argc = xo_parse_args(argc, argv); if (argc < 0) return 1; for (argc = 1; argv[argc]; argc++) { if (xo_streq(argv[argc], "xml")) xo_set_style(NULL, XO_STYLE_XML); else if (xo_streq(argv[argc], "json")) xo_set_style(NULL, XO_STYLE_JSON); else if (xo_streq(argv[argc], "text")) xo_set_style(NULL, XO_STYLE_TEXT); else if (xo_streq(argv[argc], "html")) xo_set_style(NULL, XO_STYLE_HTML); else if (xo_streq(argv[argc], "pretty")) xo_set_flags(NULL, XOF_PRETTY); else if (xo_streq(argv[argc], "xpath")) xo_set_flags(NULL, XOF_XPATH); else if (xo_streq(argv[argc], "info")) xo_set_flags(NULL, XOF_INFO); } xo_set_flags(NULL, XOF_UNITS); /* Always test w/ this */ xo_set_file(stdout); xo_open_container_h(NULL, "top"); xo_open_container("data"); xo_emit("{kt:name/%-*.*s}{eq:flags/0x%x}", 5, 5, "em0", 34883); xo_emit("{d:/%-*.*s}{etk:name}{eq:flags/0x%x}", 5, 5, "em0", "em0", 34883); xo_emit("We are {{emit}}{{ting}} some {:what}\n", "braces"); xo_message("abcdef"); close(-1); xo_message_e("abcdef"); xo_message("improper use of profanity; %s; %s", "ten yard penalty", "first down"); xo_emit("length {:length/%6.6s}\n", "abcdefghijklmnopqrstuvwxyz"); close(-1); xo_emit("close {:fd/%d} returned {:error/%m} {:test}\n", -1, "good"); close(-1); xo_emit("close {:fd/%d} returned {:error/%6.6m} {:test}\n", -1, "good"); xo_message("improper use of profanity; %s; %s", "ten yard penalty", "first down"); xo_emit(" {:lines/%7ju} {:words/%7ju} " "{:characters/%7ju} {d:filename/%s}\n", (uintmax_t) 20, (uintmax_t) 30, (uintmax_t) 40, "file"); int i; for (i = 0; i < 5; i++) xo_emit("{lw:bytes/%d}{Np:byte,bytes}\n", i); + xo_emit("{Lc:Low\\/warn granularity}{P:\t}{:granularity-lw/%d}{Uw:/%sh}\n", + 155, "mA"); xo_emit("{:mbuf-current/%u}/{:mbuf-cache/%u}/{:mbuf-total/%u} " "{N:mbufs <&> in use (current\\/cache\\/total)}\n", 10, 20, 30); xo_emit("{:distance/%u}{Uw:miles} from {:location}\n", 50, "Boston"); xo_emit("{:memory/%u}{U:k} left out of {:total/%u}{U:kb}\n", 64, 640); xo_emit("{:memory/%u}{U:/%s} left out of {:total/%u}{U:/%s}\n", 64, "k", 640, "kilobytes"); xo_emit("{,title:/before%safter:}\n", "working"); xo_emit("{,display,white,colon:some/%s}" "{,value:ten/%ju}{,value:eleven/%ju}\n", "string", (uintmax_t) 10, (uintmax_t) 11); xo_emit("{:unknown/%u} " "{N:/packet%s here\\/there\\/everywhere}\n", 1010, "s"); xo_emit("{:unknown/%u} " "{,note:/packet%s here\\/there\\/everywhere}\n", 1010, "s"); xo_emit("({[:/%d}{n:min/15}/{n:cur/20}/{:max/%d}{]:})\n", 30, 125); xo_emit("({[:30}{:min/%u}/{:cur/%u}/{:max/%u}{]:})\n", 15, 20, 125); xo_emit("({[:-30}{n:min/15}/{n:cur/20}/{n:max/125}{]:})\n"); xo_emit("({[:}{:min/%u}/{:cur/%u}/{:max/%u}{]:/%d})\n", 15, 20, 125, -30); xo_emit("Humanize: {h:val1/%u}, {h,hn-space:val2/%u}, " "{h,hn-decimal:val3/%u}, {h,hn-1000:val4/%u}, " "{h,hn-decimal:val5/%u}\n", 21, 57 * 1024, 96 * 1024 * 1024, (42 * 1024 + 420) * 1024, 1342172800); xo_open_list("flag"); xo_emit("{lq:flag/one} {lq:flag/two} {lq:flag/three}\n"); xo_close_list("flag"); xo_emit("{n:works/%s}\n", NULL); xo_emit("{e:empty-tag/}"); xo_emit("1:{qt:t1/%*d} 2:{qt:t2/test%-*u} " "3:{qt:t3/%10sx} 4:{qt:t4/x%-*.*s}\n", 6, 1000, 8, 5000, "ten-long", 10, 10, "test"); xo_emit("{E:this is an error}\n"); xo_emit("{E:/%s more error%s}\n", "two", "s" ); xo_emit("{W:this is an warning}\n"); xo_emit("{W:/%s more warning%s}\n", "two", "s" ); xo_emit("{L:/V1\\/V2 packet%s}: {:count/%u}\n", "s", 10); int test = 4; xo_emit("{:test/%04d} {L:/tr%s}\n", test, (test == 1) ? "y" : "ies"); xo_message("improper use of profanity; %s; %s", "ten yard penalty", "first down"); xo_error("Shut 'er down, Clancey! She's a-pumpin' mud! <>!,\"!<>\n"); xo_error("err message (%d)", 1); xo_error("err message (%d)\n", 2); xo_errorn("err message (%d)", 1); xo_errorn("err message (%d)\n", 2); xo_close_container("data"); xo_close_container_h(NULL, "top"); xo_finish(); return 0; } diff --git a/contrib/libxo/tests/core/test_08.c b/contrib/libxo/tests/core/test_08.c index 80cbff2a4f3a..b82a7c1dfcbc 100644 --- a/contrib/libxo/tests/core/test_08.c +++ b/contrib/libxo/tests/core/test_08.c @@ -1,158 +1,158 @@ /* * Copyright (c) 2015, 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. * Phil Shafer, July 2015 */ #include #include #include #include #include #include "xo.h" #include "xo_encoder.h" int main (int argc, char **argv) { struct item { const char *i_title; int i_count; }; struct item list[] = { { "gum", 1412 }, { "rope", 85 }, { "ladder", 0 }, { "bolt", 4123 }, { "water", 17 }, { NULL, 0 } }; struct item *ip; int i; argc = xo_parse_args(argc, argv); if (argc < 0) return 1; for (argc = 1; argv[argc]; argc++) { if (xo_streq(argv[argc], "xml")) xo_set_style(NULL, XO_STYLE_XML); else if (xo_streq(argv[argc], "json")) xo_set_style(NULL, XO_STYLE_JSON); else if (xo_streq(argv[argc], "text")) xo_set_style(NULL, XO_STYLE_TEXT); else if (xo_streq(argv[argc], "html")) xo_set_style(NULL, XO_STYLE_HTML); else if (xo_streq(argv[argc], "pretty")) xo_set_flags(NULL, XOF_PRETTY); else if (xo_streq(argv[argc], "xpath")) xo_set_flags(NULL, XOF_XPATH); else if (xo_streq(argv[argc], "info")) xo_set_flags(NULL, XOF_INFO); else if (xo_streq(argv[argc], "error")) { close(-1); xo_err(1, "error detected"); } } xo_set_flags(NULL, XOF_KEYS); xo_set_program("test"); xo_open_container_h(NULL, "top"); xo_open_container("data"); xo_open_container("contents"); xo_open_list("item"); xo_emit("{T:Item/%-10s}{T:Count/%12s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{k:name/%-10s/%s}{n:count/%12u/%u}\n", ip->i_title, ip->i_count); xo_close_instance("item"); } xo_close_list("item"); xo_close_container("contents"); xo_close_container("data"); xo_emit("\n\n"); xo_open_container("data2"); xo_open_container("contents"); xo_emit("{T:Item/%-10s}{T:Count/%12s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{k:name/%-10s/%s}{n:count/%12u/%u}\n", ip->i_title, ip->i_count); } xo_close_container("data2"); xo_emit("\n\n"); xo_open_container("data3"); xo_open_marker("m1"); xo_open_container("contents"); xo_emit("{T:Item/%-10s}{T:Count/%12s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{k:name/%-10s/%s}{n:count/%12u/%u}\n", ip->i_title, ip->i_count); } - xo_close_container("data3"); /* Should be a noop */ + xo_close_container("data3"); /* warn: fails at marker 'm1' */ xo_emit("{:test}", "one"); xo_close_marker("m1"); - xo_close_container("data3"); /* Should be a noop */ + xo_close_container("data3"); /* this one works, post-marker */ xo_emit("\n\n"); xo_open_container("data4"); xo_open_marker("m1"); xo_open_container("contents"); xo_emit("{T:Item/%-10s}{T:Count/%12s}\n"); for (ip = list; ip->i_title; ip++) { xo_open_instance("item"); xo_emit("{k:name/%-10s/%s}{n:count/%12u/%u}\n", ip->i_title, ip->i_count); xo_open_marker("m2"); for (i = 0; i < 3; i++) { xo_open_instance("sub"); xo_emit("{Lwc:/Name}{:name/%d} + 1 = {:next/%d}\n", i, i + 1); - xo_close_container("data4"); + xo_close_container("data4"); /* warn: fails at marker 'm2' */ } xo_close_marker("m2"); xo_emit("{Lwc:/Last}{:last/%d}\n", i); } - xo_close_container("data4"); /* Should be a noop */ + xo_close_container("data4"); /* warn: fails at marker 'm1' */ xo_emit("{:test}", "one"); xo_emit("\n\n"); xo_close_container_h(NULL, "top"); xo_finish(); return 0; } diff --git a/contrib/libxo/tests/xo/xo_01.sh b/contrib/libxo/tests/xo/xo_01.sh old mode 100755 new mode 100644 diff --git a/contrib/libxo/tests/xo/xo_02.sh b/contrib/libxo/tests/xo/xo_02.sh old mode 100755 new mode 100644 diff --git a/contrib/libxo/xo/xo.1 b/contrib/libxo/xo/xo.1 index cd885b3d193e..c3d062f750f1 100644 --- a/contrib/libxo/xo/xo.1 +++ b/contrib/libxo/xo/xo.1 @@ -1,211 +1,211 @@ .\" # .\" # 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 .\" .Dd December 4, 2014 .Dt XO 1 .Os .Sh NAME .Nm xo .Nd emit formatted output based on format string and arguments .Sh SYNOPSIS .Nm .Op Fl options .Op Ar argument... .Sh DESCRIPTION The .Nm utility allows command line access to the functionality of the .Nm libxo library. Using .Nm , shell scripts can emit .Em XML , .Em JSON , or .Em HTML using the same commands that emit text output. .Pp .Bl -tag -width indent .It Ic --close Ar path Close tags for the given path .It Ic -C | Ic --continuation Indicates this output is a continuation of the previous output data and should appear on the same line. This is allows HTML output to be constructed correctly. .It Ic --depth Ar num Set the depth for pretty printing .It Ic --help Display help text .It Ic -H | Ic --html Generate HTML output .It Ic -J | Ic --json Generate JSON output .It Ic --leading-xpath Ar path Add a prefix to generated XPaths (HTML) .It Ic --not-first Indicate that this content is not the first in a series of sibling objects, which is vital information for "JSON" output, which requires a comma between such objects. .It Ic --open Ar path Open tags for the given path .It Ic -p | Ic --pretty Make 'pretty' output (add indent, newlines) .It Ic --style Ar style Generate given style (xml, json, text, html) .It Ic -T | Ic --text Generate text output (the default style) .It Ic --top-warp Indicates the entire object should be placed inside a top-level object wrapper, specifically when generating JSON output. .It Ic --version Display version information .It Ic -W | Ic --warn Display warnings in text on stderr .It Ic --warn-xml Display warnings in xml on stdout .It Ic --wrap Ar path Wrap output in a set of containers .It Ic -X | Ic --xml Generate XML output .It Ic --xpath Add XPath data to HTML output .El .Pp The .Nm utility accepts a format string suitable for .Xr xo_emit 3 and a set of zero or more arguments used to supply data for that string. .Pp In addition, .Nm accepts any of the .Nm libxo options listed in .Xr xo_options 7 . .Sh EXAMPLES In this example, .Nm is used to emit the same data encoded in text and then in XML by adding the "-p" (pretty) and "-X" (XML output) flags: .Bd -literal -offset indent % xo 'The {:product} is {:status}\\n' stereo "in route" The stereo is in route % xo -p -X 'The {:product} is {:status}\\n' stereo "in route" stereo in route .Ed .Pp In this example, the output from a .Nm command is shown in several styles: .Bd -literal -offset indent xo "The {k:name} weighs {:weight/%d} pounds.\\n" fish 6 .Pp TEXT: The fish weighs 6 pounds. XML: fish 6 JSON: "name": "fish", "weight": 6 HTML:
The
fish
weighs
6
pounds.
.Ed .Pp The .Fl "-wrap " option can be used to wrap emitted content in a specific hierarchy. The path is a set of hierarchical names separated by the '/' character. .Bd -literal -offset indent xo --wrap top/a/b/c '{:tag}' value .Pp XML: value JSON: "top": { "a": { "b": { "c": { "tag": "value" } } } } .Ed .Pp The .Fl "\-open " and .Fl "\-close " can be used to emit hierarchical information without the matching close and open tag. This allows a shell script to emit open tags, data, and then close tags. The .Fl \-depth option may be used to set the depth for indentation. The .Fl "\-leading-xpath" may be used to prepend data to the XPath values used for HTML output style. .Bd -literal -offset indent #!/bin/sh xo --open top/data - xo --depth 2 '{tag}' value + xo --depth 2 '{:tag}' value xo --close top/data .Pp XML: value JSON: "top": { "data": { "tag": "value" } } .Ed .Sh SEE ALSO .Xr libxo 3 , .Xr xo_emit 3 , .Xr xo_options 7 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org . diff --git a/contrib/libxo/xolint/xolint.pl b/contrib/libxo/xolint/xolint.pl old mode 100755 new mode 100644