Freundlich's C++ toolkit
Classes | Typedefs | Functions


Library for command-line options.

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


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:

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

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{

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

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:

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.

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');

In case of failure we get an fcppt::options::error, containing a message of 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');

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:

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 the empty command-line. 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:



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.

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.


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.


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.


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.

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:

A more complex example

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

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


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

input_file_option const input_file{
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 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_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".

execute_switch const execute{
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.

openmode_option const openmode{
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.

log_level_option const log_level{
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(

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)>;

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{

We then open the input file using the input filename.

fcppt::filesystem::ifstream input{fcppt::filesystem::open_exn<fcppt::filesystem::ifstream>(
fcppt::record::get<input_file_label>(_result), // NOLINT(fuchsia-default-arguments-calls)

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");

Second, the openmode needs to be passed as well.

fcppt::filesystem::ofstream output{fcppt::filesystem::open_exn<fcppt::filesystem::ofstream>(
output_filename, // NOLINT(fuchsia-default-arguments-calls)

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


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:

auto const options_parser{
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::options::help_text{FCPPT_TEXT("The path to clone from")}})};
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.

auto const clone_command{fcppt::options::make_sub_command<clone_label>(
fcppt::options::help_text{FCPPT_TEXT("Clone from another repository")}})};
auto const pull_command{fcppt::options::make_sub_command<pull_label>(
fcppt::options::help_text{FCPPT_TEXT("Pull all changes")}})};

Finally, we combine everything into a commands parser.

auto const commands{fcppt::options::make_commands(

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::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::options::result_of<decltype(clone_command)> const &_clone) {
fcppt::io::cout() << FCPPT_TEXT("Clone from ")
<< fcppt::record::get<clone_path>(
<< 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.

[&commands](fcppt::options::error const &_error) {
fcppt::io::cerr() << _error << FCPPT_TEXT("\nUsage:\n") << commands.usage()
<< FCPPT_TEXT("\n");

Here are some example invocations:

No command specified from [clone, pull]
[ --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
[ --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".
[ --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

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":

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

fcppt::io::cout() << _result << FCPPT_TEXT('\n');
[](fcppt::options::help_text const &_help_text) {
fcppt::io::cout() << _help_text << FCPPT_TEXT('\n');

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

parser_type const parser{
fcppt::options::help_text{FCPPT_TEXT("The main argument")}}};

Here are a few example invocations:

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:

using result_type = fcppt::record::object<

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(

The parser can then be used like any other parser:

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())};


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




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::string 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.


struct  fcppt::options::active_value_tag
 The tag of strong typedefs for active values. More...
class  fcppt::options::argument< Label, Type >
 An argument parser. More...
class  fcppt::options::base< Result >
 The base class for parsers with a given result type. More...
class  fcppt::options::commands< OptionsParser, SubCommands >
 A parser for multiple sub commands. More...
struct  fcppt::options::default_value_tag
 The tag of strong typedefs for default values. More...
class  fcppt::options::flag< Label, Type >
 A flag parser. More...
struct  fcppt::options::inactive_value_tag
 The tag of strong typedefs for inactive values. More...
class  fcppt::options::many< Parser >
 A parser for zero or more elements. More...
class  fcppt::options::missing_error
 A string type representing a missing error. More...
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::optional< Parser >
 An optional parser. More...
class  fcppt::options::product< Left, Right >
 A product of two parsers. More...
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::sum< Label, Left, Right >
 A sum of two parsers. More...
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...


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. More...
template<typename Result >
using fcppt::options::base_unique_ptr = fcppt::unique_ptr< fcppt::options::base< Result > >
 A unique pointer for fcppt::options::base. More...
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. More...
template<typename Parser >
using fcppt::options::deref_type = fcppt::type_traits::remove_cv_ref_t< fcppt::deref_type< Parser > >
 The dereferenced type of a parser. More...
using fcppt::options::error = fcppt::strong_typedef< fcppt::string,_ >
 The error type retuned. More...
using fcppt::options::flag_name_set = std::set< fcppt::options::flag_name >
 The set of flag names. More...
using fcppt::options::help_switch = fcppt::options::unit_switch< fcppt::options::detail::help_label >
 The type of a help parser. More...
using fcppt::options::help_text = fcppt::strong_typedef< fcppt::string,_ >
 A string type representing a help text. More...
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. More...
using fcppt::options::indentation = fcppt::strong_typedef< unsigned,_ >
 An indentation level. More...
template<typename Type >
using fcppt::options::left = fcppt::strong_typedef< Type, fcppt::options::detail::left_tag >
 The left result type of a sum parser. More...
using fcppt::options::long_name = fcppt::strong_typedef< fcppt::string,_ >
 A string type representing a long name. More...
using fcppt::options::option_name_set = std::set< fcppt::options::option_name >
 The set of option names. More...
using fcppt::options::optional_help_text = fcppt::optional::object< fcppt::options::help_text >
 An optional help text. More...
using fcppt::options::optional_short_name = fcppt::optional::object< fcppt::options::short_name >
 An optional short name. More...
using fcppt::options::other_error = fcppt::strong_typedef< fcppt::string,_ >
 A string type representing other errors. More...
using fcppt::options::parse_error = fcppt::variant::object< fcppt::options::missing_error, fcppt::options::other_error >
 The error type returned by parsers. More...
template<typename T >
using fcppt::options::parse_result = fcppt::either::object< fcppt::options::parse_error, fcppt::options::state_with_value< T > >
 The result of a parser. More...
template<typename T >
using fcppt::options::result = fcppt::either::object< fcppt::options::error, T >
 The result of a parse operation. More...
template<typename Parser >
using fcppt::options::result_of = typename fcppt::options::deref_type< Parser >::result_type
 The result of a parser type. More...
template<typename Type >
using fcppt::options::right = fcppt::strong_typedef< Type, fcppt::options::detail::right_tag >
 The right result type of a sum parser. More...
using fcppt::options::short_name = fcppt::strong_typedef< fcppt::string,_ >
 A string type representing a short name. More...


template<typename... Parsers>
auto fcppt::options::apply (Parsers &&..._parsers)
 Combines two or more parsers. More...
FCPPT_OPTIONS_DETAIL_SYMBOL fcppt::options::help_switch fcppt::options::default_help_switch ()
 The default help switch. More...
template<typename Parser >
decltype(auto) fcppt::options::deref (Parser const &_parser)
 Dereferences a parser. More...
FCPPT_OPTIONS_DETAIL_SYMBOL bool fcppt::options::is_option (fcppt::string_view const &)
 Checks if a string is an option. More...
template<typename Type >
fcppt::options::active_value< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_active_value (Type &&_value)
 Creates an active value. More...
template<typename Result , typename Parser >
fcppt::options::base_unique_ptr< Result > fcppt::options::make_base (Parser &&_parser)
 Creates an fcppt::options::base. More...
template<typename OptionsParser , typename... SubCommands>
fcppt::options::commands< fcppt::type_traits::remove_cv_ref_t< OptionsParser >, fcppt::type_traits::remove_cv_ref_t< SubCommands >... > fcppt::options::make_commands (OptionsParser &&_options_parser, SubCommands &&..._sub_commands)
 Makes a commands parser. More...
template<typename Type >
fcppt::options::default_value< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_default_value (Type &&_value)
 Creates a default value. More...
template<typename Type >
fcppt::options::inactive_value< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_inactive_value (Type &&_value)
 Creates an inactive value. More...
template<typename Type >
fcppt::options::left< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_left (Type &&_value)
 Creates an fcppt::options::left. More...
template<typename Parser >
fcppt::options::many< fcppt::type_traits::remove_cv_ref_t< Parser > > fcppt::options::make_many (Parser &&_parser)
 Turns a parser into a many parser. More...
template<typename Parser >
fcppt::options::optional< fcppt::type_traits::remove_cv_ref_t< Parser > > fcppt::options::make_optional (Parser &&_parser)
 Turns a parser into an optional parser. More...
template<typename Type >
fcppt::options::right< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_right (Type &&_value)
 Creates an fcppt::options::right. More...
template<typename Tag , typename Parser >
fcppt::options::sub_command< Tag, fcppt::type_traits::remove_cv_ref_t< Parser > > fcppt::options::make_sub_command (fcppt::string &&_name, Parser &&_parser, fcppt::options::optional_help_text &&_help_text)
 Makes a sub command. More...
template<typename Type >
fcppt::options::result< fcppt::type_traits::remove_cv_ref_t< Type > > fcppt::options::make_success (Type &&_value)
 Creates a success value. More...
template<typename Label , typename Left , typename Right >
fcppt::options::sum< Label, fcppt::type_traits::remove_cv_ref_t< Left >, fcppt::type_traits::remove_cv_ref_t< Right > > fcppt::options::make_sum (Left &&_left, Right &&_right)
 Creates the sum of two parsers. More...
template<typename Type >
fcppt::options::default_value< fcppt::optional::object< Type > > fcppt::options::no_default_value ()
 Creates an empty default value. More...
 fcppt::options::FCPPT_RECORD_MAKE_LABEL (options_label)
 The options label name in fcppt::options::commands. More...
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. More...
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. More...
template<typename Type >
fcppt::string fcppt::options::pretty_type ()
 Returns a pretty type used for help texts. More...
 fcppt::options::FCPPT_RECORD_MAKE_LABEL (sub_command_label)
 The sub-command label name in fcppt::options::commands. More...

Typedef Documentation

◆ active_value

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

◆ base_unique_ptr

template<typename Result >
using fcppt::options::base_unique_ptr = typedef fcppt::unique_ptr<fcppt::options::base<Result> >

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

Template Parameters
ResultThe result type of the parser. Must be an fcppt::record::object.

◆ default_value

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

◆ deref_type

template<typename Parser >
using fcppt::options::deref_type = typedef fcppt::type_traits::remove_cv_ref_t<fcppt::deref_type<Parser> >

The dereferenced type of a parser.

Template Parameters
ParserA regular parser, an fcppt::reference to a parser or an fcppt::unique_ptr to a parser.

◆ error

The error type retuned.

◆ flag_name_set

The set of flag names.

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

◆ help_switch

using fcppt::options::help_switch = typedef 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

A string type representing a help text.

◆ inactive_value

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

◆ indentation

using fcppt::options::indentation = typedef fcppt::strong_typedef< unsigned ,_>

An indentation level.

◆ left

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

The left result type of a sum parser.

◆ long_name

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

◆ option_name_set

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

An optional help text.

◆ optional_short_name

An optional short name.

◆ other_error

A string type representing other errors.

Errors that are not fcppt::options::missing_error, for example failed conversion. Such errors make even fcppt::options::optional parsers fail.

◆ parse_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

The result of a parser.

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

◆ result

template<typename T >
using fcppt::options::result = typedef 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 = typedef typename fcppt::options::deref_type<Parser>::result_type

The result of a parser type.

◆ right

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

The right result type of a sum parser.

◆ short_name

A string type representing a short name.

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

Function Documentation

◆ apply()

template<typename... Parsers>
auto fcppt::options::apply ( Parsers &&...  _parsers)

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
ParsersMust 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)

Dereferences a parser.

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


fcppt::options::FCPPT_RECORD_MAKE_LABEL ( options_label  )

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


fcppt::options::FCPPT_RECORD_MAKE_LABEL ( sub_command_label  )

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

◆ is_option()

FCPPT_OPTIONS_DETAIL_SYMBOL bool fcppt::options::is_option ( fcppt::string_view const &  )

Checks if a string is an option.

Options are strings that with a '-'.

◆ make_active_value()

template<typename Type >
fcppt::options::active_value<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_active_value ( Type &&  _value)

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
ResultThe result type of the parser. Must be an fcppt::record::object.

◆ make_commands()

template<typename OptionsParser , typename... SubCommands>
fcppt::options::commands< fcppt::type_traits::remove_cv_ref_t<OptionsParser>, fcppt::type_traits::remove_cv_ref_t<SubCommands>...> fcppt::options::make_commands ( OptionsParser &&  _options_parser,
SubCommands &&...  _sub_commands 

Makes a commands parser.

Template Parameters
SubCommandsA parameter pack of fcppt::options::sub_command.

◆ make_default_value()

template<typename Type >
fcppt::options::default_value<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_default_value ( Type &&  _value)

Creates a default value.

Template Parameters
TypeMust be an fcppt::optional::object.

◆ make_inactive_value()

template<typename Type >
fcppt::options::inactive_value<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_inactive_value ( Type &&  _value)

Creates an inactive value.

◆ make_left()

template<typename Type >
fcppt::options::left<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_left ( Type &&  _value)

Creates an fcppt::options::left.

◆ make_many()

template<typename Parser >
fcppt::options::many<fcppt::type_traits::remove_cv_ref_t<Parser> > fcppt::options::make_many ( Parser &&  _parser)

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<fcppt::type_traits::remove_cv_ref_t<Parser> > fcppt::options::make_optional ( Parser &&  _parser)

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<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_right ( Type &&  _value)

Creates an fcppt::options::right.

◆ make_sub_command()

template<typename Tag , typename Parser >
fcppt::options::sub_command<Tag, fcppt::type_traits::remove_cv_ref_t<Parser> > fcppt::options::make_sub_command ( fcppt::string &&  _name,
Parser &&  _parser,
fcppt::options::optional_help_text &&  _help_text 

Makes a sub command.

◆ make_success()

template<typename Type >
fcppt::options::result<fcppt::type_traits::remove_cv_ref_t<Type> > fcppt::options::make_success ( Type &&  _value)

Creates a success value.

◆ make_sum()

template<typename Label , typename Left , typename Right >
fcppt::options::sum< Label, fcppt::type_traits::remove_cv_ref_t<Left>, fcppt::type_traits::remove_cv_ref_t<Right> > fcppt::options::make_sum ( Left &&  _left,
Right &&  _right 

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 ( )

Creates an empty default value.

◆ 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.

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

◆ pretty_type()

template<typename Type >
fcppt::string fcppt::options::pretty_type ( )

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>>.