Skip to content

Commit

Permalink
make immediate_callback inheritable, add tests for that and for valid…
Browse files Browse the repository at this point in the history 
… strings, some cleanup in the README.md

Apply suggestions from code review

Co-Authored-By: phlptp <top1@llnl.gov>
allow callbacks for option_groups, and allow some other characters as flags
  • Loading branch information
@phlptp
phlptp committed Mar 6, 2019
1 parent 2b99577 commit 3777889
Show file tree
Hide file tree
Showing 9 changed files with 125 additions and 37 deletions.
18 changes: 13 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ Option_group *app.add_option_group(name,description); // 🚧
-app.add_mutable_set_ignore_case_underscore(... // 🆕 String only
```

An option name must start with a alphabetic character, underscore, or a number🚧. For long options, after the first character '.', and '-' are also valid. For the `add_flag*` functions '{' has special meaning. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form. If you want the default value to print in the help description, pass in `true` for the final parameter for `add_option`.
An option name must start with a alphabetic character, underscore, a number 🚧, '?'🚧, or '@'🚧. For long options, after the first character '.', and '-' are also valid characters. For the `add_flag*` functions '{' has special meaning. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form. If you want the default value to print in the help description, pass in `true` for the final parameter for `add_option`.

The `add_option_function<type>(...` function will typically require the template parameter be given unless a `std::function` object with an exact match is passed. The type can be any type supported by the `add_option` function.

Expand Down Expand Up @@ -511,9 +511,10 @@ There are several options that are supported on the main app and subcommands and
#### Callbacks
A subcommand has two optional callbacks that are executed at different stages of processing. The `preparse_callback` 🚧 is executed once after the first argument of a subcommand or application is processed and gives an argument for the number of remaining arguments to process. For the main app the first argument is considered the program name, for subcommands the first argument is the subcommand name. For Option groups and nameless subcommands the first argument is after the first argument or subcommand is processed from that group.
The second callback is executed after parsing. Depending on the status of the `immediate_callback` flag 🚧. This is either immediately after the parsing of the subcommand. Or if the flag is false, once after parsing of all arguments. If the immediate_callback is set then the callback can be executed multiple times. If the main app or subcommand has a config file, no data from the config file will be reflected in immediate_callback.
The second callback is executed after parsing. The behavior depends on the status of the `immediate_callback` flag 🚧. If true, this runs immediately after the parsing of the subcommand. Or if the flag is false, once after parsing of all arguments. If the `immediate_callback` is set then the callback can be executed multiple times if the subcommand list given multiple times. If the main app or subcommand has a config file, no data from the config file will be reflected in immediate_callback. `immediate_callback()` has no effect on the main app, though it can be inherited. For option_groups `immediate_callback` causes the callback to be run prior to other option groups and options in the main app, effectively giving the options in the group priority.
For example say an application was set up like
```cpp
app.callback(ac);
sub1=app.add_subcommand("sub1")->callback(c1)->preparse_callback(pc1)->immediate_callback();
Expand All @@ -523,6 +524,7 @@ app.preparse_callback( pa1);
... A bunch of other options
```

Then the command line is given as

```
Expand All @@ -534,8 +536,8 @@ program --opt1 opt1_val sub1 --sub1opt --sub1optb val sub2 --sub2opt sub1 --sub
* c1 will be called when the `sub2` command is encountered
* pc2 will be called with value of 6 after the sub2 command is encountered.
* c1 will be called again after the second sub2 command is encountered
* ac will be called after completing the parse
* c2 will be called once after processing all arguments
* ac will be called after completing the parse and all lower level callbacks have been executed

A subcommand is considered terminated when one of the following conditions are met.
1. There are no more arguments to process
Expand All @@ -549,20 +551,26 @@ If the `immediate_callback` flag is set then all contained options are processed

#### Option groups 🚧

The subcommand method
The subcommand method

```cpp
.add_option_group(name,description)
```

Will create an option Group, and return a pointer to it. An option group allows creation of a collection of options, similar to the groups function on options, but with additional controls and requirements. They allow specific sets of options to be composed and controlled as a collective. For an example see [range test](./tests/ranges.cpp). Option groups are a specialization of an App so all [functions](#subcommand-options) that work with an App also work on option groups. Options can be created as part of an option group using the add functions just like a subcommand, or previously created options can be added through

```cpp
ogroup->add_option(option_pointer)
```
```cpp
ogroup->add_options(option_pointer)
```

```cpp
ogroup->add_options(option1,option2,option3,...)
```
The option pointers used in this function must be options defined in the parent application of the option group otherwise an error will be generated.
Options in an option group are searched for a command line match after any options in the main app, so any positionals in the main app would be matched first. So care must be taken to make sure of the order when using positional arguments and option groups.
Option groups work well with `excludes` and `require_options` methods, as an Application will treat an option group as a single option for the purpose of counting and requirements. Option groups allow specifying requirements such as requiring 1 of 3 options in one group and 1 of 3 options in a different group. Option groups can contain other groups as well. Disabling an option group will turn off all options within the group.
Expand Down Expand Up @@ -601,7 +609,7 @@ arguments, use `.config_to_str(default_also=false, prefix="", write_description=

### Inheriting defaults

Many of the defaults for subcommands and even options are inherited from their creators. The inherited default values for subcommands are `allow_extras`, `prefix_command`, `ignore_case`, 🆕 `ignore_underscore`, `fallthrough`, `group`, `footer`, and maximum number of required subcommands. The help flag existence, name, and description are inherited, as well.
Many of the defaults for subcommands and even options are inherited from their creators. The inherited default values for subcommands are `allow_extras`, `prefix_command`, `ignore_case`, 🆕 `ignore_underscore`, `fallthrough`, `group`, `footer`,`immediate_callback` and maximum number of required subcommands. The help flag existence, name, and description are inherited, as well.

Options have defaults for `group`, `required`, `multi_option_policy`, `ignore_case`, 🆕 `ignore_underscore`, 🚧 `delimiter`, and 🚧 `disable_flag_override`. To set these defaults, you should set the `option_defaults()` object, for example:

Expand Down
76 changes: 49 additions & 27 deletions include/CLI/App.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ class App {
bool pre_parse_called_{false};

/// Flag indicating that the callback for the subcommand should be executed immediately on parse completion which is
/// before help or ini files are processed.
/// before help or ini files are processed. INHERITABLE
bool immediate_callback_{false};

/// This is a function that runs prior to the start of parsing
Expand Down Expand Up @@ -246,6 +246,7 @@ class App {
allow_extras_ = parent_->allow_extras_;
allow_config_extras_ = parent_->allow_config_extras_;
prefix_command_ = parent_->prefix_command_;
immediate_callback_ = parent_->immediate_callback_;
ignore_case_ = parent_->ignore_case_;
ignore_underscore_ = parent_->ignore_underscore_;
fallthrough_ = parent_->fallthrough_;
Expand Down Expand Up @@ -320,7 +321,7 @@ class App {
return this;
}

/// Set the subcommand to be enabled by default, so on clear(), at the start of each parse it is enabled(not
/// Set the subcommand to be enabled by default, so on clear(), at the start of each parse it is enabled (not
/// disabled)
App *enabled_by_default(bool enable = true) {
enabled_by_default_ = enable;
Expand Down Expand Up @@ -1778,15 +1779,26 @@ class App {
app->_configure();
}
}
/// Internal function to run (App) callback, top down
/// Internal function to run (App) callback, bottom up
void run_callback() {
pre_callback();
if(callback_ && (parsed_ > 0))
callback_();
// run the callbacks for the received subcommands
for(App *subc : get_subcommands()) {
if((subc->get_name().empty()) || (!subc->immediate_callback_))
if(!subc->immediate_callback_)
subc->run_callback();
}
// now run callbacks for option_groups
for(auto &subc : subcommands_) {
if(!subc->immediate_callback_ && subc->name_.empty() && subc->count_all() > 0) {
subc->run_callback();
}
}
// finally run the main callback
if(callback_ && (parsed_ > 0)) {
if(!name_.empty() || count_all() > 0) {
callback_();
}
}
}

/// Check to see if a subcommand is valid. Give up immediately if subcommand max has been reached.
Expand Down Expand Up @@ -1817,7 +1829,7 @@ class App {
return detail::Classifier::SHORT;
if((allow_windows_style_options_) && (detail::split_windows_style(current, dummy1, dummy2)))
return detail::Classifier::WINDOWS;
if((current == "++") && (!name_.empty()))
if((current == "++") && !name_.empty())
return detail::Classifier::SUBCOMMAND_TERMINATOR;
return detail::Classifier::NONE;
}
Expand Down Expand Up @@ -1872,22 +1884,34 @@ class App {
}

for(App_p &sub : subcommands_) {
if((sub->get_name().empty()) || (!sub->immediate_callback_))
if(sub->get_name().empty() || !sub->immediate_callback_)
sub->_process_env();
}
}

/// Process callbacks. Runs on *all* subcommands.
void _process_callbacks() {

for(App_p &sub : subcommands_) {
// process the priority option_groups first
if(sub->get_name().empty() && sub->immediate_callback_) {
if(sub->count_all() > 0) {
sub->_process_callbacks();
sub->run_callback();
}
}
}

for(const Option_p &opt : options_) {
if(opt->count() > 0 && !opt->get_callback_run()) {
opt->run_callback();
}
}

for(App_p &sub : subcommands_) {
if((sub->get_name().empty()) || (!sub->immediate_callback_))
if(!sub->immediate_callback_) {
sub->_process_callbacks();
}
}
}

Expand Down Expand Up @@ -1979,13 +2003,12 @@ class App {
for(App_p &sub : subcommands_) {
if(sub->disabled_)
continue;
if((sub->name_.empty()) && (sub->count_all() > 0)) {
if(sub->name_.empty() && sub->count_all() > 0) {
++used_options;
}
}

if((require_option_min_ > used_options) ||
((require_option_max_ > 0) && (require_option_max_ < used_options))) {
if(require_option_min_ > used_options || (require_option_max_ > 0 && require_option_max_ < used_options)) {
auto option_list = detail::join(options_, [](const Option_p &ptr) { return ptr->get_name(false, true); });
if(option_list.compare(0, 10, "-h,--help,") == 0) {
option_list.erase(0, 10);
Expand All @@ -2001,25 +2024,25 @@ class App {
for(App_p &sub : subcommands_) {
if(sub->disabled_)
continue;
if((sub->name_.empty()) && (sub->required_ == false)) {
if(sub->name_.empty() && sub->required_ == false) {
if(sub->count_all() == 0) {
if((require_option_min_ > 0) && (require_option_min_ <= used_options)) {
if(require_option_min_ > 0 && require_option_min_ <= used_options) {
continue;
// if we have met the requirement and there is nothing in this option group skip checking
// requirements
}
if((require_option_max_ > 0) && (used_options >= require_option_min_)) {
if(require_option_max_ > 0 && used_options >= require_option_min_) {
continue;
// if we have met the requirement and there is nothing in this option group skip checking
// requirements
}
}
}
if((sub->count() > 0) || (sub->name_.empty())) {
if(sub->count() > 0 || sub->name_.empty()) {
sub->_process_requirements();
}

if((sub->required_) && (sub->count_all() == 0)) {
if(sub->required_ && sub->count_all() == 0) {
throw(CLI::RequiredError(sub->get_display_name()));
}
}
Expand Down Expand Up @@ -2225,14 +2248,13 @@ class App {
}
}
}
/// let the parent deal with it if possible
// let the parent deal with it if possible
if(parent_ != nullptr && fallthrough_)
return _get_fallthrough_parent()->_parse_positional(args);

/// Try to find a local subcommand that is repeated
auto com = _find_subcommand(args.back(), true, false);
if((com != nullptr) &&
((require_subcommand_max_ == 0) || (require_subcommand_max_ > parsed_subcommands_.size()))) {
if(com != nullptr && (require_subcommand_max_ == 0 || require_subcommand_max_ > parsed_subcommands_.size())) {
args.pop_back();
com->_parse(args);
return true;
Expand All @@ -2241,16 +2263,16 @@ class App {
/// subcommand in a broader way, if one exists let the parent deal with it
auto parent_app = (parent_ != nullptr) ? _get_fallthrough_parent() : this;
com = parent_app->_find_subcommand(args.back(), true, false);
if((com != nullptr) && ((com->parent_->require_subcommand_max_ == 0) ||
(com->parent_->require_subcommand_max_ > com->parent_->parsed_subcommands_.size()))) {
if(com != nullptr && (com->parent_->require_subcommand_max_ == 0 ||
com->parent_->require_subcommand_max_ > com->parent_->parsed_subcommands_.size())) {
return false;
}

if(positionals_at_end_) {
throw CLI::ExtrasError(args);
}
/// If this is an option group don't deal with it
if((parent_ != nullptr) && (name_.empty())) {
if(parent_ != nullptr && name_.empty()) {
return false;
}
/// We are out of other options this goes to missing
Expand All @@ -2270,15 +2292,15 @@ class App {
/// subcommands be ignored
App *_find_subcommand(const std::string &subc_name, bool ignore_disabled, bool ignore_used) const noexcept {
for(const App_p &com : subcommands_) {
if((com->disabled_) && (ignore_disabled))
if(com->disabled_ && ignore_disabled)
continue;
if(com->get_name().empty()) {
auto subc = com->_find_subcommand(subc_name, ignore_disabled, ignore_used);
if(subc != nullptr) {
return subc;
}
} else if(com->check_name(subc_name)) {
if((!*com) || (!ignore_used))
if((!*com) || !ignore_used)
return com.get();
}
}
Expand Down Expand Up @@ -2353,7 +2375,7 @@ class App {
// Option not found
if(op_ptr == std::end(options_)) {
for(auto &subc : subcommands_) {
if((subc->name_.empty()) && (!(subc->disabled_))) {
if(subc->name_.empty() && !subc->disabled_) {
if(subc->_parse_arg(args, current_type)) {
if(!subc->pre_parse_called_) {
subc->_trigger_pre_parse(args.size());
Expand All @@ -2366,7 +2388,7 @@ class App {
if(parent_ != nullptr && fallthrough_)
return _get_fallthrough_parent()->_parse_arg(args, current_type);
// don't capture missing if this is a nameless subcommand
if((parent_ != nullptr) && (name_.empty())) {
if(parent_ != nullptr && name_.empty()) {
return false;
}
// Otherwise, add to missing
Expand Down
2 changes: 1 addition & 1 deletion include/CLI/Option.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -667,7 +667,7 @@ class Option : public OptionBase<Option> {
// Run the validators (can change the string)
if(!validators_.empty()) {
for(std::string &result : results_)
for(const std::function<std::string(std::string &)> &vali : validators_) {
for(const auto &vali : validators_) {
std::string err_msg;

try {
Expand Down
8 changes: 4 additions & 4 deletions include/CLI/StringTools.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,12 +171,12 @@ inline std::ostream &format_help(std::ostream &out, std::string name, std::strin
}

/// Verify the first character of an option
template <typename T> bool valid_first_char(T c) { return std::isalnum(c, std::locale()) || c == '_'; }
template <typename T> bool valid_first_char(T c) {
return std::isalnum(c, std::locale()) || c == '_' || c == '?' || c == '@';
}

/// Verify following characters of an option
template <typename T> bool valid_later_char(T c) {
return std::isalnum(c, std::locale()) || c == '_' || c == '.' || c == '-';
}
template <typename T> bool valid_later_char(T c) { return valid_first_char(c) || c == '.' || c == '-'; }

/// Verify an option name
inline bool valid_name_string(const std::string &str) {
Expand Down
3 changes: 3 additions & 0 deletions tests/CreationTest.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,7 @@ TEST_F(TApp, SubcommandDefaults) {
// Initial defaults
EXPECT_FALSE(app.get_allow_extras());
EXPECT_FALSE(app.get_prefix_command());
EXPECT_FALSE(app.get_immediate_callback());
EXPECT_FALSE(app.get_ignore_case());
EXPECT_FALSE(app.get_ignore_underscore());
#ifdef _WIN32
Expand All @@ -487,6 +488,7 @@ TEST_F(TApp, SubcommandDefaults) {

app.allow_extras();
app.prefix_command();
app.immediate_callback();
app.ignore_case();
app.ignore_underscore();
#ifdef _WIN32
Expand All @@ -505,6 +507,7 @@ TEST_F(TApp, SubcommandDefaults) {
// Initial defaults
EXPECT_TRUE(app2->get_allow_extras());
EXPECT_TRUE(app2->get_prefix_command());
EXPECT_TRUE(app2->get_immediate_callback());
EXPECT_TRUE(app2->get_ignore_case());
EXPECT_TRUE(app2->get_ignore_underscore());
#ifdef _WIN32
Expand Down
11 changes: 11 additions & 0 deletions tests/HelpTest.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,17 @@ TEST(THelp, OnlyOneHelp) {
EXPECT_THROW(app.parse(input), CLI::ExtrasError);
}

TEST(THelp, MultiHelp) {
CLI::App app{"My prog"};

// It is not supported to have more than one help flag, last one wins
app.set_help_flag("--help,-h,-?", "No short name allowed");
app.allow_windows_style_options();

std::vector<std::string> input{"/?"};
EXPECT_THROW(app.parse(input), CLI::CallForHelp);
}

TEST(THelp, OnlyOneAllHelp) {
CLI::App app{"My prog"};

Expand Down
Loading

0 comments on commit 3777889

Please sign in to comment.