Separate tests and examples into individual packages

Also make cli module to be explicitly enabled via the config.cli configuration
variable.

1 files changed, 0 insertions, 662 deletions

diff --git a/cli/options.cli b/cli/options.cli
deleted file mode 100644
index e564bc4..0000000
--- a/cli/options.cli
+++ /dev/null
@@ -1,662 +0,0 @@
-// 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."
-  };
-};