Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
ROOT::option::Parser Class Reference

Checks argument vectors for validity and parses them into data structures that are easier to work with.

Example:
int main(int argc, char* argv[])
{
argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present
option::Stats stats(usage, argc, argv);
option::Option options[stats.options_max], buffer[stats.buffer_max];
option::Parser parse(usage, argc, argv, options, buffer);
if (parse.error())
return 1;
if (options[HELP])
...
int main()
Definition Prototype.cxx:12
A parsed option from the command line together with its argument if it has one.
Checks argument vectors for validity and parses them into data structures that are easier to work wit...
void parse(bool gnu, const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
Parses the given argument vector.
Determines the minimum lengths of the buffer and options arrays used for Parser.

Definition at line 1061 of file OptionParser.h.

Classes

struct  Action
 
class  StoreOptionAction
 

Public Member Functions

 Parser ()
 Creates a new Parser.
 
 Parser (bool gnu, const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 Parser(...) with non-const argv.
 
 Parser (bool gnu, const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 Creates a new Parser and immediately parses the given argument vector.
 
 Parser (const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 POSIX Parser(...) (gnu==false) with non-const argv.
 
 Parser (const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 POSIX Parser(...) (gnu==false).
 
bool error ()
 Returns true if an unrecoverable error occurred while parsing options.
 
const char * nonOption (int i)
 Returns nonOptions()[i] (without checking if i is in range!).
 
const char ** nonOptions ()
 Returns a pointer to an array of non-option arguments (only valid if nonOptionsCount() >0 ).
 
int nonOptionsCount ()
 Returns the number of non-option arguments that remained at the end of the most recent parse() that actually encountered non-option arguments.
 
int optionsCount ()
 Returns the number of valid Option objects in buffer[].
 
void parse (bool gnu, const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 parse() with non-const argv.
 
void parse (bool gnu, const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 Parses the given argument vector.
 
void parse (const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 POSIX parse() (gnu==false) with non-const argv.
 
void parse (const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
 POSIX parse() (gnu==false).
 

Static Private Member Functions

static bool instr (char ch, const char *st)
 
static void shift (const char **args, int count)
 
static bool streq (const char *st1, const char *st2)
 
static bool streqabbr (const char *st1, const char *st2, long long min)
 
static bool workhorse (bool gnu, const Descriptor usage[], int numargs, const char **args, Action &action, bool single_minus_longopt, bool print_errors, int min_abbr_len)
 

Private Attributes

bool err
 
const char ** nonop_args
 
int nonop_count
 
int op_count
 

Friends

struct Stats
 

#include </home/sftnight/build/workspace/root-makedoc-v626/rootspi/rdoc/src/v6-26-00-patches/core/dictgen/res/OptionParser.h>

Constructor & Destructor Documentation

◆ Parser() [1/5]

ROOT::option::Parser::Parser ( )
inline

Creates a new Parser.

Definition at line 1072 of file OptionParser.h.

◆ Parser() [2/5]

ROOT::option::Parser::Parser ( bool  gnu,
const Descriptor  usage[],
int  argc,
const char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

Creates a new Parser and immediately parses the given argument vector.

Parameters
gnuif true, parse() will not stop at the first non-option argument. Instead it will reorder arguments so that all non-options are at the end. This is the default behaviour of GNU getopt() but is not conforming to POSIX.
Note, that once the argument vector has been reordered, the gnu flag will have no further effect on this argument vector. So it is enough to pass gnu==true when creating Stats.
usageArray of Descriptor objects that describe the options to support. The last entry of this array must have 0 in all fields.
argcThe number of elements from argv that are to be parsed. If you pass -1, the number will be determined automatically. In that case the argv list must end with a NULL pointer.
argvThe arguments to be parsed. If you pass -1 as argc the last pointer in the argv list must be NULL to mark the end.
optionsEach entry is the first element of a linked list of Options. Each new option that is parsed will be appended to the list specified by that Option's Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), it will be replaced rather than appended to.
The minimum length of this array is the greatest Descriptor::index value that occurs in usage PLUS ONE.
bufferEach argument that is successfully parsed (including unknown arguments, if they have a Descriptor whose CheckArg does not return ARG_ILLEGAL) will be stored in this array. parse() scans the array for the first invalid entry and begins writing at that index. You can pass bufmax to limit the number of options stored.
min_abbr_lenPassing a value min_abbr_len > 0 enables abbreviated long options. The parser will match a prefix of a long option as if it was the full long option (e.g. --foob=10 will be interpreted as if it was --foobar=10 ), as long as the prefix has at least min_abbr_len characters (not counting the -- ) and is unambiguous.
Be careful if combining min_abbr_len=1 with single_minus_longopt=true because the ambiguity check does not consider short options and abbreviated single minus long options will take precedence over short options.
single_minus_longoptPassing true for this option allows long options to begin with a single minus. The double minus form will still be recognized. Note that single minus long options take precedence over short options and short option groups. E.g. -file would be interpreted as --file and not as -f -i -l -e (assuming a long option named "file" exists).
bufmaxThe greatest index in the buffer[] array that parse() will write to is bufmax-1. If there are more options, they will be processed (in particular their CheckArg will be called) but not stored.
If you used Stats::buffer_max to dimension this array, you can pass -1 (or not pass bufmax at all) which tells parse() that the buffer is "large enough".
Attention
Remember that options and buffer store Option objects, not pointers. Therefore it is not possible for the same object to be in both arrays. For those options that are found in both buffer[] and options[] the respective objects are independent copies. And only the objects in options[] are properly linked via Option::next() and Option::prev(). You can iterate over buffer[] to process all options in the order they appear in the argument vector, but if you want access to the other Options with the same Descriptor::index, then you must access the linked list via options[]. You can get the linked list in options from a buffer object via something like options[buffer[i].index()].

Definition at line 1081 of file OptionParser.h.

◆ Parser() [3/5]

ROOT::option::Parser::Parser ( bool  gnu,
const Descriptor  usage[],
int  argc,
char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

Parser(...) with non-const argv.

Definition at line 1089 of file OptionParser.h.

◆ Parser() [4/5]

ROOT::option::Parser::Parser ( const Descriptor  usage[],
int  argc,
const char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

POSIX Parser(...) (gnu==false).

Definition at line 1097 of file OptionParser.h.

◆ Parser() [5/5]

ROOT::option::Parser::Parser ( const Descriptor  usage[],
int  argc,
char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

POSIX Parser(...) (gnu==false) with non-const argv.

Definition at line 1105 of file OptionParser.h.

Member Function Documentation

◆ error()

bool ROOT::option::Parser::error ( )
inline

Returns true if an unrecoverable error occurred while parsing options.

An illegal argument to an option (i.e. CheckArg returns ARG_ILLEGAL) is an unrecoverable error that aborts the parse. Unknown options are only an error if their CheckArg function returns ARG_ILLEGAL. Otherwise they are collected. In that case if you want to exit the program if either an illegal argument or an unknown option has been passed, use code like this

if (parser.error() || options[UNKNOWN])
exit(1);

Definition at line 1264 of file OptionParser.h.

◆ instr()

static bool ROOT::option::Parser::instr ( char  ch,
const char *  st 
)
inlinestaticprivate

Definition at line 1346 of file OptionParser.h.

◆ nonOption()

const char * ROOT::option::Parser::nonOption ( int  i)
inline

Returns nonOptions()[i] (without checking if i is in range!).

Definition at line 1244 of file OptionParser.h.

◆ nonOptions()

const char ** ROOT::option::Parser::nonOptions ( )
inline

Returns a pointer to an array of non-option arguments (only valid if nonOptionsCount() >0 ).

Note
  • parse() does not copy arguments, so this pointer points into the actual argument vector as passed to parse().
  • As explained at nonOptionsCount() this pointer is only changed by parse() calls that actually encounter non-option arguments. A parse() call that encounters only options, will not change nonOptions().

Definition at line 1236 of file OptionParser.h.

◆ nonOptionsCount()

int ROOT::option::Parser::nonOptionsCount ( )
inline

Returns the number of non-option arguments that remained at the end of the most recent parse() that actually encountered non-option arguments.

Note
A parse() that does not encounter non-option arguments will leave this value as well as nonOptions() undisturbed. This means you can feed the Parser a default argument vector that contains non-option arguments (e.g. a default filename). Then you feed it the actual arguments from the user. If the user has supplied at least one non-option argument, all of the non-option arguments from the default disappear and are replaced by the user's non-option arguments. However, if the user does not supply any non-option arguments the defaults will still be in effect.

Definition at line 1220 of file OptionParser.h.

◆ optionsCount()

int ROOT::option::Parser::optionsCount ( )
inline

Returns the number of valid Option objects in buffer[].

Note
  • The returned value always reflects the number of Options in the buffer[] array used for the most recent call to parse().
  • The count (and the buffer[]) includes unknown options if they are collected (see Descriptor::longopt).

Definition at line 1201 of file OptionParser.h.

◆ parse() [1/4]

void ROOT::option::Parser::parse ( bool  gnu,
const Descriptor  usage[],
int  argc,
char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

parse() with non-const argv.

Definition at line 1172 of file OptionParser.h.

◆ parse() [2/4]

void ROOT::option::Parser::parse ( bool  gnu,
const Descriptor  usage[],
int  argc,
const char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

Parses the given argument vector.

Parameters
gnuif true, parse() will not stop at the first non-option argument. Instead it will reorder arguments so that all non-options are at the end. This is the default behaviour of GNU getopt() but is not conforming to POSIX.
Note, that once the argument vector has been reordered, the gnu flag will have no further effect on this argument vector. So it is enough to pass gnu==true when creating Stats.
usageArray of Descriptor objects that describe the options to support. The last entry of this array must have 0 in all fields.
argcThe number of elements from argv that are to be parsed. If you pass -1, the number will be determined automatically. In that case the argv list must end with a NULL pointer.
argvThe arguments to be parsed. If you pass -1 as argc the last pointer in the argv list must be NULL to mark the end.
optionsEach entry is the first element of a linked list of Options. Each new option that is parsed will be appended to the list specified by that Option's Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), it will be replaced rather than appended to.
The minimum length of this array is the greatest Descriptor::index value that occurs in usage PLUS ONE.
bufferEach argument that is successfully parsed (including unknown arguments, if they have a Descriptor whose CheckArg does not return ARG_ILLEGAL) will be stored in this array. parse() scans the array for the first invalid entry and begins writing at that index. You can pass bufmax to limit the number of options stored.
min_abbr_lenPassing a value min_abbr_len > 0 enables abbreviated long options. The parser will match a prefix of a long option as if it was the full long option (e.g. --foob=10 will be interpreted as if it was --foobar=10 ), as long as the prefix has at least min_abbr_len characters (not counting the -- ) and is unambiguous.
Be careful if combining min_abbr_len=1 with single_minus_longopt=true because the ambiguity check does not consider short options and abbreviated single minus long options will take precedence over short options.
single_minus_longoptPassing true for this option allows long options to begin with a single minus. The double minus form will still be recognized. Note that single minus long options take precedence over short options and short option groups. E.g. -file would be interpreted as --file and not as -f -i -l -e (assuming a long option named "file" exists).
bufmaxThe greatest index in the buffer[] array that parse() will write to is bufmax-1. If there are more options, they will be processed (in particular their CheckArg will be called) but not stored.
If you used Stats::buffer_max to dimension this array, you can pass -1 (or not pass bufmax at all) which tells parse() that the buffer is "large enough".
Attention
Remember that options and buffer store Option objects, not pointers. Therefore it is not possible for the same object to be in both arrays. For those options that are found in both buffer[] and options[] the respective objects are independent copies. And only the objects in options[] are properly linked via Option::next() and Option::prev(). You can iterate over buffer[] to process all options in the order they appear in the argument vector, but if you want access to the other Options with the same Descriptor::index, then you must access the linked list via options[]. You can get the linked list in options from a buffer object via something like options[buffer[i].index()].

Definition at line 1500 of file OptionParser.h.

◆ parse() [3/4]

void ROOT::option::Parser::parse ( const Descriptor  usage[],
int  argc,
char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

POSIX parse() (gnu==false) with non-const argv.

Definition at line 1186 of file OptionParser.h.

◆ parse() [4/4]

void ROOT::option::Parser::parse ( const Descriptor  usage[],
int  argc,
const char **  argv,
Option  options[],
Option  buffer[],
int  min_abbr_len = 0,
bool  single_minus_longopt = false,
int  bufmax = -1 
)
inline

POSIX parse() (gnu==false).

Definition at line 1179 of file OptionParser.h.

◆ shift()

static void ROOT::option::Parser::shift ( const char **  args,
int  count 
)
inlinestaticprivate

Definition at line 1358 of file OptionParser.h.

◆ streq()

static bool ROOT::option::Parser::streq ( const char *  st1,
const char *  st2 
)
inlinestaticprivate

Definition at line 1296 of file OptionParser.h.

◆ streqabbr()

static bool ROOT::option::Parser::streqabbr ( const char *  st1,
const char *  st2,
long long  min 
)
inlinestaticprivate

Definition at line 1328 of file OptionParser.h.

◆ workhorse()

bool ROOT::option::Parser::workhorse ( bool  gnu,
const Descriptor  usage[],
int  numargs,
const char **  args,
Action action,
bool  single_minus_longopt,
bool  print_errors,
int  min_abbr_len 
)
inlinestaticprivate

Definition at line 1524 of file OptionParser.h.

Friends And Related Symbol Documentation

◆ Stats

friend struct Stats
friend

Definition at line 1270 of file OptionParser.h.

Member Data Documentation

◆ err

bool ROOT::option::Parser::err
private

Definition at line 1066 of file OptionParser.h.

◆ nonop_args

const char** ROOT::option::Parser::nonop_args
private

Definition at line 1065 of file OptionParser.h.

◆ nonop_count

int ROOT::option::Parser::nonop_count
private

Definition at line 1064 of file OptionParser.h.

◆ op_count

int ROOT::option::Parser::op_count
private

Definition at line 1063 of file OptionParser.h.

  • core/dictgen/res/OptionParser.h