Import libxo 0.9.0
This commit is contained in:
parent
76c53ac649
commit
b7a4d12840
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/vendor/Juniper/libxo/dist/; revision=334066 svn path=/vendor/Juniper/libxo/0.9.0/; revision=334067; tag=vendor/Juniper/libxo/0.9.0
@ -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.
|
||||
|
@ -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
657
doc/_static/basic.css_t
vendored
Normal 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
14
doc/_templates/localtoc.html
vendored
Normal 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
1620
doc/api.rst
Normal file
File diff suppressed because it is too large
Load Diff
178
doc/conf.py
Normal file
178
doc/conf.py
Normal 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
694
doc/example.rst
Normal 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
209
doc/faq.rst
Normal 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
370
doc/field-formatting.rst
Normal 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
353
doc/field-modifiers.rst
Normal 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
310
doc/field-roles.rst
Normal 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
47
doc/format-strings.rst
Normal 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
165
doc/formatting.rst
Normal 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
185
doc/getting.rst
Normal 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
394
doc/howto.rst
Normal 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
53
doc/index.rst
Normal 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
90
doc/intro.rst
Normal 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.
|
File diff suppressed because it is too large
Load Diff
164
doc/options.rst
Normal file
164
doc/options.rst
Normal 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
125
doc/xo.rst
Normal 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
30
doc/xohtml.rst
Normal 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
40
doc/xolint.rst
Normal 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
45
doc/xopo.rst
Normal 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.
|
@ -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";
|
||||
|
@ -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]
|
||||
|
File diff suppressed because one or more lines are too long
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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"}
|
||||
}
|
||||
|
@ -1,5 +1,9 @@
|
||||
{
|
||||
"top": {
|
||||
"type": "ethernet",
|
||||
"type": "bridge",
|
||||
"type": "18u",
|
||||
"type": 24,
|
||||
"address": "0x0",
|
||||
"port": 1,
|
||||
"address": "0x0",
|
||||
|
@ -1,4 +1,4 @@
|
||||
anchor 0x0..1
|
||||
static ethernet bridge 18u 24anchor 0x0..1
|
||||
anchor 0x0..1
|
||||
anchor 0x0..1
|
||||
df 12%
|
||||
|
@ -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>
|
@ -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>
|
||||
|
@ -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"}]}}
|
||||
}
|
||||
|
@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
@ -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);
|
||||
|
@ -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"}
|
||||
}
|
||||
|
@ -36,7 +36,7 @@
|
||||
"__warning": {
|
||||
"program": "gt_01.test",
|
||||
"message": "Nableuay otay ectulatobjay orwardfay elocipingvay",
|
||||
"verb": ectulatobjay,
|
||||
"verb": "ectulatobjay",
|
||||
"error": "Ermissionpay eniedday"
|
||||
},
|
||||
"__warning": {
|
||||
|
Loading…
Reference in New Issue
Block a user