summaryrefslogtreecommitdiff
path: root/cli/cli/options.cli
diff options
context:
space:
mode:
Diffstat (limited to 'cli/cli/options.cli')
-rw-r--r--cli/cli/options.cli662
1 files changed, 662 insertions, 0 deletions
diff --git a/cli/cli/options.cli b/cli/cli/options.cli
new file mode 100644
index 0000000..e564bc4
--- /dev/null
+++ b/cli/cli/options.cli
@@ -0,0 +1,662 @@
+// file : cli/options.cli
+// author : Boris Kolpackov <boris@codesynthesis.com>
+// license : MIT; see accompanying LICENSE file
+
+// NOTE: Make sure you have a working CLI compiler around before
+// modifying this file.
+//
+
+include <map>;
+include <string>;
+include <vector>;
+include <cstddef>;
+
+include <cli/option-types.hxx>;
+
+class options
+{
+ bool --build2-metadata; // Leave undocumented/hidden.
+
+ bool --help {"Print usage information and exit."};
+ bool --version {"Print version and exit."};
+
+ std::vector<std::string> --include-path | -I
+ {
+ "<dir>",
+ "Search <dir> for bracket-included (\cb{<>}) options files."
+ };
+
+ std::string --output-dir | -o
+ {
+ "<dir>",
+ "Write the generated files to <dir> instead of the current directory."
+ };
+
+ cxx_version --std = cxx_version::cxx98
+ {
+ "<version>",
+ "Specify the C++ standard that should be used during compilation.
+ Valid values are \cb{c++98} (default), \cb{c++11}, and \cb{c++14}."
+ };
+
+ bool --generate-modifier
+ {
+ "Generate option value modifiers in addition to accessors."
+ };
+
+ bool --generate-specifier
+ {
+ "Generate functions for determining whether the option was specified
+ on the command line."
+ };
+
+ bool --generate-parse
+ {
+ "Generate \cb{parse()} 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 option
+ appending/overriding."
+ };
+
+ bool --generate-merge
+ {
+ "Generate \cb{merge()} functions. This is primarily useful for being able
+ to merge several already parsed options class instances, for example, to
+ implement option appending/overriding. Note that this option forces
+ \cb{--generate-specifier}."
+ };
+
+ bool --generate-description
+ {
+ "Generate the option description list that can be examined at runtime."
+ };
+
+ bool --generate-file-scanner
+ {
+ "Generate the \cb{argv_file_scanner} implementation. This scanner is
+ capable of reading command line arguments from the \cb{argv} array as
+ well as files specified with command line options."
+ };
+
+ bool --generate-vector-scanner
+ {
+ "Generate the \cb{vector_scanner} implementation. This scanner is capable
+ of reading command line arguments from \cb{vector<string>}."
+ };
+
+ bool --generate-group-scanner
+ {
+ "Generate the \cb{group_scanner} implementation. This scanner supports
+ grouping of arguments (usually options) to apply only to a certain
+ argument.
+
+ Groups can be specified before (leading) and/or after (trailing) the
+ argument they apply to. A leading group starts with '\cb{{}' and ends
+ with '\cb{\}+}' while a trailing group starts with '\cb{+{}' and ends
+ with '\cb{\}}'. For example:
+
+ \
+ { --foo --bar }+ arg # 'arg' with '--foo' '--bar'
+ arg +{ fox=1 baz=2 } # 'arg' with 'fox=1' 'baz=2'
+ \
+
+ Multiple leading and/or trailing groups can be specified for the
+ same argument. For example:
+
+ \
+ { -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'
+ \
+
+ Note that the group applies to a single argument only. For example:
+
+ \
+ { --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' and
+ # 'arg2' with '--bar'
+ \
+
+ The group separators ('\cb{{}', '\cb{\}+'}, etc) must be separate command
+ line arguments. In particular, they must not be adjacent either to the
+ arguments inside the group nor to the argument they apply to. All such
+ cases will be treated as ordinary arguments. For example:
+
+ \
+ {--foo}+ arg # '{--foo}+' ...
+ arg+{ --foo } # 'arg+{' ...
+ \
+
+ If one of the group separators needs to be specified as an argument
+ verbatim, then it must be escaped with '\cb{\\}'. For example:
+
+ \
+ } # error: unexpected group separator
+ }x # '}x'
+ \} # '}'
+ { \}+ }+ arg # 'arg' with '}+'
+ \
+ "
+ };
+
+ bool --suppress-inline
+ {
+ "Generate all functions non-inline. By default simple functions are
+ made inline. This option suppresses creation of the inline file."
+ };
+
+ bool --suppress-cli
+ {
+ "Do not generate the CLI support types (scanners, parser, etc). Normally,
+ the support types are generated unless another \cb{.cli} was included,
+ in which case the support types are expected to be provided by its
+ generated code."
+ };
+
+ std::string --cli-namespace = "::cli"
+ {
+ "<ns>",
+ "Generate the CLI support types in the <ns> namespace (\cb{cli} by
+ default). The namespace can be nested, for example \cb{details::cli}.
+ If the namespace is empty, then the support types are generated in
+ the global namespace."
+ };
+
+ std::string --ostream-type = "::std::ostream"
+ {
+ "<type>",
+ "Output stream type instead of the default \cb{std::ostream} that
+ should be used to print usage and exception information."
+ };
+
+ bool --generate-cxx
+ {
+ "Generate C++ code. If neither \cb{--generate-man}, \cb{--generate-html},
+ nor \cb{--generate-txt} is specified, this mode is assumed by default."
+ };
+
+ bool --generate-man
+ {
+ "Generate documentation in the man page format."
+ };
+
+ bool --generate-html
+ {
+ "Generate documentation in the HTML format."
+ };
+
+ bool --generate-txt
+ {
+ "Generate documentation in the plain text format, similar to usage."
+ };
+
+ bool --stdout
+ {
+ "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."
+ };
+
+ bool --suppress-undocumented
+ {
+ "Suppress the generation of documentation entries for undocumented
+ options."
+ };
+
+ bool --suppress-usage
+ {
+ "Suppress the generation of the usage printing code."
+ };
+
+ bool --long-usage
+ {
+ "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."
+ };
+
+ bool --short-usage
+ {
+ "If specified together with \cb{--long-usage}, generate both short
+ and long usage versions. In this mode, the long usage printing function
+ is called \cb{print_long_usage()} and in its implementation the long
+ documentation string is always used, even if the short version is
+ provided."
+ };
+
+ std::string --page-usage
+ {
+ "<name>",
+ "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).
+
+ The <name> 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:
+
+ \
+ --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
+ \
+
+ If both \cb{--long-usage} and \cb{--short-usage} options are specified,
+ then the long usage function has the \cb{*long_usage()} suffix."
+ };
+
+ std::size_t --option-length = 0
+ {
+ "<len>",
+ "Indent option descriptions <len> 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."
+ };
+
+ bool --ansi-color
+ {
+ "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 \cb{less(1)},
+ it will display them correctly."
+ };
+
+ bool --exclude-base
+ {
+ "Exclude base class information from usage and documentation."
+ };
+
+ bool --include-base-last
+ {
+ "Include base class information after derived for usage and documentation.
+ By default, base classes are included first."
+ };
+
+ std::map<std::string, std::string> --class-doc
+ {
+ "<name>=<kind>",
+ "Specify the documentation <kind> that should be used for the options class
+ <name>. The <name> value should be a fully-qualified class name, for
+ example, \cb{app::options}. The <kind> value can be \cb{short},
+ \cb{long}, \cb{exclude}, or \cb{exclude-base}. If the value is
+ \cb{exclude}, then the class documentation is excluded from usage and
+ man/HTML/text output. If it is \cb{exclude-base}, then it is only
+ excluded when used as a base. For usage, the \cb{short} and \cb{long}
+ values determine which usage function will be called when the class is
+ used as base or as part of the page usage (see \cb{--page-usage}). For
+ man/HTML/text, these values determine which documentation strings are
+ used in the output."
+ };
+
+ std::vector<std::string> --class
+ {
+ "<name>",
+ "Generate the man page, HTML, or text documentation only for the options
+ class <name>. The <name> value should be a fully-qualified options class
+ name, for example, \cb{app::options}. 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."
+ };
+
+ std::map<std::string, std::string> --docvar|-v
+ {
+ "<name>=<val>",
+ "Set documentation variable <name> to the value <val>. Documentation
+ variables can be substituted in prologues and epilogues (see
+ \cb{--*-prologue*} and \cb{--*-epilogue*} options) using the
+ \cb{$}<name>\cb{$} expansion syntax (use \cb{$$} to escape expansion).
+ They can also be defined in \cb{.cli} files using the
+ \c{\"\\<name>=<val>\"} syntax."
+ };
+
+ std::vector<std::string> --link-regex
+ {
+ "<regex>",
+ "Add <regex> 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
+ \c{\b{/}\i{pattern}\b{/}\i{replacement}\b{/}}. Any character can be
+ used as a delimiter instead of '\cb{/}' and the delimiter can be escaped
+ inside \ci{pattern} and \ci{replacement} with a backslash (\cb{\\}).
+ 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 \cb{--link-regex-trace}
+ option to debug link transformation."
+ };
+
+ bool --link-regex-trace
+ {
+ "Trace the process of applying regular expressions specified with the
+ \cb{--link-regex} option. Use this option to find out why your regular
+ expressions don't do what you expected them to do."
+ };
+
+ std::map<char, std::string> --html-heading-map
+ {
+ "<c>=<h>",
+ "Map CLI heading <c> (valid values: '\cb{H}', '\cb{0}', '\cb{1}',
+ '\cb{h}', and '\cb{2}') to HTML heading <h> (for example, '\cb{h1}',
+ '\cb{h2}', etc)."
+ };
+
+ bool --omit-link-check
+ {
+ "Don't check that local fragment link references (\\l{#ref ...}) resolve
+ to ids."
+ };
+
+ // Prologues.
+ //
+ std::vector<std::string> --hxx-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated C++ header file."
+ };
+
+ std::vector<std::string> --ixx-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated C++ inline file."
+ };
+
+ std::vector<std::string> --cxx-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated C++ source file."
+ };
+
+ std::vector<std::string> --man-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated man page file."
+ };
+
+ std::vector<std::string> --html-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated HTML file."
+ };
+
+ std::vector<std::string> --txt-prologue
+ {
+ "<text>",
+ "Insert <text> at the beginning of the generated text file."
+ };
+
+ // Epilogues.
+ //
+ std::vector<std::string> --hxx-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated C++ header file."
+ };
+
+ std::vector<std::string> --ixx-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated C++ inline file."
+ };
+
+ std::vector<std::string> --cxx-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated C++ source file."
+ };
+
+ std::vector<std::string> --man-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated man page file."
+ };
+
+ std::vector<std::string> --html-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated HTML file."
+ };
+
+ std::vector<std::string> --txt-epilogue
+ {
+ "<text>",
+ "Insert <text> at the end of the generated text file."
+ };
+
+ // Prologue files.
+ //
+ std::string --hxx-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated C++
+ header file."
+ };
+
+ std::string --ixx-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated C++
+ inline file."
+ };
+
+ std::string --cxx-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated C++
+ source file."
+ };
+
+ std::string --man-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated man
+ page file."
+ };
+
+ std::string --html-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated HTML
+ file."
+ };
+
+ std::string --txt-prologue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the beginning of the generated text
+ file."
+ };
+
+ // Epilogue files.
+ //
+ std::string --hxx-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated C++ header
+ file."
+ };
+
+ std::string --ixx-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated C++ inline
+ file."
+ };
+
+ std::string --cxx-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated C++ source
+ file."
+ };
+
+ std::string --man-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated man page file."
+ };
+
+ std::string --html-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated HTML file."
+ };
+
+ std::string --txt-epilogue-file
+ {
+ "<file>",
+ "Insert the content of <file> at the end of the generated text file."
+ };
+
+ // Output.
+ //
+ std::string --output-prefix
+ {
+ "<prefix>",
+ "Add <prefix> at the beginning of the generated output file name(s)."
+ };
+
+ std::string --output-suffix
+ {
+ "<suffix>",
+ "Add <suffix> at the end of the generated output file name(s). Note that
+ it is added before any file type-specific suffixes; see \cb{--*-suffix}
+ below."
+ };
+
+ std::string --hxx-suffix = ".hxx"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.hxx} to construct the name of
+ the generated header file."
+ };
+
+ std::string --ixx-suffix = ".ixx"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.ixx} to construct the name of
+ the generated inline file."
+ };
+
+ std::string --cxx-suffix = ".cxx"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.cxx} to construct the name of
+ the generated source file."
+ };
+
+ std::string --man-suffix = ".1"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.1} to construct the name of
+ the generated man page file."
+ };
+
+ std::string --html-suffix = ".html"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.html} to construct the name
+ of the generated HTML file."
+ };
+
+ std::string --txt-suffix = ".txt"
+ {
+ "<suffix>",
+ "Use <suffix> instead of the default \cb{.txt} to construct the name of
+ the generated text file."
+ };
+
+ std::string --option-prefix = "-"
+ {
+ "<prefix>",
+ "Use <prefix> instead of the default '\cb{-}' 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."
+ };
+
+ std::string --option-separator = "--"
+ {
+ "<sep>",
+ "Use <sep> instead of the default '\cb{--}' 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."
+ };
+
+ bool --keep-separator
+ {
+ "Leave the option separator in the scanner. This is primarily useful for
+ incremental option parsing."
+ };
+
+ bool --no-combined-flags
+ {
+ "Disable support for combining multiple single-character flags into a
+ single argument (the \cb{-xyz} form that is equivalent to \cb{-x} \cb{-y}
+ \cb{-z}). An argument is considered a combination of flags if it starts
+ with a single option prefix (\cb{--option-prefix}) and only contains
+ letters and digits. Note that an option with a value may not be part of
+ such a combination, not even if it is specified last."
+ }
+
+ bool --no-combined-values
+ {
+ "Disable support for combining an option and its value into a single
+ argument with the assignment sign (the \c{\i{option}\b{=}\i{value}}
+ form). This functionality requires a non-empty option prefix
+ (\cb{--option-prefix})."
+ }
+
+ bool --include-with-brackets
+ {
+ "Use angle brackets (\cb{<>}) instead of quotes (\cb{\"\"}) in the
+ generated \cb{#include} directives."
+ };
+
+ std::string --include-prefix
+ {
+ "<prefix>",
+ "Add <prefix> to the generated \cb{#include} directive paths."
+ };
+
+ std::string --guard-prefix
+ {
+ "<prefix>",
+ "Add <prefix> 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."
+ };
+
+ std::map<std::string, std::string> --reserved-name
+ {
+ "<name>=<rep>",
+ "Add <name> with an optional <rep> 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."
+ };
+
+ // This is a "fake" option in that it is actually handled by
+ // argv_file_scanner. We have it here to get the documentation.
+ //
+ std::string --options-file
+ {
+ "<file>",
+ "Read additional options from <file>. Each option should appear on a
+ separate line optionally followed by space or equal sign (\cb{=}) and an
+ option value. Empty lines and lines starting with \cb{#} are ignored.
+ Option values can be enclosed in double (\cb{\"}) or single (\cb{'})
+ 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 \cb{'\"x\"'}.
+ Non-leading and non-trailing quotes are interpreted as being part of the
+ option value.
+
+ 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 \cb{--options-file} option is specified except that
+ the shell escaping and quoting is not required. Repeat this option
+ to specify more than one options file."
+ };
+};
generated by cgit v1.1 at 2024-04-25 03:41:33 +0000