+The XOF_XPATH flag enables the emission of XPath expressions detailing the hierarchy of XML elements used to encode the data field, if the XPATH style of output were requested.
+The XOF_INFO flag encodes additional informational fields for HTML output. See Section 5.4.4 for details.
+If the style is XO_STYLE_XML, the following additional flags can be used:
+
| Flag |
Description |
@@ -24722,74 +24892,74 @@ jQuery(function ($) {
Flag 'key' fields for xml |
The XOF_KEYS flag adds 'key' attribute to the XML encoding for field definitions that use the 'k' modifier. The key attribute has the value "key":
-
+The XOF_KEYS flag adds 'key' attribute to the XML encoding for field definitions that use the 'k' modifier. The key attribute has the value "key":
+
xo_emit("{k:name}", item);
XML:
<name key="key">truck</name>
xo_clear_flags
-The xo_clear_flags() function turns off the given flags in a specific handle.
-
+The xo_clear_flags() function turns off the given flags in a specific handle.
+
void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags);
xo_set_options
-The xo_set_options() function accepts a comma-separated list of styles and flags and enables them for a specific handle.
-
+The xo_set_options() function accepts a comma-separated list of styles and flags and enables them for a specific handle.
+
int xo_set_options (xo_handle_t *xop, const char *input);
- The options are identical to those listed in Section 2.4.
+
The options are identical to those listed in Section 4.
xo_destroy
-The xo_destroy function releases a handle and any resources it is using. Calling xo_destroy with a NULL handle will release any resources associated with the default handle.
-
+The xo_destroy function releases a handle and any resources it is using. Calling xo_destroy with a NULL handle will release any resources associated with the default handle.
+
void xo_destroy(xo_handle_t *xop);
Emitting Content (xo_emit)
-The following functions are used to emit output:
-
+The following functions are used to emit output:
+
int xo_emit (const char *fmt, ...);
int xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
- The "fmt" argument is a string containing field descriptors as specified in Section 2.2. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See Section 3.1.
-The remaining arguments to xo_emit() and xo_emit_h() are a set of arguments corresponding to the fields in the format string. Care must be taken to ensure the argument types match the fields in the format string, since an inappropriate cast can ruin your day. The vap argument to xo_emit_hv() points to a variable argument list that can be used to retrieve arguments via va_arg().
-Section Contents:
+
The "fmt" argument is a string containing field descriptors as specified in Section 3.2. The use of a handle is optional and NULL can be passed to access the internal 'default' handle. See Section 5.1.
+The remaining arguments to xo_emit() and xo_emit_h() are a set of arguments corresponding to the fields in the format string. Care must be taken to ensure the argument types match the fields in the format string, since an inappropriate cast can ruin your day. The vap argument to xo_emit_hv() points to a variable argument list that can be used to retrieve arguments via va_arg().
+Section Contents:
Single Field Emitting Functions (xo_emit_field)
-The following functions can also make output, but only make a single field at a time:
-
+The following functions can also make output, but only make a single field at a time:
+
int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod,
const char *contents, const char *fmt,
const char *efmt, va_list vap);
@@ -24800,26 +24970,26 @@ jQuery(function ($) {
int xo_emit_field (const char *rolmod, const char *contents,
const char *fmt, const char *efmt, ...);
- These functions are intended to avoid the scenario where one would otherwise need to compose a format descriptors using snprintf(). The individual parts of the format descriptor are passed in distinctly.
-
+
These functions are intended to avoid the scenario where one would otherwise need to compose a format descriptors using snprintf(). The individual parts of the format descriptor are passed in distinctly.
+
xo_emit("T", "Host name is ", NULL, NULL);
xo_emit("V", "host-name", NULL, NULL, host-name);
Attributes (xo_attr)
-The xo_attr() function emits attributes for the XML output style.
-
+The xo_attr() function emits attributes for the XML output style.
+
int xo_attr (const char *name, const char *fmt, ...);
int xo_attr_h (xo_handle_t *xop, const char *name,
const char *fmt, ...);
int xo_attr_hv (xo_handle_t *xop, const char *name,
const char *fmt, va_list vap);
- The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().
-
+
The name parameter give the name of the attribute to be encoded. The fmt parameter gives a printf-style format string used to format the value of the attribute using any remaining arguments, or the vap parameter passed to xo_attr_hv().
+
EXAMPLE:
xo_attr("seconds", "%ld", (unsigned long) login_time);
struct tm *tmp = localtime(login_time);
@@ -24827,45 +24997,45 @@ jQuery(function ($) {
xo_emit("Logged in at {:login-time}\n", buf);
XML:
<login-time seconds="1408336270">00:14</login-time>
- xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.
-Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.
+
xo_attr is placed on the next container, instance, leaf, or leaf list that is emitted.
+Since attributes are only emitted in XML, their use should be limited to meta-data and additional or redundant representations of data already emitted in other form.
Flushing Output (xo_flush)
-libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:
-
+libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:
+
void xo_flush (void);
void xo_flush_h (xo_handle_t *xop);
- Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".
+
Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".
Finishing Output (xo_finish)
-When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.
-
+When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.
+
int xo_finish (void);
int xo_finish_h (xo_handle_t *xop);
void xo_finish_atexit (void);
- Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.
-xo_finish_atexit is suitable for use with atexit(3).
+
Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.
+xo_finish_atexit is suitable for use with atexit(3).
Emitting Hierarchy
-libxo represents to types of hierarchy: containers and lists. A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope.
-To create a container, use the xo_open_container and xo_close_container functions:
-
+libxo represents to types of hierarchy: containers and lists. A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope.
+To create a container, use the xo_open_container and xo_close_container functions:
+
int xo_open_container (const char *name);
int xo_open_container_h (xo_handle_t *xop, const char *name);
int xo_open_container_hd (xo_handle_t *xop, const char *name);
@@ -24875,28 +25045,28 @@ jQuery(function ($) {
int xo_close_container_h (xo_handle_t *xop, const char *name);
int xo_close_container_hd (xo_handle_t *xop);
int xo_close_container_d (void);
- The name parameter gives the name of the container, encoded in UTF-8. Since ASCII is a proper subset of UTF-8, traditional C strings can be used directly.
-The close functions with the "_d" suffix are used in "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by libxo to allow the caller to avoid keeping track of the open container name.
-Use the XOF_WARN flag to generate a warning if the name given on the close does not match the current open container.
-For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the XOF_XPATH flag is set.
-
+
The name parameter gives the name of the container, encoded in UTF-8. Since ASCII is a proper subset of UTF-8, traditional C strings can be used directly.
+The close functions with the "_d" suffix are used in "Do The Right Thing" mode, where the name of the open containers, lists, and instances are maintained internally by libxo to allow the caller to avoid keeping track of the open container name.
+Use the XOF_WARN flag to generate a warning if the name given on the close does not match the current open container.
+For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the XOF_XPATH flag is set.
+
EXAMPLE:
xo_open_container("system");
xo_emit("The host name is {:host-name}\n", hn);
xo_close_container("system");
XML:
<system><host-name>foo</host-name></system>
- Section Contents:
-
+ Section Contents:
+
Lists and Instances
-Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance.
-The name given to all calls must be identical, and it is strongly suggested that the name be singular, not plural, as a matter of style and usage expectations.
-
+Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance.
+The name given to all calls must be identical, and it is strongly suggested that the name be singular, not plural, as a matter of style and usage expectations.
+
EXAMPLE:
xo_open_list("user");
for (i = 0; i < num_users; i++) {
@@ -24941,68 +25111,68 @@ jQuery(function ($) {
Support Functions
-Section Contents:
+Section Contents:
Parsing Command-line Arguments (xo_parse_args)
-The xo_parse_args() function is used to process a program's arguments. libxo-specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned.
-
+The xo_parse_args() function is used to process a program's arguments. libxo-specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned.
+
argc = xo_parse_args(argc, argv);
if (argc < 0)
exit(EXIT_FAILURE);
- Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See Section 2.4 for a description of valid arguments.
+
Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See Section 4 for a description of valid arguments.
xo_set_program
-The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value.
-
+The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value.
+
xo_set_program(argv[0]);
- Note that the value is not copied, so the memory passed to xo_set_program (and xo_parse_args) must be maintained by the caller.
+
Note that the value is not copied, so the memory passed to xo_set_program (and xo_parse_args) must be maintained by the caller.
xo_set_version
-The xo_set_version function records a version number to be emitted as part of the data for encoding styles (XML and JSON). This version number is suitable for tracking changes in the content, allowing a user of the data to discern which version of the data model is in use.
-
+The xo_set_version function records a version number to be emitted as part of the data for encoding styles (XML and JSON). This version number is suitable for tracking changes in the content, allowing a user of the data to discern which version of the data model is in use.
+
void xo_set_version (const char *version);
void xo_set_version_h (xo_handle_t *xop, const char *version);
Field Information (xo_info_t)
-HTML data can include additional information in attributes that begin with "data‑". To enable this, three things must occur:
-First the application must build an array of xo_info_t structures, one per tag. The array must be sorted by name, since libxo uses a binary search to find the entry that matches names from format instructions.
-Second, the application must inform libxo about this information using the xo_set_info() call:
-
+HTML data can include additional information in attributes that begin with "data‑". To enable this, three things must occur:
+First the application must build an array of xo_info_t structures, one per tag. The array must be sorted by name, since libxo uses a binary search to find the entry that matches names from format instructions.
+Second, the application must inform libxo about this information using the xo_set_info() call:
+
typedef struct xo_info_s {
const char *xi_name; /* Name of the element */
const char *xi_type; /* Type of field */
@@ -25010,9 +25180,9 @@ jQuery(function ($) {
} xo_info_t;
void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
- Like other libxo calls, passing NULL for the handle tells libxo to use the default handle.
-If the count is -1, libxo will count the elements of infop, but there must be an empty element at the end. More typically, the number is known to the application:
-
+
Like other libxo calls, passing NULL for the handle tells libxo to use the default handle.
+If the count is -1, libxo will count the elements of infop, but there must be an empty element at the end. More typically, the number is known to the application:
+
xo_info_t info[] = {
{ "in-stock", "number", "Number of items in stock" },
{ "name", "string", "Name of the item" },
@@ -25023,116 +25193,59 @@ jQuery(function ($) {
int info_count = (sizeof(info) / sizeof(info[0]));
...
xo_set_info(NULL, info, info_count);
- Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the "‑‑libxo=info" command line argument.
-The type and help values, if present, are emitted as the "data‑type" and "data‑help" attributes:
-
+
Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the "‑‑libxo=info" command line argument.
+The type and help values, if present, are emitted as the "data‑type" and "data‑help" attributes:
+
<div class="data" data-tag="sku" data-type="string"
data-help="Stock Keeping Unit">GRO-000-533</div>
Memory Allocation
-The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available.
-
+The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available.
+
void xo_set_allocator (xo_realloc_func_t realloc_func,
xo_free_func_t free_func);
- realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment.
-By default, the standard realloc() and free() functions are used.
+
realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment.
+By default, the standard realloc() and free() functions are used.
LIBXO_OPTIONS
-The environment variable "LIBXO_OPTIONS" can be set to a string of options:
-
-
-| 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) |
-
-
-
For example, warnings can be enabled by:
-
- % env LIBXO_OPTIONS=W my-app
-
Complete HTML output can be generated with:
-
- % env LIBXO_OPTIONS=HXI my-app
-
Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "‑‑libxo" option is preferable in most situations.
+The environment variable "LIBXO_OPTIONS" can be set to a subset of libxo options, including:
+
+
+- color
+- flush
+- flush-line
+- no-color
+- no-humanize
+- no-locale
+- no-retain
+- pretty
+- retain
+- underscores
+- warn
+
+For example, warnings can be enabled by:
+
+ % env LIBXO_OPTIONS=warn my-app
+
Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "‑‑libxo" option is preferable in most situations.
Errors, Warnings, and Messages
-Many programs make use of the standard library functions err() and warn() to generate errors and warnings for the user. libxo wants to pass that information via the current output style, and provides compatible functions to allow this:
-
+Many programs make use of the standard library functions err() and warn() to generate errors and warnings for the user. libxo wants to pass that information via the current output style, and provides compatible functions to allow this:
+
void xo_warn (const char *fmt, ...);
void xo_warnx (const char *fmt, ...);
void xo_warn_c (int code, const char *fmt, ...);
@@ -25147,20 +25260,20 @@ jQuery(function ($) {
const char *fmt, ...);
void xo_message_hcv (xo_handle_t *xop, int code,
const char *fmt, va_list vap);
- These functions display the program name, a colon, a formatted message based on the arguments, and then optionally a colon and an error message associated with either "errno" or the "code" parameter.
-
+
These functions display the program name, a colon, a formatted message based on the arguments, and then optionally a colon and an error message associated with either "errno" or the "code" parameter.
+
EXAMPLE:
if (open(filename, O_RDONLY) < 0)
xo_err(1, "cannot open file '%s'", filename);
xo_error
-The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements:
-
+The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements:
+
EXAMPLE::
xo_error("Does not %s", "compute");
XML::
@@ -25169,29 +25282,29 @@ jQuery(function ($) {
"error": { "message": "Does not compute" }
xo_no_setlocale
-libxo automatically initializes the locale based on setting of the environment variables LC_CTYPE, LANG, and LC_ALL. The first of this list of variables is used and if none of the variables, the locale defaults to "UTF‑8". The caller may wish to avoid this behavior, and can do so by calling the xo_no_setlocale() function.
-
+libxo automatically initializes the locale based on setting of the environment variables LC_CTYPE, LANG, and LC_ALL. The first of this list of variables is used and if none of the variables, the locale defaults to "UTF‑8". The caller may wish to avoid this behavior, and can do so by calling the xo_no_setlocale() function.
+
void xo_no_setlocale (void);
Emitting syslog Messages
-syslog is the system logging facility used throughout the unix world. Messages are sent from commands, applications, and daemons to a hierarchy of servers, where they are filtered, saved, and forwarded based on configuration behaviors.
-syslog is an older protocol, originally documented only in source code. By the time RFC 3164 published, variation and mutation left the leading "<pri>" string as only common content. RFC 5424 defines a new version (version 1) of syslog and introduces structured data into the messages. Structured data is a set of name/value pairs transmitted distinctly alongside the traditional text message, allowing filtering on precise values instead of regular expressions.
-These name/value pairs are scoped by a two-part identifier; an enterprise identifier names the party responsible for the message catalog and a name identifying that message. Enterprise IDs are defined by IANA, the Internet Assigned Numbers Authority:
-https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
-Use the Section 3.5.3.5() function to set the Enterprise ID, as needed.
-The message name should follow the conventions in Section 8.1.3, as should the fields within the message.
-
+syslog is the system logging facility used throughout the unix world. Messages are sent from commands, applications, and daemons to a hierarchy of servers, where they are filtered, saved, and forwarded based on configuration behaviors.
+syslog is an older protocol, originally documented only in source code. By the time RFC 3164 published, variation and mutation left the leading "<pri>" string as only common content. RFC 5424 defines a new version (version 1) of syslog and introduces structured data into the messages. Structured data is a set of name/value pairs transmitted distinctly alongside the traditional text message, allowing filtering on precise values instead of regular expressions.
+These name/value pairs are scoped by a two-part identifier; an enterprise identifier names the party responsible for the message catalog and a name identifying that message. Enterprise IDs are defined by IANA, the Internet Assigned Numbers Authority:
+https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
+Use the Section 5.5.3.5() function to set the Enterprise ID, as needed.
+The message name should follow the conventions in Section 10.1.3, as should the fields within the message.
+
/* Both of these calls are optional */
xo_set_syslog_enterprise_id(32473);
xo_open_log("my-program", 0, LOG_DAEMON);
@@ -25205,26 +25318,26 @@ jQuery(function ($) {
xo_syslog(LOG_INFO, "poofd-invalid-state",
"state {:current/%u} is invalid {:connection/%u}",
state, conn);
- The developer should be aware that the message name may be used in the future to allow access to further information, including documentation. Care should be taken to choose quality, descriptive names.
-Section Contents:
+
The developer should be aware that the message name may be used in the future to allow access to further information, including documentation. Care should be taken to choose quality, descriptive names.
+Section Contents:
Priority, Facility, and Flags
-The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of flags which provide the priority of the message, the source facility, and some additional features. These values are OR'd together to create a single integer argument:
-
+The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of flags which provide the priority of the message, the source facility, and some additional features. These values are OR'd together to create a single integer argument:
+
xo_syslog(LOG_ERR | LOG_AUTH, "login-failed",
"Login failed; user '{:user}' from host '{:address}'",
user, addr);
- These values are defined in <syslog.h>.
-The priority value indicates the importance and potential impact of each message.
+
These values are defined in <syslog.h>.
+The priority value indicates the importance and potential impact of each message.
| Priority |
@@ -25265,7 +25378,7 @@ jQuery(function ($) {
The facility value indicates the source of message, in fairly generic terms.
+The facility value indicates the source of message, in fairly generic terms.
| Facility |
@@ -25330,7 +25443,7 @@ jQuery(function ($) {
In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific behaviors.
+In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific behaviors.
| Flag |
@@ -25357,14 +25470,14 @@ jQuery(function ($) {
Use the xo_syslog function to generate syslog messages by calling it with a log priority and facility, a message name, a format string, and a set of arguments. The priority/facility argument are discussed above, as is the message name.
-The format string follows the same conventions as xo_emit's format string, with each field being rendered as an SD-PARAM pair.
-
+Use the xo_syslog function to generate syslog messages by calling it with a log priority and facility, a message name, a format string, and a set of arguments. The priority/facility argument are discussed above, as is the message name.
+The format string follows the same conventions as xo_emit's format string, with each field being rendered as an SD-PARAM pair.
+
xo_syslog(LOG_ERR, "poofd-missing-file",
"'{:filename}' not found: {:error/%m}", filename);
@@ -25373,27 +25486,27 @@ jQuery(function ($) {
found: Permission denied
Support functions
-Section Contents:
+Section Contents:
xo_vsyslog
-xo_vsyslog is identical in function to xo_syslog, but takes the set of arguments using a va_list.
-
+xo_vsyslog is identical in function to xo_syslog, but takes the set of arguments using a va_list.
+
void my_log (const char *name, const char *fmt, ...)
{
va_list vap;
@@ -25403,35 +25516,35 @@ jQuery(function ($) {
}
xo_open_log
-xo_open_log functions similar to openlog(3), allowing customization of the program name, the log facility number, and the additional option flags described in Section 3.5.1.
-
+xo_open_log functions similar to openlog(3), allowing customization of the program name, the log facility number, and the additional option flags described in Section 5.5.1.
+
void
xo_open_log (const char *ident, int logopt, int facility);
xo_close_log
-xo_close_log functions similar to closelog(3), closing the log file and releasing any associated resources.
-
+xo_close_log functions similar to closelog(3), closing the log file and releasing any associated resources.
+
void
xo_close_log (void);
xo_set_logmask
-xo_set_logmask function similar to setlogmask(3), restricting the set of generated log event to those whose associated bit is set in maskpri. Use LOG_MASK(pri) to find the appropriate bit, or LOG_UPTO(toppri) to create a mask for all priorities up to and including toppri.
-
+xo_set_logmask function similar to setlogmask(3), restricting the set of generated log event to those whose associated bit is set in maskpri. Use LOG_MASK(pri) to find the appropriate bit, or LOG_UPTO(toppri) to create a mask for all priorities up to and including toppri.
+
int
xo_set_logmask (int maskpri);
@@ -25439,85 +25552,85 @@ jQuery(function ($) {
setlogmask(LOG_UPTO(LOG_WARN));
xo_set_syslog_enterprise_id
-Use the xo_set_syslog_enterprise_id to supply a platform- or application-specific enterprise id. This value is used in any future syslog messages.
-Ideally, the operating system should supply a default value via the "kern.syslog.enterprise_id" sysctl value. Lacking that, the application should provide a suitable value.
-
+Use the xo_set_syslog_enterprise_id to supply a platform- or application-specific enterprise id. This value is used in any future syslog messages.
+Ideally, the operating system should supply a default value via the "kern.syslog.enterprise_id" sysctl value. Lacking that, the application should provide a suitable value.
+
void
xo_set_syslog_enterprise_id (unsigned short eid);
- Enterprise IDs are administered by IANA, the Internet Assigned Number Authority. The complete list is EIDs on their web site:
- https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
-New EIDs can be requested from IANA using the following page:
- http://pen.iana.org/pen/PenApplication.page
-Each software development organization that defines a set of syslog messages should register their own EID and use that value in their software to ensure that messages can be uniquely identified by the combination of EID + message name.
+
Enterprise IDs are administered by IANA, the Internet Assigned Number Authority. The complete list is EIDs on their web site:
+ https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
+New EIDs can be requested from IANA using the following page:
+ http://pen.iana.org/pen/PenApplication.page
+Each software development organization that defines a set of syslog messages should register their own EID and use that value in their software to ensure that messages can be uniquely identified by the combination of EID + message name.
Creating Custom Encoders
-The number of encoding schemes in current use is staggering, with new and distinct schemes appearing daily. While libxo provide XML, JSON, HMTL, and text natively, there are requirements for other encodings.
-Rather than bake support for all possible encoders into libxo, the API allows them to be defined externally. libxo can then interfaces with these encoding modules using a simplistic API. libxo processes all functions calls, handles state transitions, performs all formatting, and then passes the results as operations to a customized encoding function, which implements specific encoding logic as required. This means your encoder doesn't need to detect errors with unbalanced open/close operations but can rely on libxo to pass correct data.
-By making a simple API, libxo internals are not exposed, insulating the encoder and the library from future or internal changes.
-The three elements of the API are:
-
+The number of encoding schemes in current use is staggering, with new and distinct schemes appearing daily. While libxo provide XML, JSON, HMTL, and text natively, there are requirements for other encodings.
+Rather than bake support for all possible encoders into libxo, the API allows them to be defined externally. libxo can then interfaces with these encoding modules using a simplistic API. libxo processes all functions calls, handles state transitions, performs all formatting, and then passes the results as operations to a customized encoding function, which implements specific encoding logic as required. This means your encoder doesn't need to detect errors with unbalanced open/close operations but can rely on libxo to pass correct data.
+By making a simple API, libxo internals are not exposed, insulating the encoder and the library from future or internal changes.
+The three elements of the API are:
+
- loading
- initialization
- operations
-The following sections provide details about these topics.
-libxo source contain an encoder for Concise Binary Object Representation, aka CBOR (RFC 7049) which can be used as used as an example for the API.
-Section Contents:
+The following sections provide details about these topics.
+libxo source contain an encoder for Concise Binary Object Representation, aka CBOR (RFC 7049) which can be used as used as an example for the API.
+Section Contents:
Loading Encoders
-Encoders can be registered statically or discovered dynamically. Applications can choose to call the xo_encoder_register() function to explicitly register encoders, but more typically they are built as shared libraries, placed in the libxo/extensions directory, and loaded based on name. libxo looks for a file with the name of the encoder and an extension of ".enc". This can be a file or a symlink to the shared library file that supports the encoder.
-
+Encoders can be registered statically or discovered dynamically. Applications can choose to call the xo_encoder_register() function to explicitly register encoders, but more typically they are built as shared libraries, placed in the libxo/extensions directory, and loaded based on name. libxo looks for a file with the name of the encoder and an extension of ".enc". This can be a file or a symlink to the shared library file that supports the encoder.
+
% ls -1 lib/libxo/extensions/*.enc
lib/libxo/extensions/cbor.enc
lib/libxo/extensions/test.enc
Encoder Initialization
-Each encoder must export a symbol used to access the library, which must have the following signature:
-
+Each encoder must export a symbol used to access the library, which must have the following signature:
+
int xo_encoder_library_init (XO_ENCODER_INIT_ARGS);
- XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines an argument called "arg", a pointer of the type xo_encoder_init_args_t. This structure contains two fields:
-
+
XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines an argument called "arg", a pointer of the type xo_encoder_init_args_t. This structure contains two fields:
+
- xei_version is the version number of the API as implemented within libxo. This version is currently as 1 using XO_ENCODER_VERSION. This number can be checked to ensure compatibility. The working assumption is that all versions should be backward compatible, but each side may need to accurately know the version supported by the other side. xo_encoder_library_init can optionally check this value, and must then set it to the version number used by the encoder, allowing libxo to detect version differences and react accordingly. For example, if version 2 adds new operations, then libxo will know that an encoding library that set xei_version to 1 cannot be expected to handle those new operations.
- xei_handler must be set to a pointer to a function of type xo_encoder_func_t, as defined in xo_encoder.h. This function takes a set of parameters: -- xop is a pointer to the opaque xo_handle_t structure -- op is an integer representing the current operation -- name is a string whose meaning differs by operation -- value is a string whose meaning differs by operation -- private is an opaque structure provided by the encoder
-Additional arguments may be added in the future, so handler functions should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate "extern" declaration is provided to help catch errors.
-Once the encoder initialization function has completed processing, it should return zero to indicate that no error has occurred. A non-zero return code will cause the handle initialization to fail.
+Additional arguments may be added in the future, so handler functions should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate "extern" declaration is provided to help catch errors.
+Once the encoder initialization function has completed processing, it should return zero to indicate that no error has occurred. A non-zero return code will cause the handle initialization to fail.
Operations
-The encoder API defines a set of operations representing the processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed.
+The encoder API defines a set of operations representing the processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed.
| Operation |
@@ -25590,22 +25703,22 @@ jQuery(function ($) {
For all the open and close operations, the name parameter holds the name of the construct. For string, content, and attribute operations, the name parameter is the name of the field and the value parameter is the value. "string" are differentiated from "content" to allow differing treatment of true, false, null, and numbers from real strings, though content values are formatted as strings before the handler is called. For version operations, the value parameter contains the version.
-All strings are encoded in UTF-8.
+For all the open and close operations, the name parameter holds the name of the construct. For string, content, and attribute operations, the name parameter is the name of the field and the value parameter is the value. "string" are differentiated from "content" to allow differing treatment of true, false, null, and numbers from real strings, though content values are formatted as strings before the handler is called. For version operations, the value parameter contains the version.
+All strings are encoded in UTF-8.
The "xo" Utility
-The "xo" utility allows command line access to the functionality of the libxo library. Using "xo", shell scripts can emit XML, JSON, and HTML using the same commands that emit text output.
-The style of output can be selected using a specific option: "‑X" for XML, "‑J" for JSON, "‑H" for HTML, or "‑T" for TEXT, which is the default. The "--style <style>" option can also be used. The LIBXO_OPTIONS environment variable can also be used to set the style, as well as other flags.
-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.
-
+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 Section 4), as well as the LIBXO_OPTIONS environment variable (see Section 5.4.6).
+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:
@@ -25624,8 +25737,8 @@ jQuery(function ($) {
<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.
-
+
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:
@@ -25648,8 +25761,8 @@ jQuery(function ($) {
}
}
}
- 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.
-
+
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.
+
#!/bin/sh
xo --open top/data
xo --depth 2 '{tag}' value
@@ -25666,19 +25779,19 @@ jQuery(function ($) {
"tag": "value"
}
}
- Section Contents:
+
Section Contents:
Command Line Options
-Usage: xo [options] format [fields]
-
+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
@@ -25697,12 +25810,12 @@ jQuery(function ($) {
--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"
@@ -25712,13 +25825,13 @@ jQuery(function ($) {
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.
+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 |
@@ -25759,23 +25872,23 @@ jQuery(function ($) {
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:
-
+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 ,
-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.
+
The "‑I" option will generate a table of xo_info_t structures ,
+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.
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.
+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 |
@@ -25796,18 +25909,18 @@ jQuery(function ($) {
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.
+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.
xopo
-The "xopo" utility filters ".pot" files generated by the "xgettext" 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 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.
+The "xopo" utility filters ".pot" files generated by the "xgettext" 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 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 |
@@ -25828,7 +25941,7 @@ jQuery(function ($) {
+
EXAMPLE:
% xopo -s "There are {:count/%u} {:event/%.6s} events\n"
There are {:count} {:event} events\n
@@ -25838,56 +25951,56 @@ jQuery(function ($) {
--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.
+
Use of the "‑‑no‑wrap" option for xgettext is required to ensure that incoming msgid strings are not wrapped across multiple lines.
FAQs
-This section contains the set of questions that users typically ask, along with answers that might be helpful.
-Section Contents:
+This section contains the set of questions that users typically ask, along with answers that might be helpful.
+Section Contents:
-Section Contents:
+Section Contents:
General
-Section Contents:
+Section Contents:
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.
-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.
+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.
+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:
-
+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;
@@ -25940,20 +26053,20 @@ jQuery(function ($) {
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.
+
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.
What makes a good field name?
-To make useful, consistent field names, follow these guidelines:
-
+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.
@@ -25966,422 +26079,422 @@ jQuery(function ($) {
- Reuse existing field names
- Nothing's worse than writing expressions like:
-
+
if ($src1/process[pid == $pid]/name ==
$src2/proc-table/proc-list
/proc-entry[process-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".
-
+
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".
+
- 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 (Section 3.2.2) or "{e:}" fields (Section 2.2.2.4) to make the data useful.
+- 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 (Section 5.2.2) or "{e:}" fields (Section 3.2.2.4) 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 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.
+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 detect different names for the same data. "dropped‑short" and "dropped‑too‑short" are both reasonable names, but using them both will lead users to ask the difference between the two fields. If there is no difference, use only one of the field names. If there is a difference, change the names to make that difference more obvious.
What does this message mean?
-Section Contents:
+Section Contents:
'A percent sign appearing in text is a literal'
-The message "A percent sign appearing in text is a literal" can be caused by code like:
-
+The message "A percent sign appearing in text is a literal" can be caused by code like:
+
xo_emit("cost: %d", cost);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{L:cost}: {:cost/%d}", cost);
- This can be a bit surprising and could be a field that was not properly converted to a libxo-style format string.
+
This can be a bit surprising and could be a field that was not properly converted to a libxo-style format string.
'Unknown long name for role/modifier'
-The message "Unknown long name for role/modifier" can be caused by code like:
-
+The message "Unknown long name for role/modifier" can be caused by code like:
+
xo_emit("{,humanization:value}", value);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{,humanize:value}", value);
- The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.
+
The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.
'Last character before field definition is a field type'
-The message "Last character before field definition is a field type" can be caused by code like:
-A common typo:
-
+The message "Last character before field definition is a field type" can be caused by code like:
+A common typo:
+
xo_emit("{T:Min} T{:Max}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{T:Min} {T:Max}");
- Twiddling the "{" and the field role is a common typo.
+
Twiddling the "{" and the field role is a common typo.
'Encoding format uses different number of arguments'
-The message "Encoding format uses different number of arguments" can be caused by code like:
-
+The message "Encoding format uses different number of arguments" can be caused by code like:
+
xo_emit("{:name/%6.6s %%04d/%s}", name, number);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:name/%6.6s %04d/%s-%d}", name, number);
- Both format should consume the same number of arguments off the stack
+
Both format should consume the same number of arguments off the stack
'Only one field role can be used'
-The message "Only one field role can be used" can be caused by code like:
-
+The message "Only one field role can be used" can be caused by code like:
+
xo_emit("{LT:Max}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{T:Max}");
'Potential missing slash after C, D, N, L, or T with format'
-The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:
-
+The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:
+
xo_emit("{T:%6.6s}\n", "Max");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{T:/%6.6s}\n", "Max");
- The "%6.6s" will be a literal, not a field format. While it's possibly valid, it's likely a missing "/".
+
The "%6.6s" will be a literal, not a field format. While it's possibly valid, it's likely a missing "/".
'An encoding format cannot be given (roles: DNLT)'
-The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:
-
+The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:
+
xo_emit("{T:Max//%s}", "Max");
- Fields with the C, D, N, L, and T roles are not emitted in the 'encoding' style (JSON, XML), so an encoding format would make no sense.
+
Fields with the C, D, N, L, and T roles are not emitted in the 'encoding' style (JSON, XML), so an encoding format would make no sense.
'Format cannot be given when content is present (roles: CDLN)'
-The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:
-
+The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:
+
xo_emit("{N:Max/%6.6s}", "Max");
- Fields with the C, D, L, or N roles can't have both static literal content ("{L:Label}") and a format ("{L:/%s}"). This error will also occur when the content has a backslash in it, like "{N:Type of I/O}"; backslashes should be escaped, like "{N:Type of I\\/O}". Note the double backslash, one for handling 'C' strings, and one for libxo.
+
Fields with the C, D, L, or N roles can't have both static literal content ("{L:Label}") and a format ("{L:/%s}"). This error will also occur when the content has a backslash in it, like "{N:Type of I/O}"; backslashes should be escaped, like "{N:Type of I\\/O}". Note the double backslash, one for handling 'C' strings, and one for libxo.
'Field has color without fg- or bg- (role: C)'
-The message "Field has color without fg- or bg- (role: C)" can be caused by code like:
-
+The message "Field has color without fg- or bg- (role: C)" can be caused by code like:
+
xo_emit("{C:green}{:foo}{C:}", x);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{C:fg-green}{:foo}{C:}", x);
- Colors must be prefixed by either "fg‑" or "bg‑".
+
Colors must be prefixed by either "fg‑" or "bg‑".
'Field has invalid color or effect (role: C)'
-The message "Field has invalid color or effect (role: C)" can be caused by code like:
-
+The message "Field has invalid color or effect (role: C)" can be caused by code like:
+
xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x);
- The list of colors and effects are limited. The set of colors includes default, black, red, green, yellow, blue, magenta, cyan, and white, which must be prefixed by either "fg‑" or "bg‑". Effects are limited to bold, no-bold, underline, no-underline, inverse, no-inverse, normal, and reset. Values must be separated by commas.
+
The list of colors and effects are limited. The set of colors includes default, black, red, green, yellow, blue, magenta, cyan, and white, which must be prefixed by either "fg‑" or "bg‑". Effects are limited to bold, no-bold, underline, no-underline, inverse, no-inverse, normal, and reset. Values must be separated by commas.
'Field has humanize modifier but no format string'
-The message "Field has humanize modifier but no format string" can be caused by code like:
-
+The message "Field has humanize modifier but no format string" can be caused by code like:
+
xo_emit("{h:value}", value);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{h:value/%d}", value);
- Humanization is only value for numbers, which are not likely to use the default format ("%s").
+
Humanization is only value for numbers, which are not likely to use the default format ("%s").
'Field has hn-* modifier but not 'h' modifier'
-The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:
-
+The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:
+
xo_emit("{,hn-1000:value}", value);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{h,hn-1000:value}", value);
- The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.
+
The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.
'Value field must have a name (as content)")'
-The message "Value field must have a name (as content)")" can be caused by code like:
-
+The message "Value field must have a name (as content)")" can be caused by code like:
+
xo_emit("{:/%s}", "value");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:tag-name/%s}", "value");
- The field name is used for XML and JSON encodings. These tags names are static and must appear directly in the field descriptor.
+
The field name is used for XML and JSON encodings. These tags names are static and must appear directly in the field descriptor.
'Use hyphens, not underscores, for value field name'
-The message "Use hyphens, not underscores, for value field name" can be caused by code like:
-
+The message "Use hyphens, not underscores, for value field name" can be caused by code like:
+
xo_emit("{:no_under_scores}", "bad");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:no-under-scores}", "bad");
- Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.
+
Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.
'Value field name cannot start with digit'
-The message "Value field name cannot start with digit" can be caused by code like:
-
+The message "Value field name cannot start with digit" can be caused by code like:
+
xo_emit("{:10-gig/}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:ten-gig/}");
- XML element names cannot start with a digit.
+
XML element names cannot start with a digit.
'Value field name should be lower case'
-The message "Value field name should be lower case" can be caused by code like:
-
+The message "Value field name should be lower case" can be caused by code like:
+
xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:why-are-you-shouting}", "no reason");
- Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Lower case rules the seas.
+
Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Lower case rules the seas.
'Value field name should be longer than two characters'
-The message "Value field name should be longer than two characters" can be caused by code like:
-
+The message "Value field name should be longer than two characters" can be caused by code like:
+
xo_emit("{:x}", "mumble");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:something-meaningful}", "mumble");
- Field names should be descriptive, and it's hard to be descriptive in less than two characters. Consider your users and try to make something more useful. Note that this error often occurs when the field type is placed after the colon ("{:T/%20s}"), instead of before it ("{T:/20s}").
+
Field names should be descriptive, and it's hard to be descriptive in less than two characters. Consider your users and try to make something more useful. Note that this error often occurs when the field type is placed after the colon ("{:T/%20s}"), instead of before it ("{T:/20s}").
'Value field name contains invalid character'
-The message "Value field name contains invalid character" can be caused by code like:
-
+The message "Value field name contains invalid character" can be caused by code like:
+
xo_emit("{:cost-in-$$/%u}", 15);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:cost-in-dollars/%u}", 15);
- An invalid character is often a sign of a typo, like "{:]}" instead of "{]:}". Field names are restricted to lower-case characters, digits, and hyphens.
+
An invalid character is often a sign of a typo, like "{:]}" instead of "{]:}". Field names are restricted to lower-case characters, digits, and hyphens.
'decoration field contains invalid character'
-The message "decoration field contains invalid character" can be caused by code like:
-
+The message "decoration field contains invalid character" can be caused by code like:
+
xo_emit("{D:not good}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{D:((}{:good}{D:))}", "yes");
- This is minor, but fields should use proper roles. Decoration fields are meant to hold punctuation and other characters used to decorate the content, typically to make it more readable to human readers.
+
This is minor, but fields should use proper roles. Decoration fields are meant to hold punctuation and other characters used to decorate the content, typically to make it more readable to human readers.
'Anchor content should be decimal width'
-The message "Anchor content should be decimal width" can be caused by code like:
-
+The message "Anchor content should be decimal width" can be caused by code like:
+
xo_emit("{[:mumble}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{[:32}");
- Anchors need an integer value to specify the width of the set of anchored fields. The value can be positive (for left padding/right justification) or negative (for right padding/left justification) and can appear in either the start or stop anchor field descriptor.
+
Anchors need an integer value to specify the width of the set of anchored fields. The value can be positive (for left padding/right justification) or negative (for right padding/left justification) and can appear in either the start or stop anchor field descriptor.
'Anchor format should be "%d"'
-The message "Anchor format should be "%d"" can be caused by code like:
-
+The message "Anchor format should be "%d"" can be caused by code like:
+
xo_emit("{[:/%s}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{[:/%d}");
- Anchors only grok integer values, and if the value is not static, if must be in an 'int' argument, represented by the "%d" format. Anything else is an error.
+
Anchors only grok integer values, and if the value is not static, if must be in an 'int' argument, represented by the "%d" format. Anything else is an error.
'Anchor cannot have both format and encoding format")'
-The message "Anchor cannot have both format and encoding format")" can be caused by code like:
-
+The message "Anchor cannot have both format and encoding format")" can be caused by code like:
+
xo_emit("{[:32/%d}");
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{[:32}");
- Anchors can have a static value or argument for the width, but cannot have both.
+
Anchors can have a static value or argument for the width, but cannot have both.
'Max width only valid for strings'
-The message "Max width only valid for strings" can be caused by code like:
-
+The message "Max width only valid for strings" can be caused by code like:
+
xo_emit("{:tag/%2.4.6d}", 55);
- This code should be replaced with code like:
-
+
This code should be replaced with code like:
+
xo_emit("{:tag/%2.6d}", 55);
- libxo allows a true 'max width' in addition to the traditional printf-style 'max number of bytes to use for input'. But this is supported only for string values, since it makes no sense for non-strings. This error may occur from a typo, like "{:tag/%6..6d}" where only one period should be used.
+
libxo allows a true 'max width' in addition to the traditional printf-style 'max number of bytes to use for input'. But this is supported only for string values, since it makes no sense for non-strings. This error may occur from a typo, like "{:tag/%6..6d}" where only one period should be used.
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.
-Section Contents:
+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.
+Section Contents:
Howto: Report bugs
-libxo uses github to track bugs or request enhancements. Please use the following URL:
- https://github.com/Juniper/libxo/issues
+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:
-
+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.
-Use "../configure --help" to display available configuration options, which include the following:
-
+
libxo uses a distinct "build" directory to keep generated files separated from source files.
+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
@@ -26389,46 +26502,46 @@ jQuery(function ($) {
--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.
-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.
-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.
-libslax is not required by libxo; it contains the "oxtradoc" program used to format documentation.
-For additional information, see Section 1.1.2.
+
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.
+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.
+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.
+libslax is not required by libxo; it contains the "oxtradoc" program used to format documentation.
+For additional information, see Section 2.2.
Howto: Convert command line applications
-
+
How do I convert an existing command line application?
- There are three basic steps for converting command line application to use libxo.
-
+
There are three basic steps for converting command line application to use libxo.
+
- Setting up the context
- Converting printf calls
- Creating hierarchy
- Converting error functions
-Section Contents:
+Section Contents:
Setting up the context
-To use libxo, you'll need to include the "xo.h" header file in your source code files:
-
+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 (Section 3.4.1). This function removes libxo-specific arguments the program's argv and returns either the number of remaining arguments or -1 to indicate an error.
-
+
In your main() function, you'll need to call xo_parse_args to handling argument parsing (Section 5.4.1). 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);
@@ -26436,31 +26549,31 @@ jQuery(function ($) {
return argc;
....
}
- At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (Section 3.1). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.
-
+
At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (Section 5.1). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.
+
atexit(xo_finish_atexit);
Converting printf Calls
-The second task is inspecting code for 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:
-
+The second task is inspecting code for 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:
+
printf("There are %d %s events\n", count, etype);
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 (Section 2.2.1.6).
-The "title" role indicates the headings of table and sections. This allows HTML output to use CSS to make this relationship more obvious.
-
+
"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 (Section 3.2.1.6).
+The "title" role indicates the headings of table and sections. This allows HTML output to use CSS to make this relationship more obvious.
+
printf("Statistics:\n");
xo_emit("{T:Statistics}:\n");
- The "color" roles controls foreground and background colors, as well as effects like bold and underline (see Section 2.2.1.1).
-
+
The "color" roles controls foreground and background colors, as well as effects like bold and underline (see Section 3.2.1.1).
+
xo_emit("{C:bold}required{C:}\n");
- Finally, the start- and stop-anchor roles allow justification and padding over multiple fields (see Section 2.2.1.10).
-
+
Finally, the start- and stop-anchor roles allow justification and padding over multiple fields (see Section 3.2.1.10).
+
snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max);
printf("%30s", buf);
@@ -26468,13 +26581,13 @@ jQuery(function ($) {
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:
-
+Text output doesn't have any sort of hierarchy, but XML and JSON require this. Typically applications use indentation to represent these relationship:
+
printf("table %d\n", tnum);
for (i = 0; i < tmax; i++) {
printf(" %s %d\n", table[i].name, table[i].size);
@@ -26489,10 +26602,10 @@ jQuery(function ($) {
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.
-
+
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.
+
printf("Paging information:\n");
printf(" Free: %lu\n", free);
printf(" Active: %lu\n", active);
@@ -26505,36 +26618,36 @@ jQuery(function ($) {
xo_close_container("paging-information");
Converting Error Functions
-libxo provides variants of the standard error and warning functions, err(3) and 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:
-
+libxo provides variants of the standard error and warning functions, err(3) and 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:
+
err(1, "cannot open output file: %s", file);
xo_err(1, "cannot open output file: %s", file);
xo_emit_err(1, "cannot open output file: {:filename}", file);
-
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 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.
-
+
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 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
@@ -26566,44 +26679,44 @@ jQuery(function ($) {
# 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:
-
+
Once these steps are complete, you can use the "gettext" command to test the message catalog:
+
gettext -d foo -e "some text"
- Section Contents:
-
+ Section Contents:
+
i18n and xo_emit
-There are three features used in libxo used to support i18n:
-
+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.
-
+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.
-
+
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 gettext(3) with that string to get a localized version. If your language were Pig Latin, the result might look like:
-
+
libxo calls 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 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 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.
-
+
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 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 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)));
@@ -26614,21 +26727,21 @@ jQuery(function ($) {
Examples
-Section Contents:
-
+Section Contents:
+
Unit Test
-Here is the unit test example:
-
+Here is the unit test example:
+
int
main (int argc, char **argv)
{
@@ -26720,8 +26833,8 @@ jQuery(function ($) {
return 0;
}
- Text output:
-
+
Text output:
+
% ./testxo --libxo text
Item 'gum':
Total sold: 1412.0
@@ -26753,8 +26866,8 @@ jQuery(function ($) {
In stock: 45
On order: 1
SKU: GRO-000-533
- JSON output:
-
+
JSON output:
+
% ./testxo --libxo json,pretty
"top": {
"data": {
@@ -26808,8 +26921,8 @@ jQuery(function ($) {
]
}
}
- XML output:
-
+
XML output:
+
% ./testxo --libxo pretty,xml
<top>
<data>
@@ -26859,8 +26972,8 @@ jQuery(function ($) {
</item>
</data>
</top>
- HMTL output:
-
+
HMTL output:
+
% ./testxo --libxo pretty,html
<div class="line">
<div class="label">Item</div>
@@ -27054,8 +27167,8 @@ jQuery(function ($) {
<div class="text">: </div>
<div class="data" data-tag="sku">GRO-000-533</div>
</div>
- HTML output with xpath and info flags:
-
+
HTML output with xpath and info flags:
+
% ./testxo --libxo pretty,html,xpath,info
<div class="line">
<div class="label">Item</div>
diff --git a/doc/libxo.txt b/doc/libxo.txt
index f4b0eff5ebc0..3e8e9545e052 100644
--- a/doc/libxo.txt
+++ b/doc/libxo.txt
@@ -16,11 +16,28 @@ You want to prepare for the future, but you need to live in the
present. You'd love a flying car, but need to get to work today. You
want to support features like XML, JSON, and HTML rendering to allow
integration with NETCONF, REST, and web browsers, but you need to make
-text output for command line users. And you don't want multiple code
-paths that can't help but get out of sync. None of this "if (xml)
-{... } else {...}" logic. And ifdefs are right out. But you'd
-really, really like all the fancy features that modern encoding
-formats can provide. libxo can help.
+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.
The libxo library allows an application to generate text, XML, JSON,
and HTML output using a common set of function calls. The application
@@ -35,8 +52,11 @@ braces with a printf-like format string (^format-strings^):
linect, wordct, charct, file);
Each field can have a role, with the 'value' role being the default,
-and the role tells libxo how and when to render that field. Output
-can then be generated in various style, using the "--libxo" option:
+and the role tells libxo how and when to render that field (see
+^field-roles^ for details). Modifiers change how the field is
+rendered in different output styles (see ^field-modifiers^ for
+details. Output can then be generated in various style, using the
+"--libxo" option:
% wc /etc/motd
25 165 1140 /etc/motd
@@ -74,7 +94,12 @@ can then be generated in various style, using the "--libxo" option:
/etc/motd
-** Getting libxo
+Same code path, same format strings, same information, but it's
+rendered in distinct styles based on run-time flags.
+
+* Getting libxo
+
+libxo now ships as part of the FreeBSD Operating System (as of -11).
libxo lives on github as:
@@ -101,7 +126,7 @@ as part of the FreeBSD operating system starting with release 11.0.
Issues, problems, and bugs should be directly to the issues page on
our github site.
-*** Downloading libxo Source Code
+** Downloading libxo Source Code
You can retrieve the source for libxo in two ways:
@@ -140,7 +165,7 @@ download the source code from svn, then you'll need to run
"autoreconf" by hand. This step is done for you by the "setup.sh"
script, described in the next section.
-*** Building libxo
+** 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.
@@ -159,7 +184,7 @@ 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
+*** Setting up the build
[If you downloaded a distfile, you can skip this step.]
@@ -171,7 +196,7 @@ generated files.
Note: We're are currently using autoreconf version 2.69.
-**** Running the "configure" Script
+*** Running the "configure" Script
Configure (and autoconf in general) provides a means of building
software in diverse environments. Our configure script supports
@@ -221,7 +246,7 @@ machine. To run the regression tests:
make test
-**** Installing libxo
+*** 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
@@ -544,6 +569,15 @@ The following color names are supported:
| 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.
+
**** The Decoration Role ({D:})
Decorations are typically punctuation marks such as colons,
@@ -818,7 +852,7 @@ more meaningful.
"hn" can be used as an alias for "humanize".
The humanize modifier only affects display styles (TEXT and HMTL).
-The "no-humanize" option (See ^LIBXO_OPTIONS^) will block the function of
+The "no-humanize" option (See ^options^) will block the function of
the humanize modifier.
There are a number of modifiers that affect details of humanization.
@@ -1444,7 +1478,7 @@ properly.
xo_close_marker("fish-guts");
}
-** Command-line Arguments
+* Command-line Arguments @options@
libxo uses command line options to trigger rendering behavior. The
following options are recognised:
@@ -1453,9 +1487,17 @@ following options are recognised:
- --libxo=
- --libxo:
+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 ^xo_parse_args^ for details.
+** Option keywords
+
Options is a comma-separated list of tokens that correspond to output
styles, flags, or features:
@@ -1463,6 +1505,7 @@ 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) |
@@ -1489,11 +1532,10 @@ styles, flags, or features:
| xpath | Add XPath expressions (HTML) |
|-------------+-------------------------------------------------------|
-The brief options are detailed in ^LIBXO_OPTIONS^.
-
Most of these option are simple and direct, but some require
additional details:
+- "colors" is described in ^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
@@ -1513,6 +1555,73 @@ 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 | Indent by |
+| J | Enable JSON output (XO_STYLE_JSON) |
+| k | Add keys to XPATH expressions in HTML |
+| n | Disable humanization (TEXT, HTML) |
+| P | Enable pretty-printed output (XOF_PRETTY) |
+| T | Enable text output (XO_STYLE_TEXT) |
+| U | Add units to HTML output |
+| u | Change "-"s to "_"s in element names (JSON) |
+| W | Enable warnings (XOF_WARN) |
+| X | Enable XML output (XO_STYLE_XML) |
+| x | Enable XPath data (XOF_XPATH) |
+|--------+---------------------------------------------|
+
+** 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
* The libxo API
@@ -1741,7 +1850,7 @@ and flags and enables them for a specific handle.
int xo_set_options (xo_handle_t *xop, const char *input);
-The options are identical to those listed in ^command-line-arguments^.
+The options are identical to those listed in ^options^.
*** xo_destroy
@@ -1965,7 +2074,7 @@ is returned. On failure, a message it emitted and -1 is returned.
exit(EXIT_FAILURE);
Following the call to xo_parse_args, the application can process the
-remaining arguments in a normal manner. See ^command-line-arguments^
+remaining arguments in a normal manner. See ^options^
for a description of valid arguments.
*** xo_set_program
@@ -2056,36 +2165,24 @@ By default, the standard realloc() and free() functions are used.
*** LIBXO_OPTIONS @LIBXO_OPTIONS@
-The environment variable "LIBXO_OPTIONS" can be set to a string of
-options:
+The environment variable "LIBXO_OPTIONS" can be set to a subset of
+libxo options, including:
-|--------+---------------------------------------------|
-| Option | Action |
-|--------+---------------------------------------------|
-| c | Enable color/effects for TEXT/HTML |
-| F | Force line-buffered flushing |
-| H | Enable HTML output (XO_STYLE_HTML) |
-| I | Enable info output (XOF_INFO) |
-| i | Indent by |
-| J | Enable JSON output (XO_STYLE_JSON) |
-| k | Add keys to XPATH expressions in HTML |
-| n | Disable humanization (TEXT, HTML) |
-| P | Enable pretty-printed output (XOF_PRETTY) |
-| T | Enable text output (XO_STYLE_TEXT) |
-| U | Add units to HTML output |
-| u | Change "-"s to "_"s in element names (JSON) |
-| W | Enable warnings (XOF_WARN) |
-| X | Enable XML output (XO_STYLE_XML) |
-| x | Enable XPath data (XOF_XPATH) |
-|--------+---------------------------------------------|
+- color
+- flush
+- flush-line
+- no-color
+- no-humanize
+- no-locale
+- no-retain
+- pretty
+- retain
+- underscores
+- warn
For example, warnings can be enabled by:
- % env LIBXO_OPTIONS=W my-app
-
-Complete HTML output can be generated with:
-
- % env LIBXO_OPTIONS=HXI my-app
+ % env LIBXO_OPTIONS=warn my-app
Since environment variables are inherited, child processes will have
the same options, which may be undesirable, making the use of the
@@ -2474,9 +2571,9 @@ 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