1 .\" groff -m man -Thtml <file>
2 .\" See groff_www(7), groff(7) and groff_man(7)
4 .\" save current font, switch to monospace font, output, switch back
12 .\" make text on the same line appear alternately in monospace and roman
15 . ds an-result \&\f[CW]\\$1\f[R]\"
17 . while (\\n[.$] >= 2) \{\
18 . as an-result \/\\$1\f[CW]\,\\$2\f[R]\"
21 . if \\n[.$] .as an-result \/\\$1\"
31 .TH lopsub 7 "DATE()" GIT_VERSION()
35 is an open source library written in
37 which aims to ease the task of creating, documenting and parsing
38 the options of Unix command line utilities. It is suitable for
39 simple commands as well as complex command line utilities with many
40 subcommands where each subcommand has its own set of options. Options
41 and documentation are kept together in a single file which can be
44 code (to be included in the application), or to a manual page.
45 The library supports single-character short options and GNU-style
46 long options. The public API is well documented and stable.
48 To make use of the library, the programmer provides a so-called
50 which describes the options of the application in an intuitive
51 syntax. At build time the suite file is translated into
55 utility which also ships with the
57 package. The generated code defines an instance of an opaque
59 structure and exposes a reference to this structure which can be passed to
62 at run time, together with the usual argument vector. The
63 option parser is part of the
66 so applications need to link with
67 .MONO_ROMAN -llopsub .
68 In addition to the option parser, the library offers many more
69 features. For example, there is a function for merging two different
71 to generate an effective configuration. This is useful for applications
72 which can be configured through command line options and via a
75 The suite file can also be processed into roff format to create
76 a manual page. Conversion into html can easily be performed with
82 .MONO_ROMAN man2html .
85 does not rely on the system's
89 functions of the C library and is thus portable across different
90 flavors of Unix. It is known to work on
103 utility is licensed under the
105 The examples and all code generated by the utilities, however, is
106 licensed with a simple all-permissive license. You are free to do
107 anything you like with the generated code, including incorporating
108 it into or linking it with proprietary software.
114 git clone git://git.tuebingen.mpg.de/lopsub.git
117 Then build the package with
123 The suite parser and the config file parser of the
125 library are both generated by running
127 a tool for generating programs that perform pattern-matching on text. Hence the
129 package must be installed for the build to succeed. Next, run
135 This will install the package in
136 .MONO_ROMAN /usr/local .
137 If you prefer to install as an unprivileged user in
138 .MONO_ROMAN /somewhere/else ,
142 make PREFIX=/somewhere/else install
145 instead. In this case, you need to specify
146 .MONO -I/somewhere/else/include
147 to compile the source files of your application and
148 .MONO -L/somewhere/else/lib
149 for linking. Alternatively, don't run
151 at all and specify the path to the top level directory of the
158 Compile and run the minimal example included at the end of
159 .UR ./lopsub-suite.5.html
166 in the source tree and run the
170 .SH API documentation
172 .UR ./lopsub-api.html
174 Alternatively, examine
177 .MONO_ROMAN lopsub.h.m4 .
181 .MT maan@tuebingen.mpg.de
185 .UR http://people.tuebingen.mpg.de/maan/