diff options
Diffstat (limited to 'cli/cli/options.cli')
-rw-r--r-- | cli/cli/options.cli | 662 |
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." + }; +}; |