// file      : cli/options.cli
// author    : Boris Kolpackov <boris@codesynthesis.com>
// copyright : Copyright (c) 2009-2019 Code Synthesis Tools CC
// 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 --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."
  };
};