LIBXO(3)

NAME
xo_parse_args, xo_set_program - detect, parse, and remove arguments for libxo

LIBRARY
libxo

SYNOPSIS
#include <libxo/xo.h>
int
xo_parse_args(int argc, char **argv);
int
xo_set_program(const char *name);

DESCRIPTION
The xo_parse_args() function is used to process command-line 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.

libxo uses command line options to trigger rendering behavior. The following options are recognised:

    --libxo <options>

    --libxo=<options>

    --libxo:<brief-options>

Options is a comma-separated list of tokens that correspond to output styles, flags, or features:

Token   Action

dtrt
    Enable "Do The Right Thing" mode

html
    Emit HTML output

indent=xx
    Set the indentation level

info
    Add info attributes (HTML)

json
    Emit JSON output

keys
    Emit the key attribute for keys (XML)

log-gettext
    Log (via stderr) each gettext(3) string lookup

log-syslog
    Log (via stderr) each syslog message (via xo_syslog(3)) Ignore the {h:} modifier (TEXT, HTML)

no-locale
    Do not initialize the locale setting

no-retain
    Prevent retaining formatting information

no-top
    Do not emit a top set of braces (JSON)

not-first
    Pretend the 1st output item was not 1st (JSON)

pretty
    Emit pretty-printed output

retain
    Force retaining formatting information

text
    Emit TEXT output Replace XML-friendly "-"s with JSON friendly "_"s e

units
    Add the 'units' (XML) or 'data-units (HTML) attribute

warn
    Emit warnings when libxo detects bad calls

warn-xml
    Emit warnings in XML

xml Emit XML output

xpath
    Add XPath expressions (HTML)

The “brief-options” are single letter commands, designed for those with too little patience to use real tokens. No comma separator is used.
Token   Action
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)
P       Enable pretty-printed output (XOF_PRETTY)
T       Enable text output (XO_STYLE_TEXT)
W       Enable warnings (XOF_WARN)
X       Enable XML output (XO_STYLE_XML)
x       Enable XPath data (XOF_XPATH)

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.

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.

SEE ALSO
xo_emit(3), libxo(3)

HISTORY
The libxo library first appeared in FreeBSD 11.0.

AUTHORS
libxo was written by Phil Shafer <phil@freebsd.org>.