![]() |
Scarab
v2.4.9
Project 8 C++ Utility Library
|
Primary application class. More...
#include <application.hh>
Public Member Functions | |
main_app () | |
virtual | ~main_app () |
virtual void | pre_callback () |
virtual void | do_config_stage_1 () |
Load default values. More... | |
virtual void | do_config_stage_2 () |
Load the config file. More... | |
virtual void | do_config_stage_3 () |
Load the directly-addressed non-option arguments. More... | |
virtual void | do_config_stage_4 () |
Load the application-specific options. More... | |
void | set_version (version_semantic *a_ver) |
mv_referrable (param_node, master_config) | |
Master configuration tree for the application. More... | |
mv_referrable (param_node, default_config) | |
Default configuration values. More... | |
mv_referrable_const (std::string, config_filename) | |
Configuration file name. More... | |
mv_accessible (unsigned, global_verbosity) | |
Global verbosity value. More... | |
mv_referrable (param_node, nonoption_kw_args) | |
Keyword configuration values coming from the command line, in the form: config.address=value. More... | |
mv_referrable (param_array, nonoption_ord_args) | |
Ordered configuration values coming in an application-specific order from the command line, in the form: value. More... | |
mv_referrable (param_node, app_options) | |
Application-specific options that are specified using add_config_option() functions. More... | |
mv_referrable (std::vector< std::shared_ptr< app_option_holder > >, app_option_holders) | |
Store the app option holder structs from this app and any subcommands. More... | |
![]() | |
config_decorator (main_app *a_main, app *a_this_app) | |
config_decorator (const config_decorator &)=delete | |
config_decorator (config_decorator &&)=delete | |
virtual | ~config_decorator () |
config_decorator & | operator= (const config_decorator &)=delete |
config_decorator & | operator= (config_decorator &&)=delete |
main_app * | main () const |
app * | this_app () const |
config_decorator * | add_config_subcommand (std::string a_subcommand_name, std::string a_description="") |
Add a subcommand that is linked to a particular main_app and can create options that modify that main_app's master config. More... | |
template<typename T , CLI::enable_if_t< ! CLI::is_vector< T >::value, CLI::detail::enabler > = CLI::detail::dummy> | |
CLI::Option * | add_config_option (std::string a_name, std::string a_master_config_addr, std::string a_description="") |
Add an option that gets automatically added to the master config of a main_app. More... | |
template<typename T , CLI::enable_if_t< ! CLI::is_vector< T >::value, CLI::detail::enabler > = CLI::detail::dummy> | |
CLI::Option * | add_config_multi_option (std::string a_name, std::string a_master_config_addr, std::string a_description="") |
Add an option that gets automatically added to the master config of a main_app. More... | |
template<typename T , CLI::enable_if_t< std::is_integral< T >::value &&! CLI::is_bool< T >::value, CLI::detail::enabler > = CLI::detail::dummy> | |
CLI::Option * | add_config_flag (std::string a_name, std::string a_master_config_addr, std::string a_description="") |
template<typename T , CLI::enable_if_t< CLI::is_bool< T >::value, CLI::detail::enabler > = CLI::detail::dummy> | |
CLI::Option * | add_config_flag (std::string a_name, std::string a_master_config_addr, std::string a_description="") |
Additional Inherited Members | |
![]() | |
using | conf_dec_ptr_t = std::unique_ptr< config_decorator > |
![]() | |
main_app * | f_main |
app * | f_this |
std::vector< conf_dec_ptr_t > | f_subcommand_decorators |
Primary application class.
This class is designed to provide an entry point for an application, and to setup the application's configuration based on information provided by the user at the command line. The application's master "configuration" is in the form of a scarab::param_node object that takes input from default values, a configuration file, directly-addressed arguments, and application-specific options. The `main_app` class uses and makes available all of the functionality of the CLI11 library, and in particular it directly extends the CLI::App class. Links to documentation on how to use CLI11 are provided below. Basic usage (customized from CLI11's basic usage): int main( int argc, char **argv ) { main_app the_main;
Add new options/flags here
Set the default config file the_main.default_config() = t_default_config;
This includes calling application::pre_callback() to finalize the global config CLI11_PARSE( the_main, argc, argv );
return 0; }
Notes on specifying and using command-line arguments:
There are two main types of command-line arguments:
-b [value]
, --broker [value]
, or -r
(flag with no value)Options need to be specified in an application (i.e. CLI11 needs to know about them at compile time). All of the functionality of CLI11 is available when using main_app
, so you can create options and flags (options with no values) that do not affect the configuration. Alternatively, main_app
provides the ability to define options that are automatically added to the configuration (see below).
Notes for setting the configuration in an application:
Stages for setting the configuration
In stage 3, arguments can have two forms:
nonoption_kw_args
nonoption_ord_args
Application specified options (stage 4) are merged with the config and are separately accessible as app_options
. They have to be specified in the application using add_config_option()
, which will map the option name to an address in the master config.
The functionality for each stage is implemented in its own virtual function, so a subclass can customize the procedure as needed.
Example: > my_app -c config.yaml –an_opt 20 nested.value="hello"
What happens:
config.yaml
will be parsed and merged with the defaultsnested { value: "hello" }
will be merged with the master configan_opt
will set something specified in the config to 20See CLI11 documentation for the CLI::App class:
There are several test examples that can be used as useful references on different ways that applications can be setup. You'll find them in the scarab/library/test directory.
Definition at line 252 of file application.hh.
main_app | ( | ) |
Definition at line 44 of file application.cc.
|
virtual |
Definition at line 69 of file application.cc.
|
virtual |
Load default values.
Definition at line 106 of file application.cc.
|
virtual |
Load the config file.
Definition at line 114 of file application.cc.
|
virtual |
Load the directly-addressed non-option arguments.
Definition at line 137 of file application.cc.
|
virtual |
Load the application-specific options.
Definition at line 145 of file application.cc.
mv_accessible | ( | unsigned | , |
global_verbosity | |||
) |
Global verbosity value.
mv_referrable | ( | param_node | , |
master_config | |||
) |
Master configuration tree for the application.
mv_referrable | ( | param_node | , |
default_config | |||
) |
Default configuration values.
mv_referrable | ( | param_node | , |
nonoption_kw_args | |||
) |
Keyword configuration values coming from the command line, in the form: config.address=value.
mv_referrable | ( | param_array | , |
nonoption_ord_args | |||
) |
Ordered configuration values coming in an application-specific order from the command line, in the form: value.
mv_referrable | ( | param_node | , |
app_options | |||
) |
Application-specific options that are specified using add_config_option() functions.
mv_referrable | ( | std::vector< std::shared_ptr< app_option_holder > > | , |
app_option_holders | |||
) |
Store the app option holder structs from this app and any subcommands.
mv_referrable_const | ( | std::string | , |
config_filename | |||
) |
Configuration file name.
|
virtual |
parses positional arguments into the global config called after parsing, before running callbacks
Definition at line 78 of file application.cc.
void set_version | ( | version_semantic * | a_ver | ) |
Definition at line 73 of file application.cc.