Options

Description

Common class to interpret the command line, based on Boost Program Options.

Options may also be partly provided via a configuration file. Additional options to split the input file are also possible. Minimal working example:

namespace DT = Darwin::Tools;
DT::Options options("Global description.", DT::config | DT::split);
options.input ("input" , &input , "input ROOT file" );
options.output("output", &output, "output ROOT file");
options.arg<int>("myArg", "correction.here", "my description");
options.args("allOtherArgs", "correction.there.list", "garbage collector");
auto const& config = options(argc, argv);

where the config is a Boost Property Tree. A one-liner is even possible:

auto const& config = DT::Options("Global description.", DT::config | DT::split).input("input", &input, "input ROOT file").output("output", &output, "output ROOT file").arg<int>("myArg", "correction.here", "my description").args("allOtherArgs", "correction.there.list", "garbage collector")(argc, argv);

The order matters only for the positional options, where input(s) should be given first, then output(s), then additional positional options. The position of explicit options (e.g. -v) does not matter. Options::args may be used as a garbage collector for extra positional options.

#include <Options.h>

Collaboration diagram for Options:

Public Member Functions
	Options (const std::string &, int=none, const char *commit=DARWIN_GIT_COMMIT, const char *example=DARWIN_EXAMPLE)
	Options ()=delete
	~Options ()
Options &	input (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
Options &	inputs (const char *, std::vector< std::filesystem::path > *, const char *, const std::vector< std::string > &={".root", ".xml"})
Options &	output (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
template<typename T >
Options &	arg (const char *name, const char *configpath, const char *desc)
Options &	args (const char *name, const char *configpath, const char *desc)
const boost::property_tree::ptree &	operator() (int, const char *const [])
auto	commit () const
int	steering () const
std::vector< std::filesystem::path >	plugins () const
std::pair< unsigned, unsigned >	slice () const
	Options (const std::string &, int=none, const char *commit=DARWIN_GIT_COMMIT, const char *example=DARWIN_EXAMPLE)
	Options ()=delete
	~Options ()
Options &	input (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
Options &	inputs (const char *, std::vector< std::filesystem::path > *, const char *, const std::vector< std::string > &={".root", ".xml"})
Options &	output (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
template<typename T >
Options &	arg (const char *name, const char *configpath, const char *desc)
Options &	args (const char *name, const char *configpath, const char *desc)
const boost::property_tree::ptree &	operator() (int, const char *const [])
auto	commit () const
int	steering () const
std::vector< std::filesystem::path >	plugins () const
std::pair< unsigned, unsigned >	slice () const

Static Public Member Functions
static std::string	parse_env_var (std::string)
static std::string	parse_env_var (const char *p)
static std::filesystem::path	parse_env_var (const std::filesystem::path &p)
static void	parse_config (boost::property_tree::ptree &, std::string="")
static std::string	parse_env_var (std::string)
static std::string	parse_env_var (const char *p)
static std::filesystem::path	parse_env_var (const std::filesystem::path &p)
static void	parse_config (boost::property_tree::ptree &, std::string="")

Static Public Attributes
static std::string	full_cmd

Private Types
enum	Stage {   Input, Output, Arg, Args,   Input, Output, Arg, Args }
enum	Stage {   Input, Output, Arg, Args,   Input, Output, Arg, Args }

Private Member Functions
void	parse_helper (int, const char *const [])
void	parse_common (int, const char *const [])
void	parse_custom (int, const char *const [])
Options &	set (const char *, const boost::program_options::value_semantic *, const char *)
template<typename T >
std::function< void(T)>	put (const std::string &configpath)
bool	allow_unregistered () const
std::string	exec (const std::string &)
void	parse_helper (int, const char *const [])
void	parse_common (int, const char *const [])
void	parse_custom (int, const char *const [])
Options &	set (const char *, const boost::program_options::value_semantic *, const char *)
template<typename T >
std::function< void(T)>	put (const std::string &configpath)
bool	allow_unregistered () const
std::string	exec (const std::string &)

Static Private Member Functions
static void	check_input (const std::filesystem::path &)
static void	check_output (const std::filesystem::path &)
static void	check_input (const std::filesystem::path &)
static void	check_output (const std::filesystem::path &)

Private Attributes
boost::program_options::options_description	hidden
boost::program_options::options_description	helper
boost::program_options::options_description	common
boost::program_options::options_description	custom
boost::program_options::positional_options_description	pos_hide
boost::property_tree::ptree	pt_conf
const std::filesystem::path	example
std::filesystem::path	config_file
const std::string	tutorial
std::string	synopsis
std::vector< std::string >	names
std::vector< std::string >	configpaths
std::optional< unsigned >	registered
Stage	stage
int	params
const std::string	m_commit
int	steer
int	j
int	k
std::vector< std::filesystem::path >	plugin_paths
std::vector< std::vector< std::string > >	inputExt
std::vector< std::vector< std::string > >	outputExt

Static Private Attributes
static std::filesystem::path	prefix

Member Enumeration Documentation

Stage [1/2]

enum Stage

private

Enumerator
Input	first the inputs
Output	then the outputs (inputs are no longer allowed)
Arg	then the registered arguments (inputs and outputs no longer allowed)
Args	finally the remaining arguments / garbage collector (must be very last)
Input	first the inputs
Output	then the outputs (inputs are no longer allowed)
Arg	then the registered arguments (inputs and outputs no longer allowed)
Args	finally the remaining arguments / garbage collector (must be very last)

               {
        Input, 
        Output, 
        Arg, 
        Args 
    }; 

Stage [2/2]

enum Stage

private

Enumerator
Input	first the inputs
Output	then the outputs (inputs are no longer allowed)
Arg	then the registered arguments (inputs and outputs no longer allowed)
Args	finally the remaining arguments / garbage collector (must be very last)
Input	first the inputs
Output	then the outputs (inputs are no longer allowed)
Arg	then the registered arguments (inputs and outputs no longer allowed)
Args	finally the remaining arguments / garbage collector (must be very last)

               {
        Input, 
        Output, 
        Arg, 
        Args 
    }; 

Constructor & Destructor Documentation

Options() [1/4]

Options	(	const std::string &	tuto,
		int	pars = none,
		const char *	commit = DARWIN_GIT_COMMIT,
		const char *	example = DARWIN_EXAMPLE
	)

Constructor:

• contains a parser for the help itself
• contains a parser for the options, like config file and verbosity
• and contains a parser for the input, output, and any other option as positional arguments

Parameters

tuto	description, to be displayed in the helper
pars	flags for explicit, generic command options (see enum)
commit	git commit for --git
example	path to example

    : hidden{"Hidden"}, helper{"Helper"}, common{"Options"}, custom{"Positional options"},
      example(example ? example : DARWIN "/test/example.info"),
      tutorial(tuto), stage(Stage::Input), params(pars),
      m_commit(commit ? commit : DARWIN_VERSION),
      steer(0), j(1), k(0)
{
    hidden.add_options()
        ("prefix,%", po::value<fs::path>(&prefix), "Prefix command, `parallel` or `submit` (for history only)");
 
    // first the helper
    helper.add_options()
        ("help,h", "Help screen (what you are seeing right now)")
        ("tutorial,t", "Brief description of the command's purpose")
        ("git,g", "Commit hash of this executable at compilation time")
        ("input_ext,i", "Expected extension for input(s) (one line for each input)")
        ("output_ext,o", "Expected extension for output(s) (one line for each output)");
    if (params & config) helper.add_options()
        ("example,e", "Print config example");
 
    // then the running options
    common.add_options()
        ("verbose,v", po::bool_switch()->default_value(false),
         "Enable debug mode (typically in slow operations such as the event loop)")
        ("mute,m", po::bool_switch()->default_value(false)->notifier(set_mute),
         "Disable standard output stream");
    if (params & config) common.add_options()
        ("config,c", po::value<fs::path>(&config_file),
         "Configuration file in INFO, JSON, or XML format");
    if (params & split) common.add_options()
        ("nSplit,j", po::value<int>(&j)->default_value(j), "Number of slices")
        ("nNow,k"  , po::value<int>(&k)->default_value(k), "Index of current slice");
    if (params & (fill | Friend)) common.add_options()
        ("fill,f", po::bool_switch()->default_value(false), "Enable `TTree::Fill()`");
    if (params & Friend) common.add_options()
        ("Friend,F", po::bool_switch()->default_value(false),
         "Use `TTree` friends instead of cloning the whole input `TTree`");
    if (params & syst) common.add_options()
        ("syst,s", po::bool_switch()->default_value(false),
         "Enable systematic variations");
    if (params & plugin) common.add_options()
        ("plugin,p", po::value<vector<fs::path>>(&plugin_paths)->multitoken()->composing(),
         "Specify a plugin to run before filling the tree (multiple use is allowed)");
 
    // positional arguments should be defined by hand by the user
    // with the various public members
}

Options() [2/4]

Options ( )

delete

No default constructor is allowed.

~Options() [1/2]

~Options ( )

inline

Destructor.

{ if (steer & verbose) std::cout << "Options: destroying options" << std::endl; }

Options() [3/4]

Options	(	const std::string &	,
		int	= none,
		const char *	commit = DARWIN_GIT_COMMIT,
		const char *	example = DARWIN_EXAMPLE
	)

Constructor:

• contains a parser for the help itself
• contains a parser for the options, like config file and verbosity
• and contains a parser for the input, output, and any other option as positional arguments

Parameters

commit	git commit for --git
example	path to example

Options() [4/4]

Options ( )

delete

No default constructor is allowed.

~Options() [2/2]

~Options ( )

inline

Destructor.

{ if (steer & verbose) std::cout << "Options: destroying options" << std::endl; }

Member Function Documentation

allow_unregistered() [1/2]

bool allow_unregistered ( ) const

inlineprivate

Returns

true if Options::registered has been initialised.

{ return bool(registered); }

allow_unregistered() [2/2]

bool allow_unregistered ( ) const

inlineprivate

Returns

true if Options::registered has been initialised.

{ return bool(registered); }

arg() [1/2]

Options& arg ( const char *  name, const char *  configpath, const char *  desc  )

inline

Member to add an argument. It can be called several times in a row. Each argument may be provided via the configuration file too.

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	name of the option, will be shown in helper
configpath	path in config
desc	description, shown in helper too

    {
        if (stage > Stage::Arg)
            BOOST_THROW_EXCEPTION(std::runtime_error(
                        "Not possible to add another argument at this stage"));
        stage = Stage::Arg;
 
        names.push_back(name);
        configpaths.push_back(configpath);
        const boost::program_options::value_semantic * s =
            boost::program_options::value<T>()->notifier(put<T>(configpath));
        return set(name, s, desc);
    }

arg() [2/2]

Options& arg ( const char *  name, const char *  configpath, const char *  desc  )

inline

Member to add an argument. It can be called several times in a row. Each argument may be provided via the configuration file too.

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	name of the option, will be shown in helper
configpath	path in config
desc	description, shown in helper too

    {
        if (stage > Stage::Arg)
            BOOST_THROW_EXCEPTION(std::runtime_error(
                        "Not possible to add another argument at this stage"));
        stage = Stage::Arg;
 
        names.push_back(name);
        configpaths.push_back(configpath);
        const boost::program_options::value_semantic * s =
            boost::program_options::value<T>()->notifier(put<T>(configpath));
        return set(name, s, desc);
    }

args() [1/2]

Options& args	(	const char *	name,
		const char *	configpath,
		const char *	desc
	)

Member to collect any addition arguments provided in command line. It should be called maximum once. The additional options will be collected as a list of strings.

Parameters

name	generic name for unregistered options
configpath	path in config.
desc	description, shown in helper too

args() [2/2]

Options & args	(	const char *	name,
		const char *	configpath,
		const char *	desc
	)

Member to collect any addition arguments provided in command line. It should be called maximum once. The additional options will be collected as a list of strings.

Parameters

name	generic name for unregistered options
configpath	path in config.
desc	description, shown in helper too

{
    if (stage >= Stage::Args)
        BOOST_THROW_EXCEPTION(runtime_error("Only one garbage collector is possible"));
    stage = Stage::Args;
 
    synopsis += " [" + string(name) + "...]";
    configpaths.push_back(configpath);
 
    registered = pos_hide.max_total_count();
    const po::value_semantic * s =
        po::value<vector<string>>()->multitoken()->zero_tokens();
    custom.add_options()(name, s, desc);
    pos_hide.add(name, -1);
 
    return *this;
}

check_input() [1/2]

void check_input ( const std::filesystem::path &  input )

staticprivate

Function used by Boost Program Options to check if the file does exist, and if yes, if it is readable and readable.

Parameters

input

path to input

{
    if (!fs::exists(input))
        BOOST_THROW_EXCEPTION(fs::filesystem_error("Bad input", input,
                    make_error_code(errc::no_such_file_or_directory)));
 
    full_cmd += ' ' + fs::canonical(input).string();
 
    if ((fs::status(input).permissions() & fs::perms::owner_read) == fs::perms::none)
        BOOST_THROW_EXCEPTION(fs::filesystem_error("Input exists but cannot be read",
                    input, make_error_code(errc::permission_denied)));
}

check_input() [2/2]

static void check_input ( const std::filesystem::path &  )

staticprivate

Function used by Boost Program Options to check if the file does exist, and if yes, if it is readable and readable.

check_output() [1/2]

void check_output ( const std::filesystem::path &  output )

staticprivate

Function used by Boost Program Options to check if the file may already exist, and if yes, then if it is writable, and not a directory. (At this stage, the automatic naming of the output according to the name of the input should not happen. Such a thing should rather be done in the executable directly.)

Parameters

output

path to output

{
    fs::path outputHist = output;
    if (!prefix.empty() && !fs::is_directory(output)) outputHist.remove_filename();
    full_cmd += ' ' + outputHist.string();
 
    if (!fs::exists(output)) return;
 
    if ((fs::status(output).permissions() & fs::perms::owner_write)
                                         == fs::perms::none) {
        full_cmd.clear();
        BOOST_THROW_EXCEPTION(fs::filesystem_error(
                    "Output already exists and cannot be overwritten",
                    output, make_error_code(errc::permission_denied)));
    }
 
    if (fs::is_directory(output) && fs::equivalent(output,".")) {
        full_cmd.clear();
        BOOST_THROW_EXCEPTION(fs::filesystem_error("Not a valid output",
                    output, make_error_code(errc::invalid_argument)));
    }
    else if (output != "/dev/null")
        cerr << orange << "Warning: you are overwriting " << output << def << '\n';
}

check_output() [2/2]

static void check_output ( const std::filesystem::path &  )

staticprivate

Function used by Boost Program Options to check if the file may already exist, and if yes, then if it is writable, and not a directory. (At this stage, the automatic naming of the output according to the name of the input should not happen. Such a thing should rather be done in the executable directly.)

commit() [1/2]

auto commit ( ) const

inline

Git commit information.

{ return m_commit; }

commit() [2/2]

auto commit ( ) const

inline

Git commit information.

{ return m_commit; }

exec() [1/2]

std::string exec ( const std::string &  )

private

Returns

output from command given to shell

exec() [2/2]

std::string exec ( const std::string &  cmd )

private

Returns

output from command given to shell

Parameters

cmd	cmd to run in the shell

{
    string result;
    char buffer[128];
    cerr << red;
    FILE * pipe = popen(cmd.c_str(), "r");
    while (!feof(pipe))
        if (fgets(buffer, 128, pipe) != NULL)
            result += buffer;
    pclose(pipe);
    cerr << def;
    return result;
}

input() [1/2]

Options& input	(	const char *	,
		std::filesystem::path *	,
		const char *	,
		const std::vector< std::string > &	= {".root", ".xml"}
	)

expected file extension

Member to add an input. It can be called several times in a row. This option should always be provided from the command line, and never via the config file.

Returns

the object itself, so that the arguments can be given in a row.

input() [2/2]

Options & input	(	const char *	name,
		std::filesystem::path *	file,
		const char *	desc,
		const std::vector< std::string > &	ext = {".root", ".xml"}
	)

expected file extension

Member to add an input. It can be called several times in a row. This option should always be provided from the command line, and never via the config file.

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	name of the option, will be shown in helper
file	path pointer to file
desc	description, shown in helper too

{
    if (stage > Stage::Input)
        BOOST_THROW_EXCEPTION(runtime_error(
                    "Not possible to add another input at this stage"));
 
    inputExt.push_back(ext);
    const po::value_semantic * s =
        po::value<fs::path>(file)->notifier(check_input)->required();
    return set(name, s, desc);
}

inputs() [1/2]

Options& inputs	(	const char *	,
		std::vector< std::filesystem::path > *	,
		const char *	,
		const std::vector< std::string > &	= {".root", ".xml"}
	)

expected file extension

Member to add an undefined amount of input. It can be called only once. This option should always be provided from the command line, and never via the config file. There can be no garbage collector in addition.

Returns

the object itself, so that the arguments can be given in a row.

inputs() [2/2]

Options & inputs	(	const char *	name,
		std::vector< std::filesystem::path > *	files,
		const char *	desc,
		const std::vector< std::string > &	ext = {".root", ".xml"}
	)

expected file extension

Member to add an undefined amount of input. It can be called only once. This option should always be provided from the command line, and never via the config file. There can be no garbage collector in addition.

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	name of the options, will be shown in helper
files	paths to files
desc	description, shown in helper too

{
    if (stage > Stage::Input)
        BOOST_THROW_EXCEPTION(runtime_error(
                    "Not possible to add another input at this stage"));
 
    auto store = [files,this](const string& pathRegex) {
 
        const string& ls = exec("ls -1d " + pathRegex);
 
        vector<fs::path> paths;
        al::split(paths, ls, al::is_any_of("\n"), al::token_compress_on);
        for (fs::path const& p: paths) {
            if (!fs::exists(p)) continue;
            files->push_back(p);
        }
 
        if (files->empty()) {
            fs::path p = pathRegex;
            full_cmd.clear();
            BOOST_THROW_EXCEPTION(
                    fs::filesystem_error("No input file could be found", p,
                                    make_error_code(errc::no_such_file_or_directory)));
        }
 
        auto inputs = accumulate(files->begin(), files->end(), string(),
               [](string inputs, fs::path input) {
                            return inputs + fs::canonical(input).string() + ' '; });
        inputs.resize(inputs.size()-1);
        if (files->size() > 1)
            inputs = '"' + inputs + '"';
        full_cmd += ' ' + inputs;
    };
 
    inputExt.push_back(ext);
    const po::value_semantic * s =
        po::value<string>()->notifier(store)->required();
    string full_desc = desc;
    full_desc += " (use a regular expression, surrounded by quotation marks)";
    return set(name, s, full_desc.c_str());
}

operator()() [1/2]

const boost::property_tree::ptree& operator()	(	int	,
		const char * const	[]
	)

Unique parser accessible by the user of the class. It should be directly given argc and argv from the main function.

operator()() [2/2]

const boost::property_tree::ptree & operator()	(	int	argc,
		const char * const	argv[]
	)

Unique parser accessible by the user of the class. It should be directly given argc and argv from the main function.

{
    pt_conf.clear();
    full_cmd.clear();
    prefix.clear();
    plugin_paths.clear();
 
    try {
        parse_helper(argc, argv);
        parse_common(argc, argv);
        parse_custom(argc, argv);
        parse_config(pt_conf);
 
        if (steer & split && j > 1) full_cmd += " -j " + to_string(j);
        if (steer & syst          ) full_cmd += " -s";
        if      (steer & Friend   ) full_cmd += " -F";
        else if (steer & fill     ) full_cmd += " -f";
 
        for (fs::path& p: plugin_paths) {
            if (fs::exists(p))
                p = fs::canonical(p);
            // else, at this stage, it is expected to be found via the environment
            full_cmd += " -p " + p.string();
        }
 
        pt_conf.put<string>("history", full_cmd);
    }
    catch (const po::error& e) {
        BOOST_THROW_EXCEPTION(po::error(e.what()));
    }
 
    return pt_conf;
}

output() [1/2]

Options& output	(	const char *	,
		std::filesystem::path *	,
		const char *	,
		const std::vector< std::string > &	= {".root", ".xml"}
	)

expected file extension

Member to add an output. It can be called several times in a row. This option should always be provided from the command line, and never via the config file.

Returns

the object itself, so that the arguments can be given in a row.

output() [2/2]

Options & output	(	const char *	name,
		std::filesystem::path *	file,
		const char *	desc,
		const std::vector< std::string > &	ext = {".root", ".xml"}
	)

expected file extension

Member to add an output. It can be called several times in a row. This option should always be provided from the command line, and never via the config file.

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	name of the option, will be shown in helper
file	path pointer to file
desc	description, shown in helper too

{
    if (stage > Stage::Output) {
        full_cmd.clear();
        BOOST_THROW_EXCEPTION(runtime_error(
                    "Not possible to add another output at this stage"));
    }
    stage = Stage::Output;
 
    outputExt.push_back(ext);
    const po::value_semantic * s =
        po::value<fs::path>(file)->notifier(check_output)->required();
 
    return set(name, s, desc);
}

parse_common() [1/2]

void parse_common ( int  argc, const char * const  argv[]  )

private

Parser for generic options, such as the config (with -c) or slices. It should be directly given argc and argv from the main function.

{
    po::options_description cmd_line;
    cmd_line.add(common)
            .add(hidden);
 
    po::command_line_parser parser{argc, argv};
    parser.options(cmd_line)
          .allow_unregistered();
 
    po::variables_map vm;
    po::store(parser.run(), vm);
    po::notify(vm);
 
    if (vm.count("nSplit")) {
        auto j = vm["nSplit"].as<int>();
        if (j <= 0)
            BOOST_THROW_EXCEPTION(
                    invalid_argument("The number of slices must be larger than 0") );
 
        if (vm.count("nNow")) {
            auto k = vm["nNow"].as<int>();
            if (k >= j)
                BOOST_THROW_EXCEPTION(
                        invalid_argument("The slice index must be smaller than the "
                                         "number of slices.") );
        }
    }
 
    if (vm.count("config")) {
        const string ext = config_file.extension();
        if      (ext == ".json") pt::read_json(config_file.c_str(), pt_conf);
        else if (ext == ".info") pt::read_info(config_file.c_str(), pt_conf);
        else if (ext == ".xml" ) {
            pt::ptree userinfo;
            pt::read_xml(config_file.c_str(), userinfo);
            pt_conf = userinfo.get_child("userinfo");
        }
        else BOOST_THROW_EXCEPTION(
                fs::filesystem_error("Extension should be .json, .xml, or .info",
                                config_file, make_error_code(errc::invalid_argument)));
    }
 
    if (params & Friend) params |= fill;
 
    if ((params & fill   ) && vm["fill"   ].as<bool>()) steer |= fill   ;
    if ((params & Friend ) && vm["Friend" ].as<bool>()) steer |= Friend | fill;
    if ((params & syst   ) && vm["syst"   ].as<bool>()) steer |= syst   ;
    if (                      vm["verbose"].as<bool>()) steer |= verbose;
}

parse_common() [2/2]

void parse_common ( int  , const char * const  []  )

private

Parser for generic options, such as the config (with -c) or slices. It should be directly given argc and argv from the main function.

parse_config() [1/2]

static void parse_config ( boost::property_tree::ptree &  , std::string  = ""  )

static

Parse config if given. This method calls itself to parse the tree structure.

key in config (for recursive call)

parse_config() [2/2]

static void parse_config ( boost::property_tree::ptree &  , std::string  = ""  )

static

Parse config if given. This method calls itself to parse the tree structure.

key in config (for recursive call)

parse_custom() [1/2]

void parse_custom ( int  argc, const char * const  argv[]  )

private

Parser for options provided with args(), defined differently in each application. It should be directly given argc and argv from the main function.

{
    po::options_description cmd_line;
    cmd_line.add(common) // only here to avoid using `allow_unregistered()`
            .add(hidden) // idem
            .add(custom);
 
    po::command_line_parser parser{argc, argv};
    parser.options(cmd_line)
          .positional(pos_hide);
 
    po::variables_map vm;
    po::parsed_options parsed = parser.run();
    po::store(parsed, vm);
 
    // if no config file is given, then options are all required
    if (!fs::exists(config_file))
    for (auto& name: names) {
        if (vm.count(name)) continue;
        throw po::required_option(name);
    }
 
    if (!prefix.empty())
        full_cmd = prefix.string() + ' ';
    full_cmd += argv[0];
 
    po::notify(vm); // necessary for config to be given the value from the cmd line
                    // note: `full_cmd` is modified here
 
    // first fetch values from config (some may be overwritten later)
    for (auto& configpath: configpaths) {
        auto arg = pt_conf.get_optional<string>(configpath);
        if (!arg) continue;
        al::erase_all(*arg, "\n");
        al::erase_all(*arg, " ");
        al::erase_all(*arg, "\"");
        if (arg->empty()) continue;
        full_cmd += ' ' + *arg;
    }
 
    if (allow_unregistered()) { // garbage collector
 
        string configpath = configpaths.back();
        if (!pt_conf.count(configpath))
            pt_conf.add<string>(configpath, "");
        auto& subtree = pt_conf.get_child(configpath);
 
        for (const auto& [key, value]: subtree) {
            const auto v = value.get_value<string>();
            if (key.empty() || key == "item")
                full_cmd += ' ' + v;
            else if (v.empty())
                full_cmd += ' ' + key;
        }
 
        vector<string> items = po::collect_unrecognized(parsed.options,
                                                    po::include_positional);
        if (items.size() > *registered) {
 
            items.erase(items.begin(), items.begin() + *registered);
 
            for (string item: items) {
                if (subtree.count(item)) continue;
                // the item may contain special characters, such as a dot
                // (e.g. in filesystem paths), thus we must make sure that
                // this stays as it should
                pt::ptree::path_type p(item, '\0');
                subtree.put<string>(p, "");
                full_cmd += ' ' + item;
            }
        }
    } // end of garbage collector
 
    full_cmd = parse_env_var(full_cmd);
}

parse_custom() [2/2]

void parse_custom ( int  , const char * const  []  )

private

Parser for options provided with args(), defined differently in each application. It should be directly given argc and argv from the main function.

parse_env_var() [1/6]

static std::string parse_env_var ( const char *  p )

inlinestatic

Parse environment variable in C-style string.

    { return parse_env_var(std::string(p)); }

parse_env_var() [2/6]

static std::string parse_env_var ( const char *  p )

inlinestatic

Parse environment variable in C-style string.

    { return parse_env_var(std::string(p)); }

parse_env_var() [3/6]

static std::filesystem::path parse_env_var ( const std::filesystem::path &  p )

inlinestatic

Parse environment variable in a path.

    { return std::filesystem::path(parse_env_var(p.string())); }

parse_env_var() [4/6]

static std::filesystem::path parse_env_var ( const std::filesystem::path &  p )

inlinestatic

Parse environment variable in a path.

    { return std::filesystem::path(parse_env_var(p.string())); }

parse_env_var() [5/6]

string parse_env_var ( std::string  s )

static

Parse environment variable in string. Adapted from https://codereview.stackexchange.com/questions/172644/c-environment-variable-expansion

Remarks

Curly brackets are needed (e.g. ${VAR}, not just $VAR)

{
    static const regex env_re{R"--(\$\{([^}]+)\})--"};
    smatch match;
    while (regex_search(s, match, env_re)) {
        auto const from = match[0];
        auto const name = match[1].str();
        auto const value = getenv(name.c_str());
        if (!value)
            BOOST_THROW_EXCEPTION(runtime_error(
                        "Environment variable ${" + name + "} does not exist."));
        s.replace(from.first, from.second, value);
    }
    return s;
} 

parse_env_var() [6/6]

static std::string parse_env_var ( std::string  )

static

Parse environment variable in string. Adapted from https://codereview.stackexchange.com/questions/172644/c-environment-variable-expansion

Remarks

Curly brackets are needed (e.g. ${VAR}, not just $VAR)

parse_helper() [1/2]

void parse_helper ( int  argc, const char * const  argv[]  )

private

First parser that is called. As soon as -h is given, or if the command is run without options, then the helper is shown. It should be directly given argc and argv from the main function.

{
    po::command_line_parser parser{argc, argv};
    parser.options(helper) // parse only the helper, but no other option at this stage
          .allow_unregistered(); // ignore unregistered options
 
    // defines actions
    po::variables_map vm;
    po::store(parser.run(), vm);
    po::notify(vm); // necessary for config to be given the value from the cmd line
 
    if (vm.count("help") || argc == 1) {
        fs::path executable = argv[0];
        cout << bold << executable.filename().string() << synopsis << def
             << "\nwhere";
        for (const auto& option: custom.options())
            cout << '\t' << option->long_name()
                 << " = " << option->description() << '\n';
    }
 
    if (vm.count("help")) {
        po::options_description cmd_line;
        cmd_line.add(helper)
                .add(common); // only used to display the helper message,
                              // but not to parse
        cout << cmd_line << endl;
    }
 
    if (vm.count("tutorial"))
        cout << wrap_paragraph(tutorial) << '\n'
             << wrap_paragraph("General remarks: "
             "unless stated otherwise, all options except the input and output files "
             "may be given either from the command line or from such a config. Unused "
             "options in the config are simply ignored. The `flags` should be set at "
             "the creation of the n-tuples; the `corrections` should be added step "
             "by step (typically a couple of corrections per executable at most). How "
             "the config is parsed may change from executable to executable. This "
             "example uses the Boost INFO format, but JSON and XML formats are also "
             "possible. It is possible to extract such a config from an existing ROOT "
             "file by using `getMetaInfo`. Arguments from command line overwrite "
             "arguments from the config.") << endl;
 
    if (vm.count("git"))
        cout << commit() << endl;
 
    if (vm.count("example")) {
        if (!fs::exists(example))
            BOOST_THROW_EXCEPTION(
                    fs::filesystem_error("The example could not be found",
                        example, make_error_code(errc::no_such_file_or_directory)));
        pt::read_info(example, pt_conf);
 
        pt::ptree reduced_config;
        for (auto const& key: configpaths) {
            auto value = pt_conf.get<string>(key);
            reduced_config.add<string>(key, value);
        }
 
        stringstream ss;
        write_info(ss, reduced_config);
        string str = ss.str();
        al::erase_all(str, "\"\"");
        cout << str << flush;
    }
 
    auto space_separate = [](const string& a, const string& b) {
        return a + ' ' + b;
    };
 
    if (vm.count("input_ext"))
        for (const vector<string>& ext: inputExt)
            if (ext.size() > 0)
                cout << accumulate(next(begin(ext)), end(ext),
                                   ext.front(), space_separate) << endl;
 
    if (vm.count("output_ext"))
        for (const vector<string>& ext: outputExt)
            if (ext.size() > 0)
                cout << accumulate(next(begin(ext)), end(ext),
                                   ext.front(), space_separate) << endl;
 
    if (!vm.empty() || argc == 1)
        exit(EXIT_SUCCESS);
}

parse_helper() [2/2]

void parse_helper ( int  , const char * const  []  )

private

First parser that is called. As soon as -h is given, or if the command is run without options, then the helper is shown. It should be directly given argc and argv from the main function.

plugins() [1/2]

std::vector<std::filesystem::path> plugins ( ) const

inline

Plugins to run in the executable

Todo:

Save in config ptree? (also need to think of reproducibility)

    {
        using namespace std;
        if (!(params & plugin))
            BOOST_THROW_EXCEPTION( runtime_error("Plugins have not been activated") );
        return plugin_paths;
    }

plugins() [2/2]

std::vector<std::filesystem::path> plugins ( ) const

inline

Plugins to run in the executable

Todo:

Save in config ptree? (also need to think of reproducibility)

    {
        using namespace std;
        if (!(params & plugin))
            BOOST_THROW_EXCEPTION( runtime_error("Plugins have not been activated") );
        return plugin_paths;
    }

put() [1/2]

std::function<void(T)> put ( const std::string &  configpath )

inlineprivate

Helper to call boost::property_tree::put in Darwin::Toos::Options::args.

Returns

true if Options::registered has been initialised.

Parameters

configpath

path in config file

    {
        return [configpath,this](T value) { pt_conf.put<T>(configpath, value); };
    }

put() [2/2]

std::function<void(T)> put ( const std::string &  configpath )

inlineprivate

Helper to call boost::property_tree::put in Darwin::Toos::Options::args.

Returns

true if Options::registered has been initialised.

Parameters

configpath

path in config file

    {
        return [configpath,this](T value) { pt_conf.put<T>(configpath, value); };
    }

set() [1/2]

Options& set ( const char *  , const boost::program_options::value_semantic *  , const char *    )

private

Generic code to add options. It is called internally by Options::input(), Options::output(), and Options::args().

Returns

the object itself, so that the arguments can be given in a row.

set() [2/2]

Options & set ( const char *  name, const boost::program_options::value_semantic *  s, const char *  desc  )

private

Generic code to add options. It is called internally by Options::input(), Options::output(), and Options::args().

Returns

the object itself, so that the arguments can be given in a row.

Parameters

name	options name
s	https://www.boost.org/doc/libs/1_80_0/doc/html/boost/program_options/value_semantic.html
desc	description (for helper)

{
    if (allow_unregistered())
        BOOST_THROW_EXCEPTION(invalid_argument(
                    "Once `Options::args()` has been called, "
                    "it is no longer possible to add any further options."));
    synopsis += ' '; synopsis += name;
    pos_hide.add(name, 1);
    custom.add_options()(name, s, desc);
    return *this;
}

slice() [1/2]

std::pair<unsigned, unsigned> slice ( ) const

inline

Compactify slice information into a pair.

    {
        using namespace std;
        if (!(params & split))
            BOOST_THROW_EXCEPTION(invalid_argument("No splitting of the input file."));
        return make_pair(j,k);
    }

slice() [2/2]

std::pair<unsigned, unsigned> slice ( ) const

inline

Compactify slice information into a pair.

    {
        using namespace std;
        if (!(params & split))
            BOOST_THROW_EXCEPTION(invalid_argument("No splitting of the input file."));
        return make_pair(j,k);
    }

steering() [1/2]

int steering ( ) const

inline

Steering information for running of executable.

{ return steer; }

steering() [2/2]

int steering ( ) const

inline

Steering information for running of executable.

{ return steer; }

Member Data Documentation

common

boost::program_options::options_description common

private

generic + explicit options like --verbose

config_file

std::filesystem::path config_file

private

path to INFO, JSON, or XML config file

configpaths

std::vector< std::string > configpaths

private

path to the options in config (except for I/O)

custom

boost::program_options::options_description custom

private

for positional arguments, depending on the actual command

example

const std::filesystem::path example

private

path to example config

full_cmd

static std::string full_cmd

static

extended version of the command for reproducibility

helper

boost::program_options::options_description helper

private

to display the helper

hidden

boost::program_options::options_description hidden

private

hidden interface (not for lambda user)

inputExt

std::vector< std::vector< std::string > > inputExt

private

expected extensions of input files

j

int j

private

slices

slices

k

int k

private

slice index

m_commit

const std::string m_commit

private

Commit SHA for –git.

names

std::vector< std::string > names

private

names of the different options (shown in synopsis)

outputExt

std::vector< std::vector< std::string > > outputExt

private

expected extensions of output files

params

int params

private

input parameters to interpret explicit options

plugin_paths

std::vector< std::filesystem::path > plugin_paths

private

plugin locations

pos_hide

boost::program_options::positional_options_description pos_hide

private

parser for positional arguments

prefix

static std::filesystem::path prefix

staticprivate

prefix command to steer -j and -k

pt_conf

boost::property_tree::ptree pt_conf

private

internal config obtained from arugments and input config

registered

std::optional< unsigned > registered

private

collect the number of registered options (only if Options::args has been called before)

stage

Stage stage

private

internal stage

steer

int steer

private

output parameters for code executation

synopsis

std::string synopsis

private

stores a clean version of the command, displayed w. -h

tutorial

const std::string tutorial

private

define in constructor, shown with option -t

---

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

• /builds/cms-analysis/general/DasAnalysisSystem/Core/Installer/Darwin/interface/Options.h
• /builds/cms-analysis/general/DasAnalysisSystem/Core/Installer/Darwin/src/Options.cc