DAS  3.0
Das Analysis System
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
 
Optionsinput (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
Optionsinputs (const char *, std::vector< std::filesystem::path > *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
Optionsoutput (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
template<typename T >
Optionsarg (const char *name, const char *configpath, const char *desc)
 
Optionsargs (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::pair< unsigned, unsigned > slice () const
 
 Options (const std::string &, int=none, const char *commit=DARWIN_GIT_COMMIT, const char *example=DARWIN_EXAMPLE)
 
 Options ()=delete
 
Optionsinput (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
Optionsinputs (const char *, std::vector< std::filesystem::path > *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
Optionsoutput (const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
 
template<typename T >
Optionsarg (const char *name, const char *configpath, const char *desc)
 
Optionsargs (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::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 [])
 
Optionsset (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 [])
 
Optionsset (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::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)

146  {
147  Input,
148  Output,
149  Arg,
150  Args
151  };

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

146  {
147  Input,
148  Output,
149  Arg,
150  Args
151  };

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
tutodescription, to be displayed in the helper
parsflags for explicit, generic command options (see enum)
commitgit commit for --git
examplepath to example
102  : hidden{"Hidden"}, helper{"Helper"}, common{"Options"}, custom{"Positional options"},
103  example(example ? example : DARWIN "/test/example.info"),
104  tutorial(tuto), stage(Stage::Input), params(pars),
106  steer(0), j(1), k(0)
107 {
108  if (params & split) hidden.add_options()
109  ("prefix,p", po::value<fs::path>(&prefix), "Prefix command, `parallel` or `submit` (for history only)");
110 
111  // first the helper
112  helper.add_options()
113  ("help,h", "Help screen (what you are seeing right now)")
114  ("tutorial,t", "Brief description of the command's purpose")
115  ("git,g", "Commit hash of this executable at compilation time")
116  ("input_ext,i", "Expected extension for input(s) (one line for each input)")
117  ("output_ext,o", "Expected extension for output(s) (one line for each output)");
118  if (params & config) helper.add_options()
119  ("example,e", "Print config example");
120 
121  // then the running options
122  common.add_options()
123  ("verbose,v", po::bool_switch()->default_value(false),
124  "Enable debug mode (typically in slow operations such as the event loop)")
125  ("mute,m", po::bool_switch()->default_value(false)->notifier(set_mute),
126  "Disable standard output stream");
127  if (params & config) common.add_options()
128  ("config,c", po::value<fs::path>(&config_file),
129  "Configuration file in INFO, JSON, or XML format");
130  if (params & split) common.add_options()
131  ("nSplit,j", po::value<int>(&j)->default_value(j), "Number of slices")
132  ("nNow,k" , po::value<int>(&k)->default_value(k), "Index of current slice");
133  if (params & (fill | Friend)) common.add_options()
134  ("fill,f", po::bool_switch()->default_value(false), "Enable `TTree::Fill()`");
135  if (params & Friend) common.add_options()
136  ("Friend,F", po::bool_switch()->default_value(false),
137  "Use `TTree` friends instead of cloning the whole input `TTree`");
138  if (params & syst) common.add_options()
139  ("syst,s", po::bool_switch()->default_value(false),
140  "Enable systematic variations");
141 
142  // positional arguments should be defined by hand by the user
143  // with the various public members
144 }

◆ Options() [2/4]

Options ( )
delete

No default constructor is allowed.

◆ 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
commitgit commit for --git
examplepath to example

◆ Options() [4/4]

Options ( )
delete

No default constructor is allowed.

Member Function Documentation

◆ allow_unregistered() [1/2]

bool allow_unregistered ( ) const
inlineprivate
Returns
true if Options::registered has been initialised.
139 { return bool(registered); }

◆ allow_unregistered() [2/2]

bool allow_unregistered ( ) const
inlineprivate
Returns
true if Options::registered has been initialised.
139 { 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
namename of the option, will be shown in helper
configpathpath in config
descdescription, shown in helper too
226  {
227  if (stage > Stage::Arg)
228  BOOST_THROW_EXCEPTION(std::runtime_error(
229  "Not possible to add another argument at this stage"));
230  stage = Stage::Arg;
231 
232  names.push_back(name);
233  configpaths.push_back(configpath);
234  const boost::program_options::value_semantic * s =
235  boost::program_options::value<T>()->notifier(put<T>(configpath));
236  return set(name, s, desc);
237  }

◆ 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
namename of the option, will be shown in helper
configpathpath in config
descdescription, shown in helper too
226  {
227  if (stage > Stage::Arg)
228  BOOST_THROW_EXCEPTION(std::runtime_error(
229  "Not possible to add another argument at this stage"));
230  stage = Stage::Arg;
231 
232  names.push_back(name);
233  configpaths.push_back(configpath);
234  const boost::program_options::value_semantic * s =
235  boost::program_options::value<T>()->notifier(put<T>(configpath));
236  return set(name, s, desc);
237  }

◆ 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
namegeneric name for unregistered options
configpathpath in config.
descdescription, 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
namegeneric name for unregistered options
configpathpath in config.
descdescription, shown in helper too
538 {
539  if (stage >= Stage::Args)
540  BOOST_THROW_EXCEPTION(runtime_error("Only one garbage collector is possible"));
541  stage = Stage::Args;
542 
543  synopsis += " [" + string(name) + "...]";
544  configpaths.push_back(configpath);
545 
546  registered = pos_hide.max_total_count();
547  const po::value_semantic * s =
548  po::value<vector<string>>()->multitoken()->zero_tokens();
549  custom.add_options()(name, s, desc);
550  pos_hide.add(name, -1);
551 
552  return *this;
553 }

◆ 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
inputpath to input
38 {
39  if (!fs::exists(input))
40  BOOST_THROW_EXCEPTION(fs::filesystem_error("Bad input", input,
41  make_error_code(errc::no_such_file_or_directory)));
42 
43  full_cmd += ' ' + fs::canonical(input).string();
44 
45  if ((fs::status(input).permissions() & fs::perms::owner_read) == fs::perms::none)
46  BOOST_THROW_EXCEPTION(fs::filesystem_error("Input exists but cannot be read",
47  input, make_error_code(errc::permission_denied)));
48 }

◆ 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
outputpath to output
51 {
52  fs::path outputHist = output;
53  if (!prefix.empty() && !fs::is_directory(output)) outputHist.remove_filename();
54  full_cmd += ' ' + outputHist.string();
55 
56  if (!fs::exists(output)) return;
57 
58  if ((fs::status(output).permissions() & fs::perms::owner_write)
59  == fs::perms::none) {
60  full_cmd.clear();
61  BOOST_THROW_EXCEPTION(fs::filesystem_error(
62  "Output already exists and cannot be overwritten",
63  output, make_error_code(errc::permission_denied)));
64  }
65 
66  if (fs::is_directory(output) && fs::equivalent(output,".")) {
67  full_cmd.clear();
68  BOOST_THROW_EXCEPTION(fs::filesystem_error("Not a valid output",
69  output, make_error_code(errc::invalid_argument)));
70  }
71  else if (output != "/dev/null")
72  cerr << orange << "Warning: you are overwriting " << output << def << '\n';
73 }

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

281 { return m_commit; }

◆ commit() [2/2]

auto commit ( ) const
inline

Git commit information.

281 { return m_commit; }

◆ exec() [1/2]

std::string exec ( const std::string &  cmd)
private
Returns
output from command given to shell
Parameters
cmdcmd to run in the shell
463 {
464  string result;
465  char buffer[128];
466  cerr << red;
467  FILE * pipe = popen(cmd.c_str(), "r");
468  while (!feof(pipe))
469  if (fgets(buffer, 128, pipe) != NULL)
470  result += buffer;
471  pclose(pipe);
472  cerr << def;
473  return result;
474 }

◆ exec() [2/2]

std::string exec ( const std::string &  )
private
Returns
output from command given to shell

◆ 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
namename of the option, will be shown in helper
filepath pointer to file
descdescription, shown in helper too
451 {
452  if (stage > Stage::Input)
453  BOOST_THROW_EXCEPTION(runtime_error(
454  "Not possible to add another input at this stage"));
455 
456  inputExt.push_back(ext);
457  const po::value_semantic * s =
458  po::value<fs::path>(file)->notifier(check_input)->required();
459  return set(name, s, desc);
460 }

◆ 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
namename of the options, will be shown in helper
filespaths to files
descdescription, shown in helper too
479 {
480  if (stage > Stage::Input)
481  BOOST_THROW_EXCEPTION(runtime_error(
482  "Not possible to add another input at this stage"));
483 
484  auto store = [files,this](const string& pathRegex) {
485 
486  const string& ls = exec("ls -1d " + pathRegex);
487 
488  vector<fs::path> paths;
489  al::split(paths, ls, al::is_any_of("\n"), al::token_compress_on);
490  for (fs::path const& p: paths) {
491  if (!fs::exists(p)) continue;
492  files->push_back(p);
493  }
494 
495  if (files->empty()) {
496  fs::path p = pathRegex;
497  full_cmd.clear();
498  BOOST_THROW_EXCEPTION(
499  fs::filesystem_error("No input file could be found", p,
500  make_error_code(errc::no_such_file_or_directory)));
501  }
502 
503  auto inputs = accumulate(files->begin(), files->end(), string(),
504  [](string inputs, fs::path input) {
505  return inputs + fs::canonical(input).string() + ' '; });
506  inputs.resize(inputs.size()-1);
507  if (files->size() > 1)
508  inputs = '"' + inputs + '"';
509  full_cmd += ' ' + inputs;
510  };
511 
512  inputExt.push_back(ext);
513  const po::value_semantic * s =
514  po::value<string>()->notifier(store)->required();
515  string full_desc = desc;
516  full_desc += " (use a regular expression, surrounded by quotation marks)";
517  return set(name, s, full_desc.c_str());
518 }

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

411 {
412  pt_conf.clear();
413  full_cmd.clear();
414  prefix.clear();
415 
416  try {
417  parse_helper(argc, argv);
418  parse_common(argc, argv);
419  parse_custom(argc, argv);
421 
422  if (steer & split && j > 1) full_cmd += " -j " + to_string(j);
423  if (steer & syst ) full_cmd += " -s";
424  if (steer & Friend ) full_cmd += " -F";
425  else if (steer & fill ) full_cmd += " -f";
426 
427  pt_conf.put<string>("history", full_cmd);
428  }
429  catch (const po::error& e) {
430  BOOST_THROW_EXCEPTION(po::error(e.what()));
431  }
432 
433  return pt_conf;
434 }

◆ 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
namename of the option, will be shown in helper
filepath pointer to file
descdescription, shown in helper too
522 {
523  if (stage > Stage::Output) {
524  full_cmd.clear();
525  BOOST_THROW_EXCEPTION(runtime_error(
526  "Not possible to add another output at this stage"));
527  }
528  stage = Stage::Output;
529 
530  outputExt.push_back(ext);
531  const po::value_semantic * s =
532  po::value<fs::path>(file)->notifier(check_output)->required();
533 
534  return set(name, s, desc);
535 }

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

269 {
270  po::options_description cmd_line;
271  cmd_line.add(common)
272  .add(hidden);
273 
274  po::command_line_parser parser{argc, argv};
275  parser.options(cmd_line)
276  .allow_unregistered();
277 
278  po::variables_map vm;
279  po::store(parser.run(), vm);
280  po::notify(vm);
281 
282  if (vm.count("nSplit")) {
283  auto j = vm["nSplit"].as<int>();
284  if (j <= 0)
285  BOOST_THROW_EXCEPTION(
286  invalid_argument("The number of slices must be larger than 0") );
287 
288  if (vm.count("nNow")) {
289  auto k = vm["nNow"].as<int>();
290  if (k >= j)
291  BOOST_THROW_EXCEPTION(
292  invalid_argument("The slice index must be smaller than the "
293  "number of slices.") );
294  }
295  }
296 
297  if (vm.count("config")) {
298  const string ext = config_file.extension();
299  if (ext == ".json") pt::read_json(config_file.c_str(), pt_conf);
300  else if (ext == ".info") pt::read_info(config_file.c_str(), pt_conf);
301  else if (ext == ".xml" ) {
302  pt::ptree userinfo;
303  pt::read_xml(config_file.c_str(), userinfo);
304  pt_conf = userinfo.get_child("userinfo");
305  }
306  else BOOST_THROW_EXCEPTION(
307  fs::filesystem_error("Extension should be .json, .xml, or .info",
308  config_file, make_error_code(errc::invalid_argument)));
309  }
310 
311  if (params & Friend) params |= fill;
312 
313  if ((params & fill ) && vm["fill" ].as<bool>()) steer |= fill ;
314  if ((params & Friend ) && vm["Friend" ].as<bool>()) steer |= Friend | fill;
315  if ((params & syst ) && vm["syst" ].as<bool>()) steer |= syst ;
316  if ( vm["verbose"].as<bool>()) steer |= verbose;
317 }

◆ 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  ,
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_custom() [2/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.

320 {
321  po::options_description cmd_line;
322  cmd_line.add(common) // only here to avoid using `allow_unregistered()`
323  .add(hidden) // idem
324  .add(custom);
325 
326  po::command_line_parser parser{argc, argv};
327  parser.options(cmd_line)
328  .positional(pos_hide);
329 
330  po::variables_map vm;
331  po::parsed_options parsed = parser.run();
332  po::store(parsed, vm);
333 
334  // if no config file is given, then options are all required
335  if (!fs::exists(config_file))
336  for (auto& name: names) {
337  if (vm.count(name)) continue;
338  throw po::required_option(name);
339  }
340 
341  if (!prefix.empty())
342  full_cmd = prefix.string() + ' ';
343  full_cmd += argv[0];
344 
345  po::notify(vm); // necessary for config to be given the value from the cmd line
346  // note: `full_cmd` is modified here
347 
348  // first fetch values from config (some may be overwritten later)
349  for (auto& configpath: configpaths) {
350  auto arg = pt_conf.get_optional<string>(configpath);
351  if (!arg) continue;
352  al::erase_all(*arg, "\n");
353  al::erase_all(*arg, " ");
354  al::erase_all(*arg, "\"");
355  if (arg->empty()) continue;
356  full_cmd += ' ' + *arg;
357  }
358 
359  if (allow_unregistered()) { // garbage collector
360 
361  string configpath = configpaths.back();
362  if (!pt_conf.count(configpath))
363  pt_conf.add<string>(configpath, "");
364  auto& subtree = pt_conf.get_child(configpath);
365 
366  for (auto& item: subtree) {
367  string key = item.first,
368  value = item.second.get_value<string>();
369  if (key.empty() || key == "item")
370  full_cmd += ' ' + value;
371  else if (value.empty())
372  full_cmd += ' ' + key;
373  }
374 
375  vector<string> items = po::collect_unrecognized(parsed.options,
376  po::include_positional);
377  if (items.size() > *registered) {
378 
379  items.erase(items.begin(), items.begin() + *registered);
380 
381  for (auto& item: items) {
382  if (subtree.count(item)) continue;
383  subtree.add<string>(item, "");
384  full_cmd += ' ' + item;
385  }
386  }
387  } // end of garbage collector
388 
390 }

◆ parse_env_var() [1/6]

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

Parse environment variable in C-style string.

263  { 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.

263  { 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.

268  { 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.

268  { 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)
76 {
77  static const regex env_re{R"--(\$\{([^}]+)\})--"};
78  smatch match;
79  while (regex_search(s, match, env_re)) {
80  auto const from = match[0];
81  auto const name = match[1].str();
82  auto const value = getenv(name.c_str());
83  if (!value)
84  BOOST_THROW_EXCEPTION(runtime_error(
85  "Environment variable ${" + name + "} does not exist."));
86  s.replace(from.first, from.second, value);
87  }
88  return s;
89 }

◆ 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  ,
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.

◆ parse_helper() [2/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.

184 {
185  po::command_line_parser parser{argc, argv};
186  parser.options(helper) // parse only the helper, but no other option at this stage
187  .allow_unregistered(); // ignore unregistered options
188 
189  // defines actions
190  po::variables_map vm;
191  po::store(parser.run(), vm);
192  po::notify(vm); // necessary for config to be given the value from the cmd line
193 
194  if (vm.count("help") || argc == 1) {
195  fs::path executable = argv[0];
196  cout << bold << executable.filename().string() << synopsis << def
197  << "\nwhere";
198  for (const auto& option: custom.options())
199  cout << '\t' << option->long_name()
200  << " = " << option->description() << '\n';
201  }
202 
203  if (vm.count("help")) {
204  po::options_description cmd_line;
205  cmd_line.add(helper)
206  .add(common); // only used to display the helper message,
207  // but not to parse
208  cout << cmd_line << endl;
209  }
210 
211  if (vm.count("tutorial"))
212  cout << wrap_paragraph(tutorial) << '\n'
213  << wrap_paragraph("General remarks: "
214  "unless stated otherwise, all options except the input and output files "
215  "may be given either from the command line or from such a config. Unused "
216  "options in the config are simply ignored. The `flags` should be set at "
217  "the creation of the n-tuples; the `corrections` should be added step "
218  "by step (typically a couple of corrections per executable at most). How "
219  "the config is parsed may change from executable to executable. This "
220  "example uses the Boost INFO format, but JSON and XML formats are also "
221  "possible. It is possible to extract such a config from an existing ROOT "
222  "file by using `getMetaInfo`. Arguments from command line overwrite "
223  "arguments from the config.") << endl;
224 
225  if (vm.count("git"))
226  cout << commit() << endl;
227 
228  if (vm.count("example")) {
229  if (!fs::exists(example))
230  BOOST_THROW_EXCEPTION(
231  fs::filesystem_error("The example could not be found",
232  example, make_error_code(errc::no_such_file_or_directory)));
233  pt::read_info(example, pt_conf);
234 
235  pt::ptree reduced_config;
236  for (auto const& key: configpaths) {
237  auto value = pt_conf.get<string>(key);
238  reduced_config.add<string>(key, value);
239  }
240 
241  stringstream ss;
242  write_info(ss, reduced_config);
243  string str = ss.str();
244  al::erase_all(str, "\"\"");
245  cout << str << flush;
246  }
247 
248  auto space_separate = [](const string& a, const string& b) {
249  return a + ' ' + b;
250  };
251 
252  if (vm.count("input_ext"))
253  for (const vector<string>& ext: inputExt)
254  if (ext.size() > 0)
255  cout << accumulate(next(begin(ext)), end(ext),
256  ext.front(), space_separate) << endl;
257 
258  if (vm.count("output_ext"))
259  for (const vector<string>& ext: outputExt)
260  if (ext.size() > 0)
261  cout << accumulate(next(begin(ext)), end(ext),
262  ext.front(), space_separate) << endl;
263 
264  if (!vm.empty() || argc == 1)
265  exit(EXIT_SUCCESS);
266 }

◆ 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
configpathpath in config file
131  {
132  return [configpath,this](T value) { pt_conf.put<T>(configpath, value); };
133  }

◆ 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
configpathpath in config file
131  {
132  return [configpath,this](T value) { pt_conf.put<T>(configpath, value); };
133  }

◆ 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
nameoptions name
shttps://www.boost.org/doc/libs/1_80_0/doc/html/boost/program_options/value_semantic.html
descdescription (for helper)
438 {
439  if (allow_unregistered())
440  BOOST_THROW_EXCEPTION(invalid_argument(
441  "Once `Options::args()` has been called, "
442  "it is no longer possible to add any further options."));
443  synopsis += ' '; synopsis += name;
444  pos_hide.add(name, 1);
445  custom.add_options()(name, s, desc);
446  return *this;
447 }

◆ slice() [1/2]

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

Compactify slice information into a pair.

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

◆ slice() [2/2]

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

Compactify slice information into a pair.

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

◆ steering() [1/2]

int steering ( ) const
inline

Steering information for running of executable.

285 { return steer; }

◆ steering() [2/2]

int steering ( ) const
inline

Steering information for running of executable.

285 { 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

◆ 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:
DYToLL_M-50_13TeV_pythia8_cff_GEN_SIM_RECOBEFMIX_DIGI_L1_DIGI2RAW_L1Reco_RECO.name
name
Definition: DYToLL_M-50_13TeV_pythia8_cff_GEN_SIM_RECOBEFMIX_DIGI_L1_DIGI2RAW_L1Reco_RECO.py:48
Darwin::Tools::Options::parse_env_var
static std::string parse_env_var(std::string)
Definition: Options.cc:75
Ntupliser_cfg.cerr
cerr
Definition: Ntupliser_cfg.py:93
Darwin::Tools::Options::check_input
static void check_input(const std::filesystem::path &)
Definition: Options.cc:37
Darwin::Tools::Options::k
int k
slice index
Definition: Options.h:160
Darwin::Tools::Options::tutorial
const std::string tutorial
define in constructor, shown with option -t
Definition: Options.h:93
Darwin::Tools::fill
@ fill
activate -f to fill the tree
Definition: Options.h:27
DYToLL_M-50_13TeV_pythia8_cff_GEN_SIM_RECOBEFMIX_DIGI_L1_DIGI2RAW_L1Reco_RECO.options
options
Definition: DYToLL_M-50_13TeV_pythia8_cff_GEN_SIM_RECOBEFMIX_DIGI_L1_DIGI2RAW_L1Reco_RECO.py:41
Darwin::Tools::Options::custom
boost::program_options::options_description custom
for positional arguments, depending on the actual command
Definition: Options.h:65
Darwin::Tools::Options::j
int j
Definition: Options.h:159
Step::def
static const char * def
Definition: Step.h:36
Darwin::Tools::Friend
@ Friend
activate -F to only fill the new branches
Definition: Options.h:28
Ntupliser_cfg.paths
paths
Definition: Ntupliser_cfg.py:296
Darwin::Tools::Options::allow_unregistered
bool allow_unregistered() const
Definition: Options.h:139
Darwin::Tools::Options::inputs
Options & inputs(const char *, std::vector< std::filesystem::path > *, const char *, const std::vector< std::string > &={".root", ".xml"})
expected file extension
Definition: Options.cc:476
Darwin::Tools::split
@ split
activate -k and -j to define slice
Definition: Options.h:26
Darwin::Tools::Options::args
Options & args(const char *name, const char *configpath, const char *desc)
Definition: Options.cc:537
Ntupliser_cfg.p
p
Definition: Ntupliser_cfg.py:358
Darwin::Tools::Options::check_output
static void check_output(const std::filesystem::path &)
Definition: Options.cc:50
Darwin::Tools::Options::Input
@ Input
first the inputs
Definition: Options.h:147
Darwin::Tools::Options::hidden
boost::program_options::options_description hidden
hidden interface (not for lambda user)
Definition: Options.h:62
Darwin::Tools::syst
@ syst
activate -s to systematic uncertainties
Definition: Options.h:29
jercExample.key
string key
Definition: jercExample.py:109
Darwin::Tools::none
@ none
default (for simple executables)
Definition: Options.h:24
compareFiles.files
files
Definition: compareFiles.py:125
Darwin::Tools::Options::synopsis
std::string synopsis
stores a clean version of the command, displayed w. -h
Definition: Options.h:94
Darwin::Tools::Options::pos_hide
boost::program_options::positional_options_description pos_hide
parser for positional arguments
Definition: Options.h:67
Darwin::Tools::Options::parse_config
static void parse_config(boost::property_tree::ptree &, std::string="")
Parse config if given. This method calls itself to parse the tree structure.
Darwin::Tools::Options::steer
int steer
output parameters for code executation
Definition: Options.h:157
Darwin::Tools::Options::commit
auto commit() const
Git commit information.
Definition: Options.h:281
Darwin::Tools::Options::Output
@ Output
then the outputs (inputs are no longer allowed)
Definition: Options.h:148
Darwin::Tools::Options::parse_common
void parse_common(int, const char *const [])
Definition: Options.cc:268
prefix
Definition: prefix.py:1
Darwin::Tools::Options::parse_helper
void parse_helper(int, const char *const [])
Definition: Options.cc:183
Step::red
static const char * red
Definition: Step.h:34
cmd
cmd
Definition: Core-cfgcmd.txt:1
Darwin::Tools::Options::names
std::vector< std::string > names
names of the different options (shown in synopsis)
Definition: Options.h:96
Darwin::Tools::Options::inputExt
std::vector< std::vector< std::string > > inputExt
expected extensions of input files
Definition: Options.h:163
Darwin::Tools::verbose
@ verbose
bit for debug mode (-v is always available)
Definition: Options.h:30
Ntupliser_cfg.config
config
Definition: Ntupliser_cfg.py:260
orange
static const char * orange
Definition: colours.h:6
Darwin::Tools::Options::set
Options & set(const char *, const boost::program_options::value_semantic *, const char *)
Definition: Options.cc:436
Darwin::Tools::Options
Common class to interpret the command line, based on Boost Program Options.
Definition: Options.h:58
wrap_paragraph
string wrap_paragraph(const string &text)
Definition: Options.cc:149
Darwin::Tools::Options::Args
@ Args
finally the remaining arguments / garbage collector (must be very last)
Definition: Options.h:150
Darwin::Tools::Options::arg
Options & arg(const char *name, const char *configpath, const char *desc)
Definition: Options.h:222
Darwin::Tools::Options::stage
Stage stage
internal stage
Definition: Options.h:153
DARWIN_VERSION
#define DARWIN_VERSION
Definition: version.h:1
Darwin::Tools
Classes and functions related to the framework.
Definition: Dict_rdict.cxx:990
Darwin::Tools::Options::registered
std::optional< unsigned > registered
collect the number of registered options (only if Options::args has been called before)
Definition: Options.h:135
Darwin::Tools::Options::m_commit
const std::string m_commit
Commit SHA for –git.
Definition: Options.h:156
Darwin::Tools::Options::helper
boost::program_options::options_description helper
to display the helper
Definition: Options.h:63
Darwin::Tools::Options::parse_custom
void parse_custom(int, const char *const [])
Definition: Options.cc:319
Darwin::Tools::Options::config_file
std::filesystem::path config_file
path to INFO, JSON, or XML config file
Definition: Options.h:90
Darwin::Tools::Options::outputExt
std::vector< std::vector< std::string > > outputExt
expected extensions of output files
Definition: Options.h:164
Darwin::Tools::Options::output
Options & output(const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
expected file extension
Definition: Options.cc:520
compareFiles.parser
parser
Definition: compareFiles.py:118
Darwin::Tools::Options::input
Options & input(const char *, std::filesystem::path *, const char *, const std::vector< std::string > &={".root", ".xml"})
expected file extension
Definition: Options.cc:449
DAS::Options
Darwin::Tools::Options Options(const char *, int=Darwin::Tools::none)
Constructs Darwin options with the correct commit information.
Definition: DASOptions.cc:14
DAS::Normalisation::match
DAS::FourVector match(const DAS::FourVector &jet, const std::vector< DAS::FourVector > *hltJets)
Definition: match.h:7
set_mute
void set_mute(bool flag)
Function used by Boost::PO to disable standard error.
Definition: Options.cc:93
Darwin::Tools::Options::exec
std::string exec(const std::string &)
Definition: Options.cc:462
Darwin::Tools::Options::Arg
@ Arg
then the registered arguments (inputs and outputs no longer allowed)
Definition: Options.h:149
Darwin::Tools::Options::params
int params
input parameters to interpret explicit options
Definition: Options.h:155
Darwin::Tools::Options::configpaths
std::vector< std::string > configpaths
path to the options in config (except for I/O)
Definition: Options.h:97
Darwin::Tools::Options::full_cmd
static std::string full_cmd
extended version of the command for reproducibility
Definition: Options.h:277
Darwin::Tools::config
@ config
activate -c option to provide config file
Definition: Options.h:25
Darwin::Tools::Options::pt_conf
boost::property_tree::ptree pt_conf
internal config obtained from arugments and input config
Definition: Options.h:69
Darwin::Tools::Options::common
boost::program_options::options_description common
generic + explicit options like --verbose
Definition: Options.h:64
Darwin::Tools::Options::example
const std::filesystem::path example
path to example config
Definition: Options.h:71
Step::bold
static const char * bold
Definition: Step.h:35