|
argagg
|
|
argagg
|
There are only two hard things in Computer Science: cache invalidation and naming things (Phil Karlton). More...
Namespaces | |
| convert | |
| The set of template instantiations that convert C-strings to other types for the option_result::as(), option_results::as(), parser_results::as(), and parser_results::all_as() methods are placed in this namespace. | |
Classes | |
| struct | unexpected_argument_error |
| This exception is thrown when a long option is parsed and is given an argument using the "=" syntax but the option doesn't expect an argument. More... | |
| struct | unexpected_option_error |
| This exception is thrown when an option is parsed unexpectedly such as when an argument was expected for a previous option or if an option was found that has not been defined. More... | |
| struct | option_lacks_argument_error |
| This exception is thrown when an option requires an argument but is not provided one. This can happen if another flag was found after the option or if we simply reach the end of the command line arguments. More... | |
| struct | invalid_flag |
| This exception is thrown when an option's flag is invalid. This can be the case if the flag is not prefixed by one or two hyphens or contains non alpha-numeric characters after the hypens. See is_valid_flag_definition() for more details. More... | |
| struct | option_result |
| Represents a single option parse result. More... | |
| struct | option_results |
| Represents multiple option parse results for a single option. If treated as a single parse result it defaults to the last parse result. Note that an instance of this struct is always created even if no option results are parsed for a given definition. In that case it will simply be empty. More... | |
| struct | parser_results |
| Represents all results of the parser including options and positional arguments. More... | |
| struct | definition |
| An option definition which essentially represents what an option is. More... | |
| struct | parser_map |
| Contains two maps which aid in option parsing. The first map, short_map, maps from a short flag (just a character) to a pointer to the original definition that the flag represents. The second map, long_map, maps from a long flag (an std::string) to a pointer to the original definition that the flag represents. More... | |
| struct | parser |
| A list of option definitions used to inform how to parse arguments. More... | |
| struct | fmt_ostream |
| A convenience output stream that will accumulate what is streamed to it and then, on destruction, format the accumulated string using the fmt program (via the argagg::fmt_string() function) to the provided std::ostream. More... | |
Functions | |
| bool | cmd_line_arg_is_option_flag (const char *s) |
| Checks whether or not a command line argument should be processed as an option flag. This is very similar to is_valid_flag_definition() but must allow for short flag groups (e.g. "-abc") and equal-assigned long flag arguments (e.g. "--output=foo.txt"). More... | |
| bool | is_valid_flag_definition (const char *s) |
| Checks whether a flag in an option definition is valid. I suggest reading through the function source to understand what dictates a valid. More... | |
| bool | flag_is_short (const char *s) |
| Tests whether or not a valid flag is short. Assumes the provided cstring is already a valid flag. More... | |
| parser_map | validate_definitions (const std::vector< definition > &definitions) |
| Validates a collection (specifically an std::vector) of definition objects by checking if the contained flags are valid. If the set of definition objects is not valid then an exception is thrown. Upon successful validation a parser_map object is returned. More... | |
| std::string | fmt_string (const std::string &s) |
| Processes the provided string using the fmt util and returns the resulting output as a string. Not the most efficient (in time or space) but gets the job done. More... | |
There are only two hard things in Computer Science: cache invalidation and naming things (Phil Karlton).
The names of types have to be succint and clear. This has turned out to be a more difficult thing than I expected. Here you'll find a quick overview of the type names you'll find in this namespace (and thus "library").
When a program is invoked it is passed a number of "command line arguments". Each of these "arguments" is a string (C-string to be more precise). An "option" is a command line argument that has special meaning. This library recognizes a command line argument as a potential option if it starts with a dash ('-') or double-dash ('–').
A "parser" is a set of "definitions" (not a literal std::set but rather a std::vector). A parser is represented by the argagg::parser struct.
A "definition" is a structure with four components that define what "options" are recognized. The four components are the name of the option, the strings that represent the option, the option's help text, and how many arguments the option should expect. "Flags" are the individual strings that represent the option ("-v" and "--verbose" are flags for the "verbose" option). A definition is represented by the argagg::definition struct.
Note at this point that the word "option" can be used interchangeably to mean the notion of an option and the actual instance of an option given a set of command line arguments. To be unambiguous we use a "definition" to represent the notion of an option and an "option result" to represent an actual option parsed from a set of command line arguments. An "option result" is represented by the argagg::option_result struct.
There's one more wrinkle to this: an option can show up multiple times in a given set of command line arguments. For example, "-n 1 -n 2 -n 3". This will parse into three distinct argagg::option_result instances, but all of them correspond to the same argagg::definition. We aggregate these into the argagg::option_results struct which represents "all parser results for a given option definition". This argagg::option_results is basically a std::vector of argagg::option_result.
Options aren't the only thing parsed though. Positional arguments are also parsed. Thus a parser produces a result that contains both option results and positional arguments. The parser results are represented by the argagg::parser_results struct. All option results are stored in a mapping from option name to the argagg::option_results. All positional arguments are simply stored in a vector of C-strings.
|
inline |
Checks whether or not a command line argument should be processed as an option flag. This is very similar to is_valid_flag_definition() but must allow for short flag groups (e.g. "-abc") and equal-assigned long flag arguments (e.g. "--output=foo.txt").
Definition at line 824 of file argagg.hpp.
|
inline |
Tests whether or not a valid flag is short. Assumes the provided cstring is already a valid flag.
Definition at line 960 of file argagg.hpp.
|
inline |
Processes the provided string using the fmt util and returns the resulting output as a string. Not the most efficient (in time or space) but gets the job done.
This function is cowardly so if there are any errors encountered such as a syscall returning -1 then the input string is returned.
__unix__ preprocessor definition is defined since it relies on the POSIX API for forking, executing a process, reading/writing to/from file descriptors, and the existence of the fmt util. Definition at line 1458 of file argagg.hpp.
|
inline |
Checks whether a flag in an option definition is valid. I suggest reading through the function source to understand what dictates a valid.
Definition at line 904 of file argagg.hpp.
|
inline |
Validates a collection (specifically an std::vector) of definition objects by checking if the contained flags are valid. If the set of definition objects is not valid then an exception is thrown. Upon successful validation a parser_map object is returned.
Definition at line 1005 of file argagg.hpp.
1.8.5