// file      : cli/options.cli
// author    : Boris Kolpackov <boris@codesynthesis.com>
// copyright : Copyright (c) 2009-2011 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>;

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."
  };

  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 merging/overriding."
  };

  bool --generate-description
  {
    "Generate the option description list that can be examined at runtime."
  };

  bool --generate-file-scanner
  {
    "Generate the \c{argv_file_scanner} implementation. This scanner is
     capable of reading command line arguments from the \c{argv} array as
     well as files specified with command line options."
  };

  bool --suppress-inline
  {
    "Generate all functions non-inline. By default simple functions are
     made inline. This option suppresses creation of the inline file."
  };

  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 --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 usage printing functions
     are called \cb{print_short_usage()} and \cb{print_long_usage()} and
     for the long usage the long documentation string is always used,
     even if the short version is provided."
  };

  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 --exclude-base
  {
    "Exclude base class information from usage and documentation."
  };

  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."
  };

  bool --generate-cxx
  {
    "Generate C++ code. If neither \cb{--generate-man} nor \cb{--generate-html}
     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."
  };

  // 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."
  };

  // 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 text."
  };

  std::vector<std::string> --html-epilogue
  {
    "<text>",
    "Insert <text> at the end of the generated HTML text."
  };

  // 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."
  };

  // 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::vector<std::string> --class
  {
    "<fq-name>",
    "Generate the man page or HTML documentation only for the <fq-name> options
     class. The <fq-name> name 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."
  };

  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."
  };

  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 --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 --include-with-brackets
  {
    "Use angle brackets (<>) instead of quotes (\"\") 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> with each option appearing on a
     separate line optionally followed by space 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."
  };
};