Small utility to parse cmdline options.
Usage:
MyAppOpts
ParseArgs(
const char **args,
int nArgs) {
}
MyAppOpts myOpts;
myOpts.fRecreate = opts.
GetSwitch(
"recreate");
return myOpts;
}
Small utility to parse cmdline options.
void AddFlag(std::initializer_list< std::string_view > aliases, EFlagType type=EFlagType::kSwitch, std::string_view help="", std::uint32_t flagOpts=0)
Defines a new flag (either a switch or a flag with argument).
void Parse(const char *const *const args, std::size_t nArgs)
Parses the given arguments, allowing for their retrieval via GetSwitch, GetFlagValue,...
const std::vector< std::string > & GetErrors() const
Returns all parsing errors.
int GetSwitch(std::string_view name) const
If name refers to a previously-defined switch (i.e.
const std::vector< std::string > & GetArgs() const
Retrieves all positional arguments.
std::string_view GetFlagValue(std::string_view name) const
If name refers to a previously-defined non-switch flag, gets its value.
std::optional< T > GetFlagValueAs(std::string_view name) const
Tries to retrieve the flag value as a type T.
static std::optional< HAddArgs > ParseArgs(int argc, char **argv)
Additional Notes
Flag grouping
By default, if all the short flags you pass (those starting with a single -) are 1 character long, the parser will accept grouped flags like "-abc" as equivalent to "-a -b -c". The last flag in the group may also accept an argument, in which case "-abc foo" will count as "-a -b -c foo" where "foo" is the argument to "-c". If you want to disable flag grouping, use:
@ kSimple
-abc will always be treated as the single flag "-abc"
Repeated flags
Multiple repeated flags, like -vvv, are supported but must explicitly be marked as such on a per-flag basis:
@ kFlagAllowMultiple
Flag is allowed to appear multiple times (default: it's an error to see the same flag twice)
This works both for switches and flags with arguments. GetSwitch returns the number of times a specific flag appeared; for flags with arguments GetFlagValues and GetFlagValuesAs<T> can be used to access the values as vectors.
Positional argument separator
The string "--" is treated as the positional argument separator: all strings after it will be treated as positional arguments even if they start with "-".
Prefix flags (aka no space between flag and argument)
If you need your flags to support the syntax "-fXYZ" where "-f" is your flag and "XYZ" its argument, you can enable that per-flag by using RCmdLineOpts::kFlagPrefixArg:
@ kFlagPrefixArg
Flag argument can appear right after this flag without a space or equal sign in between.
(see EFlagTreatment for more details). This will disable flag grouping globally, but allows the parser to interpret flags and arguments that are not separated by spaces. If prefix arg is used, the equal sign will not be considered as the key-value separator (-Dfoo=bar if -D is a prefix arg flag will be parsed as "-D", "foo=bar"). Note that this option only makes sense for flags with arguments.
Definition at line 98 of file optparse.hxx.
|
| | RCmdLineOpts (RSettings settings={}) |
| |
| void | AddFlag (std::initializer_list< std::string_view > aliases, EFlagType type=EFlagType::kSwitch, std::string_view help="", std::uint32_t flagOpts=0) |
| | Defines a new flag (either a switch or a flag with argument).
|
| |
| const std::vector< std::string > & | GetArgs () const |
| | Retrieves all positional arguments.
|
| |
| std::vector< std::pair< std::size_t, std::string > > | GetArgsWithIndices () const |
| | Retrieves all positional arguments alongside their original position in the given args array.
|
| |
| const std::vector< std::string > & | GetErrors () const |
| | Returns all parsing errors.
|
| |
| std::optional< std::size_t > | GetFirstPostDashDashArg () const |
| | Returns the index of the first positional argument that appeared after --.
|
| |
| const std::vector< RFlag > & | GetFlags () const |
| | Retrieves all parsed flags.
|
| |
| std::string_view | GetFlagValue (std::string_view name) const |
| | If name refers to a previously-defined non-switch flag, gets its value.
|
| |
| template<typename T > |
| std::optional< T > | GetFlagValueAs (std::string_view name) const |
| | Tries to retrieve the flag value as a type T.
|
| |
| std::vector< std::string_view > | GetFlagValues (std::string_view name) const |
| | If name refers to a previously-defined non-switch flag, gets its values.
|
| |
| template<typename T > |
| std::vector< T > | GetFlagValuesAs (std::string_view name) const |
| | Tries to retrieve the flag values as a type T.
|
| |
| const RSettings & | GetSettings () const |
| |
| int | GetSwitch (std::string_view name) const |
| | If name refers to a previously-defined switch (i.e.
|
| |
| const std::vector< std::size_t > & | GetUnprocessedArgsIndices () const |
| | Returns a list of the indices of all args passed to Parse() that were not parsed.
|
| |
| void | Parse (const char *const *const args, std::size_t nArgs) |
| | Parses the given arguments, allowing for their retrieval via GetSwitch, GetFlagValue, etc.
|
| |
| bool | ReportErrors (std::ostream &stream=std::cerr) const |
| | Conveniency method to print any errors to stream.
|
| |
| void ROOT::RCmdLineOpts::AddFlag |
( |
std::initializer_list< std::string_view > | aliases, |
|
|
EFlagType | type = EFlagType::kSwitch, |
|
|
std::string_view | help = "", |
|
|
std::uint32_t | flagOpts = 0 ) |
|
inline |
Defines a new flag (either a switch or a flag with argument).
The flag may be referred to as any of the values inside aliases (e.g. { "-h", "--help" }). You must pass at least 1 string inside aliases. All strings inside aliases must start with - or -- and be at least 1 character long (aside the dashes). Flags starting with a single - are considered "short", regardless of their actual length. If all short flags are 1 character long, they may be collapsed into one and parsed as individual flags (meaning a string like "-fgk" will be parsed as "-f -g -k") and the final flag may have a following argument. This does NOT happen if any short flag is longer than 1 character, to avoid ambiguity.
- Parameters
-
| aliases | All the equivalent names of this flag |
| type | What kind of flag is this: with arguments or not |
| help | Help string for the flag |
| flagOpts | Bitmask of EFlagOpt for additional options |
- Exceptions
-
| std::invalid_argument | if aliases is empty. |
| std::invalid_argument | if flagOpts and type are inconsistent (e.g. a Switch is given the opt kFlagPrefixArg). |
| std::invalid_argument | if any flag in aliases does not start with - or is empty after the prefix. |
| std::invalid_argument | if any of the values in aliases was already added previously. |
| std::invalid_argument | if the same value appears multiple times in aliases. |
| std::invalid_argument | if any of the values in aliases have a common prefix with another flag which is marked as kFlagPrefixArg. |
| std::invalid_argument | if the flag treatment was explicitly specified as kGrouped but a short flag is given in aliases which is longer than one character. |
Definition at line 246 of file optparse.hxx.