fcppt.options

Description

Library for command-line options.

Link to ${fcppt_options_TARGET}, or to fcppt_options_interface if you only need the headers.

Introduction A simple example Parser types A more complex example Commands Help option Hiding parser implementation Implementation

Introduction

Passing arguments to a program is done via the main function, int main(int argc, char **argv), where argc is the number of arguments and argv points to the arguments themselves. The first argument, argv[0], is usually the name of the program, but does not have to be. Now, consider a program that expects a single integer argument: It first has to check if argc is 2 and if so, it has to convert argv[1] into an integer. If any of these two steps fails, it should also print an appropriate error message and exit. Handling arguments this way quickly gets out of hand. For example, we might have to deal with optional arguments, flags or arbitrary many arguments.

fcppt.options features declarative parsers. Instead of writing parsing code by hand, we only write down the arguments and their types that our program excepts. A parser (if it succeeds) produces an fcppt::record::object. For example, a parser that expects a single integer with label name age has type { age : int }. Parsers can be combined to yield more complicated parsers, so for example a parser that expects zero or more strings with label name first_names has type { first_names : std::vector<std::string> }. Combining these two parsers yields a parser of type { age : int, first_names : std::vector<std::string> }.

A simple example

To start off, let us look at a simple example, where we expect a single argument of type int. First, we declare the label to be used in the parser type:

  FCPPT_RECORD_MAKE_LABEL(age_label);

Next, we declare the parser type that uses age_label to produce a single value of type int.

  using parser_type = fcppt::options::argument<age_label, int>;
 
  using result_type = fcppt::options::result_of<parser_type>;

Such a parser parses a command-line like ./program 123, yielding the record { age_label = 123 }, which is of type result_type = { age_label : int }. Next, we define the actual parser:

  parser_type const parser{
      fcppt::options::long_name{FCPPT_TEXT("age")},
      fcppt::options::optional_help_text{fcppt::options::help_text{FCPPT_TEXT("Your age")}}};

Here, we see that an fcppt::options::argument gets two parameters:

• The long name which is used as a placeholder in help messages and
• a text called help_text which can be used to explain the argument's purpose to the user.

Instead of using argc and argv directly, we first use the helper function fcppt::args_from_second which copies every argument except the first (which usually holds the program's name but does not have to) into a container:

  fcppt::args_vector const args{fcppt::args_from_second(argc, argv)};

Parsing the arguments using a parser is done by calling the fcppt::options::parse function. Its result is an fcppt::options::result which is an fcppt::either::object that encapsulates the fact that a parser can fail.

  fcppt::options::result<result_type> const result{fcppt::options::parse(parser, args)};

Now, all that needs to be done is to inspect result: First, we define a function called on_success that receives result_type (remember, this is a record of type { age_label : int }) and prints it.

  auto const on_success([](result_type const &_result) {
    fcppt::io::cout() << FCPPT_TEXT("Your age is ") << fcppt::record::get<age_label>(_result)
                      << FCPPT_TEXT('\n');
 
    return EXIT_SUCCESS;
  });

In case of failure we get an fcppt::options::error, telling the user what went wrong. In addition to that, we also print parser.usage() which tells the user what the expected format is:

  auto const on_failure([&parser](fcppt::options::error const &_error) {
    fcppt::io::cerr() << _error << FCPPT_TEXT('\n') << FCPPT_TEXT("Usage: ") << parser.usage()
                      << FCPPT_TEXT('\n');
 
    return EXIT_FAILURE;
  });

Finally, we use fcppt::either::match to call one of these functions:

  return fcppt::either::match(result, on_failure, on_success);

Here are a few example invocations:

./fcppt_example_options_simple
Missing argument "age".
Usage: age : int - Your age

./fcppt_example_options_simple 10 20
Too many arguments: 20.
Usage: age : int - Your age

./fcppt_example_options_simple test
Failed to convert "test" to int for argument "age".
Usage: age : int - Your age

./fcppt_example_options_simple 42
Your age is 42

Parser types

Parser types are split into basic and combinator parsers.

Basic parser types

There are three different types of basic parsers:

Type:	Description:
fcppt::options::argument	Parses a single argument, e.g. "arg". If there is no argument or it cannot be converted to the parser's result type, an error occurs.
fcppt::options::flag	Parses a flag, e.g. "-f" or "--flag". Depending on whether the flag was specified or not, the result type is either its inactive value or its active value. Flags never produce an error. fcppt::options::switch_ is a short-hand for a flag of type bool.
fcppt::options::option	Parses an option, e.g. "-o val" or "--opt val". Option parsers can have an optional default value which is used in case the option has not been specified. If there is no such option and no default value has been specified or the option's value cannot be converted to the parser's result type, an error occurs.
fcppt::options::unit	A parser that parses nothing. This is useful, for example, when you want a sub-command that takes no arguments or options.
fcppt::options::unit_switch	A flag that always has to be specified (e.g. if you want to parse "--help").

Combinator parser types

The following parsers can be used to create more advanced parsers:

Type:	Description:
fcppt::options::product	A parser of type fcppt::options::product<Left,Right> combines two parsers of type Left and Right, which must have disjoint records. The product parser first tries the left parser and then the right parser. It only succeeds if both succeed. Its result type is the disjoint union (see fcppt::record::multiply_disjoint) of Left's and Right's result types. To combine two or more parsers at once, use fcppt::options::apply.
fcppt::options::sum	A parser of type fcppt::options::sum<Label,Left,Right> first tries Left and if that fails tries Right. It returns the result of the first one that succeeded or an error if both fail. Its result type is a record with a single element with label Label. The type of this element is an fcppt::variant::object of fcppt::options::left<LeftResult> and fcppt::options::right<RightResult>, where LeftResult is the result type of Left and RightResult is the result type of Right.
fcppt::options::optional	A parser of type fcppt::options::optional<Parser> turns a parser of type Parser into a parser that may fail. Its result type has the same labels as Parser's result type, but with an extra fcppt::optional::object layer added on top. See fcppt::options::make_optional.
fcppt::options::many	A parser of type fcppt::options::many<Parser> turns a parser of type Parser into a parser that parsers zero or more occurrences. Its result type has the same labels as Parser's result type, but with an extra std::vector layer added on top. See fcppt::options::make_many.
fcppt::options::commands	A commands parser combines several sub-commands into a single parser. It gets a parser that parses options common to all sub-commands and for each sub-command, it gets a parser plus the name of the sub-command. For parsers O,S_1,...,S_n (n >= 1), a parser of type fcppt::options::commands<O,S_1,...,S_n> gets a list of sub-command names C_1,...,C_n in its constructor, passed as fcppt::options::sub_command<S_1>,...,fcppt::options::sub_command<S_n>. Here, O is the common options parser and S_1,...,S_n are the sub-parsers. Its result is a record with the result of O with label name fcppt::options::options_label and a variant of the result types of S_1,...,S_n with label name fcppt::options::sub_command_label. See fcppt::options::make_sub_command and fcppt::options::make_commands. Warning A commands parser looks for the first argument (i.e. a parameter that is not a flag or an option) which it uses as the name of the sub-command. Therefore, you should not include anything other than flags or options in O.

Passing a parser to another can be done in three different ways:

• By moving. In this case, the parser must be an rvalue. Use fcppt::copy to create an explicit copy if needed.
• By reference. Use fcppt::make_cref in this case. Be careful to keep all parsers alive that are passed this way.
• By moving an fcppt::unique_ptr. This is useful if you want to pass an fcppt::options::base_unique_ptr.

A more complex example

Imagine a program that copies an input file to an output file, with the following requirements:

• The input filename always needs to be specified.
• The output filename is optional. If it is not specified, it defaults to the name of the input file plus ".bak".
• The program should by default be in pretend mode in which it does nothing. Actually executing the copy operation requires to specify a flag.
• It should have the ability to append to the result file instead of overwriting it. The append behavior will be activated using a flag.
• It uses a log framework to output certain messages during its run. The log level, which dictates which log messages get printed, should be an optional option to the program. If it is not specified, a default log level is used.

We first start by declaring the labels the parsers are going to use:

  FCPPT_RECORD_MAKE_LABEL(input_file_label);
  FCPPT_RECORD_MAKE_LABEL(output_file_label);
  FCPPT_RECORD_MAKE_LABEL(execute_label);
  FCPPT_RECORD_MAKE_LABEL(openmode_label);
  FCPPT_RECORD_MAKE_LABEL(log_level_label);

The input filename is an argument parser of type fcppt::string.

  using input_file_option = fcppt::options::argument<input_file_label, fcppt::string>;
 
  input_file_option const input_file{
      fcppt::options::long_name{FCPPT_TEXT("Input filename")},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("The name of the input file to copy")}}};

The output filename is an optional argument parser. Its type is fcppt::optional::object<fcppt::string>.

  using output_file_option = fcppt::options::argument<output_file_label, fcppt::string>;
 
  using optional_output_file_option = fcppt::options::optional<output_file_option>;
 
  optional_output_file_option const output_file{fcppt::options::make_optional(output_file_option{
      fcppt::options::long_name{FCPPT_TEXT("Output filename")},
      fcppt::options::optional_help_text{fcppt::options::help_text{
          FCPPT_TEXT("The name of the output file. Defaults to input_file.bak")}}})};

The execute flag is just a switch. It can be activated using "-e" or "--execute".

  using execute_switch = fcppt::options::switch_<execute_label>;
 
  execute_switch const execute{
      fcppt::options::optional_short_name{fcppt::options::short_name{FCPPT_TEXT("e")}},
      fcppt::options::long_name{FCPPT_TEXT("execute")},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("Whether to actually execute the actions")}}};

To handle whether to append to the output file, we use a flag parser of type std::ios_base::openmode. Its inactive value is the empty openmode, while its active value is std::ios_base::trunc.

  using openmode_option = fcppt::options::flag<openmode_label, std::ios_base::openmode>;
 
  openmode_option const openmode{
      fcppt::options::optional_short_name{},
      fcppt::options::long_name{FCPPT_TEXT("trunc")},
      openmode_option::active_value{std::ios_base::trunc},
      openmode_option::inactive_value{std::ios_base::openmode{}},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("Whether to truncate the output file")}}};

The log level is an option parser of type fcppt::log::level. It can be set using "-l level" or "--loglevel level", where level has to be one of fcppt::log::level's values. The parser also gets a default value of fcppt::log::level::warning.

  using log_level_option = fcppt::options::option<log_level_label, fcppt::log::level>;
 
  log_level_option const log_level{
      fcppt::options::optional_short_name{fcppt::options::short_name{FCPPT_TEXT("l")}},
      fcppt::options::long_name{FCPPT_TEXT("loglevel")},
      log_level_option::optional_default_value{fcppt::optional::make(fcppt::log::level::warning)},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("The log level to use")}}};

Finally, the actual parser is created using fcppt::options::apply. Its type is complicated, so it is shortened using auto here. See Hiding parser implementation on how to hide a parser's actual type.

  auto const parser(fcppt::options::apply(
      fcppt::make_cref(input_file),
      fcppt::make_cref(output_file),
      fcppt::make_cref(execute),
      fcppt::make_cref(openmode),
      fcppt::make_cref(log_level)));

We also check what the result type of the parser is to make sure we did not miss anything.

  using result_type = fcppt::options::result_of<decltype(parser)>;
 
  static_assert(
      fcppt::record::are_equivalent_v<
          result_type,
          fcppt::record::object<
              fcppt::record::element<input_file_label, fcppt::string>,
              fcppt::record::element<output_file_label, fcppt::optional::object<fcppt::string>>,
              fcppt::record::element<execute_label, bool>,
              fcppt::record::element<openmode_label, std::ios_base::openmode>,
              fcppt::record::element<log_level_label, fcppt::log::level>>>);

The main program is a lambda function that gets result_type as its parameter. This is a record that contains all the options of the parsers combined.

  auto const main_program([](result_type const &_result) -> bool {

First, we check if the execute flag has been specified. If not, the executing stops.

    if (!fcppt::record::get<execute_label>(_result))
    {
      return false;
    }

Next, we create a log context that uses the log-level specified. Notice how the string specified on the command-line has already been converted to a value of fcppt::log::level.

    fcppt::log::context log_context{
        fcppt::log::optional_level{fcppt::record::get<log_level_label>(_result)},
        fcppt::log::default_level_streams()};

We then open the input file using the input filename.

    fcppt::filesystem::ifstream const input{fcppt::filesystem::open_exn<fcppt::filesystem::ifstream>(
        fcppt::record::get<input_file_label>(_result),
        std::ios_base::openmode{})};

Opening the output file consists of two things: First, we need to check whether the output filename has been specified. If not, we use the default of input_file.bak.

    fcppt::string const output_filename{
        fcppt::optional::from(fcppt::record::get<output_file_label>(_result), [&_result] {
          return fcppt::record::get<input_file_label>(_result) + FCPPT_TEXT(".bak");
        })};

Secondly, the openmode needs to be passed as well.

    fcppt::filesystem::ofstream const output{fcppt::filesystem::open_exn<fcppt::filesystem::ofstream>(
        output_filename,
        fcppt::record::get<openmode_label>(_result))};

Here is the output of the parser's usage:

Input filename : string - The name of the input file to copy
[ Output filename : string - The name of the output file. Defaults to input_file.bak ]
[ --execute|-e ] - Whether to actually execute the actions
[ --trunc ] - Whether to truncate the output file
[ --loglevel|-l : [verbose,debug,info,warning,error,fatal] / warning ] - The log level to use

Commands

Instead of creating one program per command, it is useful to combine several commands into a single parser, where the sub-command is chosen by a specific name. Examples of this are found in several programs, namely git. For example, git clone and git pull are different commands that take different arguments and options themselves. However, the git program itself can also take options common to all sub-commands, for example "--git-dir" which specifies the directory of the repository. In fcppt, this is handled by fcppt::options::commands. First, we declare the parser for the common options:

  FCPPT_RECORD_MAKE_LABEL(git_directory);
 
  auto const options_parser{
      fcppt::options::make_optional(fcppt::options::option<git_directory, fcppt::string>{
          fcppt::options::optional_short_name{},
          fcppt::options::long_name{FCPPT_TEXT("git-dir")},
          fcppt::options::no_default_value<fcppt::string>(),
          fcppt::options::optional_help_text{
              fcppt::options::help_text{FCPPT_TEXT("The path to the repository")}}})};

This parser can optionally take a "--git-dir" option.

Then, we declare two parsers, one for each sub-command. We want the clone command to take exactly one argument, which is the path to clone from. The pull command, on the other hand, should take no arguments, for which we make use of the unit parser.

  FCPPT_RECORD_MAKE_LABEL(clone_path);
 
  auto const clone_parser{fcppt::options::argument<clone_path, fcppt::string>(
      fcppt::options::long_name{FCPPT_TEXT("path")},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("The path to clone from")}})};
 
  FCPPT_RECORD_MAKE_LABEL(pull_unit);
 
  auto const pull_parser{fcppt::options::unit<pull_unit>{}};

Next, we turn each of the parsers into a sub-command, giving it a name, a label and an optional help text. The label is important to make the types of the sub-commands disjoint.

  FCPPT_RECORD_MAKE_LABEL(clone_label);
 
  auto const clone_command{fcppt::options::make_sub_command<clone_label>(
      FCPPT_TEXT("clone"),
      fcppt::make_cref(clone_parser),
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("Clone from another repository")}})};
 
  FCPPT_RECORD_MAKE_LABEL(pull_label);
 
  auto const pull_command{fcppt::options::make_sub_command<pull_label>(
      FCPPT_TEXT("pull"),
      fcppt::make_cref(pull_parser),
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("Pull all changes")}})};

Finally, we combine everything into a commands parser.

  auto const commands{fcppt::options::make_commands(
      fcppt::make_cref(options_parser),
      fcppt::make_cref(clone_command),
      fcppt::make_cref(pull_command))};

Here is an example showing how to use the parser's result. We first check if the optional git directory has been specified.

  auto const on_success([](fcppt::options::result_of<decltype(commands)> const &_result) {
    fcppt::optional::maybe_void(
        fcppt::record::get<git_directory>(
            fcppt::record::get<fcppt::options::options_label>(_result)),
        [](fcppt::string const &_dir) {
          fcppt::io::cout() << FCPPT_TEXT("Git directory is ") << _dir << FCPPT_TEXT('\n');
        });

We then match on the two different sub-commands.

    fcppt::variant::match(
        fcppt::record::get<fcppt::options::sub_command_label>(_result),
        [](fcppt::options::result_of<decltype(clone_command)> const &_clone) {
          fcppt::io::cout() << FCPPT_TEXT("Clone from ")
                            << fcppt::record::get<clone_path>(
                                   fcppt::record::get<clone_label>(_clone))
                            << FCPPT_TEXT('\n');
        },
        [](fcppt::options::result_of<decltype(pull_command)> const &) {
          fcppt::io::cout() << FCPPT_TEXT("pull\n");
        });
  });

The main program prints the parser's usage in case of an error.

  fcppt::either::match(
      fcppt::options::parse(commands, fcppt::args_from_second(argc, argv)),
      [&commands](fcppt::options::error const &_error) {
        fcppt::io::cerr() << _error << FCPPT_TEXT("\nUsage:\n") << commands.usage()
                          << FCPPT_TEXT("\n");
      },
      on_success);

Here are some example invocations:

./fcppt_example_options_commands
No command specified from [clone, pull]
Usage:
[ --git-dir : string - The path to the repository ]
  clone:  (Clone from another repository)
    path : string - The path to clone from
  pull:  (Pull all changes)

./fcppt_example_options_commands bar
Invalid command bar
Usage:
[ --git-dir : string - The path to the repository ]
  clone:  (Clone from another repository)
    path : string - The path to clone from
  pull:  (Pull all changes)

./fcppt_example_options_commands clone
Missing argument "path".
Usage:
[ --git-dir : string - The path to the repository ]
  clone:  (Clone from another repository)
    path : string - The path to clone from
  pull:  (Pull all changes)

./fcppt_example_options_commands clone dir
Clone from dir

./fcppt_example_options_commands --git-dir x clone dir
Git directory is x
Clone from dir

./fcppt_example_options_commands pull
pull

Help option

A help option is a special flag like "--help". If specified, the program should print its help text and not accept any other arguments. This layering of two parsers is implemented by fcppt::options::parse_help. It gets a parser of type fcppt::options::help_switch as its first argument, and a regular parser as its second argument. fcppt::options::default_help_switch is a switch that accepts "--help":

  fcppt::options::help_result<fcppt::options::result_of<parser_type>> const result{
      fcppt::options::parse_help(
          fcppt::options::default_help_switch(), parser, fcppt::args_from_second(argc, argv))};

If the help switch matches, the function returns an fcppt::options::usage, otherwise it returns a regular fcppt::options::result.

  fcppt::variant::match(
      result,
      [](fcppt::options::result<fcppt::options::result_of<parser_type>> const &_result) {
        fcppt::io::cout() << _result << FCPPT_TEXT('\n');
      },
      [](fcppt::options::usage const &_usage) {
        fcppt::io::cout() << _usage << FCPPT_TEXT('\n');
      });

In this example, parser is a simple parser that parses an int:

  FCPPT_RECORD_MAKE_LABEL(arg_label);
 
  using parser_type = fcppt::options::argument<arg_label, int>;
 
  parser_type const parser{
      fcppt::options::long_name{FCPPT_TEXT("arg1")},
      fcppt::options::optional_help_text{
          fcppt::options::help_text{FCPPT_TEXT("The main argument")}}};

Here are a few example invocations:

./fcppt_example_options_help
  Missing flag --help.
|
  Missing argument "arg1".

./fcppt_example_options_help --help
arg1 : int - The main argument

Hiding parser implementation

As seen in A more complex example, the type of a parser can get very complex, because it carries the exact types of all the parsers used to build it. In order to hide this, the base class fcppt::options::base can be used. Its only type parameter is the parser's result type, which means that we need to know the result type in advance. In the following example, we are going to expect a parser that returns an int and a bool:

  FCPPT_RECORD_MAKE_LABEL(int_arg_label);
  FCPPT_RECORD_MAKE_LABEL(switch_label);
 
  using result_type = fcppt::record::object<
      fcppt::record::element<int_arg_label, int>,
      fcppt::record::element<switch_label, bool>>;

Next, we define a function that creates such a parser. In a real program, this can be hidden away inside another translation unit:

  auto const create_base([]() -> fcppt::options::base_unique_ptr<result_type> {
    return fcppt::options::make_base<result_type>(fcppt::options::apply(
        fcppt::options::argument<int_arg_label, int>{
            fcppt::options::long_name{FCPPT_TEXT("arg")}, fcppt::options::optional_help_text{}},
        fcppt::options::switch_<switch_label>{
            fcppt::options::optional_short_name{},
            fcppt::options::long_name{FCPPT_TEXT("switch")},
            fcppt::options::optional_help_text{}}));
  });

The parser can then be used like any other parser:

  fcppt::options::base_unique_ptr<result_type> const base{create_base()};
 
  fcppt::options::result<result_type> const result{
      fcppt::options::parse(*base, fcppt::args_from_second(argc, argv))};

It is also possible to use such an fcppt::options::base_unique_ptr as an argument to another parser:

  auto const combined{fcppt::options::make_many(create_base())};

Implementation

The implementation of a parser consists of the following functions and types:

Type/Function:	Description
result_type	The type returned by a successful parse.
fcppt::options::flag_name_set flag_names() const	A set of flag names (parameters without an argument) this parser recognizes.
fcppt::options::option_name_set option_names() const	A set of option names (parameters with an argument) this parser recognizes.
fcppt::options::usage usage() const	A description on how to use this parser.
fcppt::options::parse_result<result_type> parse(fcppt::options::state &&, fcppt::options::parse_context const &) const	This is the main parsing function. An fcppt::options::state contains the current command-line and an fcppt::options::parse_context contains information about the surrounding parsers. An fcppt::options::parse_result contains either an error or a result together with the remaining state.

The function fcppt::options::deref dereferences a parser, which currently can be a copy, an fcppt::reference or an fcppt::unique_ptr. This is used internally by a parser to access its sub-parsers.

Classes
struct	fcppt::options::active_value_tag
	The tag of strong typedefs for active values. More...
class	fcppt::options::argument_conversion_error
class	fcppt::options::argument< Label, Type >
	An argument parser. More...
class	fcppt::options::argument_usage
class	fcppt::options::base< Result >
	The base class for parsers with a given result type. More...
class	fcppt::options::commands< OptionsParser, SubParsers >
	A parser for multiple sub commands. More...
class	fcppt::options::commands_usage
struct	fcppt::options::default_value_tag
	The tag of strong typedefs for default values. More...
class	fcppt::options::dual_flag_error
class	fcppt::options::dual_option_error
class	fcppt::options::error
	The error type retuned. More...
class	fcppt::options::flag< Label, Type >
	A flag parser. More...
class	fcppt::options::flag_usage
struct	fcppt::options::inactive_value_tag
	The tag of strong typedefs for inactive values. More...
class	fcppt::options::invalid_command_error
class	fcppt::options::leftover_error
class	fcppt::options::many< Parser >
	A parser for zero or more elements. More...
class	fcppt::options::many_usage
class	fcppt::options::missing_argument_error
class	fcppt::options::missing_command_error
class	fcppt::options::missing_error
	Occurs if an argument/flag/option is missing. More...
class	fcppt::options::missing_flag_error
class	fcppt::options::missing_option_argument_error
class	fcppt::options::missing_option_error
class	fcppt::options::option_conversion_error
class	fcppt::options::option< Label, Type >
	An option parser. More...
class	fcppt::options::option_name
	An option name that may be for a short or long option. More...
class	fcppt::options::option_usage
class	fcppt::options::optional< Parser >
	An optional parser. More...
class	fcppt::options::optional_usage
class	fcppt::options::product< Left, Right >
	A product of two parsers. More...
class	fcppt::options::product_usage
class	fcppt::options::state
	A parse state. More...
class	fcppt::options::state_with_value< T >
	A parse state together with a value. More...
class	fcppt::options::sub_command< Tag, Parser >
	A sub command consists of a command name and a parser. More...
class	fcppt::options::sub_command_usage
class	fcppt::options::sum< Label, Left, Right >
	A sum of two parsers. More...
class	fcppt::options::sum_usage
class	fcppt::options::switch_< Label >
	A switch parser. More...
class	fcppt::options::unit< Label >
	A parser that succeeds when provided with no arguments. More...
class	fcppt::options::unit_switch< Label >
	A required switch. More...
class	fcppt::options::unit_usage
class	fcppt::options::usage
	The usage type of a parser.This shows to a user how a parser is supposed to be used. More...

Typedefs
template<typename Type >
using	fcppt::options::active_value = fcppt::strong_typedef<Type, fcppt::options::active_value_tag>
	A strong typedef used as a parser's active value.
template<typename Result >
using	fcppt::options::base_unique_ptr = fcppt::unique_ptr<fcppt::options::base<Result>>
	A unique pointer for fcppt::options::base.
template<typename Type >
using	fcppt::options::default_value = fcppt::strong_typedef<Type, fcppt::options::default_value_tag>
	A strong typedef used as a parser's default value.
template<typename Parser >
using	fcppt::options::deref_type = std::remove_cvref_t<fcppt::deref_type<Parser>>
	The dereferenced type of a parser.
using	fcppt::options::error_variant
using	fcppt::options::flag_name_set = std::set<fcppt::options::flag_name>
	The set of flag names.
template<typename Result >
using	fcppt::options::help_result
	The result of invoking a regular parser and a help parser.
using	fcppt::options::help_switch = fcppt::options::unit_switch<fcppt::options::detail::help_label>
	The type of a help parser.
using	fcppt::options::help_text = fcppt::strong_typedef< fcppt::string ,_>
	A string type representing a help text.
template<typename Type >
using	fcppt::options::inactive_value = fcppt::strong_typedef<Type, fcppt::options::inactive_value_tag>
	A strong typedef used as a parser's inactive value.
template<typename Type >
using	fcppt::options::left = fcppt::strong_typedef<Type, fcppt::options::detail::left_tag>
	The left result type of a sum parser.
using	fcppt::options::long_name = fcppt::strong_typedef< fcppt::string ,_>
	A string type representing a long name.
using	fcppt::options::name = fcppt::strong_typedef< fcppt::string ,_>
using	fcppt::options::option_name_set = std::set<fcppt::options::option_name>
	The set of option names.
using	fcppt::options::optional_help_text = fcppt::optional::object<fcppt::options::help_text>
	An optional help text.
using	fcppt::options::optional_short_name = fcppt::optional::object<fcppt::options::short_name>
	An optional short name.
using	fcppt::options::parse_error = fcppt::variant::object<fcppt::options::missing_error, fcppt::options::error>
	The error type returned by parsers.
template<typename T >
using	fcppt::options::parse_result
	The result of a parser.
template<typename T >
using	fcppt::options::result = fcppt::either::object<fcppt::options::error, T>
	The result of a parse operation.
template<typename Parser >
using	fcppt::options::result_of = typename fcppt::options::deref_type<Parser>::result_type
	The result of a parser type.
template<typename Type >
using	fcppt::options::right = fcppt::strong_typedef<Type, fcppt::options::detail::right_tag>
	The right result type of a sum parser.
using	fcppt::options::short_name = fcppt::strong_typedef< fcppt::string ,_>
	A string type representing a short name.
using	fcppt::options::usage_variant

Functions
template<typename... Parsers>
auto	fcppt::options::apply (Parsers &&..._parsers)
	Combines two or more parsers.
FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::options::help_switch	fcppt::options::default_help_switch ()
	The default help switch.
template<typename Parser >
decltype(auto)	fcppt::options::deref (Parser const &_parser)
	Dereferences a parser.
FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::io::ostream &	fcppt::options::operator<< (fcppt::io::ostream &, fcppt::options::error const &)
template<typename Type >
fcppt::options::active_value< std::remove_cvref_t< Type > >	fcppt::options::make_active_value (Type &&_value)
	Creates an active value.
template<typename Result , typename Parser >
fcppt::options::base_unique_ptr< Result >	fcppt::options::make_base (Parser &&_parser)
	Creates an fcppt::options::base.
template<typename OptionsParser , typename... SubCommands>
fcppt::options::commands< std::remove_cvref_t< OptionsParser >, std::remove_cvref_t< SubCommands >... >	fcppt::options::make_commands (OptionsParser &&_options_parser, SubCommands &&..._sub_commands)
	Makes a commands parser.
template<typename Type >
fcppt::options::default_value< std::remove_cvref_t< Type > >	fcppt::options::make_default_value (Type &&_value)
	Creates a default value.
template<typename Type >
fcppt::options::inactive_value< std::remove_cvref_t< Type > >	fcppt::options::make_inactive_value (Type &&_value)
	Creates an inactive value.
template<typename Type >
fcppt::options::left< std::remove_cvref_t< Type > >	fcppt::options::make_left (Type &&_value)
	Creates an fcppt::options::left.
template<typename Parser >
fcppt::options::many< std::remove_cvref_t< Parser > >	fcppt::options::make_many (Parser &&_parser)
	Turns a parser into a many parser.
template<typename Parser >
fcppt::options::optional< std::remove_cvref_t< Parser > >	fcppt::options::make_optional (Parser &&_parser)
	Turns a parser into an optional parser.
template<typename Type >
fcppt::options::right< std::remove_cvref_t< Type > >	fcppt::options::make_right (Type &&_value)
	Creates an fcppt::options::right.
template<typename Tag , typename Parser >
fcppt::options::sub_command< Tag, std::remove_cvref_t< Parser > >	fcppt::options::make_sub_command (fcppt::string &&_name, Parser &&_parser, fcppt::options::optional_help_text &&_help_text)
	Makes a sub command.
template<typename Type >
fcppt::options::result< std::remove_cvref_t< Type > >	fcppt::options::make_success (Type &&_value)
	Creates a success value.
template<typename Label , typename Left , typename Right >
fcppt::options::sum< Label, std::remove_cvref_t< Left >, std::remove_cvref_t< Right > >	fcppt::options::make_sum (Left &&_left, Right &&_right)
	Creates the sum of two parsers.
template<typename Type >
fcppt::options::default_value< fcppt::optional::object< Type > >	fcppt::options::no_default_value ()
	Creates an empty default value.
	fcppt::options::FCPPT_RECORD_MAKE_LABEL (options_label)
	The options label name in fcppt::options::commands.
template<typename Parser >
fcppt::options::result< fcppt::options::result_of< Parser > >	fcppt::options::parse (Parser const &_parser, fcppt::args_vector const &_args)
	Parse a command-line.
template<typename Parser >
fcppt::options::help_result< fcppt::options::result_of< Parser > >	fcppt::options::parse_help (fcppt::options::help_switch const &_help, Parser const &_parser, fcppt::args_vector const &_args)
	Parse a command-line with a help parser.
template<typename Type >
fcppt::options::type_name	fcppt::options::pretty_type ()
	Returns a pretty type used for help texts.
	fcppt::options::FCPPT_RECORD_MAKE_LABEL (sub_command_label)
	The sub-command label name in fcppt::options::commands.
FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::io::ostream &	fcppt::options::operator<< (fcppt::io::ostream &, fcppt::options::usage const &)

Typedef Documentation

active_value

template<typename Type >

using fcppt::options::active_value = fcppt::strong_typedef<Type, fcppt::options::active_value_tag>

A strong typedef used as a parser's active value.

base_unique_ptr

template<typename Result >

using fcppt::options::base_unique_ptr = fcppt::unique_ptr<fcppt::options::base<Result>>

A unique pointer for fcppt::options::base.

Template Parameters

Result

The result type of the parser. Must be an fcppt::record::object.

default_value

template<typename Type >

using fcppt::options::default_value = fcppt::strong_typedef<Type, fcppt::options::default_value_tag>

A strong typedef used as a parser's default value.

deref_type

template<typename Parser >

using fcppt::options::deref_type = std::remove_cvref_t<fcppt::deref_type<Parser>>

The dereferenced type of a parser.

Template Parameters

Parser

A regular parser, an fcppt::reference to a parser or an fcppt::unique_ptr to a parser.

error_variant

using fcppt::options::error_variant

Initial value:

 fcppt::variant::object<
    fcppt::options::argument_conversion_error,
    fcppt::options::dual_flag_error,
    fcppt::options::dual_option_error,
    fcppt::options::error_pair,
    fcppt::options::leftover_error,
    fcppt::options::invalid_command_error,
    fcppt::options::missing_argument_error,
    fcppt::options::missing_command_error,
    fcppt::options::missing_flag_error,
    fcppt::options::missing_option_argument_error,
    fcppt::options::missing_option_error,
    fcppt::options::option_conversion_error>

flag_name_set

using fcppt::options::flag_name_set = std::set<fcppt::options::flag_name>

The set of flag names.

Each string in this set is expected not to be followed by a value, e.g. "--foo".

help_result

template<typename Result >

using fcppt::options::help_result

Initial value:

 
    fcppt::variant::object<fcppt::options::result<Result>, fcppt::options::usage>

The result of invoking a regular parser and a help parser.

A help result is either a regular result or the usage of the parser.

help_switch

using fcppt::options::help_switch = fcppt::options::unit_switch<fcppt::options::detail::help_label>

The type of a help parser.

A help parser is a switch used to display a help message.

help_text

using fcppt::options::help_text = fcppt::strong_typedef< fcppt::string ,_>

A string type representing a help text.

inactive_value

template<typename Type >

using fcppt::options::inactive_value = fcppt::strong_typedef<Type, fcppt::options::inactive_value_tag>

A strong typedef used as a parser's inactive value.

left

template<typename Type >

using fcppt::options::left = fcppt::strong_typedef<Type, fcppt::options::detail::left_tag>

The left result type of a sum parser.

long_name

using fcppt::options::long_name = fcppt::strong_typedef< fcppt::string ,_>

A string type representing a long name.

A long name is the name of an argument, e.g. "arg", or the long name of an option or flag, e.g. "--foo".

name

using fcppt::options::name = fcppt::strong_typedef< fcppt::string ,_>

option_name_set

using fcppt::options::option_name_set = std::set<fcppt::options::option_name>

The set of option names.

Each string in this set is expected to be followed by a value, e.g. "--foo bar".

optional_help_text

using fcppt::options::optional_help_text = fcppt::optional::object<fcppt::options::help_text>

An optional help text.

optional_short_name

using fcppt::options::optional_short_name = fcppt::optional::object<fcppt::options::short_name>

An optional short name.

parse_error

using fcppt::options::parse_error = fcppt::variant::object<fcppt::options::missing_error, fcppt::options::error>

The error type returned by parsers.

An error can either be caused by a missing argument or option, or by something else like a failed conversion.

parse_result

template<typename T >

using fcppt::options::parse_result

Initial value:

 
    fcppt::either::object<fcppt::options::parse_error, fcppt::options::state_with_value<T>>

The result of a parser.

On success, a parser returns a value and the remaining state.

result

template<typename T >

using fcppt::options::result = fcppt::either::object<fcppt::options::error, T>

The result of a parse operation.

The result of a parse is either T or an fcppt::options::error.

result_of

template<typename Parser >

using fcppt::options::result_of = typename fcppt::options::deref_type<Parser>::result_type

The result of a parser type.

right

template<typename Type >

using fcppt::options::right = fcppt::strong_typedef<Type, fcppt::options::detail::right_tag>

The right result type of a sum parser.

short_name

using fcppt::options::short_name = fcppt::strong_typedef< fcppt::string ,_>

A string type representing a short name.

A short name is the short name of an option or flag, e.g. "-f".

usage_variant

using fcppt::options::usage_variant

Initial value:

 fcppt::variant::object<
    fcppt::options::argument_usage,
    fcppt::options::commands_usage,
    fcppt::options::flag_usage,
    fcppt::options::many_usage,
    fcppt::options::option_usage,
    fcppt::options::optional_usage,
    fcppt::options::product_usage,
    fcppt::options::sum_usage,
    fcppt::options::unit_usage>

Function Documentation

apply()

template<typename... Parsers>

auto fcppt::options::apply ( Parsers &&... _parsers )

inline

Combines two or more parsers.

Combines two or more parsers into a single one that parses everything the individual parsers do. Because the resulting parser produces a record that contains all labels of the individual parsers, the label sets of the individual parsers must be pairwise disjoint.

Template Parameters

Parsers

Must be at least two parsers.

default_help_switch()

FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::options::help_switch fcppt::options::default_help_switch

(

)

The default help switch.

The default help switch that use "-h" or "--help".

deref()

template<typename Parser >

decltype(auto) fcppt::options::deref ( Parser const & _parser )

inline

Dereferences a parser.

Parsers can be stored by copy, by reference or by unique pointer.

FCPPT_RECORD_MAKE_LABEL() [1/2]

fcppt::options::FCPPT_RECORD_MAKE_LABEL

(

options_label

)

The options label name in fcppt::options::commands.

FCPPT_RECORD_MAKE_LABEL() [2/2]

fcppt::options::FCPPT_RECORD_MAKE_LABEL

(

sub_command_label

)

The sub-command label name in fcppt::options::commands.

make_active_value()

template<typename Type >

fcppt::options::active_value< std::remove_cvref_t< Type > > fcppt::options::make_active_value ( Type && _value )

inline

Creates an active value.

make_base()

template<typename Result , typename Parser >

fcppt::options::base_unique_ptr< Result > fcppt::options::make_base

(

Parser &&

_parser

)

Creates an fcppt::options::base.

Creates a unique pointer to fcppt::options::base, using the concrete parser _parser as its implementation. It is possible that the result type of Parser is a permuted version of Result.

Template Parameters

Result

The result type of the parser. Must be an fcppt::record::object.

make_commands()

template<typename OptionsParser , typename... SubCommands>

fcppt::options:: commands< std::remove_cvref_t< OptionsParser >, std::remove_cvref_t< SubCommands >... > fcppt::options::make_commands ( OptionsParser && _options_parser, SubCommands &&... _sub_commands )

inline

Makes a commands parser.

Template Parameters

SubCommands

A parameter pack of fcppt::options::sub_command.

make_default_value()

template<typename Type >

fcppt::options::default_value< std::remove_cvref_t< Type > > fcppt::options::make_default_value ( Type && _value )

inline

Creates a default value.

Template Parameters

Type	Must be an fcppt::optional::object.

make_inactive_value()

template<typename Type >

fcppt::options::inactive_value< std::remove_cvref_t< Type > > fcppt::options::make_inactive_value ( Type && _value )

inline

Creates an inactive value.

make_left()

template<typename Type >

fcppt::options::left< std::remove_cvref_t< Type > > fcppt::options::make_left ( Type && _value )

inline

Creates an fcppt::options::left.

make_many()

template<typename Parser >

fcppt::options::many< std::remove_cvref_t< Parser > > fcppt::options::make_many ( Parser && _parser )

inline

Turns a parser into a many parser.

Normally, a parser can be applied exactly once. This function turns a parser into a parser that can be applied zero or more times.

make_optional()

template<typename Parser >

fcppt::options::optional< std::remove_cvref_t< Parser > > fcppt::options::make_optional ( Parser && _parser )

inline

Turns a parser into an optional parser.

Normally, a parser can fail, for example in case an argument has not been specified. This function turns a parser into a parser that instead of failing returns optional results.

make_right()

template<typename Type >

fcppt::options::right< std::remove_cvref_t< Type > > fcppt::options::make_right ( Type && _value )

inline

Creates an fcppt::options::right.

make_sub_command()

template<typename Tag , typename Parser >

fcppt::options::sub_command< Tag, std::remove_cvref_t< Parser > > fcppt::options::make_sub_command ( fcppt::string && _name, Parser && _parser, fcppt::options::optional_help_text && _help_text )

inline

Makes a sub command.

make_success()

template<typename Type >

fcppt::options::result< std::remove_cvref_t< Type > > fcppt::options::make_success ( Type && _value )

inline

Creates a success value.

make_sum()

template<typename Label , typename Left , typename Right >

fcppt::options::sum< Label, std::remove_cvref_t< Left >, std::remove_cvref_t< Right > > fcppt::options::make_sum ( Left && _left, Right && _right )

inline

Creates the sum of two parsers.

no_default_value()

template<typename Type >

fcppt::options::default_value< fcppt::optional::object< Type > > fcppt::options::no_default_value ( )

inline

Creates an empty default value.

operator<<() [1/2]

FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::io::ostream & fcppt::options::operator<<	(	fcppt::io::ostream &	,
		fcppt::options::error const &	)

operator<<() [2/2]

FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::io::ostream & fcppt::options::operator<<	(	fcppt::io::ostream &	,
		fcppt::options::usage const &	)

parse()

template<typename Parser >

fcppt::options::result< fcppt::options::result_of< Parser > > fcppt::options::parse	(	Parser const &	_parser,
		fcppt::args_vector const &	_args )

Parse a command-line.

Applies _parser to _args.

parse_help()

template<typename Parser >

fcppt::options::help_result< fcppt::options::result_of< Parser > > fcppt::options::parse_help	(	fcppt::options::help_switch const &	_help,
		Parser const &	_parser,
		fcppt::args_vector const &	_args )

Parse a command-line with a help parser.

First, the switch parser _help is applied to _args. If its switch and nothing else is specified, the usage string is gathered from _parser and returned. Otherwise, if the switch of _help was not specified, then the result of applying _parser to _args is returned.

Warning

Do not include any short or long names in _parser that _help is using.

pretty_type()

template<typename Type >

fcppt::options::type_name fcppt::options::pretty_type ( )

inline

Returns a pretty type used for help texts.

Using fcppt::options::pretty_type_impl, one can specialize how a type name is represented as a string. For example, the pretty name of std::string is simply string instead of std::basic_string<char,std::char_traits<char>,std::allocator<char>>.