d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Import libxo 0.9.0

Browse Source
This commit is contained in:
Phil Shafer 2018-05-23 01:12:17 +00:00
parent 76c53ac649
commit b7a4d12840
38 changed files with 6081 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
configure.ac
View File

@ -12,7 +12,7 @@
#
AC_PREREQ(2.2)
AC_INIT([libxo], [0.8.4], [phil@juniper.net])
AC_INIT([libxo], [0.9.0], [phil@juniper.net])
AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability])
# Support silent build rules. Requires at least automake-1.11.

5
doc/Makefile.am
View File

@ -68,3 +68,8 @@ else
doc docs:
@${ECHO} "The 'oxtradoc' tool is not installed; see libslax.org"
endif
SPHINX = python3.4 -msphinx
html sphinx sphinx-html:
${SPHINX} -M html ${srcdir} .

657
doc/_static/basic.css_t vendored Normal file
View File

@ -0,0 +1,657 @@
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: {{ theme_sidebarwidth|toint }}px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox input[type="text"] {
width: 170px;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
blockquote.epigraph p.attribution {
margin-left: 50%;
}
blockquote.epigraph {
background-color: #eee;
padding: 0.5em;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, .figure.align-right, object.align-right {
/* clear: right; */
float: right;
margin-left: 1em;
}
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar {
margin: 1em 1em 1em 1em;
border: 1px solid #ddb;
padding: 7px 7px 0 7px;
background-color: #ffe;
width: 40%;
float: right;
}
p.sidebar-title {
font-weight: bold;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px 7px 0 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
div.admonition dl {
margin-bottom: 0;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
border: 0;
border-collapse: collapse;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
dl.function table.docutils th.field-name {
width: 100px;
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 1px solid #aaa;
border-left: 1px solid #aaa;
border-right: 1px solid #aaa;
border-bottom: 1px solid #aaa;
}
table.docutils th {
border-bottom: 2px solid #aaa;
background-color: #f2f2f2;
}
table.footnote td, table.footnote th {
border: 0 !important;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
/* -- figures --------------------------------------------------------------- */
div.figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption {
padding: 0.3em;
}
div.figure p.caption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
dl {
margin-bottom: 15px;
}
dd p {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
dt:target, .highlighted {
background-color: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
}
td.linenos pre {
padding: 5px 0px;
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
margin-left: 0.5em;
}
table.highlighttable td {
padding: 0 0.5em 0 0.5em;
}
div.code-block-caption {
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
div.code-block-caption + div > div.highlight > pre {
margin-top: 0;
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
padding: 1em 1em 0;
}
div.literal-block-wrapper div.highlight {
margin: 0;
}
code.descname {
background-color: transparent;
font-weight: bold;
font-size: 1.2em;
}
code.descclassname {
background-color: transparent;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: relative;
left: 0px;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}

14
doc/_templates/localtoc.html vendored Normal file
View File

@ -0,0 +1,14 @@
{#
basic/localtoc.html
~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: local table of contents.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if display_toc %}
<h3><a href="{{ pathto(master_doc) }}">{{ _('On This Page') }}</a></h3>
{{ toc }}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Full Documentation') }}</a></h3>
{%- endif %}

1620
doc/api.rst Normal file
View File

File diff suppressed because it is too large Load Diff

178
doc/conf.py Normal file
View File

@ -0,0 +1,178 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# JuniperStory documentation build configuration file, created by
# sphinx-quickstart on Tue Oct 10 10:18:55 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'libxo'
copyright = '2017, Juniper Networks'
author = 'Phil Shafer'
default_role = 'code'
primary_domain = 'c'
smart_quotes = False
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.8.4'
# The full version, including alpha/beta/rc tags.
release = '0.8.4'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinxdoc'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
html_theme_options = {
"sidebarwidth": 320,
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
alabaster_html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
'donate.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'libxo-manual'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'libxo.tex', 'libxo Documentation',
'Phil Shafer', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'libxo', 'libxo Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'libxo', 'libxo Documentation',
author, 'libxo', 'A Library for Generating Text, XML, JSON, and HTML Output',
'Miscellaneous'),
]

694
doc/example.rst Normal file
View File

@ -0,0 +1,694 @@
Examples
========
Unit Test
---------
Here is one of the unit tests as an example::
int
main (int argc, char **argv)
{
static char base_grocery[] = "GRO";
static char base_hardware[] = "HRD";
struct item {
const char *i_title;
int i_sold;
int i_instock;
int i_onorder;
const char *i_sku_base;
int i_sku_num;
};
struct item list[] = {
{ "gum", 1412, 54, 10, base_grocery, 415 },
{ "rope", 85, 4, 2, base_hardware, 212 },
{ "ladder", 0, 2, 1, base_hardware, 517 },
{ "bolt", 4123, 144, 42, base_hardware, 632 },
{ "water", 17, 14, 2, base_grocery, 2331 },
{ NULL, 0, 0, 0, NULL, 0 }
};
struct item list2[] = {
{ "fish", 1321, 45, 1, base_grocery, 533 },
};
struct item *ip;
xo_info_t info[] = {
{ "in-stock", "number", "Number of items in stock" },
{ "name", "string", "Name of the item" },
{ "on-order", "number", "Number of items on order" },
{ "sku", "string", "Stock Keeping Unit" },
{ "sold", "number", "Number of items sold" },
{ NULL, NULL, NULL },
};
int info_count = (sizeof(info) / sizeof(info[0])) - 1;
argc = xo_parse_args(argc, argv);
if (argc < 0)
exit(EXIT_FAILURE);
xo_set_info(NULL, info, info_count);
xo_open_container_h(NULL, "top");
xo_open_container("data");
xo_open_list("item");
for (ip = list; ip->i_title; ip++) {
xo_open_instance("item");
xo_emit("{L:Item} '{k:name/%s}':\n", ip->i_title);
xo_emit("{P: }{L:Total sold}: {n:sold/%u%s}\n",
ip->i_sold, ip->i_sold ? ".0" : "");
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
ip->i_instock);
xo_emit("{P: }{Lwc:On order}{:on-order/%u}\n",
ip->i_onorder);
xo_emit("{P: }{L:SKU}: {q:sku/%s-000-%u}\n",
ip->i_sku_base, ip->i_sku_num);
xo_close_instance("item");
}
xo_close_list("item");
xo_close_container("data");
xo_open_container("data");
xo_open_list("item");
for (ip = list2; ip->i_title; ip++) {
xo_open_instance("item");
xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
xo_emit("{P: }{L:Total sold}: {n:sold/%u%s}\n",
ip->i_sold, ip->i_sold ? ".0" : "");
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
ip->i_instock);
xo_emit("{P: }{Lwc:On order}{:on-order/%u}\n",
ip->i_onorder);
xo_emit("{P: }{L:SKU}: {q:sku/%s-000-%u}\n",
ip->i_sku_base, ip->i_sku_num);
xo_close_instance("item");
}
xo_close_list("item");
xo_close_container("data");
xo_close_container_h(NULL, "top");
return 0;
}
Text output::
% ./testxo --libxo text
Item 'gum':
Total sold: 1412.0
In stock: 54
On order: 10
SKU: GRO-000-415
Item 'rope':
Total sold: 85.0
In stock: 4
On order: 2
SKU: HRD-000-212
Item 'ladder':
Total sold: 0
In stock: 2
On order: 1
SKU: HRD-000-517
Item 'bolt':
Total sold: 4123.0
In stock: 144
On order: 42
SKU: HRD-000-632
Item 'water':
Total sold: 17.0
In stock: 14
On order: 2
SKU: GRO-000-2331
Item 'fish':
Total sold: 1321.0
In stock: 45
On order: 1
SKU: GRO-000-533
JSON output::
% ./testxo --libxo json,pretty
"top": {
"data": {
"item": [
{
"name": "gum",
"sold": 1412.0,
"in-stock": 54,
"on-order": 10,
"sku": "GRO-000-415"
},
{
"name": "rope",
"sold": 85.0,
"in-stock": 4,
"on-order": 2,
"sku": "HRD-000-212"
},
{
"name": "ladder",
"sold": 0,
"in-stock": 2,
"on-order": 1,
"sku": "HRD-000-517"
},
{
"name": "bolt",
"sold": 4123.0,
"in-stock": 144,
"on-order": 42,
"sku": "HRD-000-632"
},
{
"name": "water",
"sold": 17.0,
"in-stock": 14,
"on-order": 2,
"sku": "GRO-000-2331"
}
]
},
"data": {
"item": [
{
"name": "fish",
"sold": 1321.0,
"in-stock": 45,
"on-order": 1,
"sku": "GRO-000-533"
}
]
}
}
XML output::
% ./testxo --libxo pretty,xml
<top>
<data>
<item>
<name>gum</name>
<sold>1412.0</sold>
<in-stock>54</in-stock>
<on-order>10</on-order>
<sku>GRO-000-415</sku>
</item>
<item>
<name>rope</name>
<sold>85.0</sold>
<in-stock>4</in-stock>
<on-order>2</on-order>
<sku>HRD-000-212</sku>
</item>
<item>
<name>ladder</name>
<sold>0</sold>
<in-stock>2</in-stock>
<on-order>1</on-order>
<sku>HRD-000-517</sku>
</item>
<item>
<name>bolt</name>
<sold>4123.0</sold>
<in-stock>144</in-stock>
<on-order>42</on-order>
<sku>HRD-000-632</sku>
</item>
<item>
<name>water</name>
<sold>17.0</sold>
<in-stock>14</in-stock>
<on-order>2</on-order>
<sku>GRO-000-2331</sku>
</item>
</data>
<data>
<item>
<name>fish</name>
<sold>1321.0</sold>
<in-stock>45</in-stock>
<on-order>1</on-order>
<sku>GRO-000-533</sku>
</item>
</data>
</top>
HMTL output::
% ./testxo --libxo pretty,html
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">gum</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">1412.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">54</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">10</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">GRO-000-415</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">rope</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">85.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">4</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">HRD-000-212</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">ladder</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">1</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">HRD-000-517</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">bolt</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">4123.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">144</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">42</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">HRD-000-632</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">water</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">17.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">14</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">GRO-000-2331</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name">fish</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold">1321.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">45</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order">1</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku">GRO-000-533</div>
</div>
HTML output with xpath and info flags::
% ./testxo --libxo pretty,html,xpath,info
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">gum</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">1412.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">54</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">10</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">GRO-000-415</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">rope</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">85.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">4</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">HRD-000-212</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">ladder</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">1</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">HRD-000-517</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">bolt</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">4123.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">144</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">42</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">HRD-000-632</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">water</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">17.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">14</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">2</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">GRO-000-2331</div>
</div>
<div class="line">
<div class="label">Item</div>
<div class="text"> '</div>
<div class="data" data-tag="name"
data-xpath="/top/data/item/name" data-type="string"
data-help="Name of the item">fish</div>
<div class="text">':</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">Total sold</div>
<div class="text">: </div>
<div class="data" data-tag="sold"
data-xpath="/top/data/item/sold" data-type="number"
data-help="Number of items sold">1321.0</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock" data-type="number"
data-help="Number of items in stock">45</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">On order</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="on-order"
data-xpath="/top/data/item/on-order" data-type="number"
data-help="Number of items on order">1</div>
</div>
<div class="line">
<div class="padding"> </div>
<div class="label">SKU</div>
<div class="text">: </div>
<div class="data" data-tag="sku"
data-xpath="/top/data/item/sku" data-type="string"
data-help="Stock Keeping Unit">GRO-000-533</div>
</div>

209
doc/faq.rst Normal file
View File

@ -0,0 +1,209 @@
FAQs
====
This section contains the set of questions that users typically ask,
along with answers that might be helpful.
General
-------
Can you share the history of libxo?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In 2001, we added an XML API to the JUNOS operating system, which is
built on top of FreeBSD_. Eventually this API became standardized as
the NETCONF API (:RFC:`6241`). As part of this effort, we modified many
FreeBSD utilities to emit XML, typically via a "-X" switch. The
results were mixed. The cost of maintaining this code, updating it,
and carrying it were non-trivial, and contributed to our expense (and
the associated delay) with upgrading the version of FreeBSD on which
each release of JUNOS is based.
.. _FreeBSD: https://www.freebsd.org
A recent (2014) effort within JUNOS aims at removing our modifications
to the underlying FreeBSD code as a means of reducing the expense and
delay in tracking HEAD. JUNOS is structured to have system components
generate XML that is rendered by the CLI (think: login shell) into
human-readable text. This allows the API to use the same plumbing as
the CLI, and ensures that all components emit XML, and that it is
emitted with knowledge of the consumer of that XML, yielding an API
that have no incremental cost or feature delay.
libxo is an effort to mix the best aspects of the JUNOS strategy into
FreeBSD in a seemless way, allowing commands to make printf-like
output calls with a single code path.
Did the complex semantics of format strings evolve over time?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The history is both long and short: libxo's functionality is based
on what JUNOS does in a data modeling language called ODL (output
definition language). In JUNOS, all subcomponents generate XML,
which is feed to the CLI, where data from the ODL files tell is
how to render that XML into text. ODL might had a set of tags
like::
tag docsis-state {
help "State of the DOCSIS interface";
type string;
}
tag docsis-mode {
help "DOCSIS mode (2.0/3.0) of the DOCSIS interface";
type string;
}
tag docsis-upstream-speed {
help "Operational upstream speed of the interface";
type string;
}
tag downstream-scanning {
help "Result of scanning in downstream direction";
type string;
}
tag ranging {
help "Result of ranging action";
type string;
}
tag signal-to-noise-ratio {
help "Signal to noise ratio for all channels";
type string;
}
tag power {
help "Operational power of the signal on all channels";
type string;
}
format docsis-status-format {
picture "
State : @, Mode: @, Upstream speed: @
Downstream scanning: @, Ranging: @
Signal to noise ratio: @
Power: @
";
line {
field docsis-state;
field docsis-mode;
field docsis-upstream-speed;
field downstream-scanning;
field ranging;
field signal-to-noise-ratio;
field power;
}
}
These tag definitions are compiled into field definitions
that are triggered when matching XML elements are seen. ODL
also supports other means of defining output.
The roles and modifiers describe these details.
In moving these ideas to bsd, two things had to happen: the
formatting had to happen at the source since BSD won't have
a JUNOS-like CLI to do the rendering, and we can't depend on
external data models like ODL, which was seen as too hard a
sell to the BSD community.
The results were that the xo_emit strings are used to encode the
roles, modifiers, names, and formats. They are dense and a bit
cryptic, but not so unlike printf format strings that developers will
be lost.
libxo is a new implementation of these ideas and is distinct from
the previous implementation in JUNOS.
.. index:: XOF_UNDERSCORES
.. _good-field-names:
What makes a good field name?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To make useful, consistent field names, follow these guidelines:
Use lower case, even for TLAs
Lower case is more civilized. Even TLAs should be lower case
to avoid scenarios where the differences between "XPath" and
"Xpath" drive your users crazy. Using "xpath" is simpler and better.
Use hyphens, not underscores
Use of hyphens is traditional in XML, and the XOF_UNDERSCORES
flag can be used to generate underscores in JSON, if desired.
But the raw field name should use hyphens.
Use full words
Don't abbreviate especially when the abbreviation is not obvious or
not widely used. Use "data-size", not "dsz" or "dsize". Use
"interface" instead of "ifname", "if-name", "iface", "if", or "intf".
Use <verb>-<units>
Using the form <verb>-<units> or <verb>-<classifier>-<units> helps in
making consistent, useful names, avoiding the situation where one app
uses "sent-packet" and another "packets-sent" and another
"packets-we-have-sent". The <units> can be dropped when it is
obvious, as can obvious words in the classification.
Use "receive-after-window-packets" instead of
"received-packets-of-data-after-window".
Reuse existing field names
Nothing's worse than writing expressions like::
if ($src1/process[pid == $pid]/name ==
$src2/proc-table/proc-list
/prc-entry[prcss-id == $pid]/proc-name) {
...
}
Find someone else who is expressing similar data and follow their
fields and hierarchy. Remember the quote is not "Consistency is the
hobgoblin of little minds", but "A *foolish* consistency is the
hobgoblin of little minds". Consistency rocks!
Use containment as scoping
In the previous example, all the names are prefixed with "proc-",
which is redundant given that they are nested under the process table.
Think about your users
Have empathy for your users, choosing clear and useful fields that
contain clear and useful data. You may need to augment the display
content with xo_attr() calls (:ref:`xo_attr`) or "{e:}"
fields (:ref:`encoding-modifier`) to make the data useful.
Don't use an arbitrary number postfix
What does "errors2" mean? No one will know. "errors-after-restart"
would be a better choice. Think of your users, and think of the
future. If you make "errors2", the next guy will happily make
"errors3" and before you know it, someone will be asking what's the
difference between errors37 and errors63.
Be consistent, uniform, unsurprising, and predictable
Think of your field vocabulary as an API. You want it useful,
expressive, meaningful, direct, and obvious. You want the client
application's programmer to move between without the need to
understand a variety of opinions on how fields are named. They
should see the system as a single cohesive whole, not a sack of
cats.
Field names constitute the means by which client programmers interact
with our system. By choosing wise names now, you are making their
lives better.
After using `xolint` to find errors in your field descriptors, use
"`xolint -V`" to spell check your field names and to help you detect
different names for the same data. "dropped-short" and
"dropped-too-short" are both reasonable names, but using them both
will lead users to ask the difference between the two fields. If
there is no difference, use only one of the field names. If there is
a difference, change the names to make that difference more obvious.
.. ignore for now, since we want can't have generated content
What does this message mean?
----------------------------
!!include-file xolint.txt

370
doc/field-formatting.rst Normal file
View File

@ -0,0 +1,370 @@
.. index:: Field Formatting
Field Formatting
----------------
The field format is similar to the format string for printf(3). Its
use varies based on the role of the field, but generally is used to
format the field's contents.
If the format string is not provided for a value field, it defaults to
"%s".
Note a field definition can contain zero or more printf-style
'directives', which are sequences that start with a '%' and end with
one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive
is matched by one of more arguments to the xo_emit function.
The format string has the form::
'%' format-modifier * format-character
The format-modifier can be:
- a '#' character, indicating the output value should be prefixed
with '0x', typically to indicate a base 16 (hex) value.
- a minus sign ('-'), indicating the output value should be padded on
the right instead of the left.
- a leading zero ('0') indicating the output value should be padded on the
left with zeroes instead of spaces (' ').
- one or more digits ('0' - '9') indicating the minimum width of the
argument. If the width in columns of the output value is less than
the minimum width, the value will be padded to reach the minimum.
- a period followed by one or more digits indicating the maximum
number of bytes which will be examined for a string argument, or the maximum
width for a non-string argument. When handling ASCII strings this
functions as the field width but for multi-byte characters, a single
character may be composed of multiple bytes.
xo_emit will never dereference memory beyond the given number of bytes.
- a second period followed by one or more digits indicating the maximum
width for a string argument. This modifier cannot be given for non-string
arguments.
- one or more 'h' characters, indicating shorter input data.
- one or more 'l' characters, indicating longer input data.
- a 'z' character, indicating a 'size_t' argument.
- a 't' character, indicating a 'ptrdiff_t' argument.
- a ' ' character, indicating a space should be emitted before
positive numbers.
- a '+' character, indicating sign should emitted before any number.
Note that 'q', 'D', 'O', and 'U' are considered deprecated and will be
removed eventually.
The format character is described in the following table:
===== ================= ======================
Ltr Argument Type Format
===== ================= ======================
d int base 10 (decimal)
i int base 10 (decimal)
o int base 8 (octal)
u unsigned base 10 (decimal)
x unsigned base 16 (hex)
X unsigned long base 16 (hex)
D long base 10 (decimal)
O unsigned long base 8 (octal)
U unsigned long base 10 (decimal)
e double [-]d.ddde+-dd
E double [-]d.dddE+-dd
f double [-]ddd.ddd
F double [-]ddd.ddd
g double as 'e' or 'f'
G double as 'E' or 'F'
a double [-]0xh.hhhp[+-]d
A double [-]0Xh.hhhp[+-]d
c unsigned char a character
C wint_t a character
s char \* a UTF-8 string
S wchar_t \* a unicode/WCS string
p void \* '%#lx'
===== ================= ======================
The 'h' and 'l' modifiers affect the size and treatment of the
argument:
===== ============= ====================
Mod d, i o, u, x, X
===== ============= ====================
hh signed char unsigned char
h short unsigned short
l long unsigned long
ll long long unsigned long long
j intmax_t uintmax_t
t ptrdiff_t ptrdiff_t
z size_t size_t
q quad_t u_quad_t
===== ============= ====================
.. index:: UTF-8
.. index:: Locale
.. _utf-8:
UTF-8 and Locale Strings
~~~~~~~~~~~~~~~~~~~~~~~~
For strings, the 'h' and 'l' modifiers affect the interpretation of
the bytes pointed to argument. The default '%s' string is a 'char \*'
pointer to a string encoded as UTF-8. Since UTF-8 is compatible with
ASCII data, a normal 7-bit ASCII string can be used. '%ls' expects a
'wchar_t \*' pointer to a wide-character string, encoded as a 32-bit
Unicode values. '%hs' expects a 'char \*' pointer to a multi-byte
string encoded with the current locale, as given by the LC_CTYPE,
LANG, or LC_ALL environment varibles. The first of this list of
variables is used and if none of the variables are set, the locale
defaults to "UTF-8".
libxo will convert these arguments as needed to either UTF-8 (for XML,
JSON, and HTML styles) or locale-based strings for display in text
style::
xo_emit("All strings are utf-8 content {:tag/%ls}",
L"except for wide strings");
======== ================== ===============================
Format Argument Type Argument Contents
======== ================== ===============================
%s const char \* UTF-8 string
%S const char \* UTF-8 string (alias for '%ls')
%ls const wchar_t \* Wide character UNICODE string
%hs const char * locale-based string
======== ================== ===============================
.. admonition:: "Long", not "locale"
The "*l*" in "%ls" is for "*long*", following the convention of "%ld".
It is not "*locale*", a common mis-mnemonic. "%S" is equivalent to
"%ls".
For example, the following function is passed a locale-base name, a
hat size, and a time value. The hat size is formatted in a UTF-8
(ASCII) string, and the time value is formatted into a wchar_t
string::
void print_order (const char *name, int size,
struct tm *timep) {
char buf[32];
const char *size_val = "unknown";
if (size > 0)
snprintf(buf, sizeof(buf), "%d", size);
size_val = buf;
}
wchar_t when[32];
wcsftime(when, sizeof(when), L"%d%b%y", timep);
xo_emit("The hat for {:name/%hs} is {:size/%s}.\n",
name, size_val);
xo_emit("It was ordered on {:order-time/%ls}.\n",
when);
}
It is important to note that xo_emit will perform the conversion
required to make appropriate output. Text style output uses the
current locale (as described above), while XML, JSON, and HTML use
UTF-8.
UTF-8 and locale-encoded strings can use multiple bytes to encode one
column of data. The traditional "precision'" (aka "max-width") value
for "%s" printf formatting becomes overloaded since it specifies both
the number of bytes that can be safely referenced and the maximum
number of columns to emit. xo_emit uses the precision as the former,
and adds a third value for specifying the maximum number of columns.
In this example, the name field is printed with a minimum of 3 columns
and a maximum of 6. Up to ten bytes of data at the location given by
'name' are in used in filling those columns::
xo_emit("{:name/%3.10.6s}", name);
Characters Outside of Field Definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Characters in the format string that are not part of a field
definition are copied to the output for the TEXT style, and are
ignored for the JSON and XML styles. For HTML, these characters are
placed in a <div> with class "text"::
EXAMPLE:
xo_emit("The hat is {:size/%s}.\n", size_val);
TEXT:
The hat is extra small.
XML:
<size>extra small</size>
JSON:
"size": "extra small"
HTML:
<div class="text">The hat is </div>
<div class="data" data-tag="size">extra small</div>
<div class="text">.</div>
.. index:: errno
"%m" Is Supported
~~~~~~~~~~~~~~~~~
libxo supports the '%m' directive, which formats the error message
associated with the current value of "errno". It is the equivalent
of "%s" with the argument strerror(errno)::
xo_emit("{:filename} cannot be opened: {:error/%m}", filename);
xo_emit("{:filename} cannot be opened: {:error/%s}",
filename, strerror(errno));
"%n" Is Not Supported
~~~~~~~~~~~~~~~~~~~~~
libxo does not support the '%n' directive. It's a bad idea and we
just don't do it.
The Encoding Format (eformat)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "eformat" string is the format string used when encoding the field
for JSON and XML. If not provided, it defaults to the primary format
with any minimum width removed. If the primary is not given, both
default to "%s".
Content Strings
~~~~~~~~~~~~~~~
For padding and labels, the content string is considered the content,
unless a format is given.
.. index:: printf-like
Argument Validation
~~~~~~~~~~~~~~~~~~~
Many compilers and tool chains support validation of printf-like
arguments. When the format string fails to match the argument list,
a warning is generated. This is a valuable feature and while the
formatting strings for libxo differ considerably from printf, many of
these checks can still provide build-time protection against bugs.
libxo provide variants of functions that provide this ability, if the
"--enable-printflike" option is passed to the "configure" script.
These functions use the "_p" suffix, like "xo_emit_p()",
xo_emit_hp()", etc.
The following are features of libxo formatting strings that are
incompatible with printf-like testing:
- implicit formats, where "{:tag}" has an implicit "%s";
- the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to
ten bytes of data can be inspected to fill a minimum of 4 columns and
a maximum of 6;
- percent signs in strings, where "{:filled}%" makes a single,
trailing percent sign;
- the "l" and "h" modifiers for strings, where "{:tag/%hs}" means
locale-based string and "{:tag/%ls}" means a wide character string;
- distinct encoding formats, where "{:tag/#%s/%s}" means the display
styles (text and HTML) will use "#%s" where other styles use "%s";
If none of these features are in use by your code, then using the "_p"
variants might be wise:
================== ========================
Function printf-like Equivalent
================== ========================
xo_emit_hv xo_emit_hvp
xo_emit_h xo_emit_hp
xo_emit xo_emit_p
xo_emit_warn_hcv xo_emit_warn_hcvp
xo_emit_warn_hc xo_emit_warn_hcp
xo_emit_warn_c xo_emit_warn_cp
xo_emit_warn xo_emit_warn_p
xo_emit_warnx xo_emit_warnx_p
xo_emit_err xo_emit_err_p
xo_emit_errx xo_emit_errx_p
xo_emit_errc xo_emit_errc_p
================== ========================
.. index:: performance
.. index:: XOEF_RETAIN
.. _retain:
Retaining Parsed Format Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
libxo can retain the parsed internal information related to the given
format string, allowing subsequent xo_emit calls, the retained
information is used, avoiding repetitive parsing of the format string::
SYNTAX:
int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
EXAMPLE:
xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
some, thing, fancy);
To retain parsed format information, use the XOEF_RETAIN flag to the
xo_emit_f() function. A complete set of xo_emit_f functions exist to
match all the xo_emit function signatures (with handles, varadic
argument, and printf-like flags):
================== ========================
Function Flags Equivalent
================== ========================
xo_emit_hv xo_emit_hvf
xo_emit_h xo_emit_hf
xo_emit xo_emit_f
xo_emit_hvp xo_emit_hvfp
xo_emit_hp xo_emit_hfp
xo_emit_p xo_emit_fp
================== ========================
The format string must be immutable across multiple calls to xo_emit_f(),
since the library retains the string. Typically this is done by using
static constant strings, such as string literals. If the string is not
immutable, the XOEF_RETAIN flag must not be used.
The functions xo_retain_clear() and xo_retain_clear_all() release
internal information on either a single format string or all format
strings, respectively. Neither is required, but the library will
retain this information until it is cleared or the process exits::
const char *fmt = "{:name} {:count/%d}\n";
for (i = 0; i < 1000; i++) {
xo_open_instance("item");
xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
}
xo_retain_clear(fmt);
The retained information is kept as thread-specific data.
Example
~~~~~~~
In this example, the value for the number of items in stock is emitted::
xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
instock);
This call will generate the following output::
TEXT:
In stock: 144
XML:
<in-stock>144</in-stock>
JSON:
"in-stock": 144,
HTML:
<div class="line">
<div class="padding"> </div>
<div class="label">In stock</div>
<div class="decoration">:</div>
<div class="padding"> </div>
<div class="data" data-tag="in-stock">144</div>
</div>
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::
<div class="data" data-tag="in-stock"
data-xpath="/top/data/item/in-stock"
data-type="number"
data-help="Number of items in stock">144</div>

353
doc/field-modifiers.rst Normal file
View File

@ -0,0 +1,353 @@
.. index:: Field Modifiers
.. _field-modifiers:
Field Modifiers
~~~~~~~~~~~~~~~
Field modifiers are flags which modify the way content emitted for
particular output styles:
=== =============== ===================================================
M Name Description
=== =============== ===================================================
a argument The content appears as a 'const char \*' argument
c colon A colon (":") is appended after the label
d display Only emit field for display styles (text/HTML)
e encoding Only emit for encoding styles (XML/JSON)
g gettext Call gettext on field's render content
h humanize (hn) Format large numbers in human-readable style
\ hn-space Humanize: Place space between numeric and unit
\ hn-decimal Humanize: Add a decimal digit, if number < 10
\ hn-1000 Humanize: Use 1000 as divisor instead of 1024
k key Field is a key, suitable for XPath predicates
l leaf-list Field is a leaf-list
n no-quotes Do not quote the field when using JSON style
p plural Gettext: Use comma-separated plural form
q quotes Quote the field when using JSON style
t trim Trim leading and trailing whitespace
w white A blank (" ") is appended after the label
=== =============== ===================================================
Roles and modifiers can also use more verbose names, when preceded by
a comma. For example, the modifier string "Lwc" (or "L,white,colon")
means the field has a label role (text that describes the next field)
and should be followed by a colon ('c') and a space ('w'). The
modifier string "Vkq" (or ":key,quote") means the field has a value
role (the default role), that it is a key for the current instance,
and that the value should be quoted when encoded for JSON.
.. index:: Field Modifiers; Argument
.. _argument-modifier:
The Argument Modifier ({a:})
++++++++++++++++++++++++++++
.. index:: Field Modifiers; Argument
The argument modifier indicates that the content of the field
descriptor will be placed as a UTF-8 string (const char \*) argument
within the xo_emit parameters::
EXAMPLE:
xo_emit("{La:} {a:}\n", "Label text", "label", "value");
TEXT:
Label text value
JSON:
"label": "value"
XML:
<label>value</label>
The argument modifier allows field names for value fields to be passed
on the stack, avoiding the need to build a field descriptor using
snprintf. For many field roles, the argument modifier is not needed,
since those roles have specific mechanisms for arguments, such as
"{C:fg-%s}".
.. index:: Field Modifiers; Colon
.. _colon-modifier:
The Colon Modifier ({c:})
+++++++++++++++++++++++++
.. index:: Field Modifiers; Colon
The colon modifier appends a single colon to the data value::
EXAMPLE:
xo_emit("{Lc:Name}{:name}\n", "phil");
TEXT:
Name:phil
The colon modifier is only used for the TEXT and HTML output
styles. It is commonly combined with the space modifier ('{w:}').
It is purely a convenience feature.
.. index:: Field Modifiers; Display
.. _display-modifier:
The Display Modifier ({d:})
+++++++++++++++++++++++++++
.. index:: Field Modifiers; Display
The display modifier indicated the field should only be generated for
the display output styles, TEXT and HTML::
EXAMPLE:
xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
TEXT:
Name: phil 1
XML:
<id>1</id>
The display modifier is the opposite of the encoding modifier, and
they are often used to give to distinct views of the underlying data.
.. index:: Field Modifiers; Encoding
.. _encoding-modifier:
The Encoding Modifier ({e:})
++++++++++++++++++++++++++++
.. index:: Field Modifiers; Encoding
The display modifier indicated the field should only be generated for
the display output styles, TEXT and HTML::
EXAMPLE:
xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
TEXT:
Name: phil
XML:
<name>phil</name><id>1</id>
The encoding modifier is the opposite of the display modifier, and
they are often used to give to distinct views of the underlying data.
.. index:: Field Modifiers; Gettext
.. _gettext-modifier:
The Gettext Modifier ({g:})
+++++++++++++++++++++++++++
.. index:: Field Modifiers; Gettext
.. index:: gettext
The gettext modifier is used to translate individual fields using the
gettext domain (typically set using the "`{G:}`" role) and current
language settings. Once libxo renders the field value, it is passed
to gettext(3), where it is used as a key to find the native language
translation.
In the following example, the strings "State" and "full" are passed
to gettext() to find locale-based translated strings::
xo_emit("{Lgwc:State}{g:state}\n", "full");
See :ref:`gettext-role`, :ref:`plural-modifier`, and
:ref:`i18n` for additional details.
.. index:: Field Modifiers; Humanize
.. _humanize-modifier:
The Humanize Modifier ({h:})
++++++++++++++++++++++++++++
.. index:: Field Modifiers; Humanize
The humanize modifier is used to render large numbers as in a
human-readable format. While numbers like "44470272" are completely
readable to computers and savants, humans will generally find "44M"
more meaningful.
"hn" can be used as an alias for "humanize".
The humanize modifier only affects display styles (TEXT and HMTL).
The "`no-humanize`" option (See :ref:`options`) will block
the function of the humanize modifier.
There are a number of modifiers that affect details of humanization.
These are only available in as full names, not single characters. The
"`hn-space`" modifier places a space between the number and any
multiplier symbol, such as "M" or "K" (ex: "44 K"). The
"`hn-decimal`" modifier will add a decimal point and a single tenths
digit when the number is less than 10 (ex: "4.4K"). The "`hn-1000`"
modifier will use 1000 as divisor instead of 1024, following the
JEDEC-standard instead of the more natural binary powers-of-two
tradition::
EXAMPLE:
xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
"{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
"{h,hn-decimal:remaining/%u}\n",
input, output, errors, capacity, remaining);
TEXT:
21, 57 K, 96M, 44M, 1.2G
In the HTML style, the original numeric value is rendered in the
"data-number" attribute on the <div> element::
<div class="data" data-tag="errors"
data-number="100663296">96M</div>
.. index:: Field Modifiers; Key
.. _key-modifier:
The Key Modifier ({k:})
+++++++++++++++++++++++
.. index:: Field Modifiers; Key
The key modifier is used to indicate that a particular field helps
uniquely identify an instance of list data::
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
xo_open_instance("user");
xo_emit("User {k:name} has {:count} tickets\n",
user[i].u_name, user[i].u_tickets);
xo_close_instance("user");
}
xo_close_list("user");
.. index:: XOF_XPATH
Currently the key modifier is only used when generating XPath value
for the HTML output style when XOF_XPATH is set, but other uses are
likely in the near future.
.. index:: Field Modifiers; Leaf-List
.. _leaf-list:
The Leaf-List Modifier ({l:})
+++++++++++++++++++++++++++++
.. index:: Field Modifiers; Leaf-List
The leaf-list modifier is used to distinguish lists where each
instance consists of only a single value. In XML, these are
rendered as single elements, where JSON renders them as arrays::
EXAMPLE:
for (i = 0; i < num_users; i++) {
xo_emit("Member {l:user}\n", user[i].u_name);
}
XML:
<user>phil</user>
<user>pallavi</user>
JSON:
"user": [ "phil", "pallavi" ]
The name of the field must match the name of the leaf list.
.. index:: Field Modifiers; No-Quotes
.. _no-quotes-modifier:
The No-Quotes Modifier ({n:})
+++++++++++++++++++++++++++++
.. index:: Field Modifiers; No-Quotes
The no-quotes modifier (and its twin, the 'quotes' modifier) affect
the quoting of values in the JSON output style. JSON uses quotes for
string value, but no quotes for numeric, boolean, and null data.
xo_emit applies a simple heuristic to determine whether quotes are
needed, but often this needs to be controlled by the caller::
EXAMPLE:
const char *bool = is_true ? "true" : "false";
xo_emit("{n:fancy/%s}", bool);
JSON:
"fancy": true
.. index:: Field Modifiers; Plural
.. _plural-modifier:
The Plural Modifier ({p:})
++++++++++++++++++++++++++
.. index:: Field Modifiers; Plural
.. index:: gettext
The plural modifier selects the appropriate plural form of an
expression based on the most recent number emitted and the current
language settings. The contents of the field should be the singular
and plural English values, separated by a comma::
xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
The plural modifier is meant to work with the gettext modifier ({g:})
but can work independently. See :ref:`gettext-modifier`.
When used without the gettext modifier or when the message does not
appear in the message catalog, the first token is chosen when the last
numeric value is equal to 1; otherwise the second value is used,
mimicking the simple pluralization rules of English.
When used with the gettext modifier, the ngettext(3) function is
called to handle the heavy lifting, using the message catalog to
convert the singular and plural forms into the native language.
.. index:: Field Modifiers; Quotes
.. _quotes-modifier:
The Quotes Modifier ({q:})
++++++++++++++++++++++++++
.. index:: Field Modifiers; Quotes
The quotes modifier (and its twin, the 'no-quotes' modifier) affect
the quoting of values in the JSON output style. JSON uses quotes for
string value, but no quotes for numeric, boolean, and null data.
xo_emit applies a simple heuristic to determine whether quotes are
needed, but often this needs to be controlled by the caller::
EXAMPLE:
xo_emit("{q:time/%d}", 2014);
JSON:
"year": "2014"
The heuristic is based on the format; if the format uses any of the
following conversion specifiers, then no quotes are used::
d i o u x X D O U e E f F g G a A c C p
.. index:: Field Modifiers; Trim
.. _trim-modifier:
The Trim Modifier ({t:})
++++++++++++++++++++++++
.. index:: Field Modifiers; Trim
The trim modifier removes any leading or trailing whitespace from
the value::
EXAMPLE:
xo_emit("{t:description}", " some input ");
JSON:
"description": "some input"
.. index:: Field Modifiers; White Space
.. _white-space-modifier:
The White Space Modifier ({w:})
+++++++++++++++++++++++++++++++
.. index:: Field Modifiers; White Space
The white space modifier appends a single space to the data value::
EXAMPLE:
xo_emit("{Lw:Name}{:name}\n", "phil");
TEXT:
Name phil
The white space modifier is only used for the TEXT and HTML output
styles. It is commonly combined with the colon modifier ('{c:}').
It is purely a convenience feature.
Note that the sense of the 'w' modifier is reversed for the units role
({Uw:}); a blank is added before the contents, rather than after it.

310
doc/field-roles.rst Normal file
View File

@ -0,0 +1,310 @@
.. index:: Field Roles
.. _field-roles:
Field Roles
~~~~~~~~~~~
Field roles are optional, and indicate the role and formatting of the
content. The roles are listed below; only one role is permitted:
=== ============== =================================================
R Name Description
=== ============== =================================================
C color Field has color and effect controls
D decoration Field is non-text (e.g., colon, comma)
E error Field is an error message
G gettext Call gettext(3) on the format string
L label Field is text that prefixes a value
N note Field is text that follows a value
P padding Field is spaces needed for vertical alignment
T title Field is a title value for headings
U units Field is the units for the previous value field
V value Field is the name of field (the default)
W warning Field is a warning message
[ start-anchor Begin a section of anchored variable-width text
] stop-anchor End a section of anchored variable-width text
=== ============== =================================================
EXAMPLE:
xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n",
free_blocks);
When a role is not provided, the "*value*" role is used as the default.
Roles and modifiers can also use more verbose names, when preceded by
a comma::
EXAMPLE:
xo_emit("{,label:Free}{,decoration::}{,padding: }"
"{,value:free/%u} {,units:Blocks}\n",
free_blocks);
.. index:: Field Roles; Color
.. _color-role:
The Color Role ({C:})
+++++++++++++++++++++
Colors and effects control how text values are displayed; they are
used for display styles (TEXT and HTML)::
xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
Colors and effects remain in effect until modified by other "C"-role
fields::
xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
If the content is empty, the "*reset*" action is performed::
xo_emit("{C:both,underline}{:value}{C:}\n", value);
The content should be a comma-separated list of zero or more colors or
display effects::
xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n");
The color content can be either static, when placed directly within
the field descriptor, or a printf-style format descriptor can be used,
if preceded by a slash ("/"):
xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
need_underline ? "underline" : "", value);
Color names are prefixed with either "fg-" or "bg-" to change the
foreground and background colors, respectively::
xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
fg_color, bg_color, cost);
The following table lists the supported effects:
=============== =================================================
Name Description
=============== =================================================
bg-XXXXX Change background color
bold Start bold text effect
fg-XXXXX Change foreground color
inverse Start inverse (aka reverse) text effect
no-bold Stop bold text effect
no-inverse Stop inverse (aka reverse) text effect
no-underline Stop underline text effect
normal Reset effects (only)
reset Reset colors and effects (restore defaults)
underline Start underline text effect
=============== =================================================
The following color names are supported:
========= ============================================
Name Description
========= ============================================
black
blue
cyan
default Default color for foreground or background
green
magenta
red
white
yellow
========= ============================================
When using colors, the developer should remember that users will
change the foreground and background colors of terminal session
according to their own tastes, so assuming that "blue" looks nice is
never safe, and is a constant annoyance to your dear author. In
addition, a significant percentage of users (1 in 12) will be color
blind. Depending on color to convey critical information is not a
good idea. Color should enhance output, but should not be used as the
sole means of encoding information.
.. index:: Field Roles; Decoration
.. _decoration-role:
The Decoration Role ({D:})
++++++++++++++++++++++++++
Decorations are typically punctuation marks such as colons,
semi-colons, and commas used to decorate the text and make it simpler
for human readers. By marking these distinctly, HTML usage scenarios
can use CSS to direct their display parameters::
xo_emit("{D:((}{:name}{D:))}\n", name);
.. index:: Field Roles; Gettext
.. _gettext-role:
The Gettext Role ({G:})
+++++++++++++++++++++++
libxo supports internationalization (i18n) through its use of
gettext(3). Use the "{G:}" role to request that the remaining part of
the format string, following the "{G:}" field, be handled using
gettext().
Since gettext() uses the string as the key into the message catalog,
libxo uses a simplified version of the format string that removes
unimportant field formatting and modifiers, stopping minor formatting
changes from impacting the expensive translation process. A developer
change such as changing "/%06d" to "/%08d" should not force hand
inspection of all .po files.
The simplified version can be generated for a single message using the
"`xopo -s $text`" command, or an entire .pot can be translated using
the "`xopo -f $input -o $output`" command.
xo_emit("{G:}Invalid token\n");
The {G:} role allows a domain name to be set. gettext calls will
continue to use that domain name until the current format string
processing is complete, enabling a library function to emit strings
using it's own catalog. The domain name can be either static as the
content of the field, or a format can be used to get the domain name
from the arguments.
xo_emit("{G:libc}Service unavailable in restricted mode\n");
See :ref:`i18n` for additional details.
.. index:: Field Roles; Label
.. _label-role:
The Label Role ({L:})
+++++++++++++++++++++
Labels are text that appears before a value::
xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
.. index:: Field Roles; Note
.. _note-role:
The Note Role ({N:})
++++++++++++++++++++
Notes are text that appears after a value::
xo_emit("{:cost/%u} {N:per year}\n", cost);
.. index:: Field Roles; Padding
.. _padding-role:
The Padding Role ({P:})
+++++++++++++++++++++++
Padding represents whitespace used before and between fields.
The padding content can be either static, when placed directly within
the field descriptor, or a printf-style format descriptor can be used,
if preceded by a slash ("/")::
xo_emit("{P: }{Lwc:Cost}{:cost/%u}\n", cost);
xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
.. index:: Field Roles; Title
.. _title-role:
The Title Role ({T:})
+++++++++++++++++++++
Title are heading or column headers that are meant to be displayed to
the user. The title can be either static, when placed directly within
the field descriptor, or a printf-style format descriptor can be used,
if preceded by a slash ("/")::
xo_emit("{T:Interface Statistics}\n");
xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
Title fields have an extra convenience feature; if both content and
format are specified, instead of looking to the argument list for a
value, the content is used, allowing a mixture of format and content
within the field descriptor::
xo_emit("{T:Name/%20s}{T:Count/%6s}\n");
Since the incoming argument is a string, the format must be "%s" or
something suitable.
.. index:: Field Roles; Units
.. index:: XOF_UNITS
.. _units-role:
The Units Role ({U:})
+++++++++++++++++++++
Units are the dimension by which values are measured, such as degrees,
miles, bytes, and decibels. The units field carries this information
for the previous value field::
xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
Note that the sense of the 'w' modifier is reversed for units;
a blank is added before the contents, rather than after it.
When the XOF_UNITS flag is set, units are rendered in XML as the
"units" attribute::
<distance units="miles">50</distance>
Units can also be rendered in HTML as the "data-units" attribute::
<div class="data" data-tag="distance" data-units="miles"
data-xpath="/top/data/distance">50</div>
.. index:: Field Roles; Value
.. _value-role:
The Value Role ({V:} and {:})
+++++++++++++++++++++++++++++
The value role is used to represent the a data value that is
interesting for the non-display output styles (XML and JSON). Value
is the default role; if no other role designation is given, the field
is a value. The field name must appear within the field descriptor,
followed by one or two format descriptors. The first format
descriptor is used for display styles (TEXT and HTML), while the
second one is used for encoding styles (XML and JSON). If no second
format is given, the encoding format defaults to the first format,
with any minimum width removed. If no first format is given, both
format descriptors default to "%s"::
xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
length, width, height);
xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n,
author, poem, year);
.. index:: Field Roles; Anchor
.. _anchor-role:
The Anchor Roles ({[:} and {]:})
++++++++++++++++++++++++++++++++
The anchor roles allow a set of strings by be padded as a group,
but still be visible to xo_emit as distinct fields. Either the start
or stop anchor can give a field width and it can be either directly in
the descriptor or passed as an argument. Any fields between the start
and stop anchor are padded to meet the minimum width given.
To give a width directly, encode it as the content of the anchor tag::
xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
To pass a width as an argument, use "%d" as the format, which must
appear after the "/". Note that only "%d" is supported for widths.
Using any other value could ruin your day::
xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
If the width is negative, padding will be added on the right, suitable
for left justification. Otherwise the padding will be added to the
left of the fields between the start and stop anchors, suitable for
right justification. If the width is zero, nothing happens. If the
number of columns of output between the start and stop anchors is less
than the absolute value of the given width, nothing happens.
.. index:: XOF_WARN
Widths over 8k are considered probable errors and not supported. If
XOF_WARN is set, a warning will be generated.

47
doc/format-strings.rst Normal file
View File

@ -0,0 +1,47 @@
.. index:: Format Strings
.. _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 ]* [',' 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);
This single line of code can generate text (" In stock: 65\n"), XML
("<in-stock>65</in-stock>"), JSON ('"in-stock": 6'), or HTML (too
lengthy to be listed here).
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::
xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65);

165
doc/formatting.rst Normal file
View File

@ -0,0 +1,165 @@
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; "<div>" 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:
Connecting to my-box.example.com...
XML:
<host>my-box</host>
<domain>example.com</domain>
JSON:
"host": "my-box",
"domain": "example.com"
HTML:
<div class="line">
<div class="text">Connecting to </div>
<div class="data" data-tag="host"
data-xpath="/top/host">my-box</div>
<div class="text">.</div>
<div class="data" data-tag="domain"
data-xpath="/top/domain">example.com</div>
<div class="text">...</div>
</div>
Encoding Styles
---------------
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 :ref:`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
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::
<item>
<blocks>36</blocks>
<path>./src</path>
</item>
<item>
<blocks>40</blocks>
<path>./bin</path>
</item>
<item>
<blocks>90</blocks>
<path>.</path>
</item>
`XML`_ is the W3C standard for encoding data.
.. _XML: https://w3c.org/TR/xml
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 <div> 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::
<div class="line">
<div class="data" data-tag="blocks">36</div>
<div class="padding"> </div>
<div class="data" data-tag="path">./src</div>
</div>
<div class="line">
<div class="data" data-tag="blocks">40</div>
<div class="padding"> </div>
<div class="data" data-tag="path">./bin</div>
</div>
<div class="line">
<div class="data" data-tag="blocks">90</div>
<div class="padding"> </div>
<div class="data" data-tag="path">./</div>
</div>

185
doc/getting.rst Normal file
View File

@ -0,0 +1,185 @@
.. index:: Getting libxo
Getting libxo
=============
libxo now ships as part of the FreeBSD Operating System (as of Release
11).
libxo source code lives on github:
https://github.com/Juniper/libxo
The latest release of libxo is available at:
https://github.com/Juniper/libxo/releases
We're using `Semantic Versioning`_ to number our releases. libxo is
open source, distributed under the BSD license. We follow the
branching scheme from `A Successful Git Branching Model`_:
we 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
.. _Semantic Versioning: http://semver.org/spec/v2.0.0.html
.. _A Successful Git Branching Model:
http://nvie.com/posts/a-successful-git-branching-model
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 the `release page`_ to see the list of
releases. To download the latest, look for the release witeh the
green "Latest release" button and the green "libxo-RELEASE.tar.gz"
button under that section.
.. _release page: https://github.com/Juniper/libxo/releases
After downloading that release's distfile, untar it as follows::
tar -zxf libxo-RELEASE.tar.gz
cd libxo-RELEASE
.. admonition:: Solaris Users
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
.. admonition:: 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:
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 through each of these steps with
additional details and options, but the above directions should be all
that's needed.
Setting up the build
~~~~~~~~~~~~~~~~~~~~
.. admonition: Note
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

394
doc/howto.rst Normal file
View File

@ -0,0 +1,394 @@
Howtos: Focused Directions
==========================
This section provides task-oriented instructions for selected tasks.
If you have a task that needs instructions, please open a request as
an enhancement issue on github.
Howto: Report bugs
------------------
libxo uses github to track bugs or request enhancements. Please use
the following URL:
https://github.com/Juniper/libxo/issues
Howto: Install libxo
--------------------
libxo is open source, under a new BSD license. Source code is
available on github, as are recent releases. To get the most
current release, please visit:
https://github.com/Juniper/libxo/releases
After downloading and untarring the source code, building involves the
following steps::
sh bin/setup.sh
cd build
../configure
make
make test
sudo make install
libxo uses a distinct "*build*" directory to keep generated files
separated from source files.
.. index:: configure
Use "`../configure --help`" to display available configuration
options, which include the following::
--enable-warnings Turn on compiler warnings
--enable-debug Turn on debugging
--enable-text-only Turn on text-only rendering
--enable-printflike Enable use of GCC __printflike attribute
--disable-libxo-options Turn off support for LIBXO_OPTIONS
--with-gettext=PFX Specify location of gettext installation
--with-libslax-prefix=PFX Specify location of libslax config
Compiler warnings are a very good thing, but recent compiler version
have added some very pedantic checks. While every attempt is made to
keep libxo code warning-free, warnings are now optional. If you are
doing development work on libxo, it is required that you
use --enable-warnings to keep the code warning free, but most users
need not use this option.
.. index:: --enable-text-only
libxo provides the `--enable-text-only` option to reduce the
footprint of the library for smaller installations. XML, JSON, and
HTML rendering logic is removed.
.. index:: --with-gettext
The gettext library does not provide a simple means of learning its
location, but libxo will look for it in /usr and /opt/local. If
installed elsewhere, the installer will need to provide this
information using the "`--with-gettext=/dir/path`" option.
.. index:: libslax
libslax is not required by libxo; it contains the "oxtradoc" program
used to format documentation.
For additional information, see :ref:`building`.
Howto: Convert command line applications
----------------------------------------
Common question: How do I convert an existing command line application?
There are four basic steps for converting command line application to
use libxo::
- Setting up the context
- Converting printf calls
- Creating hierarchy
- Converting error functions
Setting up the context
~~~~~~~~~~~~~~~~~~~~~~
To use libxo, you'll need to include the "xo.h" header file in your
source code files::
#include <libxo/xo.h>
In your main() function, you'll need to call xo_parse_args to handling
argument parsing (:ref:`xo_parse_args`). This function removes
libxo-specific arguments the program's argv and returns either the
number of remaining arguments or -1 to indicate an error::
int
main (int argc, char **argv)
{
argc = xo_parse_args(argc, argv);
if (argc < 0)
return argc;
....
}
.. index:: atexit
.. index:: xo_finish_atexit
At the bottom of your main(), you'll need to call xo_finish() to
complete output processing for the default handle (:ref:`handles`). This
is required to flush internal information buffers. libxo provides the
xo_finish_atexit function that is suitable for use with the
:manpage:`atexit(3)` function::
atexit(xo_finish_atexit);
Converting printf Calls
~~~~~~~~~~~~~~~~~~~~~~~
The second task is inspecting code for :manpage:`printf(3)` calls and
replacing them with xo_emit() calls. The format strings are similar
in task, but libxo format strings wrap output fields in braces. The
following two calls produce identical text output::
OLD::
printf("There are %d %s events\n", count, etype);
NEW::
xo_emit("There are {:count/%d} {:event} events\n", count, etype);
"count" and "event" are used as names for JSON and XML output. The
"count" field uses the format "%d" and "event" uses the default "%s"
format. Both are "value" roles, which is the default role.
Since text outside of output fields is passed verbatim, other roles
are less important, but their proper use can help make output more
useful. The "note" and "label" roles allow HTML output to recognize
the relationship between text and the associated values, allowing
appropriate "hover" and "onclick" behavior. Using the "units" role
allows the presentation layer to perform conversions when needed. The
"warning" and "error" roles allows use of color and font to draw
attention to warnings. The "padding" role makes the use of vital
whitespace more clear (:ref:`padding-role`).
The "*title*" role indicates the headings of table and sections. This
allows HTML output to use CSS to make this relationship more obvious::
OLD::
printf("Statistics:\n");
NEW::
xo_emit("{T:Statistics}:\n");
The "*color*" roles controls foreground and background colors, as well
as effects like bold and underline (see :ref:`color-role`)::
NEW::
xo_emit("{C:bold}required{C:}\n");
Finally, the start- and stop-anchor roles allow justification and
padding over multiple fields (see :ref:`anchor-role`)::
OLD::
snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max);
printf("%30s", buf);
NEW::
xo_emit("{[:30}({:minimum/%u}/{:average/%u}/{:maximum/%u}{]:}",
min, ave, max);
Creating Hierarchy
~~~~~~~~~~~~~~~~~~
Text output doesn't have any sort of hierarchy, but XML and JSON
require this. Typically applications use indentation to represent
these relationship::
OLD::
printf("table %d\n", tnum);
for (i = 0; i < tmax; i++) {
printf(" %s %d\n", table[i].name, table[i].size);
}
NEW::
xo_emit("{T:/table %d}\n", tnum);
xo_open_list("table");
for (i = 0; i < tmax; i++) {
xo_open_instance("table");
xo_emit("{P: }{k:name} {:size/%d}\n",
table[i].name, table[i].size);
xo_close_instance("table");
}
xo_close_list("table");
The open and close list functions are used before and after the list,
and the open and close instance functions are used before and after
each instance with in the list.
Typically these developer looks for a "for" loop as an indication of
where to put these calls.
In addition, the open and close container functions allow for
organization levels of hierarchy::
OLD::
printf("Paging information:\n");
printf(" Free: %lu\n", free);
printf(" Active: %lu\n", active);
printf(" Inactive: %lu\n", inactive);
NEW::
xo_open_container("paging-information");
xo_emit("{P: }{L:Free: }{:free/%lu}\n", free);
xo_emit("{P: }{L:Active: }{:active/%lu}\n", active);
xo_emit("{P: }{L:Inactive: }{:inactive/%lu}\n", inactive);
xo_close_container("paging-information");
Converting Error Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~
libxo provides variants of the standard error and warning functions,
:manpage:`err(3)` and :manpage:`warn(3)`. There are two variants, one
for putting the errors on standard error, and the other writes the
errors and warnings to the handle using the appropriate encoding
style::
OLD::
err(1, "cannot open output file: %s", file);
NEW::
xo_err(1, "cannot open output file: %s", file);
xo_emit_err(1, "cannot open output file: {:filename}", file);
.. index:: xo_finish
Call xo_finish
~~~~~~~~~~~~~~
One important item: call `xo_finish` at the end of your program so
ensure that all buffered data is written out. You can call it
explicitly call it, or use :manpage:`atexit(3)` to have
`xo_finish_atexit` called implicitly on exit::
OLD::
exit(0);
NEW::
xo_finish();
exit(0);
Howto: Use "xo" in Shell Scripts
--------------------------------
.. admonition:: Needed
Documentation is needed for this area.
.. index:: Internationalization (i18n)
.. index:: gettext
.. index:: xopo
.. _i18n:
Howto: Internationalization (i18n)
-----------------------------------------------
How do I use libxo to support internationalization?
libxo allows format and field strings to be used a keys into message
catalogs to enable translation into a user's native language by
invoking the standard :manpage:`gettext(3)` functions.
gettext setup is a bit complicated: text strings are extracted from
source files into "*portable object template*" (.pot) files using the
`xgettext` command. For each language, this template file is used as
the source for a message catalog in the "*portable object*" (.po)
format, which are translated by hand and compiled into "*machine
object*" (.mo) files using the `msgfmt` command. The .mo files are
then typically installed in the /usr/share/locale or
/opt/local/share/locale directories. At run time, the user's language
settings are used to select a .mo file which is searched for matching
messages. Text strings in the source code are used as keys to look up
the native language strings in the .mo file.
Since the xo_emit format string is used as the key into the message
catalog, libxo removes unimportant field formatting and modifiers from
the format string before use so that minor formatting changes will not
impact the expensive translation process. We don't want a developer
change such as changing "/%06d" to "/%08d" to force hand inspection of
all .po files. The simplified version can be generated for a single
message using the `xopo -s $text` command, or an entire .pot can be
translated using the `xopo -f $input -o $output` command::
EXAMPLE:
% xopo -s "There are {:count/%u} {:event/%.6s} events\n"
There are {:count} {:event} events\n
Recommended workflow:
# Extract text messages
xgettext --default-domain=foo --no-wrap \
--add-comments --keyword=xo_emit --keyword=xo_emit_h \
--keyword=xo_emit_warn -C -E -n --foreign-user \
-o foo.pot.raw foo.c
# Simplify format strings for libxo
xopo -f foo.pot.raw -o foo.pot
# For a new language, just copy the file
cp foo.pot po/LC/my_lang/foo.po
# For an existing language:
msgmerge --no-wrap po/LC/my_lang/foo.po \
foo.pot -o po/LC/my_lang/foo.po.new
# Now the hard part: translate foo.po using tools
# like poedit or emacs' po-mode
# Compile the finished file; Use of msgfmt's "-v" option is
# strongly encouraged, so that "fuzzy" entries are reported.
msgfmt -v -o po/my_lang/LC_MESSAGES/foo.mo po/my_lang/foo.po
# Install the .mo file
sudo cp po/my_lang/LC_MESSAGES/foo.mo \
/opt/local/share/locale/my_lang/LC_MESSAGE/
Once these steps are complete, you can use the `gettext` command to
test the message catalog::
gettext -d foo -e "some text"
i18n and xo_emit
~~~~~~~~~~~~~~~~
There are three features used in libxo used to support i18n:
- The "{G:}" role looks for a translation of the format string.
- The "{g:}" modifier looks for a translation of the field.
- The "{p:}" modifier looks for a pluralized version of the field.
Together these three flags allows a single function call to give
native language support, as well as libxo's normal XML, JSON, and HTML
support::
printf(gettext("Received %zu %s from {g:server} server\n"),
counter, ngettext("byte", "bytes", counter),
gettext("web"));
xo_emit("{G:}Received {:received/%zu} {Ngp:byte,bytes} "
"from {g:server} server\n", counter, "web");
libxo will see the "{G:}" role and will first simplify the format
string, removing field formats and modifiers::
"Received {:received} {N:byte,bytes} from {:server} server\n"
libxo calls :manpage:`gettext(3)` with that string to get a localized
version. If your language were *Pig Latin*, the result might look
like::
"Eceivedray {:received} {N:byte,bytes} omfray "
"{:server} erversay\n"
Note the field names do not change and they should not be translated.
The contents of the note ("byte,bytes") should also not be translated,
since the "g" modifier will need the untranslated value as the key for
the message catalog.
The field "{g:server}" requests the rendered value of the field be
translated using :manpage:`gettext(3)`. In this example, "web" would
be used.
The field "{Ngp:byte,bytes}" shows an example of plural form using the
"{p:}" modifier with the "{g:}" modifier. The base singular and plural
forms appear inside the field, separated by a comma. At run time,
libxo uses the previous field's numeric value to decide which form to
use by calling :manpage:`ngettext(3)`.
If a domain name is needed, it can be supplied as the content of the
{G:} role. Domain names remain in use throughout the format string
until cleared with another domain name::
printf(dgettext("dns", "Host %s not found: %d(%s)\n"),
name, errno, dgettext("strerror", strerror(errno)));
xo_emit("{G:dns}Host {:hostname} not found: "
"%d({G:strerror}{g:%m})\n", name, errno);

53
doc/index.rst Normal file
View File

@ -0,0 +1,53 @@
.. #
# Copyright (c) 2014, Juniper Networks, Inc.
# All rights reserved.
# This SOFTWARE is licensed under the LICENSE provided in the
# ../Copyright file. By downloading, installing, copying, or
# using the SOFTWARE, you agree to be bound by the terms of that
# LICENSE.
# Phil Shafer, July 2014
#
.. default-role:: code
libxo - A Library for Generating Text, XML, JSON, and HTML Output
===================================================================
The libxo library allows an application to generate text, XML, JSON,
and HTML output, suitable for both command line use and for web
applications. The application decides at run time which output style
should be produced. By using libxo, a single source code path can
emit multiple styles of output using command line options to select
the style, along with optional behaviors. libxo includes support for
multiple output streams, pluralization, color, syslog,
:manpage:`humanized(3)` output, internationalization, and UTF-8. The
library aims to minimize the cost of migrating code to libxo.
libxo ships as part of FreeBSD.
.. toctree::
:maxdepth: 3
:caption: Documentation Contents:
intro
getting
formatting
options
format-strings
field-roles
field-modifiers
field-formatting
api
xo
xolint
xohtml
xopo
faq
howto
example
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

90
doc/intro.rst Normal file
View File

@ -0,0 +1,90 @@
Introducing libxo
=================
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 printf-like :ref:`format-strings`::
xo_emit(" {:lines/%7ju} {:words/%7ju} "
"{: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 (see
:ref:`field-roles` for details). Modifiers change how the field is
rendered in different output styles (see :ref:`field-modifiers` for
details. 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
<wc>
<file>
<lines>25</lines>
<words>165</words>
<characters>1140</characters>
<filename>/etc/motd</filename>
</file>
</wc>
% wc --libxo json,pretty,warn /etc/motd
{
"wc": {
"file": [
{
"lines": 25,
"words": 165,
"characters": 1140,
"filename": "/etc/motd"
}
]
}
}
% wc --libxo html,pretty,warn /etc/motd
<div class="line">
<div class="text"> </div>
<div class="data" data-tag="lines"> 25</div>
<div class="text"> </div>
<div class="data" data-tag="words"> 165</div>
<div class="text"> </div>
<div class="data" data-tag="characters"> 1140</div>
<div class="text"> </div>
<div class="data" data-tag="filename">/etc/motd</div>
</div>
Same code path, same format strings, same information, but it's
rendered in distinct styles based on run-time flags.
.. admonition:: Tale of Two Code Paths
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 work done 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 */
if (xml) {
/* some code to make xml */
} else {
/* other code to make text */
/* oops! forgot to add something on both clauses! */
}
/* And ifdefs are right out. */
#ifdef MAKE_XML
/* icky */
#else
/* pooh */
#endif
But you'd really, really like all the fancy features that modern
encoding formats can provide. libxo can help.

436
doc/libxo-manual.html
View File

File diff suppressed because it is too large Load Diff

164
doc/options.rst Normal file
View File

@ -0,0 +1,164 @@
.. index:: --libxo
.. index:: Options
.. _options:
Command-line Arguments
======================
libxo uses command line options to trigger rendering behavior. There
are multiple conventions for passing options, all using the
"`--libxo`" option::
--libxo <options>
--libxo=<options>
--libxo:<brief-options>
The *brief-options* is a series of single letter abbrevations, where
the *options* is a comma-separated list of words. Both provide access
to identical functionality. The following invocations are all
identical in outcome::
my-app --libxo warn,pretty arg1
my-app --libxo=warn,pretty arg1
my-app --libxo:WP arg1
Programs using libxo are expecting to call the xo_parse_args function
to parse these arguments. See :ref:`xo_parse_args` for details.
Option Keywords
---------------
Options is a comma-separated list of tokens that correspond to output
styles, flags, or features:
=============== =======================================================
Token Action
=============== =======================================================
color Enable colors/effects for display styles (TEXT, HTML)
colors=xxxx Adjust color output values
dtrt Enable "Do The Right Thing" mode
flush Flush after every libxo function call
flush-line Flush after every line (line-buffered)
html Emit HTML output
indent=xx Set the indentation level
info Add info attributes (HTML)
json Emit JSON output
keys Emit the key attribute for keys (XML)
log-gettext Log (via stderr) each gettext(3) string lookup
log-syslog Log (via stderr) each syslog message (via xo_syslog)
no-humanize Ignore the {h:} modifier (TEXT, HTML)
no-locale Do not initialize the locale setting
no-retain Prevent retaining formatting information
no-top Do not emit a top set of braces (JSON)
not-first Pretend the 1st output item was not 1st (JSON)
pretty Emit pretty-printed output
retain Force retaining formatting information
text Emit TEXT output
underscores Replace XML-friendly "-"s with JSON friendly "_"s
units Add the 'units' (XML) or 'data-units (HTML) attribute
warn Emit warnings when libxo detects bad calls
warn-xml Emit warnings in XML
xml Emit XML output
xpath Add XPath expressions (HTML)
=============== =======================================================
Most of these option are simple and direct, but some require
additional details:
- "colors" is described in :ref:`color-mapping`.
- "flush-line" performs line buffering, even when the output is not
directed to a TTY device.
- "info" generates additional data for HTML, encoded in attributes
using names that state with "data-".
- "keys" adds a "key" attribute for XML output to indicate that a leaf
is an identifier for the list member.
- "no-humanize" avoids "humanizing" numeric output (see
:ref:`humanize-modifier` for details).
- "no-locale" instructs libxo to avoid translating output to the
current locale.
- "no-retain" disables the ability of libxo to internally retain
"compiled" information about formatting strings (see :ref:`retain`
for details).
- "underscores" can be used with JSON output to change XML-friendly
names with dashes into JSON-friendly name with underscores.
- "warn" allows libxo to emit warnings on stderr when application code
make incorrect calls.
- "warn-xml" causes those warnings to be placed in XML inside the
output.
Brief Options
-------------
The brief options are simple single-letter aliases to the normal
keywords, as detailed below:
======== =============================================
Option Action
======== =============================================
c Enable color/effects for TEXT/HTML
F Force line-buffered flushing
H Enable HTML output (XO_STYLE_HTML)
I Enable info output (XOF_INFO)
i<num> Indent by <number>
J Enable JSON output (XO_STYLE_JSON)
k Add keys to XPATH expressions in HTML
n Disable humanization (TEXT, HTML)
P Enable pretty-printed output (XOF_PRETTY)
T Enable text output (XO_STYLE_TEXT)
U Add units to HTML output
u Change "-"s to "_"s in element names (JSON)
W Enable warnings (XOF_WARN)
X Enable XML output (XO_STYLE_XML)
x Enable XPath data (XOF_XPATH)
======== =============================================
.. index:: Colors
.. _color-mapping:
Color Mapping
-------------
The "colors" option takes a value that is a set of mappings from the
pre-defined set of colors to new foreground and background colors.
The value is a series of "fg/bg" values, separated by a "+". Each
pair of "fg/bg" values gives the colors to which a basic color is
mapped when used as a foreground or background color. The order is
the mappings is:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
Pairs may be skipped, leaving them mapped as normal, as are missing
pairs or single colors.
For example consider the following xo_emit call::
xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n");
To turn all colored output to red-on-blue, use eight pairs of
"red/blue" mappings separated by "+"s::
--libxo colors=red/blue+red/blue+red/blue+red/blue+\
red/blue+red/blue+red/blue+red/blue
To turn the red-on-green text to magenta-on-cyan, give a "magenta"
foreground value for red (the second mapping) and a "cyan" background
to green (the third mapping)::
--libxo colors=+magenta+/cyan
Consider the common situation where blue output looks unreadable on a
terminal session with a black background. To turn both "blue"
foreground and background output to "yellow", give only the fifth
mapping, skipping the first four mappings with bare "+"s::
--libxo colors=++++yellow/yellow

125
doc/xo.rst Normal file
View File

@ -0,0 +1,125 @@
.. index:: --libxo, xo
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 <style>" option can also be used. The standard
set of "--libxo" options are available (see :ref:`options`), as well
as the `LIBXO_OPTIONS`_ environment variable.
.. _`LIBXO_OPTIONS`: :ref:`libxo-options`
The `xo` utility accepts a format string suitable for `xo_emit` and
a set of zero or more arguments used to supply data for that string::
xo "The {k:name} weighs {:weight/%d} pounds.\n" fish 6
TEXT:
The fish weighs 6 pounds.
XML:
<name>fish</name>
<weight>6</weight>
JSON:
"name": "fish",
"weight": 6
HTML:
<div class="line">
<div class="text">The </div>
<div class="data" data-tag="name">fish</div>
<div class="text"> weighs </div>
<div class="data" data-tag="weight">6</div>
<div class="text"> pounds.</div>
</div>
The `--wrap $path` option can be used to wrap emitted content in a
specific hierarchy. The path is a set of hierarchical names separated
by the '/' character::
xo --wrap top/a/b/c '{:tag}' value
XML:
<top>
<a>
<b>
<c>
<tag>value</tag>
</c>
</b>
</a>
</top>
JSON:
"top": {
"a": {
"b": {
"c": {
"tag": "value"
}
}
}
}
The `--open $path` and `--close $path` can be used to emit
hierarchical information without the matching close and open
tag. This allows a shell script to emit open tags, data, and
then close tags. The `--depth` option may be used to set the
depth for indentation. The `--leading-xpath` may be used to
prepend data to the XPath values used for HTML output style::
EXAMPLE;
#!/bin/sh
xo --open top/data
xo --depth 2 '{tag}' value
xo --close top/data
XML:
<top>
<data>
<tag>value</tag>
</data>
</top>
JSON:
"top": {
"data": {
"tag": "value"
}
}
Command Line Options
--------------------
::
Usage: xo [options] format [fields]
--close <path> Close tags for the given path
--depth <num> Set the depth for pretty printing
--help Display this help text
--html OR -H Generate HTML output
--json OR -J Generate JSON output
--leading-xpath <path> Add a prefix to generated XPaths (HTML)
--open <path> Open tags for the given path
--pretty OR -p Make 'pretty' output (add indent, newlines)
--style <style> Generate given style (xml, json, text, html)
--text OR -T Generate text output (the default style)
--version Display version information
--warn OR -W Display warnings in text on stderr
--warn-xml Display warnings in xml on stdout
--wrap <path> Wrap output in a set of containers
--xml OR -X Generate XML output
--xpath Add XPath data to HTML output);
Example
-------
::
% xo 'The {:product} is {:status}\n' stereo "in route"
The stereo is in route
% ./xo/xo -p -X 'The {:product} is {:status}\n' stereo "in route"
<product>stereo</product>
<status>in route</status>

30
doc/xohtml.rst Normal file
View File

@ -0,0 +1,30 @@
.. index:: xohtml
.. _xohtml:
xohtml
======
`xohtml` is a tool for turning the output of libxo-enabled commands into
html files suitable for display in modern HTML web browsers. It can
be used to test and debug HTML output, as well as to make the user
ache to escape the world of '70s terminal devices.
`xohtml` is given a command, either on the command line or via the "-c"
option. If not command is given, standard input is used. The
command's output is wrapped in HTML tags, with references to
supporting CSS and Javascript files, and written to standard output or
the file given in the "-f" option. The "-b" option can be used to
provide an alternative base path for the support files:
============== ===================================================
Option Meaning
============== ===================================================
-b <base> Base path for finding css/javascript files
-c <command> Command to execute
-f <file> Output file name
============== ===================================================
The "-c" option takes a full command with arguments, including
any libxo options needed to generate html (`--libxo=html`). This
value must be quoted if it consists of multiple tokens.

40
doc/xolint.rst Normal file
View File

@ -0,0 +1,40 @@
xolint
======
`xolint` is a tool for reporting common mistakes in format strings
in source code that invokes `xo_emit`. It allows these errors
to be diagnosed at build time, rather than waiting until runtime.
`xolint` takes the one or more C files as arguments, and reports
and errors, warning, or informational messages as needed:
============ ===================================================
Option Meaning
============ ===================================================
-c Invoke 'cpp' against the input file
-C <flags> Flags that are passed to 'cpp
-d Enable debug output
-D Generate documentation for all xolint messages
-I Generate info table code
-p Print the offending lines after the message
-V Print vocabulary of all field names
-X Extract samples from xolint, suitable for testing
============ ===================================================
The output message will contain the source filename and line number, the
class of the message, the message, and, if -p is given, the
line that contains the error::
% xolint.pl -t xolint.c
xolint.c: 16: error: anchor format should be "%d"
16 xo_emit("{[:/%s}");
The "-I" option will generate a table of `xo_info_t`_ structures,
suitable for inclusion in source code.
.. _xo_info_t: :ref:`field-information`
The "-V" option does not report errors, but prints a complete list of
all field names, sorted alphabetically. The output can help spot
inconsistencies and spelling errors.

45
doc/xopo.rst Normal file
View File

@ -0,0 +1,45 @@
xopo
====
The `xopo` utility filters ".pot" files generated by the
:manpage:`xgettext(1)` utility to remove formatting information
suitable for use with the "{G:}" modifier. This means that when the
developer changes the formatting portion of the field definitions, or
the fields modifiers, the string passed to :manpage:`gettext(3)` is
unchanged, avoiding the expense of updating any existing translation
files (".po" files).
The syntax for the xopo command is one of two forms; it can be used as
a filter for processing a .po or .pot file, rewriting the "*msgid*"
strings with a simplified message string. In this mode, the input is
either standard input or a file given by the "-f" option, and the
output is either standard output or a file given by the "-o" option.
In the second mode, a simple message given using the "-s" option on
the command, and the simplified version of that message is printed on
stdout:
=========== =================================
Option Meaning
=========== =================================
-o <file> Output file name
-f <file> Use the given .po file as input
-s <text> Simplify a format string
=========== =================================
::
EXAMPLE:
% xopo -s "There are {:count/%u} {:event/%.6s} events\n"
There are {:count} {:event} events\n
% xgettext --default-domain=foo --no-wrap \
--add-comments --keyword=xo_emit --keyword=xo_emit_h \
--keyword=xo_emit_warn -C -E -n --foreign-user \
-o foo.pot.raw foo.c
% xopo -f foo.pot.raw -o foo.pot
Use of the `--no-wrap` option for `xgettext` is required to
ensure that incoming msgid strings are not wrapped across multiple
lines.

59
libxo/libxo.c
View File

@ -4180,6 +4180,59 @@ xo_format_title (xo_handle_t *xop, xo_field_info_t *xfip,
}
}
/*
* strspn() with a string length
*/
static ssize_t
xo_strnspn (const char *str, size_t len, const char *accept)
{
ssize_t i;
const char *cp, *ep;
for (i = 0, cp = str, ep = str + len; cp < ep && *cp != '\0'; i++, cp++) {
if (strchr(accept, *cp) == NULL)
break;
}
return i;
}
/*
* Decide if a format string should be considered "numeric",
* in the sense that the number does not need to be quoted.
* This means that it consists only of a single numeric field
* with nothing exotic or "interesting". This means that
* static values are never considered numeric.
*/
static int
xo_format_is_numeric (const char *fmt, ssize_t flen)
{
if (flen <= 0 || *fmt++ != '%') /* Must start with '%' */
return FALSE;
flen -= 1;
/* Handle leading flags; don't want "#" since JSON can't handle hex */
ssize_t spn = xo_strnspn(fmt, flen, "0123456789.*+ -");
if (spn >= flen)
return FALSE;
fmt += spn; /* Move along the input string */
flen -= spn;
/* Handle the length modifiers */
spn = xo_strnspn(fmt, flen, "hljtqz");
if (spn >= flen)
return FALSE;
fmt += spn; /* Move along the input string */
flen -= spn;
if (flen != 1) /* Should only be one character left */
return FALSE;
return (strchr("diouDOUeEfFgG", *fmt) == NULL) ? FALSE : TRUE;
}
static void
xo_format_prep (xo_handle_t *xop, xo_xff_flags_t flags)
{
@ -4408,10 +4461,10 @@ xo_format_value (xo_handle_t *xop, const char *name, ssize_t nlen,
quote = 0;
fmt = "true"; /* JSON encodes empty tags as a boolean true */
flen = 4;
} else if (strchr("diouDOUeEfFgG", fmt[flen - 1]) == NULL)
quote = 1;
else
} else if (xo_format_is_numeric(fmt, flen))
quote = 0;
else
quote = 1;
if (nlen == 0) {
static char missing[] = "missing-field-name";

4
tests/core/saved/test_01.E.out
View File

@ -1,5 +1,9 @@
op create: [] [] [0]
op open_container: [top] [] [0x810]
op string: [type] [ethernet] [0]
op content: [type] [bridge] [0]
op content: [type] [18u] [0]
op content: [type] [24] [0]
op content: [address] [0x0] [0]
op content: [port] [1] [0]
op content: [address] [0x0] [0]

2
tests/core/saved/test_01.H.out
View File

File diff suppressed because one or more lines are too long

8
tests/core/saved/test_01.HIPx.out
View File

@ -1,4 +1,12 @@
<div class="line">
<div class="text">static </div>
<div class="data" data-tag="type" data-xpath="/top/type">ethernet</div>
<div class="text"> </div>
<div class="data" data-tag="type" data-xpath="/top/type">bridge</div>
<div class="text"> </div>
<div class="data" data-tag="type" data-xpath="/top/type"> 18u</div>
<div class="text"> </div>
<div class="data" data-tag="type" data-xpath="/top/type"> 24</div>
<div class="text">anchor </div>
<div class="padding"> </div>
<div class="data" data-tag="address" data-xpath="/top/address">0x0</div>

8
tests/core/saved/test_01.HP.out
View File

@ -1,4 +1,12 @@
<div class="line">
<div class="text">static </div>
<div class="data" data-tag="type">ethernet</div>
<div class="text"> </div>
<div class="data" data-tag="type">bridge</div>
<div class="text"> </div>
<div class="data" data-tag="type"> 18u</div>
<div class="text"> </div>
<div class="data" data-tag="type"> 24</div>
<div class="text">anchor </div>
<div class="padding"> </div>
<div class="data" data-tag="address">0x0</div>

2
tests/core/saved/test_01.J.out
View File

@ -1,2 +1,2 @@
{"top": {"address":"0x0","port":1,"address":"0x0","port":1,"address":"0x0","port":1,"used-percent":12,"kve_start":"0xdeadbeef","kve_end":"0xcabb1e","host":"my-box","domain":"example.com","host":"my-box","domain":"example.com","label":"value","max-chaos":"very","min-chaos":42,"some-chaos":"[42]","host":"my-box","domain":"example.com", "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17,"in-stock":14,"on-order":2}]}, "data2": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412.0,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85.0,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123.0,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17.0,"in-stock":14,"on-order":2}]}, "data3": {"item": [{"sku":"GRO-000-533","name":"fish","sold":1321.0,"in-stock":45,"on-order":1}]}, "data4": {"item": ["gum","rope","ladder","bolt","water"]},"cost":425,"cost":455,"mode":"mode","mode_octal":"octal","links":"links","user":"user","group":"group","pre":"that","links":3,"post":"this","mode":"/some/file","mode_octal":640,"links":1,"user":"user","group":"group"}
{"top": {"type":"ethernet","type":"bridge","type":"18u","type":24,"address":"0x0","port":1,"address":"0x0","port":1,"address":"0x0","port":1,"used-percent":12,"kve_start":"0xdeadbeef","kve_end":"0xcabb1e","host":"my-box","domain":"example.com","host":"my-box","domain":"example.com","label":"value","max-chaos":"very","min-chaos":42,"some-chaos":"[42]","host":"my-box","domain":"example.com", "data": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17,"in-stock":14,"on-order":2}]}, "data2": {"item": [{"sku":"GRO-000-415","name":"gum","sold":1412.0,"in-stock":54,"on-order":10}, {"sku":"HRD-000-212","name":"rope","sold":85.0,"in-stock":4,"on-order":2}, {"sku":"HRD-000-517","name":"ladder","sold":0,"in-stock":2,"on-order":1}, {"sku":"HRD-000-632","name":"bolt","sold":4123.0,"in-stock":144,"on-order":42}, {"sku":"GRO-000-2331","name":"water","sold":17.0,"in-stock":14,"on-order":2}]}, "data3": {"item": [{"sku":"GRO-000-533","name":"fish","sold":1321.0,"in-stock":45,"on-order":1}]}, "data4": {"item": ["gum","rope","ladder","bolt","water"]},"cost":425,"cost":455,"mode":"mode","mode_octal":"octal","links":"links","user":"user","group":"group","pre":"that","links":3,"post":"this","mode":"/some/file","mode_octal":640,"links":1,"user":"user","group":"group"}
}

4
tests/core/saved/test_01.JP.out
View File

@ -1,5 +1,9 @@
{
"top": {
"type": "ethernet",
"type": "bridge",
"type": "18u",
"type": 24,
"address": "0x0",
"port": 1,
"address": "0x0",

2
tests/core/saved/test_01.T.out
View File

@ -1,4 +1,4 @@
anchor 0x0..1
static ethernet bridge 18u 24anchor 0x0..1
anchor 0x0..1
anchor 0x0..1
df 12%

2
tests/core/saved/test_01.X.out
View File

@ -1 +1 @@
<top><address>0x0</address><port>1</port><address>0x0</address><port>1</port><address>0x0</address><port>1</port><used-percent>12</used-percent><kve_start>0xdeadbeef</kve_start><kve_end>0xcabb1e</kve_end><host>my-box</host><domain>example.com</domain><host>my-box</host><domain>example.com</domain><label>value</label><max-chaos>very</max-chaos><min-chaos>42</min-chaos><some-chaos>[42]</some-chaos><host>my-box</host><domain>example.com</domain><data test="value"><item test2="value2"><sku test3="value3" key="key">GRO-000-415</sku><name key="key">gum</name><sold>1412</sold><in-stock>54</in-stock><on-order>10</on-order></item><item><sku test3="value3" key="key">HRD-000-212</sku><name key="key">rope</name><sold>85</sold><in-stock>4</in-stock><on-order>2</on-order></item><item><sku test3="value3" key="key">HRD-000-517</sku><name key="key">ladder</name><sold>0</sold><in-stock>2</in-stock><on-order>1</on-order></item><item><sku test3="value3" key="key">HRD-000-632</sku><name key="key">bolt</name><sold>4123</sold><in-stock>144</in-stock><on-order>42</on-order></item><item><sku test3="value3" key="key">GRO-000-2331</sku><name key="key">water</name><sold>17</sold><in-stock>14</in-stock><on-order>2</on-order></item></data><data2><item><sku key="key">GRO-000-415</sku><name key="key">gum</name><sold>1412.0</sold><in-stock>54</in-stock><on-order>10</on-order></item><item><sku key="key">HRD-000-212</sku><name key="key">rope</name><sold>85.0</sold><in-stock>4</in-stock><on-order>2</on-order></item><item><sku key="key">HRD-000-517</sku><name key="key">ladder</name><sold>0</sold><in-stock>2</in-stock><on-order>1</on-order></item><item><sku key="key">HRD-000-632</sku><name key="key">bolt</name><sold>4123.0</sold><in-stock>144</in-stock><on-order>42</on-order></item><item><sku key="key">GRO-000-2331</sku><name key="key">water</name><sold>17.0</sold><in-stock>14</in-stock><on-order>2</on-order></item></data2><data3><item><sku key="key">GRO-000-533</sku><name key="key">fish</name><sold>1321.0</sold><in-stock>45</in-stock><on-order>1</on-order></item></data3><data4><item test4="value4">gum</item><item test4="value4">rope</item><item test4="value4">ladder</item><item test4="value4">bolt</item><item test4="value4">water</item></data4><cost>425</cost><cost>455</cost><mode>mode</mode><mode_octal>octal</mode_octal><links>links</links><user>user</user><group>group</group><pre>that</pre><links>3</links><post>this</post><mode>/some/file</mode><mode_octal>640</mode_octal><links>1</links><user>user</user><group>group</group></top>
<top><type>ethernet</type><type>bridge</type><type>18u</type><type>24</type><address>0x0</address><port>1</port><address>0x0</address><port>1</port><address>0x0</address><port>1</port><used-percent>12</used-percent><kve_start>0xdeadbeef</kve_start><kve_end>0xcabb1e</kve_end><host>my-box</host><domain>example.com</domain><host>my-box</host><domain>example.com</domain><label>value</label><max-chaos>very</max-chaos><min-chaos>42</min-chaos><some-chaos>[42]</some-chaos><host>my-box</host><domain>example.com</domain><data test="value"><item test2="value2"><sku test3="value3" key="key">GRO-000-415</sku><name key="key">gum</name><sold>1412</sold><in-stock>54</in-stock><on-order>10</on-order></item><item><sku test3="value3" key="key">HRD-000-212</sku><name key="key">rope</name><sold>85</sold><in-stock>4</in-stock><on-order>2</on-order></item><item><sku test3="value3" key="key">HRD-000-517</sku><name key="key">ladder</name><sold>0</sold><in-stock>2</in-stock><on-order>1</on-order></item><item><sku test3="value3" key="key">HRD-000-632</sku><name key="key">bolt</name><sold>4123</sold><in-stock>144</in-stock><on-order>42</on-order></item><item><sku test3="value3" key="key">GRO-000-2331</sku><name key="key">water</name><sold>17</sold><in-stock>14</in-stock><on-order>2</on-order></item></data><data2><item><sku key="key">GRO-000-415</sku><name key="key">gum</name><sold>1412.0</sold><in-stock>54</in-stock><on-order>10</on-order></item><item><sku key="key">HRD-000-212</sku><name key="key">rope</name><sold>85.0</sold><in-stock>4</in-stock><on-order>2</on-order></item><item><sku key="key">HRD-000-517</sku><name key="key">ladder</name><sold>0</sold><in-stock>2</in-stock><on-order>1</on-order></item><item><sku key="key">HRD-000-632</sku><name key="key">bolt</name><sold>4123.0</sold><in-stock>144</in-stock><on-order>42</on-order></item><item><sku key="key">GRO-000-2331</sku><name key="key">water</name><sold>17.0</sold><in-stock>14</in-stock><on-order>2</on-order></item></data2><data3><item><sku key="key">GRO-000-533</sku><name key="key">fish</name><sold>1321.0</sold><in-stock>45</in-stock><on-order>1</on-order></item></data3><data4><item test4="value4">gum</item><item test4="value4">rope</item><item test4="value4">ladder</item><item test4="value4">bolt</item><item test4="value4">water</item></data4><cost>425</cost><cost>455</cost><mode>mode</mode><mode_octal>octal</mode_octal><links>links</links><user>user</user><group>group</group><pre>that</pre><links>3</links><post>this</post><mode>/some/file</mode><mode_octal>640</mode_octal><links>1</links><user>user</user><group>group</group></top>

4
tests/core/saved/test_01.XP.out
View File

@ -1,4 +1,8 @@
<top>
<type>ethernet</type>
<type>bridge</type>
<type>18u</type>
<type>24</type>
<address>0x0</address>
<port>1</port>
<address>0x0</address>

2
tests/core/saved/test_12.J.out
View File

@ -1,2 +1,2 @@
{"top": {"data": {"animal":"fish","animal":"fish", "thing": [{"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}, {"name":"thing","color":"green","time":2:15,"hand":"left","color":"blue","time":3:45}]}}
{"top": {"data": {"animal":"fish","animal":"fish", "thing": [{"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}, {"name":"thing","color":"green","time":"2:15","hand":"left","color":"blue","time":"3:45"}]}}
}

40
tests/core/saved/test_12.JP.out
View File

@ -7,82 +7,82 @@
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
},
{
"name": "thing",
"color": "green",
"time": 2:15,
"time": "2:15",
"hand": "left",
"color": "blue",
"time": 3:45
"time": "3:45"
}
]
}

3
tests/core/test_01.c
View File

@ -80,6 +80,9 @@ main (int argc, char **argv)
xo_open_container_h(NULL, "top");
xo_emit("static {:type/ethernet} {:type/bridge} {:type/%4du} {:type/%3d}",
18, 24);
xo_emit("anchor {[:/%d}{:address/%p}..{:port/%u}{]:}\n", 18, NULL, 1);
xo_emit("anchor {[:18}{:address/%p}..{:port/%u}{]:}\n", NULL, 1);
xo_emit("anchor {[:/18}{:address/%p}..{:port/%u}{]:}\n", NULL, 1);

2
tests/gettext/saved/gt_01.J.out
View File

@ -1,2 +1,2 @@
{"top": {"adjective":"amingflay","noun":"ordsway","verb":"urningbay","owner":"ymay","target":"ouchcay","adjective":"amingflay","noun":"ordsway","verb":"urningbay","owner":"ymay","target":"ouchcay", "bytes": [0,1,2,3,4],"total":1234,"received":1234,"from":"foop","port":4321,"time":32,"received":1234,"from":"foop","port":4321,"time":32,"received":1234,"from":"foop","port":4321,"time":32,"marzlevanes":3,"version":"1.2.3","date":"Tue Jun 23 18:47:09 UTC 2015", "__warning": {"program":"gt_01.test","message":"Nableuay otay ectulatobjay orwardfay elocipingvay","verb":ectulatobjay,"error":"Ermissionpay eniedday"}, "__warning": {"program":"gt_01.test","message":"automaticyay ynchronizationsay ofyay ardinalyay ammetersgray ailedfay","style":"automaticyay","type":"ardinalyay","target":"ammetersgray","error":"Ermissionpay eniedday"},"marzlevanes":6,"windings":"otuslay-oyay-eltayay"}
{"top": {"adjective":"amingflay","noun":"ordsway","verb":"urningbay","owner":"ymay","target":"ouchcay","adjective":"amingflay","noun":"ordsway","verb":"urningbay","owner":"ymay","target":"ouchcay", "bytes": [0,1,2,3,4],"total":1234,"received":1234,"from":"foop","port":4321,"time":32,"received":1234,"from":"foop","port":4321,"time":32,"received":1234,"from":"foop","port":4321,"time":32,"marzlevanes":3,"version":"1.2.3","date":"Tue Jun 23 18:47:09 UTC 2015", "__warning": {"program":"gt_01.test","message":"Nableuay otay ectulatobjay orwardfay elocipingvay","verb":"ectulatobjay","error":"Ermissionpay eniedday"}, "__warning": {"program":"gt_01.test","message":"automaticyay ynchronizationsay ofyay ardinalyay ammetersgray ailedfay","style":"automaticyay","type":"ardinalyay","target":"ammetersgray","error":"Ermissionpay eniedday"},"marzlevanes":6,"windings":"otuslay-oyay-eltayay"}
}

2
tests/gettext/saved/gt_01.JP.out
View File

@ -36,7 +36,7 @@
"__warning": {
"program": "gt_01.test",
"message": "Nableuay otay ectulatobjay orwardfay elocipingvay",
"verb": ectulatobjay,
"verb": "ectulatobjay",
"error": "Ermissionpay eniedday"
},
"__warning": {