Author: phil
Date: Fri Apr 15 18:46:15 2016
New Revision: 298083
URL: https://svnweb.freebsd.org/changeset/base/298083
Log:
Import to 0.6.1
0.5.0:
document "trim" modifier
add xo_emit_field functions
Add xo_set_file{,_h} functions
Fix LIBXO_* variables; add -L and -I as needed
add --disable-silent-rules and an explicit make;
s/PACKAGE-NAME/PACKAGE_NAME/; add /download/ to 'url'
fix silliness where xo_flush_h emitted closing tag (html); make the
caller (xo_message) do it
flush after transitions; fix flush call in xo_do_emit
mkdir the version-specific packaging dir
use "XO_" instead of LIBXO_
0.6.0:
Add --with-retain-size to set the size (in bits) of the retain hash
buckets
Add The Argument Modifier ({a:})
Add retain and no-retain to --libxo
autoconf: Add test for monitor.h
Document quote heuristic
go deep with nroff backslashes
Use "ULL" for 32 bit check
add xo_retain_clear and xo_retain_clear_all
docs: combine two 'handles' section; move command line argument section
handle GETTEXT when msgfmt isn't where it's supposed to be (FreeBSD)
make 'retain' a flag (XOEF_RETAIN) instead of a role; it's simpler, and
doesn't feel as tacky. "{R:}" was painful to document, which means it's painful
to use.
new xo_emit_f functions
nuke some unused UNUSEDs
test code: path must be static
update test cases
0.6.1:
fix version number (missed a commit during new-release)
Reviewed by: sjg
Approved by: sjg (mentor)
Added:
head/contrib/libxo/libxo/xo_emit_f.3
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/libxo/xo_emit_f.3
head/contrib/libxo/tests/core/saved/test_12.E.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.E.err
head/contrib/libxo/tests/core/saved/test_12.E.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.E.out
head/contrib/libxo/tests/core/saved/test_12.H.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.H.err
head/contrib/libxo/tests/core/saved/test_12.H.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.H.out
head/contrib/libxo/tests/core/saved/test_12.HIPx.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.HIPx.err
head/contrib/libxo/tests/core/saved/test_12.HIPx.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.HIPx.out
head/contrib/libxo/tests/core/saved/test_12.HP.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.HP.err
head/contrib/libxo/tests/core/saved/test_12.HP.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.HP.out
head/contrib/libxo/tests/core/saved/test_12.J.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.J.err
head/contrib/libxo/tests/core/saved/test_12.J.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.J.out
head/contrib/libxo/tests/core/saved/test_12.JP.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.JP.err
head/contrib/libxo/tests/core/saved/test_12.JP.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.JP.out
head/contrib/libxo/tests/core/saved/test_12.T.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.T.err
head/contrib/libxo/tests/core/saved/test_12.T.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.T.out
head/contrib/libxo/tests/core/saved/test_12.X.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.X.err
head/contrib/libxo/tests/core/saved/test_12.X.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.X.out
head/contrib/libxo/tests/core/saved/test_12.XP.err
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.XP.err
head/contrib/libxo/tests/core/saved/test_12.XP.out
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/saved/test_12.XP.out
head/contrib/libxo/tests/core/test_12.c
- copied unchanged from r298078,
vendor/Juniper/libxo/dist/tests/core/test_12.c
Modified:
head/contrib/libxo/Makefile.am
head/contrib/libxo/configure.ac
head/contrib/libxo/doc/libxo-manual.html
head/contrib/libxo/doc/libxo.txt
head/contrib/libxo/encoder/cbor/enc_cbor.c
head/contrib/libxo/libxo-config.in
head/contrib/libxo/libxo/libxo.c
head/contrib/libxo/libxo/xo.h
head/contrib/libxo/libxo/xo_format.5
head/contrib/libxo/libxo/xo_parse_args.3
head/contrib/libxo/packaging/libxo.pc.in
head/contrib/libxo/packaging/libxo.rb.base.in
head/contrib/libxo/tests/core/Makefile.am
head/contrib/libxo/tests/core/saved/test_01.E.out
head/contrib/libxo/tests/core/saved/test_01.H.out
head/contrib/libxo/tests/core/saved/test_01.HIPx.out
head/contrib/libxo/tests/core/saved/test_01.HP.out
head/contrib/libxo/tests/core/saved/test_01.J.out
head/contrib/libxo/tests/core/saved/test_01.JP.out
head/contrib/libxo/tests/core/saved/test_01.T.out
head/contrib/libxo/tests/core/saved/test_01.X.out
head/contrib/libxo/tests/core/saved/test_01.XP.out
head/contrib/libxo/tests/core/test_01.c
head/contrib/libxo/tests/core/test_02.c
head/contrib/libxo/tests/gettext/gt_01.c
head/lib/libxo/add.man
head/lib/libxo/xo_config.h
Directory Properties:
head/contrib/libxo/ (props changed)
Modified: head/contrib/libxo/Makefile.am
==============================================================================
--- head/contrib/libxo/Makefile.am Fri Apr 15 18:43:54 2016
(r298082)
+++ head/contrib/libxo/Makefile.am Fri Apr 15 18:46:15 2016
(r298083)
@@ -77,6 +77,7 @@ GH_PAGES_PACKAGE_DIR = ${GH_PAGES_DIR}/$
packages:
@-[ -d ${GH_PAGES_DIR} ] && set -x \
&& echo "Updating packages on gh-pages ..." \
+ && mkdir -p ${GH_PAGES_DIR}/${GH_PACKAGING_DIR} \
&& SHA1="`openssl sha1 ${PACKAGE_FILE} | awk '{print $$2}'`" \
&& SHA256="`openssl sha256 ${PACKAGE_FILE} | awk '{print
$$2}'`" \
&& SIZE="`ls -l ${PACKAGE_FILE} | awk '{print $$5}'`" \
Modified: head/contrib/libxo/configure.ac
==============================================================================
--- head/contrib/libxo/configure.ac Fri Apr 15 18:43:54 2016
(r298082)
+++ head/contrib/libxo/configure.ac Fri Apr 15 18:46:15 2016
(r298083)
@@ -12,7 +12,7 @@
#
AC_PREREQ(2.2)
-AC_INIT([libxo], [0.4.7], [p...@juniper.net])
+AC_INIT([libxo], [0.6.1], [p...@juniper.net])
AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability])
# Support silent build rules. Requires at least automake-1.11.
@@ -74,6 +74,7 @@ AC_CHECK_HEADERS([ctype.h errno.h stdio.
AC_CHECK_HEADERS([string.h sys/param.h unistd.h ])
AC_CHECK_HEADERS([sys/sysctl.h])
AC_CHECK_HEADERS([threads.h])
+AC_CHECK_HEADERS([monitor.h])
dnl humanize_number(3) is a great function, but it's not standard.
dnl Note Macosx has the function in libutil.a but doesn't ship the
@@ -148,10 +149,18 @@ 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)
+if test -x ${GETTEXT_PREFIX}/bin/msgfmt ; then
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/bin
+elif test -x ${GETTEXT_PREFIX}/local/bin/msgfmt ; then
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/local/bin
+else
+ AC_MSG_NOTICE("could not find msgfmt tool")
+ # Use a (bad) fall back value
+ GETTEXT_BINDIR=${GETTEXT_PREFIX}/bin
+fi
+AC_SUBST(GETTEXT_BINDIR)
AM_CONDITIONAL([HAVE_GETTEXT], [test "$HAVE_GETTEXT" = "yes"])
@@ -287,6 +296,18 @@ if test "${LIBXO_WCWIDTH}" != "no"; then
AC_DEFINE([LIBXO_WCWIDTH], [1], [Enable local wcwidth implementation])
fi
+AC_MSG_CHECKING([retain hash bucket size])
+AC_ARG_WITH(retain-size,
+ [ --with-retain-size=[DIR] Specify retain hash bucket size
(in bits)],
+ [XO_RETAIN_SIZE=$withval],
+ [XO_RETAIN_SIZE=default]
+)
+
+AC_MSG_RESULT([$XO_RETAIN_SIZE])
+if test "${XO_RETAIN_SIZE}" != "default"; then
+ AC_DEFINE_UNQUOTED([XO_RETAIN_SIZE], ${XO_RETAIN_SIZE}, [Retain hash bucket
size])
+fi
+
AC_CHECK_LIB([m], [lrint])
AM_CONDITIONAL([HAVE_LIBM], [test "$HAVE_LIBM" != "no"])
@@ -347,12 +368,15 @@ XO_SRCDIR=${srcdir}
XO_LIBDIR=${libdir}
XO_BINDIR=${bindir}
XO_INCLUDEDIR=${includedir}
+XO_CFLAGS="${CFLAGS}"
+AC_SUBST(XO_LIBS)
AC_SUBST(XO_SRCDIR)
AC_SUBST(XO_LIBDIR)
AC_SUBST(XO_BINDIR)
AC_SUBST(XO_INCLUDEDIR)
AC_SUBST(XO_LIBEXT)
+AC_SUBST(XO_CFLAGS)
AC_ARG_WITH(encoder-dir,
[ --with-encoder-dir=[DIR] Specify location of encoder
libraries],
@@ -449,4 +473,5 @@ AC_MSG_NOTICE([summary of build options:
isthreaded: ${HAVE_ISTHREADED:-no}
thread-local: ${THREAD_LOCAL:-no}
local wcwidth: ${LIBXO_WCWIDTH:-no}
+ retain size: ${XO_RETAIN_SIZE:-no}
])
Modified: head/contrib/libxo/doc/libxo-manual.html
==============================================================================
--- head/contrib/libxo/doc/libxo-manual.html Fri Apr 15 18:43:54 2016
(r298082)
+++ head/contrib/libxo/doc/libxo-manual.html Fri Apr 15 18:46:15 2016
(r298083)
@@ -515,7 +515,7 @@ li.indline1 {
}
@top-right {
- content: "December 2015";
+ content: "April 2016";
}
@top-center {
@@ -22009,7 +22009,7 @@ jQuery(function ($) {
</tr>
<tr>
<td class="header left"></td>
-<td class="header right">December 30, 2015</td>
+<td class="header right">April 15, 2016</td>
</tr>
</table></div>
<p id="title" class="title">libxo: The Easy Way to Generate text, XML, JSON,
and HTML output<br><span class="filename">libxo-manual</span></p>
@@ -22130,46 +22130,54 @@ jQuery(function ($) {
<a href="#field-modifiers">Field Modifiers</a><ul class="toc">
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_1">2.2.2.1���</div>
-<a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
+<a href="#the-argument-modifier-a">The Argument Modifier ({a:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_2">2.2.2.2���</div>
-<a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
+<a href="#the-colon-modifier-c">The Colon Modifier ({c:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_3">2.2.2.3���</div>
-<a href="#e-modifier">The Encoding Modifier ({e:})</a>
+<a href="#the-display-modifier-d">The Display Modifier ({d:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_4">2.2.2.4���</div>
-<a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
+<a href="#e-modifier">The Encoding Modifier ({e:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_5">2.2.2.5���</div>
-<a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
+<a href="#gettext-modifier">The Gettext Modifier ({g:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_6">2.2.2.6���</div>
-<a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
+<a href="#the-humanize-modifier-h">The Humanize Modifier ({h:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_7">2.2.2.7���</div>
-<a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
+<a href="#the-key-modifier-k">The Key Modifier ({k:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_8">2.2.2.8���</div>
-<a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
+<a href="#the-leaf-list-modifier-l">The Leaf-List Modifier ({l:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_9">2.2.2.9���</div>
-<a href="#plural-modifier">The Plural Modifier ({p:})</a>
+<a href="#the-no-quotes-modifier-n">The No-Quotes Modifier ({n:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_10">2.2.2.10���</div>
-<a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
+<a href="#plural-modifier">The Plural Modifier ({p:})</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_2_11">2.2.2.11���</div>
+<a href="#the-quotes-modifier-q">The Quotes Modifier ({q:})</a>
+</li>
+<li class="tocline1">
+<div class="section-number" id="toc_doc_section_2_2_2_12">2.2.2.12���</div>
+<a href="#the-trim-modifier-t">The Trim Modifier ({t:})</a>
+</li>
+<li class="tocline1">
+<div class="section-number" id="toc_doc_section_2_2_2_13">2.2.2.13���</div>
<a href="#the-white-space-modifier-w">The White Space Modifier ({w:})</a>
</li>
</ul>
@@ -22208,42 +22216,38 @@ jQuery(function ($) {
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_2_11">2.2.11���</div>
+<a href="#retain">Retaining Parsed Format Information</a>
+</li>
+<li class="tocline1">
+<div class="section-number" id="toc_doc_section_2_2_12">2.2.12���</div>
<a href="#example">Example</a>
</li>
</ul>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_2_3">2.3���</div>
-<a href="#command-line-arguments">Command-line Arguments</a>
-</li>
-<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_4">2.4���</div>
<a href="#representing-hierarchy">Representing Hierarchy</a><ul class="toc">
<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_4_1">2.4.1���</div>
+<div class="section-number" id="toc_doc_section_2_3_1">2.3.1���</div>
<a href="#containers">Containers</a>
</li>
<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_4_2">2.4.2���</div>
+<div class="section-number" id="toc_doc_section_2_3_2">2.3.2���</div>
<a href="#lists-and-instances">Lists and Instances</a>
</li>
<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_4_3">2.4.3���</div>
+<div class="section-number" id="toc_doc_section_2_3_3">2.3.3���</div>
<a href="#dtrt-mode">DTRT Mode</a>
</li>
<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_4_4">2.4.4���</div>
+<div class="section-number" id="toc_doc_section_2_3_4">2.3.4���</div>
<a href="#markers">Markers</a>
</li>
</ul>
</li>
<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_5">2.5���</div>
-<a href="#handles">Handles</a>
-</li>
-<li class="tocline1">
-<div class="section-number" id="toc_doc_section_2_6">2.6���</div>
-<a href="#utf-8">UTF-8</a>
+<div class="section-number" id="toc_doc_section_2_4">2.4���</div>
+<a href="#command-line-arguments">Command-line Arguments</a>
</li>
</ul>
</li>
@@ -22252,7 +22256,7 @@ jQuery(function ($) {
<a href="#the-libxo-api">The libxo API</a><ul class="toc top-toc">
<li class="tocline1">
<div class="section-number" id="toc_doc_section_3_1">3.1���</div>
-<a href="#handles-2">Handles</a><ul class="toc">
+<a href="#handles">Handles</a><ul class="toc">
<li class="tocline1">
<div class="section-number" id="toc_doc_section_3_1_1">3.1.1���</div>
<a href="#xo_create">xo_create</a>
@@ -22306,14 +22310,18 @@ jQuery(function ($) {
<a href="#emitting-content-xo_emit">Emitting Content (xo_emit)</a><ul
class="toc">
<li class="tocline1">
<div class="section-number" id="toc_doc_section_3_2_1">3.2.1���</div>
-<a href="#xo_attr">Attributes (xo_attr)</a>
+<a href="#xo_emit_field">Single Field Emitting Functions (xo_emit_field)</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_3_2_2">3.2.2���</div>
-<a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
+<a href="#xo_attr">Attributes (xo_attr)</a>
</li>
<li class="tocline1">
<div class="section-number" id="toc_doc_section_3_2_3">3.2.3���</div>
+<a href="#flushing-output-xo_flush">Flushing Output (xo_flush)</a>
+</li>
+<li class="tocline1">
+<div class="section-number" id="toc_doc_section_3_2_4">3.2.4���</div>
<a href="#finishing-output-xo_finish">Finishing Output (xo_finish)</a>
</li>
</ul>
@@ -22851,10 +22859,8 @@ jQuery(function ($) {
<ul>
<li><a href="#encoding-styles" title="Encoding Styles">Section�2.1</a></li>
<li><a href="#format-strings" title="Format Strings">Section�2.2</a></li>
-<li><a href="#command-line-arguments" title="Command-line
Arguments">Section�2.3</a></li>
-<li><a href="#representing-hierarchy" title="Representing
Hierarchy">Section�2.4</a></li>
-<li><a href="#handles" title="Handles">Section�2.5</a></li>
-<li><a href="#utf-8" title="UTF-8">Section�2.6</a></li>
+<li><a href="#representing-hierarchy" title="Representing
Hierarchy">Section�2.3</a></li>
+<li><a href="#command-line-arguments" title="Command-line
Arguments">Section�2.4</a></li>
</ul>
<div class="content">
<h2 id="doc_section_2_1">
@@ -22992,7 +22998,8 @@ jQuery(function ($) {
<li><a href="#the-encoding-format-eformat" title="The Encoding Format
(eformat)">Section�2.2.8</a></li>
<li><a href="#content-strings" title="Content Strings">Section�2.2.9</a></li>
<li><a href="#printf-like" title="Argument Validation">Section�2.2.10</a></li>
-<li><a href="#example" title="Example">Section�2.2.11</a></li>
+<li><a href="#retain" title="Retaining Parsed Format
Information">Section�2.2.11</a></li>
+<li><a href="#example" title="Example">Section�2.2.12</a></li>
</ul>
<div class="content">
<h3 id="doc_section_2_2_1">
@@ -23356,6 +23363,11 @@ jQuery(function ($) {
</tr></thead>
<tbody>
<tr>
+<td>a</td>
+<td>argument</td>
+<td>The content appears as a 'const char *' argument</td>
+</tr>
+<tr>
<td>c</td>
<td>colon</td>
<td>A colon (":") is appended after the label</td>
@@ -23435,87 +23447,107 @@ jQuery(function ($) {
<p id="doc_section_2_2_2_p_2">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.</p>
<p id="doc_section_2_2_2_p_3">Section Contents: </p>
<ul>
-<li><a href="#the-colon-modifier-c" title="The Colon Modifier
({c:})">Section�2.2.2.1</a></li>
-<li><a href="#the-display-modifier-d" title="The Display Modifier
({d:})">Section�2.2.2.2</a></li>
-<li><a href="#e-modifier" title="The Encoding Modifier
({e:})">Section�2.2.2.3</a></li>
-<li><a href="#gettext-modifier" title="The Gettext Modifier
({g:})">Section�2.2.2.4</a></li>
-<li><a href="#the-humanize-modifier-h" title="The Humanize Modifier
({h:})">Section�2.2.2.5</a></li>
-<li><a href="#the-key-modifier-k" title="The Key Modifier
({k:})">Section�2.2.2.6</a></li>
-<li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier
({l:})">Section�2.2.2.7</a></li>
-<li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier
({n:})">Section�2.2.2.8</a></li>
-<li><a href="#plural-modifier" title="The Plural Modifier
({p:})">Section�2.2.2.9</a></li>
-<li><a href="#the-quotes-modifier-q" title="The Quotes Modifier
({q:})">Section�2.2.2.10</a></li>
-<li><a href="#the-white-space-modifier-w" title="The White Space Modifier
({w:})">Section�2.2.2.11</a></li>
+<li><a href="#the-argument-modifier-a" title="The Argument Modifier
({a:})">Section�2.2.2.1</a></li>
+<li><a href="#the-colon-modifier-c" title="The Colon Modifier
({c:})">Section�2.2.2.2</a></li>
+<li><a href="#the-display-modifier-d" title="The Display Modifier
({d:})">Section�2.2.2.3</a></li>
+<li><a href="#e-modifier" title="The Encoding Modifier
({e:})">Section�2.2.2.4</a></li>
+<li><a href="#gettext-modifier" title="The Gettext Modifier
({g:})">Section�2.2.2.5</a></li>
+<li><a href="#the-humanize-modifier-h" title="The Humanize Modifier
({h:})">Section�2.2.2.6</a></li>
+<li><a href="#the-key-modifier-k" title="The Key Modifier
({k:})">Section�2.2.2.7</a></li>
+<li><a href="#the-leaf-list-modifier-l" title="The Leaf-List Modifier
({l:})">Section�2.2.2.8</a></li>
+<li><a href="#the-no-quotes-modifier-n" title="The No-Quotes Modifier
({n:})">Section�2.2.2.9</a></li>
+<li><a href="#plural-modifier" title="The Plural Modifier
({p:})">Section�2.2.2.10</a></li>
+<li><a href="#the-quotes-modifier-q" title="The Quotes Modifier
({q:})">Section�2.2.2.11</a></li>
+<li><a href="#the-trim-modifier-t" title="The Trim Modifier
({t:})">Section�2.2.2.12</a></li>
+<li><a href="#the-white-space-modifier-w" title="The White Space Modifier
({w:})">Section�2.2.2.13</a></li>
</ul>
<div class="content">
<h4 id="doc_section_2_2_2_1">
<div class="self-section-number">
<a href="#doc_section_2_2_2_1">2.2.2.1</a>�</div>
-<a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier
({c:})</a>
+<a id="the-argument-modifier-a" href="#the-argument-modifier-a">The Argument
Modifier ({a:})</a>
</h4>
-<p id="doc_section_2_2_2_1_p_1">The colon modifier appends a single colon to
the data value:</p>
+<p id="doc_section_2_2_2_1_p_1">The argument modifier indicates that the
content of the field descriptor will be placed as a UTF-8 string (const char *)
argument within the xo_emit parameters.</p>
<div id="doc_figure_u.48"></div> <pre>
EXAMPLE:
- xo_emit("{Lc:Name}{:name}\n", "phil");
+ xo_emit("{La:} {a:}\n", "Label text", "label", "value");
TEXT:
- Name:phil
- </pre> <p id="doc_section_2_2_2_1_p_3">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.</p>
+ Label text value
+ JSON:
+ "label": "value"
+ XML:
+ <label>value</label>
+ </pre> <p id="doc_section_2_2_2_1_p_3">The argument modifier allows
field names for value fields to be passed on the stack, avoiding the need to
build a field descriptor using snprintf. For many field roles, the argument
modifier is not needed, since those roles have specific mechanisms for
arguments, such as "{C:fg‑%s}".</p>
</div>
<div class="content">
<h4 id="doc_section_2_2_2_2">
<div class="self-section-number">
<a href="#doc_section_2_2_2_2">2.2.2.2</a>�</div>
-<a id="the-display-modifier-d" href="#the-display-modifier-d">The Display
Modifier ({d:})</a>
+<a id="the-colon-modifier-c" href="#the-colon-modifier-c">The Colon Modifier
({c:})</a>
</h4>
-<p id="doc_section_2_2_2_2_p_1">The display modifier indicated the field
should only be generated for the display output styles, TEXT and HTML.</p>
+<p id="doc_section_2_2_2_2_p_1">The colon modifier appends a single colon to
the data value:</p>
<div id="doc_figure_u.49"></div> <pre>
EXAMPLE:
+ xo_emit("{Lc:Name}{:name}\n", "phil");
+ TEXT:
+ Name:phil
+ </pre> <p id="doc_section_2_2_2_2_p_3">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.</p>
+</div>
+<div class="content">
+<h4 id="doc_section_2_2_2_3">
+<div class="self-section-number">
+<a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
+<a id="the-display-modifier-d" href="#the-display-modifier-d">The Display
Modifier ({d:})</a>
+</h4>
+<p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field
should only be generated for the display output styles, TEXT and HTML.</p>
+<div id="doc_figure_u.50"></div> <pre>
+ EXAMPLE:
xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
TEXT:
Name: phil 1
XML:
<id>1</id>
- </pre> <p id="doc_section_2_2_2_2_p_3">The display modifier is the
opposite of the encoding modifier, and they are often used to give to distinct
views of the underlying data.</p>
+ </pre> <p id="doc_section_2_2_2_3_p_3">The display modifier is the
opposite of the encoding modifier, and they are often used to give to distinct
views of the underlying data.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_3">
+<h4 id="doc_section_2_2_2_4">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_3">2.2.2.3</a>�</div>
+<a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
<a id="e-modifier" href="#e-modifier">The Encoding Modifier ({e:})</a>
</h4>
-<p id="doc_section_2_2_2_3_p_1">The display modifier indicated the field
should only be generated for the display output styles, TEXT and HTML.</p>
-<div id="doc_figure_u.50"></div> <pre>
+<p id="doc_section_2_2_2_4_p_1">The display modifier indicated the field
should only be generated for the display output styles, TEXT and HTML.</p>
+<div id="doc_figure_u.51"></div> <pre>
EXAMPLE:
xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
TEXT:
Name: phil
XML:
<name>phil</name><id>1</id>
- </pre> <p id="doc_section_2_2_2_3_p_3">The encoding modifier is the
opposite of the display modifier, and they are often used to give to distinct
views of the underlying data.</p>
+ </pre> <p id="doc_section_2_2_2_4_p_3">The encoding modifier is the
opposite of the display modifier, and they are often used to give to distinct
views of the underlying data.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_4">
+<h4 id="doc_section_2_2_2_5">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_4">2.2.2.4</a>�</div>
+<a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
<a id="gettext-modifier" href="#gettext-modifier">The Gettext Modifier
({g:})</a>
</h4>
-<p id="doc_section_2_2_2_4_p_1">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.</p>
-<p id="doc_section_2_2_2_4_p_2">In the following example, the strings "State"
and "full" are passed to gettext() to find locale-based translated strings.</p>
-<div id="doc_figure_u.51"></div> <pre>
+<p id="doc_section_2_2_2_5_p_1">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.</p>
+<p id="doc_section_2_2_2_5_p_2">In the following example, the strings "State"
and "full" are passed to gettext() to find locale-based translated strings.</p>
+<div id="doc_figure_u.52"></div> <pre>
xo_emit("{Lgwc:State}{g:state}\n", "full");
- </pre> <p id="doc_section_2_2_2_4_p_4">See <a href="#gettext-role"
title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier"
title="The Plural Modifier ({p:})">Section�2.2.2.9</a>, and <a
href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a>
for additional details.</p>
+ </pre> <p id="doc_section_2_2_2_5_p_4">See <a href="#gettext-role"
title="The Gettext Role ({G:})">Section�2.2.1.3</a>, <a href="#plural-modifier"
title="The Plural Modifier ({p:})">Section�2.2.2.10</a>, and <a
href="#howto-i18n" title="Howto: Internationalization (i18n)">Section�9.5</a>
for additional details.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_5">
+<h4 id="doc_section_2_2_2_6">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_5">2.2.2.5</a>�</div>
+<a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
<a id="the-humanize-modifier-h" href="#the-humanize-modifier-h">The Humanize
Modifier ({h:})</a>
</h4>
-<p id="doc_section_2_2_2_5_p_1">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.</p>
-<p id="doc_section_2_2_2_5_p_2">"hn" can be used as an alias for
"humanize".</p>
-<p id="doc_section_2_2_2_5_p_3">The humanize modifier only affects display
styles (TEXT and HMTL). The "no‑humanize" option (See <a
href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the
function of the humanize modifier.</p>
-<p id="doc_section_2_2_2_5_p_4">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.</p>
-<div id="doc_figure_u.52"></div> <pre>
+<p id="doc_section_2_2_2_6_p_1">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.</p>
+<p id="doc_section_2_2_2_6_p_2">"hn" can be used as an alias for
"humanize".</p>
+<p id="doc_section_2_2_2_6_p_3">The humanize modifier only affects display
styles (TEXT and HMTL). The "no‑humanize" option (See <a
href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>) will block the
function of the humanize modifier.</p>
+<p id="doc_section_2_2_2_6_p_4">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.</p>
+<div id="doc_figure_u.53"></div> <pre>
EXAMPLE:
xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
"{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
@@ -23523,19 +23555,19 @@ jQuery(function ($) {
input, output, errors, capacity, remaining);
TEXT:
21, 57 K, 96M, 44M, 1.2G
- </pre> <p id="doc_section_2_2_2_5_p_6">In the HTML style, the
original numeric value is rendered in the "data‑number" attribute on the
<div> element:</p>
-<div id="doc_figure_u.53"></div> <pre>
+ </pre> <p id="doc_section_2_2_2_6_p_6">In the HTML style, the
original numeric value is rendered in the "data‑number" attribute on the
<div> element:</p>
+<div id="doc_figure_u.54"></div> <pre>
<div class="data" data-tag="errors"
data-number="100663296">96M</div>
</pre> </div>
<div class="content">
-<h4 id="doc_section_2_2_2_6">
+<h4 id="doc_section_2_2_2_7">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_6">2.2.2.6</a>�</div>
+<a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
<a id="the-key-modifier-k" href="#the-key-modifier-k">The Key Modifier
({k:})</a>
</h4>
-<p id="doc_section_2_2_2_6_p_1">The key modifier is used to indicate that a
particular field helps uniquely identify an instance of list data.</p>
-<div id="doc_figure_u.54"></div> <pre>
+<p id="doc_section_2_2_2_7_p_1">The key modifier is used to indicate that a
particular field helps uniquely identify an instance of list data.</p>
+<div id="doc_figure_u.55"></div> <pre>
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
@@ -23545,16 +23577,16 @@ jQuery(function ($) {
xo_close_instance("user");
}
xo_close_list("user");
- </pre> <p id="doc_section_2_2_2_6_p_3">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.</p>
+ </pre> <p id="doc_section_2_2_2_7_p_3">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.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_7">
+<h4 id="doc_section_2_2_2_8">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_7">2.2.2.7</a>�</div>
+<a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
<a id="the-leaf-list-modifier-l" href="#the-leaf-list-modifier-l">The
Leaf-List Modifier ({l:})</a>
</h4>
-<p id="doc_section_2_2_2_7_p_1">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.</p>
-<div id="doc_figure_u.55"></div> <pre>
+<p id="doc_section_2_2_2_8_p_1">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.</p>
+<div id="doc_figure_u.56"></div> <pre>
EXAMPLE:
for (i = 0; i < num_users; i++) {
xo_emit("Member {l:user}\n", user[i].u_name);
@@ -23564,16 +23596,16 @@ jQuery(function ($) {
<user>pallavi</user>
JSON:
"user": [ "phil", "pallavi" ]
- </pre> <p id="doc_section_2_2_2_7_p_3">The name of the field must
match the name of the leaf list.</p>
+ </pre> <p id="doc_section_2_2_2_8_p_3">The name of the field must
match the name of the leaf list.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_8">
+<h4 id="doc_section_2_2_2_9">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_8">2.2.2.8</a>�</div>
+<a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
<a id="the-no-quotes-modifier-n" href="#the-no-quotes-modifier-n">The
No-Quotes Modifier ({n:})</a>
</h4>
-<p id="doc_section_2_2_2_8_p_1">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.</p>
-<div id="doc_figure_u.56"></div> <pre>
+<p id="doc_section_2_2_2_9_p_1">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.</p>
+<div id="doc_figure_u.57"></div> <pre>
EXAMPLE:
const char *bool = is_true ? "true" : "false";
xo_emit("{n:fancy/%s}", bool);
@@ -23581,45 +23613,61 @@ jQuery(function ($) {
"fancy": true
</pre> </div>
<div class="content">
-<h4 id="doc_section_2_2_2_9">
+<h4 id="doc_section_2_2_2_10">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_9">2.2.2.9</a>�</div>
+<a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
<a id="plural-modifier" href="#plural-modifier">The Plural Modifier ({p:})</a>
</h4>
-<p id="doc_section_2_2_2_9_p_1">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:</p>
-<div id="doc_figure_u.57"></div> <pre>
+<p id="doc_section_2_2_2_10_p_1">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:</p>
+<div id="doc_figure_u.58"></div> <pre>
xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
- </pre> <p id="doc_section_2_2_2_9_p_3">The plural modifier is meant
to work with the gettext modifier ({g:}) but can work independently. See <a
href="#gettext-modifier" title="The Gettext Modifier
({g:})">Section�2.2.2.4</a>.</p>
-<p id="doc_section_2_2_2_9_p_4">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.</p>
-<p id="doc_section_2_2_2_9_p_5">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.</p>
+ </pre> <p id="doc_section_2_2_2_10_p_3">The plural modifier is
meant to work with the gettext modifier ({g:}) but can work independently. See
<a href="#gettext-modifier" title="The Gettext Modifier
({g:})">Section�2.2.2.5</a>.</p>
+<p id="doc_section_2_2_2_10_p_4">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.</p>
+<p id="doc_section_2_2_2_10_p_5">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.</p>
</div>
<div class="content">
-<h4 id="doc_section_2_2_2_10">
+<h4 id="doc_section_2_2_2_11">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_10">2.2.2.10</a>�</div>
+<a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
<a id="the-quotes-modifier-q" href="#the-quotes-modifier-q">The Quotes
Modifier ({q:})</a>
</h4>
-<p id="doc_section_2_2_2_10_p_1">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.</p>
-<div id="doc_figure_u.58"></div> <pre>
+<p id="doc_section_2_2_2_11_p_1">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.</p>
+<div id="doc_figure_u.59"></div> <pre>
EXAMPLE:
xo_emit("{q:time/%d}", 2014);
JSON:
"year": "2014"
+ </pre> <p id="doc_section_2_2_2_11_p_3">The heuristic is based on
the format; if the format uses any of the following conversion specifiers, then
no quotes are used:</p>
+<div id="doc_figure_u.60"></div> <pre>
+ d i o u x X D O U e E f F g G a A c C p
</pre> </div>
<div class="content">
-<h4 id="doc_section_2_2_2_11">
+<h4 id="doc_section_2_2_2_12">
<div class="self-section-number">
-<a href="#doc_section_2_2_2_11">2.2.2.11</a>�</div>
+<a href="#doc_section_2_2_2_12">2.2.2.12</a>�</div>
+<a id="the-trim-modifier-t" href="#the-trim-modifier-t">The Trim Modifier
({t:})</a>
+</h4>
+<p id="doc_section_2_2_2_12_p_1">The trim modifier removes any leading or
trailing whitespace from the value.</p>
+<div id="doc_figure_u.61"></div> <pre>
+ EXAMPLE:
+ xo_emit("{t:description}", " some input ");
+ JSON:
+ "description": "some input"
+ </pre> </div>
+<div class="content">
+<h4 id="doc_section_2_2_2_13">
+<div class="self-section-number">
+<a href="#doc_section_2_2_2_13">2.2.2.13</a>�</div>
<a id="the-white-space-modifier-w" href="#the-white-space-modifier-w">The
White Space Modifier ({w:})</a>
</h4>
-<p id="doc_section_2_2_2_11_p_1">The white space modifier appends a single
space to the data value:</p>
-<div id="doc_figure_u.59"></div> <pre>
+<p id="doc_section_2_2_2_13_p_1">The white space modifier appends a single
space to the data value:</p>
+<div id="doc_figure_u.62"></div> <pre>
EXAMPLE:
xo_emit("{Lw:Name}{:name}\n", "phil");
TEXT:
Name phil
- </pre> <p id="doc_section_2_2_2_11_p_3">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.</p>
-<p id="doc_section_2_2_2_11_p_4">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.</p>
+ </pre> <p id="doc_section_2_2_2_13_p_3">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.</p>
+<p id="doc_section_2_2_2_13_p_4">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.</p>
</div>
</div>
<div class="content">
@@ -23632,7 +23680,7 @@ jQuery(function ($) {
<p id="doc_section_2_2_3_p_2">If the format string is not provided for a value
field, it defaults to "%s".</p>
<p id="doc_section_2_2_3_p_3">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.</p>
<p id="doc_section_2_2_3_p_4">The format string has the form:</p>
-<div id="doc_figure_u.60"></div> <pre>
+<div id="doc_figure_u.63"></div> <pre>
'%' format-modifier * format-character
</pre> <p id="doc_section_2_2_3_p_6">The format- modifier can
be:</p>
<p id="doc_section_2_2_3_p_7"> </p>
@@ -23829,8 +23877,42 @@ jQuery(function ($) {
<a id="utf-8-and-locale-strings" href="#utf-8-and-locale-strings">UTF-8 and
Locale Strings</a>
</h3>
<p id="doc_section_2_2_4_p_1">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".</p>
-<p id="doc_section_2_2_4_p_2">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.</p>
-<div id="doc_figure_u.61"></div> <pre>
+<p id="doc_section_2_2_4_p_2">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.</p>
+<div id="doc_figure_u.64"></div> <pre>
+ xo_emit("Alll strings are utf-8 content {:tag/%ls}",
+ L"except for wide strings");
+ </pre> <p id="doc_section_2_2_4_p_4">"%S" is equivalent to
"%ls".</p>
+<div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
+<thead><tr>
+<th class="left">Format</th>
+<th class="left">Argument Type</th>
+<th class="left">Argument Contents</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>%s</td>
+<td>const char *</td>
+<td>UTF-8 string</td>
+</tr>
+<tr>
+<td>%S</td>
+<td>const char *</td>
+<td>UTF-8 string (alias for '%s')</td>
+</tr>
+<tr>
+<td>%ls</td>
+<td>const wchar_t *</td>
+<td>Wide character UNICODE string</td>
+</tr>
+<tr>
+<td>%hs</td>
+<td>const char *</td>
+<td>locale-based string</td>
+</tr>
+</tbody>
+</table></div>
+<p id="doc_section_2_2_4_p_5">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.</p>
+<div id="doc_figure_u.65"></div> <pre>
void print_order (const char *name, int size,
struct tm *timep) {
char buf[32];
@@ -23849,10 +23931,10 @@ jQuery(function ($) {
xo_emit("It was ordered on {:order-time/%ls}.\n",
when);
}
- </pre> <p id="doc_section_2_2_4_p_4">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.</p>
-<p id="doc_section_2_2_4_p_5">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.</p>
-<p id="doc_section_2_2_4_p_6">In this example, the name field is printed with
a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the
location given by 'name' are in used in filling those columns.</p>
-<div id="doc_figure_u.62"></div> <pre>
+ </pre> <p id="doc_section_2_2_4_p_7">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.</p>
+<p id="doc_section_2_2_4_p_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.</p>
+<p id="doc_section_2_2_4_p_9">In this example, the name field is printed with
a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the
location given by 'name' are in used in filling those columns.</p>
+<div id="doc_figure_u.66"></div> <pre>
xo_emit("{:name/%3.10.6s}", name);
</pre> </div>
<div class="content">
@@ -23862,7 +23944,7 @@ jQuery(function ($) {
<a id="characters-outside-of-field-definitions"
href="#characters-outside-of-field-definitions">Characters Outside of Field
Definitions</a>
</h3>
<p id="doc_section_2_2_5_p_1">Characters in the format string that are not
part of a field definition are copied to the output for the TEXT style, and are
ignored for the JSON and XML styles. For HTML, these characters are placed in a
<div> with class "text".</p>
-<div id="doc_figure_u.63"></div> <pre>
+<div id="doc_figure_u.67"></div> <pre>
EXAMPLE:
xo_emit("The hat is {:size/%s}.\n", size_val);
TEXT:
@@ -23883,7 +23965,7 @@ jQuery(function ($) {
<a id="m-is-supported" href="#m-is-supported">"%m" Is Supported</a>
</h3>
<p id="doc_section_2_2_6_p_1">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).</p>
-<div id="doc_figure_u.64"></div> <pre>
+<div id="doc_figure_u.68"></div> <pre>
xo_emit("{:filename} cannot be opened: {:error/%m}", filename);
xo_emit("{:filename} cannot be opened: {:error/%s}",
filename, strerror(errno));
@@ -23930,7 +24012,7 @@ jQuery(function ($) {
<li>distinct encoding formats, where "{:tag/#%s/%s}" means the display styles
(text and HTML) will use "#%s" where other styles use "%s";</li>
</ul>
<p id="doc_section_2_2_10_p_5">If none of these features are in use by your
code, then using the "_p" variants might be wise.</p>
-<div id="doc_table_u.7"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
+<div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
<thead><tr>
<th class="left">Function</th>
<th class="left">printf-like Equivalent</th>
@@ -23987,14 +24069,71 @@ jQuery(function ($) {
<h3 id="doc_section_2_2_11">
<div class="self-section-number">
<a href="#doc_section_2_2_11">2.2.11</a>�</div>
+<a id="retain" href="#retain">Retaining Parsed Format Information</a>
+</h3>
+<p id="doc_section_2_2_11_p_1">libxo can retain the parsed internal
information related to the given format string, allowing subsequent xo_emit
calls, the retained information is used, avoiding repetitive parsing of the
format string.</p>
+<div id="doc_figure_u.69"></div> <pre>
+ SYNTAX:
+ int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
+ EXAMPLE:
+ xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
+ some, thing, fancy);
+ </pre> <p id="doc_section_2_2_11_p_3">To retain parsed format
information, use the XOEF_RETAIN flag to the xo_emit_f() function. A complete
set of xo_emit_f functions exist to match all the xo_emit function signatures
(with handles, varadic argument, and printf-like flags):</p>
+<div id="doc_table_u.9"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
+<thead><tr>
+<th class="left">Function</th>
+<th class="left">Flags Equivalent</th>
+</tr></thead>
+<tbody>
+<tr>
+<td>xo_emit_hv</td>
+<td>xo_emit_hvf</td>
+</tr>
+<tr>
+<td>xo_emit_h</td>
+<td>xo_emit_hf</td>
+</tr>
+<tr>
+<td>xo_emit</td>
+<td>xo_emit_f</td>
+</tr>
+<tr>
+<td>xo_emit_hvp</td>
+<td>xo_emit_hvfp</td>
+</tr>
+<tr>
+<td>xo_emit_hp</td>
+<td>xo_emit_hfp</td>
+</tr>
+<tr>
+<td>xo_emit_p</td>
+<td>xo_emit_fp</td>
+</tr>
+</tbody>
+</table></div>
+<p id="doc_section_2_2_11_p_4">The format string must be immutable across
multiple calls to xo_emit_f(), since the library retains the string. Typically
this is done by using static constant strings, such as string literals. If the
string is not immutable, the XOEF_RETAIN flag must not be used.</p>
+<p id="doc_section_2_2_11_p_5">The functions xo_retain_clear() and
xo_retain_clear_all() release internal information on either a single format
string or all format strings, respectively. Neither is required, but the
library will retain this information until it is cleared or the process
exits.</p>
+<div id="doc_figure_u.70"></div> <pre>
+ const char *fmt = "{:name} {:count/%d}\n";
+ for (i = 0; i < 1000; i++) {
+ xo_open_instance("item");
+ xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
+ }
+ xo_retain_clear(fmt);
+ </pre> <p id="doc_section_2_2_11_p_7">The retained information is
kept as thread-specific data.</p>
+</div>
+<div class="content">
+<h3 id="doc_section_2_2_12">
+<div class="self-section-number">
+<a href="#doc_section_2_2_12">2.2.12</a>�</div>
<a id="example" href="#example">Example</a>
</h3>
-<p id="doc_section_2_2_11_p_1">In this example, the value for the number of
items in stock is emitted:</p>
-<div id="doc_figure_u.65"></div> <pre>
+<p id="doc_section_2_2_12_p_1">In this example, the value for the number of
items in stock is emitted:</p>
+<div id="doc_figure_u.71"></div> <pre>
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
instock);
- </pre> <p id="doc_section_2_2_11_p_3">This call will generate the
following output:</p>
-<div id="doc_figure_u.66"></div> <pre>
+ </pre> <p id="doc_section_2_2_12_p_3">This call will generate the
following output:</p>
+<div id="doc_figure_u.72"></div> <pre>
TEXT:
In stock: 144
XML:
@@ -24009,8 +24148,8 @@ jQuery(function ($) {
<div class="padding"> </div>
<div class="data" data-tag="in-stock">144</div>
</div>
- </pre> <p id="doc_section_2_2_11_p_5">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:</p>
-<div id="doc_figure_u.67"></div> <pre>
+ </pre> <p id="doc_section_2_2_12_p_5">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:</p>
+<div id="doc_figure_u.73"></div> <pre>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock"
data-type="number"
@@ -24021,17 +24160,148 @@ jQuery(function ($) {
<h2 id="doc_section_2_3">
<div class="self-section-number">
<a href="#doc_section_2_3">2.3</a>�</div>
+<a id="representing-hierarchy" href="#representing-hierarchy">Representing
Hierarchy</a>
+</h2>
+<p id="doc_section_2_3_p_1">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.</p>
+<p id="doc_section_2_3_p_2">XML encodes lists as set of sequential
elements:</p>
+<div id="doc_figure_u.74"></div> <pre>
+ <user>phil</user>
+ <user>pallavi</user>
+ <user>sjg</user>
+ </pre> <p id="doc_section_2_3_p_4">JSON encodes lists using a
single name and square brackets:</p>
+<div id="doc_figure_u.75"></div> <pre>
+ "user": [ "phil", "pallavi", "sjg" ]
+ </pre> <p id="doc_section_2_3_p_6">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.</p>
+<p id="doc_section_2_3_p_7">Section Contents: </p>
+<ul>
+<li><a href="#containers" title="Containers">Section�2.3.1</a></li>
+<li><a href="#lists-and-instances" title="Lists and
Instances">Section�2.3.2</a></li>
+<li><a href="#dtrt-mode" title="DTRT Mode">Section�2.3.3</a></li>
+<li><a href="#markers" title="Markers">Section�2.3.4</a></li>
+</ul>
+<div class="content">
+<h3 id="doc_section_2_3_1">
+<div class="self-section-number">
+<a href="#doc_section_2_3_1">2.3.1</a>�</div>
+<a id="containers" href="#containers">Containers</a>
+</h3>
+<p id="doc_section_2_3_1_p_1">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.</p>
+<p id="doc_section_2_3_1_p_2">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.</p>
+<div id="doc_figure_u.76"></div> <pre>
+ int xo_open_container_h (xo_handle_t *xop, const char *name);
+ int xo_open_container (const char *name);
+ </pre> <p id="doc_section_2_3_1_p_4">To close a level, use the
xo_close_container() or xo_close_container_h() functions:</p>
+<div id="doc_figure_u.77"></div> <pre>
+ int xo_close_container_h (xo_handle_t *xop, const char *name);
+ int xo_close_container (const char *name);
+ </pre> <p id="doc_section_2_3_1_p_6">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.</p>
+<div id="doc_figure_u.78"></div> <pre>
+ 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:
+ <top>
+ <system>
+ <host-name>my-host.example.org</host-name>
+ </system>
+ </top>
+ JSON:
+ "top" : {
+ "system" : {
+ "host-name": "my-host.example.org"
+ }
+ }
+ HTML:
+ <div class="data"
+ data-tag="host-name">my-host.example.org</div>
+ </pre> </div>
+<div class="content">
+<h3 id="doc_section_2_3_2">
+<div class="self-section-number">
+<a href="#doc_section_2_3_2">2.3.2</a>�</div>
+<a id="lists-and-instances" href="#lists-and-instances">Lists and Instances</a>
+</h3>
+<p id="doc_section_2_3_2_p_1">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:</p>
+<div id="doc_figure_u.79"></div> <pre>
+ 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");
+ </pre> <p id="doc_section_2_3_2_p_3">Getting the list and instance
calls correct is critical to the proper generation of XML and JSON data.</p>
+</div>
+<div class="content">
+<h3 id="doc_section_2_3_3">
+<div class="self-section-number">
+<a href="#doc_section_2_3_3">2.3.3</a>�</div>
+<a id="dtrt-mode" href="#dtrt-mode">DTRT Mode</a>
+</h3>
+<p id="doc_section_2_3_3_p_1">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.</p>
+<div id="doc_figure_u.80"></div> <pre>
+ xo_set_flags(NULL, XOF_DTRT);
+ </pre> <p id="doc_section_2_3_3_p_3">Each open and close function
has a version with the suffix "_d", which will close the open container, list,
or instance:</p>
+<div id="doc_figure_u.81"></div> <pre>
+ xo_open_container("top");
+ ...
+ xo_close_container_d();
+ </pre> <p id="doc_section_2_3_3_p_5">This also works for lists and
instances:</p>
+<div id="doc_figure_u.82"></div> <pre>
+ xo_open_list("item");
+ for (...) {
+ xo_open_instance("item");
+ xo_emit(...);
+ xo_close_instance_d();
+ }
+ xo_close_list_d();
+ </pre> <p id="doc_section_2_3_3_p_7">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.</p>
+</div>
+<div class="content">
+<h3 id="doc_section_2_3_4">
+<div class="self-section-number">
+<a href="#doc_section_2_3_4">2.3.4</a>�</div>
+<a id="markers" href="#markers">Markers</a>
+</h3>
+<p id="doc_section_2_3_4_p_1">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.</p>
+<p id="doc_section_2_3_4_p_2">Markers use names which are not user-visible,
allowing the caller to choose appropriate internal names.</p>
+<p id="doc_section_2_3_4_p_3">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.</p>
+<div id="doc_figure_u.83"></div> <pre>
+ for (i = 0; fish[i]; i++) {
+ xo_open_instance("fish");
+ xo_open_marker("fish-guts");
+ dump_fish_details(i);
+ xo_close_marker("fish-guts");
+ }
+ </pre> </div>
+</div>
+<div class="content">
+<h2 id="doc_section_2_4">
+<div class="self-section-number">
+<a href="#doc_section_2_4">2.4</a>�</div>
<a id="command-line-arguments" href="#command-line-arguments">Command-line
Arguments</a>
</h2>
-<p id="doc_section_2_3_p_1">libxo uses command line options to trigger
rendering behavior. The following options are recognised:</p>
-<p id="doc_section_2_3_p_2"> </p>
+<p id="doc_section_2_4_p_1">libxo uses command line options to trigger
rendering behavior. The following options are recognised:</p>
+<p id="doc_section_2_4_p_2"> </p>
<ul>
<li>--libxo <options></li>
<li>--libxo=<options></li>
<li>--libxo:<brief‑options></li>
</ul>
-<p id="doc_section_2_3_p_3">Options is a comma-separated list of tokens that
correspond to output styles, flags, or features:</p>
-<div id="doc_table_u.8"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
+<p id="doc_section_2_4_p_3">Programs using libxo are expecting to call the
xo_parse_args function to parse these arguments. See <a href="#xo_parse_args"
title="Parsing Command-line Arguments (xo_parse_args)">Section�3.4.1</a> for
details.</p>
+<p id="doc_section_2_4_p_4">Options is a comma-separated list of tokens that
correspond to output styles, flags, or features:</p>
+<div id="doc_table_u.10"><table summary="" class="tt full" cellpadding="3"
cellspacing="0">
<thead><tr>
<th class="left">Token</th>
<th class="left">Action</th>
@@ -24082,6 +24352,10 @@ jQuery(function ($) {
<td>Do not initialize the locale setting</td>
</tr>
<tr>
+<td>no-retain</td>
+<td>Prevent retaining formatting information</td>
+</tr>
+<tr>
<td>no-top</td>
<td>Do not emit a top set of braces (JSON)</td>
</tr>
@@ -24094,6 +24368,10 @@ jQuery(function ($) {
<td>Emit pretty-printed output</td>
</tr>
<tr>
+<td>retain</td>
+<td>Force retaining formatting information</td>
+</tr>
+<tr>
<td>text</td>
<td>Emit TEXT output</td>
</tr>
@@ -24123,165 +24401,7 @@ jQuery(function ($) {
</tr>
</tbody>
</table></div>
-<p id="doc_section_2_3_p_4">The brief options are detailed in <a
href="#LIBXO_OPTIONS" title="LIBXO_OPTIONS">Section�3.4.6</a>.</p>
-</div>
-<div class="content">
-<h2 id="doc_section_2_4">
-<div class="self-section-number">
-<a href="#doc_section_2_4">2.4</a>�</div>
-<a id="representing-hierarchy" href="#representing-hierarchy">Representing
Hierarchy</a>
-</h2>
-<p id="doc_section_2_4_p_1">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.</p>
-<p id="doc_section_2_4_p_2">XML encodes lists as set of sequential
elements:</p>
-<div id="doc_figure_u.68"></div> <pre>
- <user>phil</user>
- <user>pallavi</user>
- <user>sjg</user>
- </pre> <p id="doc_section_2_4_p_4">JSON encodes lists using a
single name and square brackets:</p>
-<div id="doc_figure_u.69"></div> <pre>
- "user": [ "phil", "pallavi", "sjg" ]
- </pre> <p id="doc_section_2_4_p_6">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.</p>
-<p id="doc_section_2_4_p_7">Section Contents: </p>
-<ul>
-<li><a href="#containers" title="Containers">Section�2.4.1</a></li>
-<li><a href="#lists-and-instances" title="Lists and
Instances">Section�2.4.2</a></li>
-<li><a href="#dtrt-mode" title="DTRT Mode">Section�2.4.3</a></li>
-<li><a href="#markers" title="Markers">Section�2.4.4</a></li>
-</ul>
-<div class="content">
-<h3 id="doc_section_2_4_1">
-<div class="self-section-number">
-<a href="#doc_section_2_4_1">2.4.1</a>�</div>
-<a id="containers" href="#containers">Containers</a>
-</h3>
-<p id="doc_section_2_4_1_p_1">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.</p>
-<p id="doc_section_2_4_1_p_2">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.</p>
-<div id="doc_figure_u.70"></div> <pre>
- int xo_open_container_h (xo_handle_t *xop, const char *name);
- int xo_open_container (const char *name);
- </pre> <p id="doc_section_2_4_1_p_4">To close a level, use the
xo_close_container() or xo_close_container_h() functions:</p>
-<div id="doc_figure_u.71"></div> <pre>
- int xo_close_container_h (xo_handle_t *xop, const char *name);
- int xo_close_container (const char *name);
- </pre> <p id="doc_section_2_4_1_p_6">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.</p>
-<div id="doc_figure_u.72"></div> <pre>
- 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");
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
_______________________________________________
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
