Scarab  v2.4.8
Project 8 C++ Utility Library
Public Member Functions | List of all members
main_app Class Reference

Primary application class. More...

#include <application.hh>

Inheritance diagram for main_app:
Inheritance graph

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...
 
- Public Member Functions inherited from config_decorator
 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_decoratoroperator= (const config_decorator &)=delete
 
config_decoratoroperator= (config_decorator &&)=delete
 
main_appmain () const
 
appthis_app () const
 
config_decoratoradd_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

- Protected Types inherited from config_decorator
using conf_dec_ptr_t = std::unique_ptr< config_decorator >
 
- Protected Attributes inherited from config_decorator
main_appf_main
 
appf_this
 
std::vector< conf_dec_ptr_tf_subcommand_decorators
 

Detailed Description

Primary application class.

Author
N. S. Oblath
 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:

  1. "Options" are named arguments. On the command line they look like -b [value], --broker [value], or -r (flag with no value)
  2. "Non-option" arguments have no name, and typically rely on the order they fall on the command line to interpret their meaning.

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

  1. Default options
  2. Config file
  3. Non-option arguments
  4. Application-specified options

In stage 3, arguments can have two forms:

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:

  1. my_app will have default values hard-coded
  2. File config.yaml will be parsed and merged with the defaults
  3. Configuration nested { value: "hello" } will be merged with the master config
  4. Option an_opt will set something specified in the config to 20

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

Constructor & Destructor Documentation

◆ main_app()

main_app ( )

Definition at line 44 of file application.cc.

◆ ~main_app()

~main_app ( )
virtual

Definition at line 69 of file application.cc.

Member Function Documentation

◆ do_config_stage_1()

void do_config_stage_1 ( )
virtual

Load default values.

Definition at line 106 of file application.cc.

◆ do_config_stage_2()

void do_config_stage_2 ( )
virtual

Load the config file.

Definition at line 114 of file application.cc.

◆ do_config_stage_3()

void do_config_stage_3 ( )
virtual

Load the directly-addressed non-option arguments.

Definition at line 137 of file application.cc.

◆ do_config_stage_4()

void do_config_stage_4 ( )
virtual

Load the application-specific options.

Definition at line 145 of file application.cc.

◆ mv_accessible()

mv_accessible ( unsigned  ,
global_verbosity   
)

Global verbosity value.

◆ mv_referrable() [1/6]

mv_referrable ( param_node  ,
master_config   
)

Master configuration tree for the application.

◆ mv_referrable() [2/6]

mv_referrable ( param_node  ,
default_config   
)

Default configuration values.

◆ mv_referrable() [3/6]

mv_referrable ( param_node  ,
nonoption_kw_args   
)

Keyword configuration values coming from the command line, in the form: config.address=value.

◆ mv_referrable() [4/6]

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() [5/6]

mv_referrable ( param_node  ,
app_options   
)

Application-specific options that are specified using add_config_option() functions.

◆ mv_referrable() [6/6]

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

mv_referrable_const ( std::string  ,
config_filename   
)

Configuration file name.

◆ pre_callback()

void pre_callback ( )
virtual

parses positional arguments into the global config called after parsing, before running callbacks

Definition at line 78 of file application.cc.

◆ set_version()

void set_version ( version_semantic a_ver)

Definition at line 73 of file application.cc.


The documentation for this class was generated from the following files: