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
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
<!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="© 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> <code><i>dir</i></code></dt>
<dd>Search <code><i>dir</i></code> for bracket-included
(<code><b><></b></code>) options files.</dd>
<dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <code><i>dir</i></code></dt>
<dd>Write the generated files to <code><i>dir</i></code> instead of the
current directory.</dd>
<dt><code><b>--std</b></code> <code><i>version</i></code></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>--generate-vector-scanner</b></code></dt>
<dd>Generate the <code>vector_scanner</code> implementation. This scanner
is capable of reading command line arguments from
<code><b>vector<string></b></code>.</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>--suppress-cli</b></code></dt>
<dd>Do not generate the CLI support types (scanners, parser, etc).
Normally, the support types are generated unless another
<code><b>.cli</b></code> was included, in which case the support types are
expected to be provided by its generated code.</dd>
<dt><code><b>--cli-namespace</b></code> <code><i>ns</i></code></dt>
<dd>Generate the CLI support types in the <code><i>ns</i></code> 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> <code><i>type</i></code></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>,
<code><b>--generate-html</b></code>, nor
<code><b>--generate-txt</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>--generate-txt</b></code></dt>
<dd>Generate documentation in the plain text format, similar to
usage.</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> <code><i>name</i></code></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 <code><i>name</i></code> 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> <code><i>len</i></code></dt>
<dd>Indent option descriptions <code><i>len</i></code> 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(1)</b></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> <code><i>name</i></code>=<code><i>kind</i></code></dt>
<dd>Specify the documentation <code><i>kind</i></code> that should be used
for the options class <code><i>name</i></code>. The
<code><i>name</i></code> value should be a fully-qualified class name, for
example, <code><b>app::options</b></code>. The <code><i>kind</i></code>
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/text
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/text, these values
determine which documentation strings are used in the output.</dd>
<dt><code><b>--class</b></code> <code><i>name</i></code></dt>
<dd>Generate the man page, HTML, or text documentation only for the
options class <code><i>name</i></code>. The <code><i>name</i></code> 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> <code><i>name</i></code>=<code><i>val</i></code></dt>
<dd>Set documentation variable <code><i>name</i></code> to the value
<code><i>val</i></code>. 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><code><i>name</i></code><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>"\<code><i>name</i></code>=<code><i>val</i></code>"</code>
syntax.</dd>
<dt><code><b>--link-regex</b></code> <code><i>regex</i></code></dt>
<dd>Add <code><i>regex</i></code> to the list of regular expressions used
to transform link targets in the generated documentation. The argument to
this option is a Perl-like regular expression in the form
<code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any
character can be used as a delimiter instead of '<code><b>/</b></code>'
and the delimiter can be escaped inside <code><i>pattern</i></code> and
<code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
You can specify multiple regular expressions by repeating this option. All
the regular expressions are tried in the order specified and the first
expression that matches is used. Use the
<code><b>--link-regex-trace</b></code> option to debug link
transformation.</dd>
<dt><code><b>--link-regex-trace</b></code></dt>
<dd>Trace the process of applying regular expressions specified with the
<code><b>--link-regex</b></code> option. Use this option to find out why
your regular expressions don't do what you expected them to do.</dd>
<dt><code><b>--html-heading-map</b></code> <code><i>c</i></code>=<code><i>h</i></code></dt>
<dd>Map CLI heading <code><i>c</i></code> (valid values:
'<code><b>H</b></code>', '<code><b>0</b></code>', '<code><b>1</b></code>',
'<code><b>h</b></code>', and '<code><b>2</b></code>') to HTML heading
<code><i>h</i></code> (for example, '<code><b>h1</b></code>',
'<code><b>h2</b></code>', etc).</dd>
<dt><code><b>--omit-link-check</b></code></dt>
<dd>Don't check that local fragment link references (\l{#ref ...}) resolve
to ids.</dd>
<dt><code><b>--hxx-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated C++
header file.</dd>
<dt><code><b>--ixx-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated C++
inline file.</dd>
<dt><code><b>--cxx-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated C++
source file.</dd>
<dt><code><b>--man-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated man
page file.</dd>
<dt><code><b>--html-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated HTML
file.</dd>
<dt><code><b>--txt-prologue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the beginning of the generated text
file.</dd>
<dt><code><b>--hxx-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated C++ header
file.</dd>
<dt><code><b>--ixx-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated C++ inline
file.</dd>
<dt><code><b>--cxx-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated C++ source
file.</dd>
<dt><code><b>--man-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated man page
file.</dd>
<dt><code><b>--html-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated HTML
file.</dd>
<dt><code><b>--txt-epilogue</b></code> <code><i>text</i></code></dt>
<dd>Insert <code><i>text</i></code> at the end of the generated text
file.</dd>
<dt><code><b>--hxx-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated C++ header file.</dd>
<dt><code><b>--ixx-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated C++ inline file.</dd>
<dt><code><b>--cxx-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated C++ source file.</dd>
<dt><code><b>--man-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated man page file.</dd>
<dt><code><b>--html-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated HTML file.</dd>
<dt><code><b>--txt-prologue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the beginning of the
generated text file.</dd>
<dt><code><b>--hxx-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated C++ header file.</dd>
<dt><code><b>--ixx-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated C++ inline file.</dd>
<dt><code><b>--cxx-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated C++ source file.</dd>
<dt><code><b>--man-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated man page file.</dd>
<dt><code><b>--html-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated HTML file.</dd>
<dt><code><b>--txt-epilogue-file</b></code> <code><i>file</i></code></dt>
<dd>Insert the content of <code><i>file</i></code> at the end of the
generated text file.</dd>
<dt><code><b>--output-prefix</b></code> <code><i>prefix</i></code></dt>
<dd>Add <code><i>prefix</i></code> at the beginning of the generated
output file name(s).</dd>
<dt><code><b>--output-suffix</b></code> <code><i>suffix</i></code></dt>
<dd>Add <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> 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> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> instead of the default
<code><b>.html</b></code> to construct the name of the generated HTML
file.</dd>
<dt><code><b>--txt-suffix</b></code> <code><i>suffix</i></code></dt>
<dd>Use <code><i>suffix</i></code> instead of the default
<code><b>.txt</b></code> to construct the name of the generated text
file.</dd>
<dt><code><b>--option-prefix</b></code> <code><i>prefix</i></code></dt>
<dd>Use <code><i>prefix</i></code> 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> <code><i>sep</i></code></dt>
<dd>Use <code><i>sep</i></code> 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 (<code><b><></b></code>) instead of quotes
(<code><b>""</b></code>) in the generated <code><b>#include</b></code>
directives.</dd>
<dt><code><b>--include-prefix</b></code> <code><i>prefix</i></code></dt>
<dd>Add <code><i>prefix</i></code> to the generated
<code><b>#include</b></code> directive paths.</dd>
<dt><code><b>--guard-prefix</b></code> <code><i>prefix</i></code></dt>
<dd>Add <code><i>prefix</i></code> 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> <code><i>name</i></code>=<code><i>rep</i></code></dt>
<dd>Add <code><i>name</i></code> with an optional <code><i>rep</i></code>
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> <code><i>file</i></code></dt>
<dd>Read additional options from <code><i>file</i></code> 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">
© 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>
|