# 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 n 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. d -literal -offset indent argc = xo_parse_args(argc, argv); if (argc < 0) exit(EXIT_FAILURE); .Ed
p Following the call to .Fn xo_parse_args , the application can process the remaining arguments in a normal manner.
p .Nm libxo uses command line options to trigger rendering behavior. The following options are recognised:
p l -tag -width "--libxo" t -\^-libxo <options> t -\^-libxo=<options> t -\^-libxo:<brief-options> .El
p Options is a comma-separated list of tokens that correspond to output styles, flags, or features:
p l -tag -width "12345678" t Sy "Token Action" t Dv dtrt Enable "Do The Right Thing" mode t Dv html Emit HTML output t Dv indent=xx Set the indentation level t Dv info Add info attributes (HTML) t Dv json Emit JSON output t Dv keys Emit the key attribute for keys (XML) t Dv log-gettext Log (via stderr) each .Xr gettext 3 string lookup t Dv log-syslog Log (via stderr) each syslog message (via .Xr xo_syslog 3 ) f Dv no-humanize Ignore the {h:} modifier (TEXT, HTML) t Dv no-locale Do not initialize the locale setting t Dv no-retain Prevent retaining formatting information t Dv no-top Do not emit a top set of braces (JSON) t Dv not-first Pretend the 1st output item was not 1st (JSON) t Dv pretty Emit pretty-printed output t Dv retain Force retaining formatting information t Dv text Emit TEXT output f Dv underscores Replace XML-friendly "-"s with JSON friendly "_"s e t Dv units Add the 'units' (XML) or 'data-units (HTML) attribute t Dv warn Emit warnings when libxo detects bad calls t Dv warn-xml Emit warnings in XML t Dv xml Emit XML output t Dv xpath Add XPath expressions (HTML) .El
p The .Dq brief-options are single letter commands, designed for those with too little patience to use real tokens. No comma separator is used. l -column "i<num>" t Sy "Token Action" t "H " "Enable HTML output (XO_STYLE_HTML)" t "I " "Enable info output (XOF_INFO)" t "i<num> " "Indent by <number>" t "J " "Enable JSON output (XO_STYLE_JSON)" t "P " "Enable pretty-printed output (XOF_PRETTY)" t "T " "Enable text output (XO_STYLE_TEXT)" t "W " "Enable warnings (XOF_WARN)" t "X " "Enable XML output (XO_STYLE_XML)" t "x " "Enable XPath data (XOF_XPATH)" .El
p 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.
p 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.
p .Sh SEE ALSO .Xr xo_emit 3 , .Xr libxo 3 .Sh HISTORY The .Nm libxo library first appeared in .Fx 11.0 . .Sh AUTHORS .Nm libxo was written by .An Phil Shafer Aq Mt phil@freebsd.org .