contrib/libxo/libxo/xo_parse_args.3

   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
  25 The
  26 .Fn xo_parse_args
  27 function is used to process command-line arguments.
  28 .Nm libxo
  29 specific
  30 options are processed and removed
  31 from the argument list so the calling application does not
  32 need to process them.
  33 If successful, a new value for argc is returned.
  34 On 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
  41 Following the call to
  42 .Fn xo_parse_args ,
  43 the application can process the remaining arguments in a normal manner.
  44 .Pp
  45 .Nm libxo
  46 uses command line options to trigger rendering behavior.
  47 The 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
  58 Options is a comma-separated list of tokens that correspond to output
  59 styles, flags, or features:
  60 .Pp
  61 .Bl -tag -width "12345678"
  62 .It Sy "Token   Action"
  63 .It Dv dtrt
  64 Enable "Do The Right Thing" mode
  65 .It Dv html
  66 Emit HTML output
  67 .It Dv indent=xx
  68 Set the indentation level
  69 .It Dv info
  70 Add info attributes (HTML)
  71 .It Dv json
  72 Emit JSON output
  73 .It Dv keys
  74 Emit the key attribute for keys (XML)
  75 .It Dv log-gettext
  76 Log (via stderr) each
  77 .Xr gettext 3
  78 string lookup
  79 .It Dv log-syslog
  80 Log (via stderr) each syslog message (via
  81 .Xr xo_syslog 3 )
  82 .If Dv no-humanize
  83 Ignore the {h:} modifier (TEXT, HTML)
  84 .It Dv no-locale
  85 Do not initialize the locale setting
  86 .It Dv no-retain
  87 Prevent retaining formatting information
  88 .It Dv no-top
  89 Do not emit a top set of braces (JSON)
  90 .It Dv not-first
  91 Pretend the 1st output item was not 1st (JSON)
  92 .It Dv pretty
  93 Emit pretty-printed output
  94 .It Dv retain
  95 Force retaining formatting information
  96 .It Dv text
  97 Emit TEXT output
  98 .If Dv underscores
  99 Replace XML-friendly "-"s with JSON friendly "_"s e
 100 .It Dv units
 101 Add the 'units' (XML) or 'data-units (HTML) attribute
 102 .It Dv warn
 103 Emit warnings when libxo detects bad calls
 104 .It Dv warn-xml
 105 Emit warnings in XML
 106 .It Dv xml
 107 Emit XML output
 108 .It Dv xpath
 109 Add XPath expressions (HTML)
 110 .El
 111 .Pp
 112 The
 113 .Dq brief-options
 114 are single letter commands, designed for those with
 115 too little patience to use real tokens.
 116 No 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
 130 The
 131 .Fn xo_set_program
 132 function sets name of the program as reported by
 133 functions like
 134 .Fn xo_failure ,
 135 .Fn xo_warn ,
 136 .Fn xo_err ,
 137 etc.
 138 The program name is initialized by
 139 .Fn xo_parse_args ,
 140 but subsequent calls to
 141 .Fn xo_set_program
 142 can override this value.
 143 .Pp
 144 Note that the value is not copied, so the memory passed to
 145 .Fn xo_set_program
 146 (and
 147 .Fn xo_parse_args )
 148 must be maintained by the caller.
 149 .Pp
 150 .Sh SEE ALSO
 151 .Xr xo_emit 3 ,
 152 .Xr libxo 3
 153 .Sh HISTORY
 154 The
 155 .Nm libxo
 156 library first appeared in
 157 .Fx 11.0 .
 158 .Sh AUTHORS
 159 .Nm libxo
 160 was written by
 161 .An Phil Shafer Aq Mt phil@freebsd.org .
 162