From b49c3c21127efe76c6728af39ce87ae694b10ba4 Mon Sep 17 00:00:00 2001 From: Evelin Aasna Date: Tue, 22 Feb 2022 13:32:05 +0100 Subject: [PATCH] [DOC] Clarify flag documentation. --- doc/tutorial/argument_parser/index.md | 12 ++++++++---- doc/tutorial/argument_parser/small_snippets.cpp | 2 +- doc/tutorial/argument_parser/solution3.cpp | 2 +- doc/tutorial/argument_parser/solution4.cpp | 2 +- doc/tutorial/argument_parser/solution5.cpp | 2 +- doc/tutorial/argument_parser/solution6.cpp | 2 +- 6 files changed, 13 insertions(+), 9 deletions(-) diff --git a/doc/tutorial/argument_parser/index.md b/doc/tutorial/argument_parser/index.md index 1da95b23..013b306c 100644 --- a/doc/tutorial/argument_parser/index.md +++ b/doc/tutorial/argument_parser/index.md @@ -20,7 +20,7 @@ This class will give you the following functionality: * Robust parsing of command line arguments. * Simple validation of arguments (e.g. within a range or one of a list of allowed values). * Automatically generated and nicely formatted help screens when your program is called with `--help`. You can also -* export this help to HTML and man pages. +export this help to HTML and man pages. * In the future, you are also able to automatically generate nodes for work flow engines such as KNIME or Galaxy. ## Command line argument terminology @@ -79,12 +79,13 @@ screen. The argument parser checks the following restrictions and throws a sharg::design_error if they are not satisfied: * **Long identifiers**: must be unique, more than one character long, may only contain alphanumeric characters, as well -* as `_`, `-`, or `@`, but never start with `-`. +as `_`, `-`, or `@`, but never start with `-`. * **Short identifiers**: must be unique and consist of only a single letter that is alphanumeric characters, `_` or `@`. -* either the short or long id may be empty but not both at the same time. +Either the short or long id may be empty but not both at the same time. * Only the last positional option may be a list (see [lists](#section_list_positional_options)). * The flag identifiers `-h`, `--help`, `--advanced-help`, `--advanced-help`, `--export-help`, `--version`, `--copyright` -* are predefined and cannot be specified manually or used otherwise. +are predefined and cannot be specified manually or used otherwise. +* **Flags**: value must be false by default. Passing the flag identifier on the command line marks it as true. * The sharg::argument_parser::parse function may only be called once (per parser). ## Input restrictions @@ -204,6 +205,9 @@ Additionally to the variable that will store the value and the description, you identifier. The example above will recognize an option `-n` or `--my-number` given on the command line and expect it to be followed by a value separated only by `=` or space or by nothing at all. +\note Unlike regular options which take id-value pairs, flags are passed as an identifier only. The variable associated +to a flag must be false by default and is switched to true when the flag is present on the command line. + Finally, you can add a flag with the following call: \snippet doc/tutorial/argument_parser/small_snippets.cpp add_flag diff --git a/doc/tutorial/argument_parser/small_snippets.cpp b/doc/tutorial/argument_parser/small_snippets.cpp index cf96c61a..2f4ef2fe 100644 --- a/doc/tutorial/argument_parser/small_snippets.cpp +++ b/doc/tutorial/argument_parser/small_snippets.cpp @@ -36,7 +36,7 @@ parser.add_option(variable, 'n', "my-number", "This is a description."); { sharg::argument_parser parser{"Example-Parser", argc, argv}; //![add_flag] -bool variable{}; +bool variable{false}; parser.add_flag(variable, 'f', "my_flag", "This is a description."); //![add_flag] } diff --git a/doc/tutorial/argument_parser/solution3.cpp b/doc/tutorial/argument_parser/solution3.cpp index d24fec3f..8ee7285a 100644 --- a/doc/tutorial/argument_parser/solution3.cpp +++ b/doc/tutorial/argument_parser/solution3.cpp @@ -60,7 +60,7 @@ struct cmd_arguments std::filesystem::path file_path{}; uint32_t year{}; std::string aggregate_by{"mean"}; - bool header_is_set{}; + bool header_is_set{false}; }; //![program] diff --git a/doc/tutorial/argument_parser/solution4.cpp b/doc/tutorial/argument_parser/solution4.cpp index ae364696..69bdb4d3 100644 --- a/doc/tutorial/argument_parser/solution4.cpp +++ b/doc/tutorial/argument_parser/solution4.cpp @@ -62,7 +62,7 @@ struct cmd_arguments std::filesystem::path file_path{}; std::vector seasons{}; std::string aggregate_by{"mean"}; - bool header_is_set{}; + bool header_is_set{false}; }; void initialise_argument_parser(sharg::argument_parser & parser, cmd_arguments & args) diff --git a/doc/tutorial/argument_parser/solution5.cpp b/doc/tutorial/argument_parser/solution5.cpp index 8af80548..68e5f674 100644 --- a/doc/tutorial/argument_parser/solution5.cpp +++ b/doc/tutorial/argument_parser/solution5.cpp @@ -59,7 +59,7 @@ struct cmd_arguments std::filesystem::path file_path{}; std::vector seasons{}; std::string aggregate_by{"mean"}; - bool header_is_set{}; + bool header_is_set{false}; }; void initialise_argument_parser(sharg::argument_parser & parser, cmd_arguments & args) diff --git a/doc/tutorial/argument_parser/solution6.cpp b/doc/tutorial/argument_parser/solution6.cpp index e71c9114..ac064543 100644 --- a/doc/tutorial/argument_parser/solution6.cpp +++ b/doc/tutorial/argument_parser/solution6.cpp @@ -59,7 +59,7 @@ struct cmd_arguments std::filesystem::path file_path{}; std::vector seasons{}; std::string aggregate_by{"mean"}; - bool header_is_set{}; + bool header_is_set{false}; }; void initialise_argument_parser(sharg::argument_parser & parser, cmd_arguments & args)