153 lines
3.6 KiB
Groff
153 lines
3.6 KiB
Groff
.\" #
|
|
.\" # Copyright (c) 2014, Juniper Networks, Inc.
|
|
.\" # All rights reserved.
|
|
.\" # This SOFTWARE is licensed under the LICENSE provided in the
|
|
.\" # ../Copyright file. By downloading, installing, copying, or
|
|
.\" # using the SOFTWARE, you agree to be bound by the terms of that
|
|
.\" # LICENSE.
|
|
.\" # Phil Shafer, July 2014
|
|
.\"
|
|
.Dd December 4, 2014
|
|
.Dt LIBXO 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm xo_parse_args , xo_set_program
|
|
.Nd detect, parse, and remove arguments for libxo
|
|
.Sh LIBRARY
|
|
.Lb libxo
|
|
.Sh SYNOPSIS
|
|
.In libxo/xo.h
|
|
.Ft int
|
|
.Fn xo_parse_args "int argc" "char **argv"
|
|
.Ft int
|
|
.Fn xo_set_program "const char *name"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn xo_parse_args
|
|
function is used to process command-line arguments.
|
|
.Nm 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.
|
|
.Bd -literal -offset indent
|
|
argc = xo_parse_args(argc, argv);
|
|
if (argc < 0)
|
|
exit(EXIT_FAILURE);
|
|
.Ed
|
|
.Pp
|
|
Following the call to
|
|
.Fn xo_parse_args ,
|
|
the application can process the remaining arguments in a normal manner.
|
|
.Pp
|
|
.Nm libxo
|
|
uses command line options to trigger rendering behavior.
|
|
The following options are recognised:
|
|
.Pp
|
|
.Bl -tag -width "--libxo"
|
|
.It
|
|
\-\^\-libxo <options>
|
|
.It
|
|
\-\^\-libxo=<options>
|
|
.It
|
|
\-\^\-libxo:<brief-options>
|
|
.El
|
|
.Pp
|
|
Options is a comma-separated list of tokens that correspond to output
|
|
styles, flags, or features:
|
|
.Pp
|
|
.Bl -tag -width "12345678"
|
|
.It Sy "Token Action"
|
|
.It Dv dtrt
|
|
Enable "Do The Right Thing" mode
|
|
.It Dv html
|
|
Emit HTML output
|
|
.It Dv indent=xx
|
|
Set the indentation level
|
|
.It Dv info
|
|
Add info attributes (HTML)
|
|
.It Dv json
|
|
Emit JSON output
|
|
.It Dv keys
|
|
Emit the key attribute for keys (XML)
|
|
.It Dv log-gettext
|
|
Log (via stderr) each
|
|
.Xr gettext 3
|
|
string lookup
|
|
.It Dv log-syslog
|
|
Log (via stderr) each syslog message (via
|
|
.Xr xo_syslog 3 )
|
|
.If Dv no-humanize
|
|
Ignore the {h:} modifier (TEXT, HTML)
|
|
.It Dv no-locale
|
|
Do not initialize the locale setting
|
|
.It Dv no-retain
|
|
Prevent retaining formatting information
|
|
.It Dv no-top
|
|
Do not emit a top set of braces (JSON)
|
|
.It Dv not-first
|
|
Pretend the 1st output item was not 1st (JSON)
|
|
.It Dv pretty
|
|
Emit pretty-printed output
|
|
.It Dv retain
|
|
Force retaining formatting information
|
|
.It Dv text
|
|
Emit TEXT output
|
|
.If Dv underscores
|
|
Replace XML-friendly "-"s with JSON friendly "_"s e
|
|
.It Dv units
|
|
Add the 'units' (XML) or 'data-units (HTML) attribute
|
|
.It Dv warn
|
|
Emit warnings when libxo detects bad calls
|
|
.It Dv warn-xml
|
|
Emit warnings in XML
|
|
.It Dv xml
|
|
Emit XML output
|
|
.It Dv xpath
|
|
Add XPath expressions (HTML)
|
|
.El
|
|
.Pp
|
|
The
|
|
.Dq brief-options
|
|
are single letter commands, designed for those with
|
|
too little patience to use real tokens.
|
|
No comma separator is used.
|
|
.Bl -column "i<num>"
|
|
.It Sy "Token Action"
|
|
.It "H " "Enable HTML output (XO_STYLE_HTML)"
|
|
.It "I " "Enable info output (XOF_INFO)"
|
|
.It "i<num> " "Indent by <number>"
|
|
.It "J " "Enable JSON output (XO_STYLE_JSON)"
|
|
.It "P " "Enable pretty-printed output (XOF_PRETTY)"
|
|
.It "T " "Enable text output (XO_STYLE_TEXT)"
|
|
.It "W " "Enable warnings (XOF_WARN)"
|
|
.It "X " "Enable XML output (XO_STYLE_XML)"
|
|
.It "x " "Enable XPath data (XOF_XPATH)"
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn xo_set_program
|
|
function sets name of the program as reported by
|
|
functions like
|
|
.Fn xo_failure ,
|
|
.Fn xo_warn ,
|
|
.Fn xo_err ,
|
|
etc.
|
|
The program name is initialized by
|
|
.Fn xo_parse_args ,
|
|
but subsequent calls to
|
|
.Fn xo_set_program
|
|
can override this value.
|
|
.Pp
|
|
Note that the value is not copied, so the memory passed to
|
|
.Fn xo_set_program
|
|
(and
|
|
.Fn xo_parse_args )
|
|
must be maintained by the caller.
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr xo_emit 3 ,
|
|
.Xr libxo 3
|