Index: head/bin/ls/Makefile =================================================================== --- head/bin/ls/Makefile (revision 287110) +++ head/bin/ls/Makefile (revision 287111) @@ -1,16 +1,16 @@ # @(#)Makefile 8.1 (Berkeley) 6/2/93 # $FreeBSD$ .include PROG= ls SRCS= cmp.c ls.c print.c util.c -LIBADD= util xo +LIBADD= xo util .if !defined(RELEASE_CRUNCH) && \ ${MK_LS_COLORS} != no CFLAGS+= -DCOLORLS LIBADD+= termcapw .endif .include Index: head/bin/ps/Makefile =================================================================== --- head/bin/ps/Makefile (revision 287110) +++ head/bin/ps/Makefile (revision 287111) @@ -1,16 +1,16 @@ # $FreeBSD$ # @(#)Makefile 8.1 (Berkeley) 6/2/93 PROG= ps SRCS= fmt.c keyword.c nlist.c print.c ps.c # # To support "lazy" ps for non root/wheel users # add -DLAZY_PS to the cflags. This helps # keep ps from being an unnecessary load # on large systems. # CFLAGS+=-DLAZY_PS -LIBADD= m kvm jail xo +LIBADD= m kvm jail xo util .include Index: head/contrib/libxo/.gitignore =================================================================== --- head/contrib/libxo/.gitignore (revision 287110) +++ head/contrib/libxo/.gitignore (revision 287111) @@ -1,43 +1,46 @@ # Object files *.o # Libraries *.lib *.a # Shared objects (inc. Windows DLLs) *.dll *.so *.so.* *.dylib # Executables *.exe *.app *~ *.orig aclocal.m4 ar-lib autom4te.cache build compile config.guess config.h.in config.sub depcomp +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 Index: head/contrib/libxo/.travis.yml =================================================================== --- head/contrib/libxo/.travis.yml (revision 287110) +++ head/contrib/libxo/.travis.yml (revision 287111) @@ -1,12 +1,12 @@ language: c -script: printenv && uname -a && /bin/sh ./bin/setup.sh && cd build && ../configure --enable-warnings && make && sudo make install && make test +script: printenv && uname -a && ls -l && /bin/sh -x ./bin/setup.sh && cd build && ../configure --enable-warnings && make && sudo make install && make test notifications: recipients: - libslax-noise@googlegroups.com branches: only: - master - develop Index: head/contrib/libxo/INSTALL.md =================================================================== --- head/contrib/libxo/INSTALL.md (nonexistent) +++ head/contrib/libxo/INSTALL.md (revision 287111) @@ -0,0 +1,15 @@ + + +## Instructions for building libxo + +Instructions for building libxo are now available in the +[wiki](http://juniper.github.io/libxo/libxo-manual.html#getting-libxo). Index: head/contrib/libxo/Makefile.am =================================================================== --- head/contrib/libxo/Makefile.am (revision 287110) +++ head/contrib/libxo/Makefile.am (revision 287111) @@ -1,96 +1,102 @@ # # $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 xolint xohtml tests doc +SUBDIRS = libxo xo xopo xolint xohtml tests doc encoder bin_SCRIPTS=libxo-config dist_doc_DATA = Copyright EXTRA_DIST = \ libxo-config.in \ warnings.mk \ README.md \ INSTALL.md \ packaging/libxo.spec .PHONY: test tests test tests: @(cd tests ; ${MAKE} test) errors: @(cd tests/errors ; ${MAKE} test) docs: @(cd doc ; ${MAKE} docs) DIST_FILES_DIR = ~/Dropbox/dist-files/ GH_PAGES_DIR = gh-pages/ GH_PAGES_DIR_VER = gh-pages/${PACKAGE_VERSION} PACKAGE_FILE = ${PACKAGE_TARNAME}-${PACKAGE_VERSION}.tar.gz upload: dist upload-docs @echo "Remember to run:" @echo " gt tag ${PACKAGE_VERSION}" upload-docs: docs @echo "Uploading libxo-manual.html ... " @-[ -d ${GH_PAGES_DIR} ] \ && echo "Updating manual on gh-pages ..." \ && mkdir -p ${GH_PAGES_DIR_VER} \ && cp doc/libxo-manual.html ${GH_PAGES_DIR} \ && cp doc/libxo-manual.html ${GH_PAGES_DIR_VER} \ && (cd ${GH_PAGES_DIR} \ && git add ${PACKAGE_VERSION} \ && git add libxo-manual.html \ && git commit -m 'new docs' \ libxo-manual.html ${PACKAGE_VERSION} \ && 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 ..." \ && 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: + ${ANALYZE_CMD} -o ${ANALYZE_DIR} ${MAKE} Index: head/contrib/libxo/bin/Zaliases =================================================================== --- head/contrib/libxo/bin/Zaliases (revision 287110) +++ head/contrib/libxo/bin/Zaliases (revision 287111) @@ -1,24 +1,29 @@ set top_src=`pwd` alias Zautoreconf "(cd $top_src ; autoreconf)" set opts=' \ --with-libslax-prefix=/Users/phil/work/root \ --enable-debug \ --enable-warnings \ --enable-printflike \ +--with-gettext=/opt/local \ --prefix ${HOME}/work/root \ ' set opts=`echo $opts` setenv CONFIGURE_OPTS "$opts" setenv ADB_PATH $top_src/build/libxo/.libs alias Zconfigure "(cd $top_src/build; ../configure $opts)" alias Zbuild "(cd $top_src/build; make \!* )" alias mi "(cd $top_src/build; make && make install); ." mkdir -p build cd build alias xx 'cc -I.. -W -Wall -Wstrict-prototypes -Wmissing-prototypes -Wpointer-arith -Werror -Waggregate-return -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment -Wformat -Wimplicit -Wmissing-declarations -Wnested-externs -Wparentheses -Wreturn-type -Wshadow -Wswitch -Wtrigraphs -Wuninitialized -Wunused -Wwrite-strings -fno-inline-functions-called-once -g -O2 -o xtest -DUNIT_TEST libxo.c' + +alias mm "make CFLAGS='-O0 -g'" + +alias mmi 'mm && mi' Index: head/contrib/libxo/bin/setup.sh =================================================================== --- head/contrib/libxo/bin/setup.sh (revision 287110) +++ head/contrib/libxo/bin/setup.sh (revision 287111) @@ -1,31 +1,33 @@ # # Copyright 2013, 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 [ ! -f configure ]; then vers=`autoreconf --version | head -1` echo "Using" $vers + mkdir -p m4 + autoreconf --install if [ ! -f configure ]; then echo "Failed to create configure script" exit 1 fi fi echo "Creating build directory ..." mkdir build echo "Setup is complete. To build libslax:" echo " 1) Type 'cd build ; ../configure' to configure libslax" echo " 2) Type 'make' to build libslax" echo " 3) Type 'make install' to install libslax" exit 0 Index: head/contrib/libxo/configure.ac =================================================================== --- head/contrib/libxo/configure.ac (revision 287110) +++ head/contrib/libxo/configure.ac (revision 287111) @@ -1,276 +1,452 @@ # # $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], [0.3.2], [phil@juniper.net]) +AC_INIT([libxo], [0.4.5], [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 AM_PROG_AR 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]) +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 +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_BINDIR=${GETTEXT_PREFIX}/bin +AC_SUBST(GETTEXT_BINDIR) +GETTEXT_LIBDIR=${GETTEXT_PREFIX}/lib +AC_SUBST(GETTEXT_LIBDIR) + +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 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_CHECK_LIB([m], [lrint]) AM_CONDITIONAL([HAVE_LIBM], [test "$HAVE_LIBM" != "no"]) AC_MSG_CHECKING([compiler for gcc]) HAVE_GCC=no if test "${CC}" != ""; then HAVE_GCC=`${CC} --version 2>&1 | grep GCC` if test "${HAVE_GCC}" != ""; then HAVE_GCC=yes else HAVE_GCC=no fi fi AC_MSG_RESULT([$HAVE_GCC]) AM_CONDITIONAL([HAVE_GCC], [test "$HAVE_GCC" = "yes"]) AC_MSG_CHECKING([whether to build with printflike]) AC_ARG_ENABLE([printflike], [ --enable-printflike Enable use of GCC __printflike attribute], [HAVE_PRINTFLIKE=yes; AC_DEFINE([HAVE_PRINTFLIKE], [1], [Support printflike])], [HAVE_PRINTFLIKE=no]) AC_MSG_RESULT([$HAVE_PRINTFLIKE]) AM_CONDITIONAL([HAVE_PRINTFLIKE], [test "$HAVE_PRINTFLIKE" != ""]) AC_MSG_CHECKING([whether to build with LIBXO_OPTIONS]) AC_ARG_ENABLE([libxo-options], [ --disable-libxo-options Turn off support for LIBXO_OPTIONS], [LIBXO_OPTS=$enableval], [LIBXO_OPTS=yes]) AC_MSG_RESULT([$LIBXO_OPTS]) AM_CONDITIONAL([NO_LIBXO_OPTIONS], [test "$LIBXO_OPTS" != "yes"]) case $host_os in darwin*) LIBTOOL=glibtool + XO_LIBEXT=dylib ;; Linux*|linux*) CFLAGS="-D_GNU_SOURCE $CFLAGS" LDFLAGS=-ldl + XO_LIBEXT=so ;; cygwin*|CYGWIN*) LDFLAGS=-no-undefined + XO_LIBEXT=ddl ;; esac case $prefix in NONE) prefix=/usr/local ;; esac XO_LIBS=-lxo XO_SRCDIR=${srcdir} XO_LIBDIR=${libdir} XO_BINDIR=${bindir} XO_INCLUDEDIR=${includedir} AC_SUBST(XO_SRCDIR) AC_SUBST(XO_LIBDIR) AC_SUBST(XO_BINDIR) AC_SUBST(XO_INCLUDEDIR) +AC_SUBST(XO_LIBEXT) +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_CONFIG_HEADERS([libxo/xoconfig.h]) +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/xoversion.h + libxo/add.man + encoder/Makefile + encoder/cbor/Makefile + encoder/test/Makefile xo/Makefile xolint/Makefile xohtml/Makefile + xopo/Makefile packaging/libxo.pc doc/Makefile 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} ]) Index: head/contrib/libxo/doc/Makefile.am =================================================================== --- head/contrib/libxo/doc/Makefile.am (revision 287110) +++ head/contrib/libxo/doc/Makefile.am (revision 287111) @@ -1,65 +1,70 @@ # # $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. +if HAVE_OXTRADOC OXTRADOC_DIR = ${SLAX_OXTRADOCDIR} OXTRADOC_PREFIX = ${OXTRADOC_DIR} OXTRADOC = ${OXTRADOC_DIR}/oxtradoc SLAXPROC_BINDIR = ${SLAX_BINDIR} XML2RFC = ${OXTRADOC_DIR}/xml2rfc.tcl XML2HTMLDIR = ${OXTRADOC_DIR} XML2HTMLBIN = ${XML2HTMLDIR}/rfc2629-to-html.slax SLAXPROC = ${SLAX_BINDIR}/slaxproc SLAXPROC_ARGS = \ -a oxtradoc-dir ${OXTRADOC_DIR} \ -a oxtradoc-install-dir ${OXTRADOC_DIR} \ -a anchor-prefix docs SLAXPROC_ARGS_INLINE = \ -a oxtradoc-inline yes SLAXPROC_ARGS += ${SLAXPROC_ARGS_INLINE} XML2HTML = \ ${SLAXPROC} -g -e -I ${OXTRADOC_DIR} -I . \ ${SLAXPROC_ARGS} \ ${XML2HTMLBIN} OX_ARGS = -P ${OXTRADOC_PREFIX} -L ${OXTRADOC_PREFIX} OX_ARGS += -S ${SLAXPROC} -p doc OX_CMD = ${PERL} ${PERLOPTS} ${OXTRADOC} ${OX_ARGS} OXTRADOC_CMD = ${OX_CMD} - OUTPUT = libxo-manual -INPUT = libxo.txt +INPUT = libxo EXTRA_DIST = \ - ${INPUT} \ + ${INPUT}.txt \ ${OUTPUT}.html \ ${OUTPUT}.txt doc docs: ${OUTPUT}.txt ${OUTPUT}.html -${OUTPUT}.txt: ${INPUT} ${OXTRADOC} xolint.txt +${OUTPUT}.txt: ${INPUT}.txt ${OXTRADOC} xolint.txt ${OXTRADOC_CMD} -m text -o $@ $< -${OUTPUT}.html: ${INPUT} ${OXTRADOC} ${XML2HTMLBIN} xolint.txt +${OUTPUT}.html: ${INPUT}.txt ${OXTRADOC} ${XML2HTMLBIN} xolint.txt ${OXTRADOC_CMD} -m html -o $@ $< xolint.txt: ${top_srcdir}/xolint/xolint.pl perl ${top_srcdir}/xolint/xolint.pl -D > xolint.txt CLEANFILES = \ -${OUTPUT}.xml \ -${OUTPUT}.txt \ -${OUTPUT}.fxml \ -${OUTPUT}.html +xolint.txt \ +${INPUT}.xml \ +${INPUT}.txt \ +${INPUT}.fxml \ +${INPUT}.html +else +doc docs: + @${ECHO} "The 'oxtradoc' tool is not installed; see libslax.org" +endif Index: head/contrib/libxo/doc/libxo.txt =================================================================== --- head/contrib/libxo/doc/libxo.txt (revision 287110) +++ head/contrib/libxo/doc/libxo.txt (revision 287111) @@ -1,2682 +1,3757 @@ # # 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 # -* libxo +* Overview libxo - A Library for Generating Text, XML, JSON, and HTML Output You want to prepare for the future, but you need to live in the present. You'd love a flying car, but need to get to work today. You want to support features like XML, JSON, and HTML rendering to allow integration with NETCONF, REST, and web browsers, but you need to make text output for command line users. And you don't want multiple code paths that can't help but get out of sync. None of this "if (xml) {... } else {...}" logic. And ifdefs are right out. But you'd really, really like all the fancy features that modern encoding formats can provide. libxo can help. The libxo library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced. The application calls a function "xo_emit" to product output that is described in a format string. A "field descriptor" tells libxo what the field is and what it means. Each field descriptor is placed in -braces with a printf-like format string: +braces with a printf-like format string (^format-strings^): xo_emit(" {:lines/%7ju} {:words/%7ju} " - "{:characters/%7ju}{d:filename/%s}\n", + "{:characters/%7ju} {d:filename/%s}\n", linect, wordct, charct, file); Each field can have a role, with the 'value' role being the default, and the role tells libxo how and when to render that field. Output can then be generated in various style, using the "--libxo" option: % wc /etc/motd 25 165 1140 /etc/motd % wc --libxo xml,pretty,warn /etc/motd - /etc/motd 25 165 1140 + /etc/motd % wc --libxo json,pretty,warn /etc/motd { "wc": { "file": [ { - "filename": "/etc/motd", "lines": 25, "words": 165, - "characters": 1140 + "characters": 1140, + "filename": "/etc/motd" } ] } } % wc --libxo html,pretty,warn /etc/motd
25
165
1140
/etc/motd
** Getting libxo libxo lives on github as: https://github.com/Juniper/libxo The latest release of libxo is available at: https://github.com/Juniper/libxo/releases We are following the branching scheme from ^http://nvie.com/posts/a-successful-git-branching-model/^ which means we will do development under the "develop" branch, and release from the "master" branch. To clone a developer tree, run the following command: git clone https://github.com/Juniper/libxo.git -b develop We're using semantic release numbering, as defined in ^http://semver.org/spec/v2.0.0.html^. -libxo is open source, distributed under the BSD license. It -is shipped as part of FreeBSD 11.0. +libxo is open source, distributed under the BSD license. It shipped +as part of the FreeBSD operating system starting with release 11.0. -* Overview +Issues, problems, and bugs should be directly to the issues page on +our github site. +*** Downloading libxo Source Code + +You can retrieve the source for libxo in two ways: + +A) Use a "distfile" for a specific release. We use +github to maintain our releases. Visit +github release page (^https://github.com/Juniper/libxo/releases^) +to see the list of releases. To download the latest, look for the +release with the green "Latest release" button and the green +"libxo-RELEASE.tar.gz" button under that section. + +After downloading that release's distfile, untar it as follows: + + tar -zxf libxo-RELEASE.tar.gz + cd libxo-RELEASE + +[Note: for Solaris users, your "tar" command lacks the "-z" flag, +so you'll need to substitute "gzip -dc "file" | tar xf -" instead of +"tar -zxf "file"".] + +B) Use the current build from github. This gives you the most recent +source code, which might be less stable than a specific release. To +build libxo from the git repo: + + git clone https://github.com/Juniper/libxo.git + cd libxo + +_BE AWARE_: The github repository does _not_ contain the files +generated by "autoreconf", with the notable exception of the "m4" +directory. Since these files (depcomp, configure, missing, +install-sh, etc) are generated files, we keep them out of the source +code repository. + +This means that if you download the a release distfile, these files +will be ready and you'll just need to run "configure", but if you +download the source code from svn, then you'll need to run +"autoreconf" by hand. This step is done for you by the "setup.sh" +script, described in the next section. + +*** Building libxo + +To build libxo, you'll need to set up the build, run the "configure" +script, run the "make" command, and run the regression tests. + +The following is a summary of the commands needed. These commands are +explained in detail in the rest of this section. + + sh bin/setup.sh + cd build + ../configure + make + make test + sudo make install + +The following sections will walk thru each of these steps with +additional details and options, but the above directions should be all +that's needed. + +**** Setting up the build + +[If you downloaded a distfile, you can skip this step.] + +Run the "setup.sh" script to set up the build. This script runs the +"autoreconf" command to generate the "configure" script and other +generated files. + + sh bin/setup.sh + +Note: We're are currently using autoreconf version 2.69. + +**** Running the "configure" Script + +Configure (and autoconf in general) provides a means of building +software in diverse environments. Our configure script supports +a set of options that can be used to adjust to your operating +environment. Use "configure --help" to view these options. + +We use the "build" directory to keep object files and generated files +away from the source tree. + +To run the configure script, change into the "build" directory, and +run the "configure" script. Add any required options to the +"../configure" command line. + + cd build + ../configure + +Expect to see the "configure" script generate the following error: + + /usr/bin/rm: cannot remove `libtoolT': No such file or directory + +This error is harmless and can be safely ignored. + +By default, libxo installs architecture-independent files, including +extension library files, in the /usr/local directories. To specify an +installation prefix other than /usr/local for all installation files, +include the --prefix=prefix option and specify an alternate +location. To install just the extension library files in a different, +user-defined location, include the --with-extensions-dir=dir option +and specify the location where the extension libraries will live. + + cd build + ../configure [OPTION]... [VAR=VALUE]... + +**** Running the "make" command + +Once the "configure" script is run, build the images using the "make" +command: + + make + +**** Running the Regression Tests + +libxo includes a set of regression tests that can be run to ensure +the software is working properly. These test are optional, but will +help determine if there are any issues running libxo on your +machine. To run the regression tests: + + make test + +**** Installing libxo + +Once the software is built, you'll need to install libxo using the +"make install" command. If you are the root user, or the owner of the +installation directory, simply issue the command: + + make install + +If you are not the "root" user and are using the "sudo" package, use: + + sudo make install + +Verify the installation by viewing the output of "xo --version": + + % xo --version + libxo version 0.3.5-git-develop + xo version 0.3.5-git-develop + +* Formatting with libxo + Most unix 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 in such output. Often programmers need to extract information from this human-oriented output. Programmers use tools like grep, awk, and regular expressions to ferret out the pieces of information they need. Such solutions are fragile and require maintenance when output contents change or evolve, along with testing and validation. Modern tool developers 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. Changes to content can be done in ways that do not break existing users of the data, which can reduce maintenance costs and increase feature velocity. In addition, modern reality means that more output ends up in web browsers than in terminals, making HTML output valuable. libxo 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. A single libxo function call in source code is all that's required: xo_emit("Connecting to {:host}.{:domain}...\n", host, domain); - Text: - Connection to my-box.example.com... + TEXT: + Connecting to my-box.example.com... XML: my-box example.com JSON: "host": "my-box", "domain": "example.com" - -For brevity, the HTML output is emitted. + HTML: +
+
Connecting to
+
my-box
+
.
+
example.com
+
...
+
** Encoding Styles -There are four encoding styles supported by libxo: TEXT, HTML, JSON, -and XML. JSON and XML are suitable for encoding data, while TEXT and -HTML are suited for display to the user. TEXT output can be display -on a terminal session, allowing compatibility with traditional usage. -HTML can be matched with a small CSS file to permit rendering in any -HTML5 browser. XML output is suitable for tools like XPath and -protocols like NETCONF. JSON output can be used for RESTful APIs. +There are four encoding styles supported by libxo: +- TEXT output can be display on a terminal session, allowing +compatibility with traditional command line usage. +- XML output is suitable for tools like XPath and protocols like +NETCONF. +- JSON output can be used for RESTful APIs and integration with +languages like Javascript and Python. +- HTML can be matched with a small CSS file to permit rendering in any +HTML5 browser. + +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 ^xohtml^). + *** Text Output Most traditional programs generate text output on standard output, with contents like: 36 ./src 40 ./bin 90 . In this example (taken from du source code), the code to generate this data might look like: printf("%d\t%s\n", num_blocks, path); Simple, direct, obvious. But it's only making text output. Imagine -using a single code path to make text, XML, JSON or HTML, deciding at +using a single code path to make TEXT, XML, JSON or HTML, deciding at run time which to generate. libxo expands on the idea of printf format strings to make a single format containing instructions for creating multiple output styles: xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path); This line will generate the same text output as the earlier printf call, but also has enough information to generate XML, JSON, and HTML. The following sections introduce the other formats. *** XML Output XML output consists of a hierarchical set of elements, each encoded with a start tag and an end tag. The element should be named for data value that it is encoding: 36 ./src 40 ./bin 90 . XML is a W3C standard for encoding data. See w3c.org/TR/xml for additional information. *** JSON Output JSON output consists of a hierarchical set of objects and lists, each encoded with a quoted name, a colon, and a value. If the value is a string, it must be quoted, but numbers are not quoted. Objects are encoded using braces; lists are encoded using square brackets. Data inside objects and lists is separated using commas: items: [ { "blocks": 36, "path" : "./src" }, { "blocks": 40, "path" : "./bin" }, { "blocks": 90, "path" : "./" } ] *** HTML Output HTML output is designed to allow the output to be rendered in a web browser with minimal effort. Each piece of output data is rendered inside a
element, with a class name related to the role of the data. By using a small set of class attribute values, a CSS stylesheet can render the HTML into rich text that mirrors the traditional text content. Additional attributes can be enabled to provide more details about the data, including data type, description, and an XPath location.
36
./src
40
./bin
90
./
** Format Strings @format-strings@ libxo uses format strings to control the rendering of data into the various output styles. Each format string contains a set of zero or more field descriptions, which describe independent data fields. Each field description contains a set of modifiers, a content string, and zero, one, or two format descriptors. The modifiers tell libxo what the field is and how to treat it, while the format descriptors are formatting instructions using printf-style format strings, telling libxo how to format the field. The field description is placed inside a set of braces, with a colon (":") after the modifiers and a slash ("/") before each format descriptors. Text may be intermixed with field descriptions within the format string. The field description is given as follows: - '{' [ role | modifier ]* ':' [ content ] + '{' [ role | modifier ]* [',' long-names ]* ':' [ content ] [ '/' field-format [ '/' encoding-format ]] '}' 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. 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 xo_emit function as an unsigned integer. - xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65); + xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65); This single line of code can generate text (" In stock: 65\n"), XML ("65"), JSON ('"in-stock": 6'), or HTML (too lengthy to be listed here). -*** Modifier Roles +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: -Modifiers are optional, and indicate the role and formatting of the + xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65); + +*** 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: |---+--------------+-------------------------------------------------| -| M | Name | Description | +| R | Name | Description | |---+--------------+-------------------------------------------------| -| C | color/effect | Field has color and effect controls | +| 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 | +| [ | start-anchor | Begin a section of anchored variable-width text | +| ] | stop-anchor | End a section of anchored variable-width text | |---+--------------+-------------------------------------------------| -**** The Color Role ({C:}) + 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 preceeded by +a comma: + + EXAMPLE: + xo_emit("{,label:Free}{,decoration::}{,padding: }" + "{,value:free/%u} {,units:Blocks}\n", + free_blocks); + +**** The Color Role ({C:}) @color-role@ + Colors and effects control how text values are displayed; they are -used for display styles (TEXT and HTML). 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 ("/"): +used for display styles (TEXT and HTML). - xo_emit("{C:bold}{Lwc:Cost}{:cost/%u}{C:reset}\n", cost); + 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 content should be a comma-separated list of zero or more colors or -display effects. Colors and effects remain in effect until -modified by other "C" roles. If the content is empty, the "reset" -action is performed. +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 | -|---------------| -| black | -| blue | -| cyan | -| default | -| green | -| magenta | -| red | -| white | -| yellow | -|---------------| +|---------+--------------------------------------------| +| Name | Description | +|---------+--------------------------------------------| +| black | | +| blue | | +| cyan | | +| default | Default color for foreground or background | +| green | | +| magenta | | +| red | | +| white | | +| yellow | | +|---------+--------------------------------------------| -Color names are prefixed with either "fg-" or "bg-" to change the -foreground and background colors, respectively. - **** 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); +**** The Gettext Role ({G:}) @gettext-role@ + +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 " command, or an entire .pot can be translated using +the "xopo -f -o " 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 ^howto-i18n^ for additional details. + **** The Label Role ({L:}) Labels are text that appears before a value. xo_emit("{Lwc:Cost}{:cost/%u}\n", cost); **** The Note Role ({N:}) Notes are text that appears after a value. xo_emit("{:cost/%u} {N:per year}\n", cost); -**** The Padding Role ({P:}) +**** The Padding Role ({P:}) @padding-role@ 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); **** 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. **** 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
**** 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); -**** The Anchor Modifiers ({[:} and {]:}) +**** The Anchor Roles ({[:} and {]:}) @anchor-role@ 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. Widths over 8k are considered probable errors and not supported. If XOF_WARN is set, a warning will be generated. -*** Modifier Flags +*** Field Modifiers -The modifiers can also include the following flags, which modify the -content emitted for some output styles: +Field modifiers are flags which modify the way content emitted for +particular output styles: -|---+--------------+-------------------------------------------------| -| M | Name | Description | -|---+--------------+-------------------------------------------------| -| c | colon | A colon (":") is appended after the label | -| d | display | Only emit field for display styles (text/HTML) | -| e | encoding | Only emit for encoding styles (XML/JSON) | -| k | key | Field is a key, suitable for XPath predicates | -| l | leaf-list | Field is a leaf-list -| n | no-quotes | Do not quote the field when using JSON style | -| q | quotes | Quote the field when using JSON style | -| w | white space | A blank (" ") is appended after the label | -|---+--------------+-------------------------------------------------| +|---+---------------+-------------------------------------------------| +| M | Name | Description | +|---+---------------+-------------------------------------------------| +| c | colon | A colon (":") is appended after the label | +| d | display | Only emit field for display styles (text/HTML) | +| e | encoding | Only emit for encoding styles (XML/JSON) | +| g | gettext | Call gettext on field's render content | +| h | humanize (hn) | Format large numbers in human-readable style | +| | hn-space | Humanize: Place space between numeric and unit | +| | hn-decimal | Humanize: Add a decimal digit, if number < 10 | +| | hn-1000 | Humanize: Use 1000 as divisor instead of 1024 | +| k | key | Field is a key, suitable for XPath predicates | +| l | leaf-list | Field is a leaf-list | +| n | no-quotes | Do not quote the field when using JSON style | +| p | plural | Gettext: Use comma-separated plural form | +| q | quotes | Quote the field when using JSON style | +| t | trim | Trim leading and trailing whitespace | +| w | white | A blank (" ") is appended after the label | +|---+---------------+-------------------------------------------------| -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 ('c') and a space ('w'). 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. +Roles and modifiers can also use more verbose names, when preceeded by +a comma. For example, the modifier string "Lwc" (or "L,white,colon") +means the field has a label role (text that describes the next field) +and should be followed by a colon ('c') and a space ('w'). The +modifier string "Vkq" (or ":key,quote") means the field has a value +role (the default role), that it is a key for the current instance, +and that the value should be quoted when encoded for JSON. **** The Colon Modifier ({c:}) The colon modifier appends a single colon to the data value: EXAMPLE: xo_emit("{Lc:Name}{:name}\n", "phil"); TEXT: Name:phil The colon modifier is only used for the TEXT and HTML output styles. It is commonly combined with the space modifier ('{w:}'). It is purely a convenience feature. **** The Display Modifier ({d:}) The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML. EXAMPLE: xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1); TEXT: Name: phil 1 XML: 1 The display modifier is the opposite of the encoding modifier, and they are often used to give to distinct views of the underlying data. **** The Encoding Modifier ({e:}) @e-modifier@ The display modifier indicated the field should only be generated for the display output styles, TEXT and HTML. EXAMPLE: xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1); TEXT: Name: phil XML: phil1 The encoding modifier is the opposite of the display modifier, and they are often used to give to distinct views of the underlying data. +**** The Gettext Modifier ({g:}) @gettext-modifier@ + +The gettext modifier is used to translate individual fields using the +gettext domain (typically set using the "{G:}" role) and current +language settings. Once libxo renders the field value, it is passed +to gettext(3), where it is used as a key to find the native language +translation. + +In the following example, the strings "State" and "full" are passed +to gettext() to find locale-based translated strings. + + xo_emit("{Lgwc:State}{g:state}\n", "full"); + +See ^gettext-role^, ^plural-modifier^, and ^howto-i18n^ for additional +details. + +**** 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. + +"hn" can be used as an alias for "humanize". + +The humanize modifier only affects display styles (TEXT and HMTL). +The "no-humanize" option (See ^LIBXO_OPTIONS^) will block the function of +the humanize modifier. + +There are a number of modifiers that affect details of humanization. +These are only available in as full names, not single characters. The +"hn-space" modifier places a space between the number and any +multiplier symbol, such as "M" or "K" (ex: "44 K"). The "hn-decimal" +modifier will add a decimal point and a single tenths digit when the number is +less than 10 (ex: "4.4K"). The "hn-1000" modifier will use 1000 as divisor +instead of 1024, following the JEDEC-standard instead of the more +natural binary powers-of-two tradition. + + EXAMPLE: + xo_emit("{h:input/%u}, {h,hn-space:output/%u}, " + "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, " + "{h,hn-decimal:remaining/%u}\n", + input, output, errors, capacity, remaining); + TEXT: + 21, 57 K, 96M, 44M, 1.2G + +In the HTML style, the original numeric value is rendered in the +"data-number" attribute on the
element: + +
96M
+ **** The Key Modifier ({k:}) The key modifier is used to indicate that a particular field helps uniquely identify an instance of list data. EXAMPLE: xo_open_list("user"); for (i = 0; i < num_users; i++) { xo_open_instance("user"); xo_emit("User {k:name} has {:count} tickets\n", user[i].u_name, user[i].u_tickets); xo_close_instance("user"); } xo_close_list("user"); Currently the key modifier is only used when generating XPath value for the HTML output style when XOF_XPATH is set, but other uses are likely in the near future. **** The Leaf-List Modifier ({l:}) The leaf-list modifier is used to distinguish lists where each instance consists of only a single value. In XML, these are rendered as single elements, where JSON renders them as arrays. EXAMPLE: for (i = 0; i < num_users; i++) { xo_emit("Member {l:user}\n", user[i].u_name); } XML: phil pallavi JSON: "user": [ "phil", "pallavi" ] The name of the field must match the name of the leaf list. **** The No-Quotes Modifier ({n:}) The no-quotes modifier (and its twin, the 'quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller. EXAMPLE: const char *bool = is_true ? "true" : "false"; xo_emit("{n:fancy/%s}", bool); JSON: "fancy": true +**** The Plural Modifier ({p:}) @plural-modifier@ + +The plural modifier selects the appropriate plural form of an +expression based on the most recent number emitted and the current +language settings. The contents of the field should be the singular +and plural English values, separated by a comma: + + xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes); + +The plural modifier is meant to work with the gettext modifier ({g:}) +but can work independently. See ^gettext-modifier^. + +When used without the gettext modifier or when the message does not +appear in the message catalog, the first token is chosen when the last +numeric value is equal to 1; otherwise the second value is used, +mimicking the simple pluralization rules of English. + +When used with the gettext modifier, the ngettext(3) function is +called to handle the heavy lifting, using the message catalog to +convert the singular and plural forms into the native language. + **** The Quotes Modifier ({q:}) The quotes modifier (and its twin, the 'no-quotes' modifier) affect the quoting of values in the JSON output style. JSON uses quotes for string value, but no quotes for numeric, boolean, and null data. xo_emit applies a simple heuristic to determine whether quotes are needed, but often this needs to be controlled by the caller. EXAMPLE: xo_emit("{q:time/%d}", 2014); JSON: "year": "2014" **** The White Space Modifier ({w:}) The white space modifier appends a single space to the data value: EXAMPLE: xo_emit("{Lw:Name}{:name}\n", "phil"); TEXT: Name phil The white space modifier is only used for the TEXT and HTML output styles. It is commonly combined with the colon modifier ('{c:}'). It is purely a convenience feature. Note that the sense of the 'w' modifier is reversed for the units role ({Uw:}); a blank is added before the contents, rather than after it. *** 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 that the minumum width, the value will be padded to reach the minimum. - a period followed by one or more digits indicating the maximum number of bytes which will be examined for a string argument, or the maximum width for a non-string argument. When handling ASCII strings this 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 | |-----+-------------+--------------------| *** 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". 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. 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 are in used in filling those -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
.
-*** "%n" is Not Supported +*** "%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. +*** Argument Validation @printf-like@ + +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 | +|------------------+------------------------| + *** 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
** Command-line Arguments libxo uses command line options to trigger rendering behavior. The following options are recognised: - --libxo - --libxo= - --libxo: Options is a comma-separated list of tokens that correspond to output styles, flags, or features: -|-----------+-------------------------------------------------------| -| Token | Action | -|-----------+-------------------------------------------------------| -| dtrt | Enable "Do The Right Thing" mode | -| html | Emit HTML output | -| indent=xx | Set the indentation level | -| info | Add info attributes (HTML) | -| json | Emit JSON output | -| keys | Emit the key attribute for keys (XML) | -| no-locale | Do not initialize the locale setting | -| no-top | Do not emit a top set of braces (JSON) | -| not-first | Pretend the 1st output item was not 1st (JSON) | -| pretty | Emit pretty-printed output | -| text | Emit TEXT output | -| units | Add the 'units' (XML) or 'data-units (HTML) attribute | -| warn | Emit warnings when libxo detects bad calls | -| warn-xml | Emit warnings in XML | -| xml | Emit XML output | -| xpath | Add XPath expressions (HTML) | -|-----------+-------------------------------------------------------| +|-------------+-------------------------------------------------------| +| Token | Action | +|-------------+-------------------------------------------------------| +| color | Enable colors/effects for display styles (TEXT, HTML) | +| dtrt | Enable "Do The Right Thing" mode | +| html | Emit HTML output | +| indent=xx | Set the indentation level | +| info | Add info attributes (HTML) | +| json | Emit JSON output | +| keys | Emit the key attribute for keys (XML) | +| log-gettext | Log (via stderr) each gettext(3) string lookup | +| log-syslog | Log (via stderr) each syslog message (via xo_syslog) | +| no-humanize | Ignore the {h:} modifier (TEXT, HTML) | +| no-locale | Do not initialize the locale setting | +| no-top | Do not emit a top set of braces (JSON) | +| not-first | Pretend the 1st output item was not 1st (JSON) | +| pretty | Emit pretty-printed output | +| text | Emit TEXT output | +| underscores | Replace XML-friendly "-"s with JSON friendly "_"s e | +| units | Add the 'units' (XML) or 'data-units (HTML) attribute | +| warn | Emit warnings when libxo detects bad calls | +| warn-xml | Emit warnings in XML | +| xml | Emit XML output | +| xpath | Add XPath expressions (HTML) | +|-------------+-------------------------------------------------------| The brief options are detailed in ^LIBXO_OPTIONS^. ** Representing Hierarchy 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. *** 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 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. int xo_open_container_h (xo_handle_t *xop, const char *name); int xo_open_container (const char *name); To close a level, use the xo_close_container() or xo_close_container_h() functions: int xo_close_container_h (xo_handle_t *xop, const char *name); int xo_close_container (const char *name); 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. 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
*** 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: 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. *** 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); Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance: xo_open_container("top"); ... xo_close_container_d(); This also works for lists and instances: xo_open_list("item"); for (...) { xo_open_instance("item"); xo_emit(...); xo_close_instance_d(); } xo_close_list_d(); Note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match. *** Markers Markers are used to protect and restore the state of open constructs. While a marker is open, no other open constructs can be closed. When a marker is closed, all constructs open since the marker was opened will be closed. Markers use names which are not user-visible, allowing the caller to choose appropriate internal names. In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish-guts" is used to ensure that any constructs opened by the function are closed properly. for (i = 0; fish[i]; i++) { xo_open_instance("fish"); xo_open_marker("fish-guts"); dump_fish_details(i); xo_close_marker("fish-guts"); } -** Handles +** 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. A default handle is used when a NULL is passed to functions accepting a handle. This handle is initialized to write its data to stdout using the default style of text (XO_STYLE_TEXT). For the convenience of callers, the libxo library includes handle-less functions that implicitly use the default handle. Any function that takes a handle will use the default handle is a value of NULL is passed in place of a valid 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(). ** UTF-8 All strings for libxo must be UTF-8. libxo will handle turning them into locale-based strings for display to the user. The only exception is argument formatted using the "%ls" format, which require a wide character string (wchar_t *) as input. 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("Alll strings are utf-8 content {:tag/%ls}", L"except for wide strings"); "%S" is equivalent to "%ls". * The libxo API This section gives details about the functions in libxo, how to call them, and the actions they perform. ** Handles 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 to standard output. The xo_set_style and xo_set_flags functions can be used to change this behavior. Many libxo functions take a handle as their first parameter; most that do not use the default handle. Any function taking a handle can be passed NULL to access the default handle. 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. *** xo_create A handle can be allocated using the xo_create() function: xo_handle_t *xo_create (unsigned style, unsigned flags); Example: xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN); .... xo_emit_h(xop, "testing\n"); See also ^styles^ and ^flags^. *** xo_create_to_file By default, libxo writes output to standard output. A convenience function is provided for situations when output should be written to a different file: xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, unsigned flags); Use the XOF_CLOSE_FP flag to trigger a call to fclose() for the FILE pointer when the handle is destroyed. *** xo_set_writer The xo_set_writer function allows custom 'write' functions which can tailor how libxo writes data. An opaque argument is recorded and passed back to the write function, allowing the function to acquire context information. The 'close' function can release this opaque data and any other resources as needed. The flush function can flush buffered data associated with the opaque object. void xo_set_writer (xo_handle_t *xop, void *opaque, xo_write_func_t write_func, xo_close_func_t close_func); xo_flush_func_t flush_func); *** xo_set_style To set the style, use the xo_set_style() function: void xo_set_style(xo_handle_t *xop, unsigned style); To use the default handle, pass a NULL handle: xo_set_style(NULL, XO_STYLE_XML); **** Output Styles (XO_STYLE_*) @styles@ 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 | |---------------+-------------------------| **** xo_set_style_name The xo_set_style_name() can be used to set the style based on a name encoded as a string: int xo_set_style_name (xo_handle_t *xop, const char *style); The name can be any of the styles: "text", "xml", "json", or "html". EXAMPLE: xo_set_style_name(NULL, "html"); *** xo_set_flags To set the flags, use the xo_set_flags() function: void xo_set_flags(xo_handle_t *xop, unsigned flags); To use the default handle, pass a NULL handle: xo_set_style(NULL, XO_STYLE_XML); **** Flags (XOF_*) @flags@ The set of valid flags include: -|-----------------+---------------------------------------| -| Flag | Description | -|-----------------+---------------------------------------| -| XOF_CLOSE_FP | Close file pointer on xo_destroy() | -| 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 LIBXO_OPTIONS env var | -| XOF_PRETTY | Make 'pretty printed' output | -| XOF_UNDERSCORES | Replaces hyphens with underscores | -| XOF_UNITS | Display units (XML and 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 | -|-----------------+---------------------------------------| +|-------------------+----------------------------------------| +| 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 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 ^info^ 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 **** xo_clear_flags The xo_clear_flags() function turns off the given flags in a specific handle. void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags); **** xo_set_options The xo_set_options() function accepts a comma-separated list of styles and flags and enables them for a specific handle. int xo_set_options (xo_handle_t *xop, const char *input); The options are identical to those listed in ^command-line-arguments^. *** xo_destroy 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. void xo_destroy(xo_handle_t *xop); ** Emitting Content (xo_emit) The following functions are used to emit output: int xo_emit (const char *fmt, ...); int xo_emit_h (xo_handle_t *xop, const char *fmt, ...); int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap); The "fmt" argument is a string containing field descriptors as specified in ^format-strings^. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See ^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(). *** Attributes (xo_attr) @xo_attr@ The xo_attr() function emits attributes for the XML output style. int xo_attr (const char *name, const char *fmt, ...); int xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...); int xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap); 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(). 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 xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted. Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form. *** Flushing Output (xo_flush) libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this: void xo_flush (void); void xo_flush_h (xo_handle_t *xop); Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);". *** Finishing Output (xo_finish) When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations. - void xo_finish (void); - void xo_finish_h (xo_handle_t *xop); + int xo_finish (void); + int xo_finish_h (xo_handle_t *xop); + void xo_finish_atexit (void); Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles. +xo_finish_atexit is suitable for use with atexit(3). + ** Emitting Hierarchy libxo represents to types of hierarchy: containers and 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. To create a container, use the xo_open_container and xo_close_container functions: int xo_open_container (const char *name); int xo_open_container_h (xo_handle_t *xop, const char *name); int xo_open_container_hd (xo_handle_t *xop, const char *name); int xo_open_container_d (const char *name); int xo_close_container (const char *name); int xo_close_container_h (xo_handle_t *xop, const char *name); int xo_close_container_hd (xo_handle_t *xop); int xo_close_container_d (void); 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. The close functions with the "_d" suffix are used in "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by libxo to allow the caller to avoid keeping track of the open container name. Use the 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 when the XOF_XPATH flag is set. EXAMPLE: xo_open_container("system"); xo_emit("The host name is {:host-name}\n", hn); xo_close_container("system"); XML: foo *** Lists and Instances 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. 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("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", } ] -** Additional Functionality +** Support Functions -*** Parsing Command-line Arguments (xo_parse_args) +*** Parsing Command-line Arguments (xo_parse_args) @xo_parse_args@ 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 it emitted and -1 is returned. argc = xo_parse_args(argc, argv); if (argc < 0) - exit(1); + exit(EXIT_FAILURE); Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See ^command-line-arguments^ for a description of valid arguments. *** xo_set_program The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value. 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. *** xo_set_version 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. void xo_set_version (const char *version); void xo_set_version_h (xo_handle_t *xop, const char *version); *** Field Information (xo_info_t) @info@ 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
*** Memory Allocation The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available. void xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func); realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment. By default, the standard realloc() and free() functions are used. *** LIBXO_OPTIONS @LIBXO_OPTIONS@ The environment variable "LIBXO_OPTIONS" can be set to a string of options: -|--------+-------------------------------------------| -| Option | Action | -|--------+-------------------------------------------| -| H | Enable HTML output (XO_STYLE_HTML) | -| I | Enable info output (XOF_INFO) | -| i | Indent by | -| J | Enable JSON output (XO_STYLE_JSON) | -| P | Enable pretty-printed output (XOF_PRETTY) | -| T | Enable text output (XO_STYLE_TEXT) | -| W | Enable warnings (XOF_WARN) | -| X | Enable XML output (XO_STYLE_XML) | -| x | Enable XPath data (XOF_XPATH) | -|--------+-------------------------------------------| +|--------+---------------------------------------------| +| Option | Action | +|--------+---------------------------------------------| +| c | Enable color/effects for TEXT/HTML | +| F | Force line-buffered flushing | +| H | Enable HTML output (XO_STYLE_HTML) | +| I | Enable info output (XOF_INFO) | +| i | Indent by | +| J | Enable JSON output (XO_STYLE_JSON) | +| k | Add keys to XPATH expressions in HTML | +| n | Disable humanization (TEXT, HTML) | +| P | Enable pretty-printed output (XOF_PRETTY) | +| T | Enable text output (XO_STYLE_TEXT) | +| U | Add units to HTML output | +| u | Change "-"s to "_"s in element names (JSON) | +| W | Enable warnings (XOF_WARN) | +| X | Enable XML output (XO_STYLE_XML) | +| x | Enable XPath data (XOF_XPATH) | +|--------+---------------------------------------------| For example, warnings can be enabled by: % env LIBXO_OPTIONS=W my-app Complete HTML output can be generated with: % env LIBXO_OPTIONS=HXI my-app Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "--libxo" option is preferable in most situations. *** Errors, Warnings, and Messages Many programs make use of the standard library functions err() and warn() 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); *** xo_error The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements: EXAMPLE:: xo_error("Does not %s", "compute"); XML:: Does not compute JSON:: "error": { "message": "Does not compute" } *** xo_no_setlocale 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. void xo_no_setlocale (void); +** 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: + +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 ^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. + +*** Priority, Facility, and Flags @priority@ + +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. login(1)) | +| LOG_AUTHPRIV | As LOG_AUTH, but logged to a privileged file | +| LOG_CRON | The cron daemon: 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 ipfw(4) | +| LOG_SYSLOG | Messages generated internally by 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 behaviors. + +|------------+----------------------------------------------------| +| Flag | Description | +|------------+----------------------------------------------------| +| LOG_CONS | If syslogd fails, attempt to write to /dev/console | +| LOG_NDELAY | Open the connection to syslogd(8) immediately | +| LOG_PERROR | Write the message also to standard error output | +| LOG_PID | Log the process id with each message | +|------------+----------------------------------------------------| + +*** xo_syslog + +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 + +**** xo_vsyslog + +xo_vsyslog is identical in function to xo_syslog, but takes the set of +arguments using a va_list. + + 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); + } + +**** xo_open_log + +xo_open_log functions similar to openlog(3), allowing customization of +the program name, the log facility number, and the additional option +flags described in ^priority^. + + void + xo_open_log (const char *ident, int logopt, int facility); + +**** xo_close_log + +xo_close_log functions similar to closelog(3), closing the log file +and releasing any associated resources. + + void + xo_close_log (void); + +**** xo_set_logmask + +xo_set_logmask function similar to 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. + + int + xo_set_logmask (int maskpri); + + Example: + setlogmask(LOG_UPTO(LOG_WARN)); + +**** xo_set_syslog_enterprise_id + +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. + + void + xo_set_syslog_enterprise_id (unsigned short eid); + +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. + +libxo source contain an encoder for Concise Binary Object +Representation, aka CBOR (RFC 7049) which can be used as used as an +example for the API. + +*** 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. + * The "xo" Utility The "xo" utility allows command line access to the functionality of the libxo library. Using "xo", shell scripts can emit XML, JSON, and HTML using the same commands that emit text output. The style of output can be selected using a specific option: "-X" for XML, "-J" for JSON, "-H" for HTML, or "-T" for TEXT, which is the default. The "--style ardinalyayammetersgrayErmissionpay eniedday6otuslay-oyay-eltayay \ No newline at end of file Index: head/contrib/libxo/tests/gettext/saved/gt_01.XP.err =================================================================== Index: head/contrib/libxo/tests/gettext/saved/gt_01.XP.out =================================================================== --- head/contrib/libxo/tests/gettext/saved/gt_01.XP.out (nonexistent) +++ head/contrib/libxo/tests/gettext/saved/gt_01.XP.out (revision 287111) @@ -0,0 +1,49 @@ + + amingflay + ordsway + urningbay + ymay + ouchcay + amingflay + ordsway + urningbay + ymay + ouchcay + 0 + 1 + 2 + 3 + 4 + 1234 + 1234 + foop + 4321 + + 1234 + foop + 4321 + + 1234 + foop + 4321 + + 3 + 1.2.3 + Tue Jun 23 18:47:09 UTC 2015 + <__warning> + gt_01.test + Nableuay otay ectulatobjay orwardfay elocipingvay + ectulatobjay + Ermissionpay eniedday + + <__warning> + gt_01.test + automaticyay ynchronizationsay ofyay ardinalyay ammetersgray ailedfay + + ardinalyay + ammetersgray + Ermissionpay eniedday + + 6 + otuslay-oyay-eltayay + Index: head/contrib/libxo/tests/gettext/strerror.pot =================================================================== --- head/contrib/libxo/tests/gettext/strerror.pot (nonexistent) +++ head/contrib/libxo/tests/gettext/strerror.pot (revision 287111) @@ -0,0 +1,468 @@ +# +# Copyright (c) 1982, 1985, 1993 +# The Regents of the University of California. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# 4. Neither the name of the University nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +# SUCH DAMAGE. +# +# List of system errors ala strerror() and sys_errlist +# Phil Shafer , 2015. +# +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2015-07-01 16:15-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=CHARSET\n" +"Content-Transfer-Encoding: 8bit\n" + +msgid "Received {:received} {N:byte,bytes} from {:from}#{:port} in {:time} ms\n" +msgstr "" + +# 0 - ENOERROR +msgid "No error: 0" +msgstr "" + +# 1 - EPERM +msgid "Operation not permitted" +msgstr "" + +# 2 - ENOENT +msgid "No such file or directory" +msgstr "" + +# 3 - ESRCH +msgid "No such process" +msgstr "" + +# 4 - EINTR +msgid "Interrupted system call" +msgstr "" + +# 5 - EIO +msgid "Input/output error" +msgstr "" + +# 6 - ENXIO +msgid "Device not configured" +msgstr "" + +# 7 - E2BIG +msgid "Argument list too long" +msgstr "" + +# 8 - ENOEXEC +msgid "Exec format error" +msgstr "" + +# 9 - EBADF +msgid "Bad file descriptor" +msgstr "" + +# 10 - ECHILD +msgid "No child processes" +msgstr "" + +# 11 - EDEADLK +msgid "Resource deadlock avoided" +msgstr "" + +# 12 - ENOMEM +msgid "Cannot allocate memory" +msgstr "" + +# 13 - EACCES +msgid "Permission denied" +msgstr "" + +# 14 - EFAULT +msgid "Bad address" +msgstr "" + +# 15 - ENOTBLK +msgid "Block device required" +msgstr "" + +# 16 - EBUSY +msgid "Device busy" +msgstr "" + +# 17 - EEXIST +msgid "File exists" +msgstr "" + +# 18 - EXDEV +msgid "Cross-device link" +msgstr "" + +# 19 - ENODEV +msgid "Operation not supported by device" +msgstr "" + +# 20 - ENOTDIR +msgid "Not a directory" +msgstr "" + +# 21 - EISDIR +msgid "Is a directory" +msgstr "" + +# 22 - EINVAL +msgid "Invalid argument" +msgstr "" + +# 23 - ENFILE +msgid "Too many open files in system" +msgstr "" + +# 24 - EMFILE +msgid "Too many open files" +msgstr "" + +# 25 - ENOTTY +msgid "Inappropriate ioctl for device" +msgstr "" + +# 26 - ETXTBSY +msgid "Text file busy" +msgstr "" + +# 27 - EFBIG +msgid "File too large" +msgstr "" + +# 28 - ENOSPC +msgid "No space left on device" +msgstr "" + +# 29 - ESPIPE +msgid "Illegal seek" +msgstr "" + +# 30 - EROFS +msgid "Read-only file system" +msgstr "" + +# 31 - EMLINK +msgid "Too many links" +msgstr "" + +# 32 - EPIPE +msgid "Broken pipe" +msgstr "" + +# +# math software +# + +# 33 - EDOM +msgid "Numerical argument out of domain" +msgstr "" + +# 34 - ERANGE +msgid "Result too large" +msgstr "" + +# +# non-blocking and interrupt i/o +# + +# 35 - EAGAIN +# 35 - EWOULDBLOCK +msgid "Resource temporarily unavailable" +msgstr "" + +# 36 - EINPROGRESS +msgid "Operation now in progress" +msgstr "" + +# 37 - EALREADY +msgid "Operation already in progress" +msgstr "" + + +# +# ipc/network software -- argument errors +# + +# 38 - ENOTSOCK +msgid "Socket operation on non-socket" +msgstr "" + +# 39 - EDESTADDRREQ +msgid "Destination address required" +msgstr "" + +# 40 - EMSGSIZE +msgid "Message too long" +msgstr "" + +# 41 - EPROTOTYPE +msgid "Protocol wrong type for socket" +msgstr "" + +# 42 - ENOPROTOOPT +msgid "Protocol not available" +msgstr "" + +# 43 - EPROTONOSUPPORT +msgid "Protocol not supported" +msgstr "" + +# 44 - ESOCKTNOSUPPORT +msgid "Socket type not supported" +msgstr "" + +# 45 - EOPNOTSUPP +msgid "Operation not supported" +msgstr "" + +# 46 - EPFNOSUPPORT +msgid "Protocol family not supported" +msgstr "" + +# 47 - EAFNOSUPPORT +msgid "Address family not supported by protocol family" +msgstr "" + +# 48 - EADDRINUSE +msgid "Address already in use" +msgstr "" + +# 49 - EADDRNOTAVAIL +msgid "Can't assign requested address" +msgstr "" + +# +# ipc/network software -- operational errors +# + +# 50 - ENETDOWN +msgid "Network is down" +msgstr "" + +# 51 - ENETUNREACH +msgid "Network is unreachable" +msgstr "" + +# 52 - ENETRESET +msgid "Network dropped connection on reset" +msgstr "" + +# 53 - ECONNABORTED +msgid "Software caused connection abort" +msgstr "" + +# 54 - ECONNRESET +msgid "Connection reset by peer" +msgstr "" + +# 55 - ENOBUFS +msgid "No buffer space available" +msgstr "" + +# 56 - EISCONN +msgid "Socket is already connected" +msgstr "" + +# 57 - ENOTCONN +msgid "Socket is not connected" +msgstr "" + +# 58 - ESHUTDOWN +msgid "Can't send after socket shutdown" +msgstr "" + +# 59 - ETOOMANYREFS +msgid "Too many references: can't splice" +msgstr "" + +# 60 - ETIMEDOUT +msgid "Operation timed out" +msgstr "" + +# 61 - ECONNREFUSED +msgid "Connection refused" +msgstr "" + +# 62 - ELOOP +msgid "Too many levels of symbolic links" +msgstr "" + +# 63 - ENAMETOOLONG +msgid "File name too long" +msgstr "" + +# +# should be rearranged +# + +# 64 - EHOSTDOWN +msgid "Host is down" +msgstr "" + +# 65 - EHOSTUNREACH +msgid "No route to host" +msgstr "" + +# 66 - ENOTEMPTY +msgid "Directory not empty" +msgstr "" + +# +# quotas & mush +# + +# 67 - EPROCLIM +msgid "Too many processes" +msgstr "" + +# 68 - EUSERS +msgid "Too many users" +msgstr "" + +# 69 - EDQUOT +msgid "Disc quota exceeded" +msgstr "" + +# +# Network File System +# + +# 70 - ESTALE +msgid "Stale NFS file handle" +msgstr "" + +# 71 - EREMOTE +msgid "Too many levels of remote in path" +msgstr "" + +# 72 - EBADRPC +msgid "RPC struct is bad" +msgstr "" + +# 73 - ERPCMISMATCH +msgid "RPC version wrong" +msgstr "" + +# 74 - EPROGUNAVAIL +msgid "RPC prog. not avail" +msgstr "" + +# 75 - EPROGMISMATCH +msgid "Program version wrong" +msgstr "" + +# 76 - EPROCUNAVAIL +msgid "Bad procedure for program" +msgstr "" + +# 77 - ENOLCK +msgid "No locks available" +msgstr "" + +# 78 - ENOSYS +msgid "Function not implemented" +msgstr "" + +# 79 - EFTYPE +msgid "Inappropriate file type or format" +msgstr "" + +# 80 - EAUTH +msgid "Authentication error" +msgstr "" + +# 81 - ENEEDAUTH +msgid "Need authenticator" +msgstr "" + +# 82 - EIDRM +msgid "Identifier removed" +msgstr "" + +# 83 - ENOMSG +msgid "No message of desired type" +msgstr "" + +# 84 - EOVERFLOW +msgid "Value too large to be stored in data type" +msgstr "" + +# 85 - ECANCELED +msgid "Operation canceled" +msgstr "" + +# 86 - EILSEQ +msgid "Illegal byte sequence" +msgstr "" + +# 87 - ENOATTR +msgid "Attribute not found" +msgstr "" + +# +# General +# + +# 88 - EDOOFUS +msgid "Programming error" +msgstr "" + +# 89 - EBADMSG +msgid "Bad message" +msgstr "" + +# 90 - EMULTIHOP +msgid "Multihop attempted" +msgstr "" + +# 91 - ENOLINK +msgid "Link has been severed" +msgstr "" + +# 92 - EPROTO +msgid "Protocol error" +msgstr "" + +# 93 - ENOTCAPABLE +msgid "Capabilities insufficient" +msgstr "" + +# 94 - ECAPMODE +msgid "Not permitted in capability mode" +msgstr "" + +# 95 - ENOTRECOVERABLE +msgid "State not recoverable" +msgstr "" + +# 96 - EOWNERDEAD +msgid "Previous owner died" +msgstr "" Index: head/contrib/libxo/xo/Makefile.am =================================================================== --- head/contrib/libxo/xo/Makefile.am (revision 287110) +++ head/contrib/libxo/xo/Makefile.am (revision 287111) @@ -1,35 +1,43 @@ # # 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 include ${top_srcdir}/warnings.mk AM_CFLAGS = \ -DLIBXO_XMLSOFT_NEED_PRIVATE \ -I${top_builddir} \ -I${top_srcdir} \ -I${top_srcdir}/libxo \ ${WARNINGS} LIBS = \ ${LIBXO_LIBS} bin_PROGRAMS = xo xo_SOURCES = xo.c #xo_LDADD = ../libxo/libxo.la #xo_LDFLAGS = -static LDADD = \ ${top_builddir}/libxo/libxo.la +if HAVE_HUMANIZE_NUMBER +LDADD += -lutil +endif + man_MANS = xo.1 EXTRA_DIST = xo.1 + +install-data-hook: + for file in ${man_MANS}; do \ + cat ../libxo/add.man >> ${DESTDIR}${man1dir}/$$file ; done Index: head/contrib/libxo/xo/xo.1 =================================================================== --- head/contrib/libxo/xo/xo.1 (revision 287110) +++ head/contrib/libxo/xo/xo.1 (revision 287111) @@ -1,198 +1,173 @@ .\" # .\" # 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 "12345678901234567" .It Fl "-close " Close tags for the given path .It Fl "-depth " Set the depth for pretty printing .It Fl "-help" Display this help text .It Fl "-html OR -H" Generate HTML output .It Fl "-json OR -J" Generate JSON output .It Fl "-leading-xpath " Add a prefix to generated XPaths (HTML) .It Fl "-open " Open tags for the given path .It Fl "-pretty OR -p" Make 'pretty' output (add indent, newlines) .It Fl "-style