1.\" # 2.\" # Copyright (c) 2014, Juniper Networks, Inc. 3.\" # All rights reserved. 4.\" # This SOFTWARE is licensed under the LICENSE provided in the 5.\" # ../Copyright file. By downloading, installing, copying, or 6.\" # using the SOFTWARE, you agree to be bound by the terms of that 7.\" # LICENSE. 8.\" # Phil Shafer, July 2014 9.\" 10.Dd December 4, 2014 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_parse_args , xo_set_program 15.Nd detect, parse, and remove arguments for libxo 16.Sh LIBRARY 17.Lb libxo 18.Sh SYNOPSIS 19.In libxo/xo.h 20.Ft int 21.Fn xo_parse_args "int argc" "char **argv" 22.Ft int 23.Fn xo_set_program "const char *name" 24.Sh DESCRIPTION 25The 26.Fn xo_parse_args 27function is used to process command-line arguments. 28.Nm libxo 29specific 30options are processed and removed 31from the argument list so the calling application does not 32need to process them. 33If successful, a new value for argc is returned. 34On failure, a message it emitted and -1 is returned. 35.Bd -literal -offset indent 36 argc = xo_parse_args(argc, argv); 37 if (argc < 0) 38 exit(EXIT_FAILURE); 39.Ed 40.Pp 41Following the call to 42.Fn xo_parse_args , 43the application can process the remaining arguments in a normal manner. 44.Pp 45.Nm libxo 46uses command line options to trigger rendering behavior. 47The following options are recognised: 48.Pp 49.Bl -tag -width "--libxo" 50.It 51\-\^\-libxo <options> 52.It 53\-\^\-libxo=<options> 54.It 55\-\^\-libxo:<brief-options> 56.El 57.Pp 58Options is a comma-separated list of tokens that correspond to output 59styles, flags, or features: 60.Pp 61.Bl -tag -width "12345678" 62.It Sy "Token Action" 63.It Dv dtrt 64Enable "Do The Right Thing" mode 65.It Dv html 66Emit HTML output 67.It Dv indent=xx 68Set the indentation level 69.It Dv info 70Add info attributes (HTML) 71.It Dv json 72Emit JSON output 73.It Dv keys 74Emit the key attribute for keys (XML) 75.It Dv log-gettext 76Log (via stderr) each 77.Xr gettext 3 78string lookup 79.It Dv log-syslog 80Log (via stderr) each syslog message (via 81.Xr xo_syslog 3 ) 82.If Dv no-humanize 83Ignore the {h:} modifier (TEXT, HTML) 84.It Dv no-locale 85Do not initialize the locale setting 86.It Dv no-retain 87Prevent retaining formatting information 88.It Dv no-top 89Do not emit a top set of braces (JSON) 90.It Dv not-first 91Pretend the 1st output item was not 1st (JSON) 92.It Dv pretty 93Emit pretty-printed output 94.It Dv retain 95Force retaining formatting information 96.It Dv text 97Emit TEXT output 98.If Dv underscores 99Replace XML-friendly "-"s with JSON friendly "_"s e 100.It Dv units 101Add the 'units' (XML) or 'data-units (HTML) attribute 102.It Dv warn 103Emit warnings when libxo detects bad calls 104.It Dv warn-xml 105Emit warnings in XML 106.It Dv xml 107Emit XML output 108.It Dv xpath 109Add XPath expressions (HTML) 110.El 111.Pp 112The 113.Dq brief-options 114are single letter commands, designed for those with 115too little patience to use real tokens. 116No comma separator is used. 117.Bl -column "i<num>" 118.It Sy "Token Action" 119.It "H " "Enable HTML output (XO_STYLE_HTML)" 120.It "I " "Enable info output (XOF_INFO)" 121.It "i<num> " "Indent by <number>" 122.It "J " "Enable JSON output (XO_STYLE_JSON)" 123.It "P " "Enable pretty-printed output (XOF_PRETTY)" 124.It "T " "Enable text output (XO_STYLE_TEXT)" 125.It "W " "Enable warnings (XOF_WARN)" 126.It "X " "Enable XML output (XO_STYLE_XML)" 127.It "x " "Enable XPath data (XOF_XPATH)" 128.El 129.Pp 130The 131.Fn xo_set_program 132function sets name of the program as reported by 133functions like 134.Fn xo_failure , 135.Fn xo_warn , 136.Fn xo_err , 137etc. 138The program name is initialized by 139.Fn xo_parse_args , 140but subsequent calls to 141.Fn xo_set_program 142can override this value. 143.Pp 144Note that the value is not copied, so the memory passed to 145.Fn xo_set_program 146(and 147.Fn xo_parse_args ) 148must be maintained by the caller. 149.Pp 150.Sh SEE ALSO 151.Xr xo_emit 3 , 152.Xr libxo 3 153.Sh HISTORY 154The 155.Nm libxo 156library first appeared in 157.Fx 11.0 . 158.Sh AUTHORS 159.Nm libxo 160was written by 161.An Phil Shafer Aq Mt phil@freebsd.org . 162 163