Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MISC] Change seqan3::option_spec enum names to lower case. #2285

Merged
merged 4 commits into from
Dec 17, 2020
Merged

[MISC] Change seqan3::option_spec enum names to lower case. #2285

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6d786e9
[MISC] Change seqan3::option_spec enum names to lower case.
smehringer Nov 26, 2020
db17ba3
apply requested changes.
smehringer Dec 7, 2020
d502d00
Change defaulted->standard.
smehringer Dec 15, 2020
3226f4d
Update doc/tutorial/argument_parser/index.md
smehringer Dec 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,17 @@ If possible, provide tooling that performs the changes, e.g. a shell-script.
* The `seqan3::regex_validator` parses `std::filesystem::path`'s correctly now
([\#2216](https://github.com/seqan/seqan3/pull/2216)).

## API changes

#### Argument Parser

* The enum names of `seqan3::option_spec` were changed to lower case
([\#2285](https://github.com/seqan/seqan3/pull/2285)):
* `seqan3::option_spec::DEFAULT` is replaced by `seqan3::option_spec::standard`.
* `seqan3::option_spec::REQUIRED` is replaced by `seqan3::option_spec::required`.
* `seqan3::option_spec::ADVANCED` is replaced by `seqan3::option_spec::advanced`.
* `seqan3::option_spec::HIDDEN` is replaced by `seqan3::option_spec::hidden`.

# 3.0.2

Note that 3.1.0 will be the first API stable release and interfaces in this release might still change.
Expand Down
14 changes: 7 additions & 7 deletions doc/tutorial/argument_parser/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,12 +308,12 @@ Set an option/flag to hidden, if you want to completely hide it from the user. I

Summary:

| Tag | Description |
|:-----------|:---------------------------------------------------------------|
| DEFAULT | The default tag with no special behaviour. |
| REQUIRED | Required options will cause an error if not provided. |
| ADVANCED | Advanced options are only displayed wit `-hh/--advanced-help`. |
| HIDDEN | Hidden options are never displayed when exported. |
| Tag | Description |
|:-----------|:--------------------------------------------------------------------------------------------------|
| standard | The default tag (non-required and always visible). |
| required | Required options will cause an error if not provided (required and always visible). |
| advanced | Advanced options are only displayed wit `-hh/--advanced-help`. (non-required and partly visible). |
smehringer marked this conversation as resolved.
Show resolved Hide resolved
| hidden | Hidden options are never displayed when exported (non-required and non-visible). |

\assignment{Assignment 5}

Expand All @@ -340,7 +340,7 @@ Our applications often do not allow just any value to be passed as input argumen

A *validator* is a [functor](https://stackoverflow.com/questions/356950/what-are-c-functors-and-their-uses) that is called within the argument parser after retrieving and converting a command line argument. We provide several validators, which we hope cover most of the use cases, but you can always create your own validator (see section [Create your own validator](#section_create_your_own_validator)).

\attention You can pass a validator to the seqan3::argument_parser::add_option function only after passing the seqan3::option_spec parameter. Pass the seqan3::option_spec::DEFAULT tag, if there are no further restrictions on your option.
\attention You can pass a validator to the seqan3::argument_parser::add_option function only after passing the seqan3::option_spec parameter. Pass the seqan3::option_spec::standard tag if there are no further restrictions on your option.

## SeqAn validators

Expand Down
2 changes: 1 addition & 1 deletion doc/tutorial/argument_parser/small_snippets.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ parser.add_positional_option(list_variable, "Give me one or more variables!.");
seqan3::argument_parser parser{"Example-Parser", argc, argv};
//![required_option]
std::string required_variable{};
parser.add_option(required_variable, 'n', "name", "I really need a name.", seqan3::option_spec::REQUIRED);
parser.add_option(required_variable, 'n', "name", "I really need a name.", seqan3::option_spec::required);
//![required_option]
}

Expand Down
2 changes: 1 addition & 1 deletion doc/tutorial/argument_parser/solution5.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.add_positional_option(args.file_path, "Please provide a tab separated data file.");

//![solution]
parser.add_option(args.seasons, 's', "season", "Choose the seasons to aggregate.", seqan3::option_spec::REQUIRED);
parser.add_option(args.seasons, 's', "season", "Choose the seasons to aggregate.", seqan3::option_spec::required);
//![solution]

parser.add_option(args.aggregate_by, 'a', "aggregate-by", "Choose your method of aggregation: mean or median.");
Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial/argument_parser/solution6.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,12 +84,12 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments

//![arithmetic_range_validator]
parser.add_option(args.seasons, 's', "season", "Choose the seasons to aggregate.",
seqan3::option_spec::REQUIRED, seqan3::arithmetic_range_validator{1, 7});
seqan3::option_spec::required, seqan3::arithmetic_range_validator{1, 7});
//![arithmetic_range_validator]

//![value_list_validator]
parser.add_option(args.aggregate_by, 'a', "aggregate-by", "Choose your method of aggregation.",
seqan3::option_spec::DEFAULT, seqan3::value_list_validator{"median", "mean"});
seqan3::option_spec::standard, seqan3::value_list_validator{"median", "mean"});
//![value_list_validator]

parser.add_flag(args.header_is_set, 'H', "header-is-set", "Let us know whether your data file contains a "
Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial/concepts/custom_validator_solution2.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@ int main(int argc, char ** argv)
int32_t variable{};
int16_t variable2{};

myparser.add_option(variable, 'i', "", "An int that is a square", seqan3::option_spec::DEFAULT,
myparser.add_option(variable, 'i', "", "An int that is a square", seqan3::option_spec::standard,
custom_validator{}); // ← your validator is used!

myparser.add_option(variable2, 'j', "", "An int that is a square and within [0,20].", seqan3::option_spec::DEFAULT,
myparser.add_option(variable2, 'j', "", "An int that is a square and within [0,20].", seqan3::option_spec::standard,
custom_validator{} | seqan3::arithmetic_range_validator{0, 20}); // ← now it's chained

try
Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial/read_mapper/read_mapper_indexer_step1.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Creates an index over a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.index_path, 'o', "output", "The output index file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"index"}});
}

Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial/read_mapper/read_mapper_indexer_step2.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Creates an index over a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.index_path, 'o', "output", "The output index file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"index"}});
}

Expand Down
4 changes: 2 additions & 2 deletions doc/tutorial/read_mapper/read_mapper_indexer_step3.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,10 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Creates an index over a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.index_path, 'o', "output", "The output index file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"index"}});
}

Expand Down
10 changes: 5 additions & 5 deletions doc/tutorial/read_mapper/read_mapper_step1.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,19 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Map reads against a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.query_path, 'q', "query", "The path to the query.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fq","fastq"}});
parser.add_option(args.index_path, 'i', "index", "The path to the index.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"index"}});
parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"sam"}});
parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::arithmetic_range_validator{0, 4});
}

Expand Down
10 changes: 5 additions & 5 deletions doc/tutorial/read_mapper/read_mapper_step2.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,19 +93,19 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Map reads against a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.query_path, 'q', "query", "The path to the query.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fq","fastq"}});
parser.add_option(args.index_path, 'i', "index", "The path to the index.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"index"}});
parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"sam"}});
parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::arithmetic_range_validator{0, 4});
}

Expand Down
10 changes: 5 additions & 5 deletions doc/tutorial/read_mapper/read_mapper_step3.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,19 +116,19 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Map reads against a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.query_path, 'q', "query", "The path to the query.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fq","fastq"}});
parser.add_option(args.index_path, 'i', "index", "The path to the index.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"index"}});
parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"sam"}});
parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::arithmetic_range_validator{0, 4});
}

Expand Down
10 changes: 5 additions & 5 deletions doc/tutorial/read_mapper/read_mapper_step4.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,19 +125,19 @@ void initialise_argument_parser(seqan3::argument_parser & parser, cmd_arguments
parser.info.short_description = "Map reads against a reference.";
parser.info.version = "1.0.0";
parser.add_option(args.reference_path, 'r', "reference", "The path to the reference.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fa","fasta"}});
parser.add_option(args.query_path, 'q', "query", "The path to the query.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"fq","fastq"}});
parser.add_option(args.index_path, 'i', "index", "The path to the index.",
seqan3::option_spec::REQUIRED,
seqan3::option_spec::required,
seqan3::input_file_validator{{"index"}});
parser.add_option(args.sam_path, 'o', "output", "The output SAM file path.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::output_file_validator{seqan3::output_file_open_options::create_new, {"sam"}});
parser.add_option(args.errors, 'e', "error", "Maximum allowed errors.",
seqan3::option_spec::DEFAULT,
seqan3::option_spec::standard,
seqan3::arithmetic_range_validator{0, 4});
}

Expand Down
30 changes: 16 additions & 14 deletions include/seqan3/argument_parser/argument_parser.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ class argument_parser
char const short_id,
std::string const & long_id,
std::string const & desc,
option_spec const spec = option_spec::DEFAULT,
option_spec const spec = option_spec::standard,
validator_type option_validator = validator_type{}) // copy to bind rvalues
{
if (sub_parser != nullptr)
Expand All @@ -266,7 +266,7 @@ class argument_parser
char const short_id,
std::string const & long_id,
std::string const & desc,
option_spec const spec = option_spec::DEFAULT)
option_spec const spec = option_spec::standard)
{
verify_identifiers(short_id, long_id);
// copy variables into the lambda because the calls are pushed to a stack
Expand Down Expand Up @@ -488,45 +488,45 @@ class argument_parser

/*!\brief Adds an help page section to the seqan3::argument_parser.
* \param[in] title The title of the section.
* \param[in] spec Whether to always display this section title (seqan3::option_spec::DEFAULT), only when showing
* the advanced help page (seqan3::option_spec::ADVANCED) or never (seqan3::option_spec::HIDDEN).
* \param[in] spec Whether to always display this section title (seqan3::option_spec::standard), only when showing
* the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).
* \details This only affects the help page and other output formats.
*/
void add_section(std::string const & title, option_spec const spec = option_spec::DEFAULT)
void add_section(std::string const & title, option_spec const spec = option_spec::standard)
{
std::visit([&] (auto & f) { f.add_section(title, spec); }, format);
}

/*!\brief Adds an help page subsection to the seqan3::argument_parser.
* \param[in] title The title of the subsection.
* \param[in] spec Whether to always display this subsection title (seqan3::option_spec::DEFAULT), only when showing
* the advanced help page (seqan3::option_spec::ADVANCED) or never (seqan3::option_spec::HIDDEN).
* \param[in] spec Whether to always display this subsection title (seqan3::option_spec::standard), only when showing
* the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).
* \details This only affects the help page and other output formats.
*/
void add_subsection(std::string const & title, option_spec const spec = option_spec::DEFAULT)
void add_subsection(std::string const & title, option_spec const spec = option_spec::standard)
{
std::visit([&] (auto & f) { f.add_subsection(title, spec); }, format);
}

/*!\brief Adds an help page text line to the seqan3::argument_parser.
* \param[in] text The text to print.
* \param[in] is_paragraph Whether to insert as paragraph or just a line (Default: false).
* \param[in] spec Whether to always display this line (seqan3::option_spec::DEFAULT), only when showing
* the advanced help page (seqan3::option_spec::ADVANCED) or never (seqan3::option_spec::HIDDEN).
* \param[in] spec Whether to always display this line (seqan3::option_spec::standard), only when showing
* the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).
* \details
* If the line is not a paragraph (false), only one line break is appended, otherwise two line breaks are appended.
* This only affects the help page and other output formats.
*/
void add_line(std::string const & text, bool is_paragraph = false, option_spec const spec = option_spec::DEFAULT)
void add_line(std::string const & text, bool is_paragraph = false, option_spec const spec = option_spec::standard)
{
std::visit([&] (auto & f) { f.add_line(text, is_paragraph, spec); }, format);
}

/*!\brief Adds an help page list item (key-value) to the seqan3::argument_parser.
* \param[in] key The key of the key-value pair of the list item.
* \param[in] desc The value of the key-value pair of the list item.
* \param[in] spec Whether to always display this list item (seqan3::option_spec::DEFAULT), only when showing
* the advanced help page (seqan3::option_spec::ADVANCED) or never (seqan3::option_spec::HIDDEN).
* \param[in] spec Whether to always display this list item (seqan3::option_spec::standard), only when showing
* the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).
*
* \details
*
Expand All @@ -540,7 +540,9 @@ class argument_parser
* Super important integer for age.
*```
*/
void add_list_item(std::string const & key, std::string const & desc, option_spec const spec = option_spec::DEFAULT)
void add_list_item(std::string const & key,
std::string const & desc,
option_spec const spec = option_spec::standard)
{
std::visit([&] (auto & f) { f.add_list_item(key, desc, spec); }, format);
}
Expand Down
Loading