summaryrefslogtreecommitdiff
path: root/doc/cli.xhtml
blob: 99c2f78344118b3c5ea12f89290c83ab2b1bc8ff (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

<head>
  <title>CLI 1.2.0 Compiler Command Line Manual</title>

  <meta name="copyright" content="&copy; 2009-2011 Code Synthesis Tools CC"/>
  <meta name="keywords" content="cli,command,line,interface,compiler,c++"/>
  <meta name="description" content="CLI Compiler Command Line Manual"/>

  <link rel="stylesheet" type="text/css" href="default.css" />

<style type="text/css">

  #synopsis {
    list-style-type:  none;
  }

  #synopsis li {
    padding-top      : 0.0em;
    padding-bottom   : 0.0em;
  }

  .options {
    margin: 1em 0 1em 0;
  }

  .options dt {
    margin: 1em 0 0 0;
  }

  .options dd {
    margin: .1em 0 0 4.5em;
  }

</style>
</head>

<body>
<div id="container">
  <div id="content">

  <h1>NAME</h1>

  <p>cli - command line interface compiler for C++</p>

  <h1>SYNOPSIS</h1>

  <dl id="synopsis">
    <dt><code><b>cli</b> [<i>options</i>] <i>file</i></code></dt>
  </dl>

  <h1>DESCRIPTION</h1>

  <p><code><b>cli</b></code> generates C++ implementation and
  documentation in various formats for a command line interface
  defined in the CLI language. For an input file in the form
  <code><b>name.cli</b></code> the following is generated. By
  default or if the <code><b>--generate-cxx</b></code> option is
  specified, the following C++ files are generated:
  <code><b>name.hxx</b></code> (header file), <code><b>name.ixx</b></code>
  (inline file, generated unless the <code><b>--suppress-inline</b></code>
  option is specified), and <code><b>name.cxx</b></code> (source file).
  If the <code><b>--generate-html</b></code> option is specified, then
  the <code><b>name.html</b></code> HTML documentation file is generated.
  If the <code><b>--generate-man</b></code> option is specified, then
  the <code><b>name.1</b></code> man page file is generated. When
  <code><b>--generate-html</b></code> or <code><b>--generate-man</b></code>
  is specified, the <code><b>--stdout</b></code> option can be used to
  redirect the output to STDOUT instead of a file.</p>

  <h1>OPTIONS</h1>
  <dl class="options">
    <dt><code><b>--help</b></code></dt>
    <dd>Print usage information and exit.</dd>

    <dt><code><b>--version</b></code></dt>
    <dd>Print version and exit.</dd>

    <dt><code><b>--include-path</b></code>|<code><b>-I</b></code> <i>dir</i></dt>
    <dd>Search <i>dir</i> for bracket-included (<code><b>&lt;></b></code>)
    options files.</dd>

    <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <i>dir</i></dt>
    <dd>Write the generated files to <i>dir</i> instead of the current
    directory.</dd>

    <dt><code><b>--std</b></code> <i>version</i></dt>
    <dd>Specify the C++ standard that should be used during compilation. Valid
    values are <code><b>c++98</b></code> (default), <code><b>c++11</b></code>,
    and <code><b>c++14</b></code>.</dd>

    <dt><code><b>--generate-modifier</b></code></dt>
    <dd>Generate option value modifiers in addition to accessors.</dd>

    <dt><code><b>--generate-specifier</b></code></dt>
    <dd>Generate functions for determining whether the option was specified on
    the command line.</dd>

    <dt><code><b>--generate-parse</b></code></dt>
    <dd>Generate <code><b>parse()</b></code> functions instead of parsing
    constructors. This is primarily useful for being able to parse into an
    already initialized options class instance, for example, to implement
    merging/overriding.</dd>

    <dt><code><b>--generate-description</b></code></dt>
    <dd>Generate the option description list that can be examined at
    runtime.</dd>

    <dt><code><b>--generate-file-scanner</b></code></dt>
    <dd>Generate the <code>argv_file_scanner</code> implementation. This
    scanner is capable of reading command line arguments from the
    <code>argv</code> array as well as files specified with command line
    options.</dd>

    <dt><code><b>--suppress-inline</b></code></dt>
    <dd>Generate all functions non-inline. By default simple functions are
    made inline. This option suppresses creation of the inline file.</dd>

    <dt><code><b>--cli-namespace</b></code> <i>ns</i></dt>
    <dd>Generate the CLI support types in the <i>ns</i> namespace
    (<code><b>cli</b></code> by default). The namespace can be nested, for
    example <code><b>details::cli</b></code>. If the namespace is empty, then
    the support types are generated in the global namespace.</dd>

    <dt><code><b>--ostream-type</b></code> <i>type</i></dt>
    <dd>Output stream type instead of the default
    <code><b>std::ostream</b></code> that should be used to print usage and
    exception information.</dd>

    <dt><code><b>--generate-cxx</b></code></dt>
    <dd>Generate C++ code. If neither <code><b>--generate-man</b></code> nor
    <code><b>--generate-html</b></code> is specified, this mode is assumed by
    default.</dd>

    <dt><code><b>--generate-man</b></code></dt>
    <dd>Generate documentation in the man page format.</dd>

    <dt><code><b>--generate-html</b></code></dt>
    <dd>Generate documentation in the HTML format.</dd>

    <dt><code><b>--stdout</b></code></dt>
    <dd>Write output to STDOUT instead of a file. This option is not valid
    when generating C++ code and is normally used to combine generated
    documentation for several option classes in a single file.</dd>

    <dt><code><b>--suppress-undocumented</b></code></dt>
    <dd>Suppress the generation of documentation entries for undocumented
    options.</dd>

    <dt><code><b>--suppress-usage</b></code></dt>
    <dd>Suppress the generation of the usage printing code.</dd>

    <dt><code><b>--long-usage</b></code></dt>
    <dd>If no short documentation string is provided, use the complete long
    documentation string in usage. By default, in this situation only the
    first sentence from the long string is used.</dd>

    <dt><code><b>--short-usage</b></code></dt>
    <dd>If specified together with <code><b>--long-usage</b></code>, generate
    both short and long usage versions. In this mode, the long usage printing
    function is called <code><b>print_long_usage()</b></code> and in its
    implementation the long documentation string is always used, even if the
    short version is provided.</dd>

    <dt><code><b>--page-usage</b></code> <i>name</i></dt>
    <dd>Generate the combined usage printing code for the entire page.
    Specifically, this will include all the namespace-level documentation as
    well as usage for all the options classes printed in the order they are
    defined in the main translation unit (documentation/classes from included
    units are ignored except for base classes).

    <p>The <i>name</i> argument is used as a prefix to form the name of the
    usage printing function. It can include the namespace qualification as
    well as documentation variable expansion, for example:</p>

    <pre>--page-usage print_         # print_usage() in global namespace
--page-usage app::print_    # print_usage() in app namespace
--page-usage print_$name$_  # print_foo_usage() if name is foo</pre>

    <p>If both <code><b>--long-usage</b></code> and
    <code><b>--short-usage</b></code> options are specified, then the long
    usage function has the <code><b>*long_usage()</b></code> suffix.</p></dd>

    <dt><code><b>--option-length</b></code> <i>len</i></dt>
    <dd>Indent option descriptions <i>len</i> characters when printing usage.
    This is useful when you have multiple options classes, potentially in
    separate files, and would like their usage to have the same indentation
    level.</dd>

    <dt><code><b>--ansi-color</b></code></dt>
    <dd>Use ANSI color escape sequences when printing usage. By "color" we
    really only mean the bold and underline modifiers. Note that Windows
    console does not recognize ANSI escape sequences and will display them as
    garbage. However, if you pipe such output through
    <code><b>less</b>(1)</code>, it will display them correctly.</dd>

    <dt><code><b>--exclude-base</b></code></dt>
    <dd>Exclude base class information from usage and documentation.</dd>

    <dt><code><b>--include-base-last</b></code></dt>
    <dd>Include base class information after derived for usage and
    documentation. By default, base classes are included first.</dd>

    <dt><code><b>--class-doc</b></code> <i>name</i>=<i>kind</i></dt>
    <dd>Specify the documentation <i>kind</i> that should be used for the
    options class <i>name</i>. The <i>name</i> value should be a
    fully-qualified class name, for example, <code><b>app::options</b></code>.
    The <i>kind</i> value can be <code><b>short</b></code>,
    <code><b>long</b></code>, or <code><b>exclude</b></code>. If the value is
    <code><b>exclude</b></code>, then the class documentation is excluded from
    usage and man/HTML output. For usage, the <code><b>short</b></code> and
    <code><b>long</b></code> values determine which usage function will be
    called when the class is used as base or as part of the page usage (see
    <code><b>--page-usage</b></code>). For man/HTML, these values determine
    which documentation strings are used in the output.</dd>

    <dt><code><b>--class</b></code> <i>name</i></dt>
    <dd>Generate the man page or HTML documentation only for the options class
    <i>name</i>. The <i>name</i> value should be a fully-qualified options
    class name, for example, <code><b>app::options</b></code>. To generate
    documentation for multiple classes, repeat this option and the
    documentation will be produced in the order specified. This functionality
    is useful if you need to assemble documentation from multiple classes in a
    specific order or to insert custom documentation between options belonging
    to different classes.</dd>

    <dt><code><b>--docvar</b></code>|<code><b>-v</b></code> <i>name</i>=<i>val</i></dt>
    <dd>Set documentation variable <i>name</i> to the value <i>val</i>.
    Documentation variables can be substituted in prologues and epilogues (see
    <code><b>--*-prologue*</b></code> and <code><b>--*-epilogue*</b></code>
    options) using the <code><b>$</b></code><i>name</i><code><b>$</b></code>
    expansion syntax (use <code><b>$$</b></code> to escape expansion). They
    can also be defined in <code><b>.cli</b></code> files using the
    <code>"\<i>name</i>=<i>val</i>"</code> syntax.</dd>

    <dt><code><b>--hxx-prologue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the beginning of the generated C++ header
    file.</dd>

    <dt><code><b>--ixx-prologue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the beginning of the generated C++ inline
    file.</dd>

    <dt><code><b>--cxx-prologue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the beginning of the generated C++ source
    file.</dd>

    <dt><code><b>--man-prologue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the beginning of the generated man page
    file.</dd>

    <dt><code><b>--html-prologue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the beginning of the generated HTML file.</dd>

    <dt><code><b>--hxx-epilogue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the end of the generated C++ header file.</dd>

    <dt><code><b>--ixx-epilogue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the end of the generated C++ inline file.</dd>

    <dt><code><b>--cxx-epilogue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the end of the generated C++ source file.</dd>

    <dt><code><b>--man-epilogue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the end of the generated man page text.</dd>

    <dt><code><b>--html-epilogue</b></code> <i>text</i></dt>
    <dd>Insert <i>text</i> at the end of the generated HTML text.</dd>

    <dt><code><b>--hxx-prologue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the beginning of the generated
    C++ header file.</dd>

    <dt><code><b>--ixx-prologue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the beginning of the generated
    C++ inline file.</dd>

    <dt><code><b>--cxx-prologue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the beginning of the generated
    C++ source file.</dd>

    <dt><code><b>--man-prologue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the beginning of the generated
    man page file.</dd>

    <dt><code><b>--html-prologue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the beginning of the generated
    HTML file.</dd>

    <dt><code><b>--hxx-epilogue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the end of the generated C++
    header file.</dd>

    <dt><code><b>--ixx-epilogue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the end of the generated C++
    inline file.</dd>

    <dt><code><b>--cxx-epilogue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the end of the generated C++
    source file.</dd>

    <dt><code><b>--man-epilogue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the end of the generated man page
    file.</dd>

    <dt><code><b>--html-epilogue-file</b></code> <i>file</i></dt>
    <dd>Insert the content of <i>file</i> at the end of the generated HTML
    file.</dd>

    <dt><code><b>--output-prefix</b></code> <i>prefix</i></dt>
    <dd>Add <i>prefix</i> at the beginning of the generated output file
    name(s).</dd>

    <dt><code><b>--output-suffix</b></code> <i>suffix</i></dt>
    <dd>Add <i>suffix</i> at the end of the generated output file name(s).
    Note that it is added before any file type-specific suffixes; see
    <code><b>--*-suffix</b></code> below.</dd>

    <dt><code><b>--hxx-suffix</b></code> <i>suffix</i></dt>
    <dd>Use <i>suffix</i> instead of the default <code><b>.hxx</b></code> to
    construct the name of the generated header file.</dd>

    <dt><code><b>--ixx-suffix</b></code> <i>suffix</i></dt>
    <dd>Use <i>suffix</i> instead of the default <code><b>.ixx</b></code> to
    construct the name of the generated inline file.</dd>

    <dt><code><b>--cxx-suffix</b></code> <i>suffix</i></dt>
    <dd>Use <i>suffix</i> instead of the default <code><b>.cxx</b></code> to
    construct the name of the generated source file.</dd>

    <dt><code><b>--man-suffix</b></code> <i>suffix</i></dt>
    <dd>Use <i>suffix</i> instead of the default <code><b>.1</b></code> to
    construct the name of the generated man page file.</dd>

    <dt><code><b>--html-suffix</b></code> <i>suffix</i></dt>
    <dd>Use <i>suffix</i> instead of the default <code><b>.html</b></code> to
    construct the name of the generated HTML file.</dd>

    <dt><code><b>--option-prefix</b></code> <i>prefix</i></dt>
    <dd>Use <i>prefix</i> instead of the default <code><b>-</b></code> as an
    option prefix. Unknown command line arguments that start with this prefix
    are treated as unknown options. If you set the option prefix to the empty
    value, then all the unknown command line arguments will be treated as
    program arguments.</dd>

    <dt><code><b>--option-separator</b></code> <i>sep</i></dt>
    <dd>Use <i>sep</i> instead of the default <code><b>--</b></code> as an
    optional separator between options and arguments. All the command line
    arguments that are parsed after this separator are treated as program
    arguments. Set the option separator to the empty value if you don't want
    this functionality.</dd>

    <dt><code><b>--include-with-brackets</b></code></dt>
    <dd>Use angle brackets (&lt;>) instead of quotes ("") in the generated
    <code><b>#include</b></code> directives.</dd>

    <dt><code><b>--include-prefix</b></code> <i>prefix</i></dt>
    <dd>Add <i>prefix</i> to the generated <code><b>#include</b></code>
    directive paths.</dd>

    <dt><code><b>--guard-prefix</b></code> <i>prefix</i></dt>
    <dd>Add <i>prefix</i> to the generated header inclusion guards. The prefix
    is transformed to upper case and characters that are illegal in a
    preprocessor macro name are replaced with underscores.</dd>

    <dt><code><b>--reserved-name</b></code> <i>name</i>=<i>rep</i></dt>
    <dd>Add <i>name</i> with an optional <i>rep</i> replacement to the list of
    names that should not be used as identifiers. If provided, the replacement
    name is used instead. All C++ keywords are already in this list.</dd>

    <dt><code><b>--options-file</b></code> <i>file</i></dt>
    <dd>Read additional options from <i>file</i> with each option appearing on
    a separate line optionally followed by space and an option value. Empty
    lines and lines starting with <code><b>#</b></code> are ignored. Option
    values can be enclosed in double (<code><b>"</b></code>) or single
    (<code><b>'</b></code>) quotes  to preserve leading and trailing
    whitespaces as well as to specify empty values. If the value itself
    contains trailing or leading quotes, enclose it with an extra pair of
    quotes, for example <code><b>'"x"'</b></code>. Non-leading and
    non-trailing quotes are interpreted as being part of the option value.

    <p>The semantics of providing options in a file is equivalent to providing
    the same set of options in the same order on the command line at the point
    where the <code><b>--options-file</b></code> option is specified except
    that the shell escaping and quoting is not required. Repeat this option to
    specify more than one options file.</p></dd>
  </dl>

  <h1>DIAGNOSTICS</h1>

  <p>If the input file is not a valid CLI definition, <code><b>cli</b></code>
     will issue diagnostic messages to STDERR and exit with non-zero exit
     code.</p>

  <h1>BUGS</h1>

  <p>Send bug reports to the
     <a href="mailto:cli-users@codesynthesis.com">cli-users@codesynthesis.com</a> mailing list.</p>

  </div>
  <div id="footer">
    &copy; 2009-2011 <a href="http://www.codesynthesis.com">Code Synthesis Tools CC</a>

    <div id="terms">
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the
      <a href="http://www.codesynthesis.com/licenses/mit.txt">MIT License</a>.
    </div>
  </div>
</div>
</body>
</html>