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 July, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_parse_args
  15 .Nd detect, parse, and remove arguments for libxo
  16 .Sh LIBRARY
  17 .Nm libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft int
  21 .Fn xo_parse_args "int argc" "char **argv"
  22 .Sh DESCRIPTION
  23 The
  24 .Fn xo_parse_args
  25 function is used to process command-line arguments.
  26 .Em libxo -specific
  27 options are processed and removed
  28 from the argument list so the calling application does not
  29 need to process them.  If successful, a new value for argc
  30 is returned.  On failure, a message it emitted and -1 is returned.
  31 .Bd -literal -offset indent
  32     argc = xo_parse_args(argc, argv);
  33     if (argc < 0)
  34         exit(1);
  35 .Ed
  36 .Pp
  37 Following the call to
  38 .Fn xo_parse_args ,
  39 the application can process the remaining arguments in a normal manner.
  40 .Pp
  41 .Em libxo
  42 uses command line options to trigger rendering behavior.  The
  43 following options are recognised:
  44 .Pp
  45 .Bl -tag -width "--libxo"
  46 .It
  47 \-\^\-libxo <options>
  48 .It
  49 \-\^\-libxo=<options>
  50 .It
  51 \-\^\-libxo:<brief-options>
  52 .El
  53 .Pp
  54 Options is a comma-separated list of tokens that correspond to output
  55 styles, flags, or features:
  56 .Pp
  57 .Bl -tag -width "12345678"
  58 .It Sy "Token   Action"
  59 .It dtrt
  60 Enable "Do The Right Thing" mode
  61 .It html
  62 Emit HTML output
  63 .It indent=xx
  64 Set the indentation level
  65 .It info
  66 Add info attributes (HTML)
  67 .It json
  68 Emit JSON output
  69 .It keys
  70 Emit the key attribute for keys (XML)
  71 .It no-locale
  72 Do not initialize the locale setting
  73 .It no-top
  74 Do not emit a top set of braces (JSON)
  75 .It not-first
  76 Pretend the 1st output item was not 1st (JSON)
  77 .It pretty
  78 Emit pretty-printed output
  79 .It text
  80 Emit TEXT output
  81 .It units
  82 Add the 'units' (XML) or 'data-units (HTML) attribute
  83 .It warn
  84 Emit warnings when libxo detects bad calls
  85 .It warn-xml
  86 Emit warnings in XML
  87 .It xml
  88 Emit XML output
  89 .It xpath
  90 Add XPath expressions (HTML)
  91 .El
  92 .Pp
  93 The
  94 .Dq brief-options
  95 are single letter commands, designed for those with
  96 too little patience to use real tokens.  No comma separator is used.
  97 .Bl -column "i<num>"
  98 .It Sy "Token   Action"
  99 .It "H      " "Enable HTML output (XO_STYLE_HTML)"
 100 .It "I      " "Enable info output (XOF_INFO)"
 101 .It "i<num> " "Indent by <number>"
 102 .It "J      " "Enable JSON output (XO_STYLE_JSON)"
 103 .It "P      " "Enable pretty-printed output (XOF_PRETTY)"
 104 .It "T      " "Enable text output (XO_STYLE_TEXT)"
 105 .It "W      " "Enable warnings (XOF_WARN)"
 106 .It "X      " "Enable XML output (XO_STYLE_XML)"
 107 .It "x      " "Enable XPath data (XOF_XPATH)"
 108 .El
 109 .Pp
 110 .Sh ADDITIONAL DOCUMENTATION
 111 .Pp
 112 Complete documentation can be found on github:
 113 .Bd -literal -offset indent
 114 http://juniper.github.io/libxo/libxo-manual.html
 115 .Ed
 116 .Pp
 117 libxo lives on github as:
 118 .Bd -literal -offset indent
 119 https://github.com/Juniper/libxo
 120 .Ed
 121 .Pp
 122 The latest release of libxo is available at:
 123 .Bd -literal -offset indent
 124 https://github.com/Juniper/libxo/releases
 125 .Ed
 126 .Sh SEE ALSO
 127 .Xr xo_emit 3
 128 .Sh HISTORY
 129 The
 130 .Fa libxo
 131 library was added in FreeBSD 11.0.
 132 .Sh AUTHOR
 133 Phil Shafer