README.md
1# libbase components
2
3## pandargs
4
5### Description:
6
7pandargs is header-only utility tool that helps to parse command line arguments. It supports several argument types:
8- integer
9- double
10- boolean
11- string
12- uint64_t
13- list
14
15The more detail description of each type is in "Usage" section below.
16
17Source code of pandargs is contained in `utils/pandargs.h` file.
18
19### Usage:
20
21pandargs API consists of two major entities: template class `PandArg`, which represents an argument and `PandArgParser` class, which represents a parser.
22
23#### Arguments
24
25To create an argument, its template constructor should be called. Here is an instance:
26
27```c++
28 // argument name | default value | argument description
29 panda::PandArg<bool> pab("bool", false, "Sample boolean argument");
30```
31
32Constructor can accept:
33- 3 parameters: argument name, default value, description.
34- 4 parameters for single list: argument name, default value, description, delimiter.
35- 5 parameters for integer args: argument name, default value, description, min value, max value
36
37There is description for them:
38- Argument name, is a name, which will appear in a command line.
39- Default value is a value argument will have regardless was it parsed or not.
40- Argument description will be used to form a help messsage.
41- Delimiter is a character or string that separates the different value if the single argument list.
42- Min value is the number that the integer argument cannot be less than.
43- Max value is the number that the integer argument cannot be greater than.
44
45Template parameter is an argument type. Following values could be passed:
46- `int` for integer argument
47- `double` for double argument
48- `bool` for boolean argument
49- `std::string` for string argument
50- `uint64_t` for uint64_t argument
51- `arg_list_t` for list argument
52
53`arg_list_t` is a type, declared in `pandargs.h` under `panda` namespace, which is an alias for `std::vector<std::string>` type.
54
55`PandArg` provide following public API:
56- `PandArgType GetType()` - return type of an argument
57- `std::string GetName()` - return name of an argument
58- `std::string GetDesc()` - return description of an argument
59- `T GetValue()` - return value of an argument depending on its type
60- `T GetDefaultValue()` - return default value of an argument
61- `void SetValue(T val)` - set value of an argument
62- `ResetDefaultValue()` - set value back to default one
63
64#### Argument types
65There are three global argument types in pandargs:
66- regular arguments
67- tail arguments
68- remainder arguments
69
70Regular arguments are typical non-positional arguments like ```--arg=1```
71Tail arguments are positional arguments, which should be introduced with help of parser API
72Remainder arguments are arguments that come after trailing `--`. All of them are plain std::vector of std::string
73
74#### Parser
75
76`PandArgParser` provides following public API:
77- `bool Add(PandArgBase* arg)` - add an argument to parser. Return `true` if argument was succsessfully added. `PandArgBase` is a base type for all template argument types
78- `bool Parse(int argc, const char* argv[])` - parse arguments. Return `true` on success. Note: `argv` & `argc` should be passed as is, without any amendments
79- `std::string GetErrorString()` - return error string if error occurred on argument addition or parsing
80- `void EnableTail()` - enable positional arguments
81- `void DisableTail()` - disable positional arguments
82- `bool IsTailEnabled()` - return `true` if positional arguments enabled
83- `bool IsArgSet(PandArgBase* arg)` - return `true` if an argument was added to a parser
84- `bool IsArgSet(const std::string& arg_name)` - return `true` if an argument with given name was added to a parser
85- `bool PushBackTail(PandArgBase* arg)` - add tail argument to the end of tail arguments list. `false` if argument already in a tail list
86- `bool PopBackTail()` - remove last argument from tail list
87- `void EraseTail()` - remove all arguments from tail list
88- `void EnableRemainder()` - enable remainder argument
89- `void DisableRemainder()` - disable remainder argument
90- `bool IsRemainderEnabled()` - return `true` if remainder argument enabled
91- `arg_list_t GetRemainder()` - return remainder argument
92- `std::string GetHelpString()` - return string with all arguments and their description
93- `std::string GetRegularArgs()` - return string with all regular arguments and their values
94
95Tail argument is a sequence of positinal arguments values. Function ```PushBackTail()``` adds an argument to the end of sequence, and ```PopBackTail()``` removes the last added argument. Tail arguments may be added to a parser when tail is disabled, but they will be ignored if tail is disabled while parsing.
96
97Sample parser usage:
98```c++
99 panda::PandArgParser pa_parser;
100 pa_parser.EnableTail();
101 pa_parser.Add(&pab);
102 if (!pa_parser.Add(&pab)) {
103 std::cout << pa_parser.GetErrorString();
104 }
105 if (!pa_parser.Parse(argc, argv)) {
106 std::cout << pa_parser.GetErrorString();
107 }
108```
109
110#### Command line arguments convention
111
112- Any non-positional argument should start with `--` (double dash) prefix.
113- Argument and it's value may be separated either by whitespace (` `) or by equals (`=`) sign.
114- If tail (positional arguments) enabled, first argument without double dash prefix concidered as a begin of positional arguments sequence.
115- Positional arguments should be without names or `=` signs, separated by whitespaces.
116- Boolean argument may be used without a value. This arguments are always considered as `true`.
117- Remainder arguments are all literals that come after trailing `--`.
118- True values for boolean arguments: **true**, **on**, **1**.
119- False values for boolean arguments: **false**, **off**, **0**.
120- For integer arguments it's possible to define value range.
121- List values must be repeated with arg name or separated by delimiter.
122- String and list arguments may accept no parameters.
123
124Sample command line usage:
125```bash
126$ ./app --bool # bool is true
127$ ./app --bool= # bool is true
128$ ./app --bool on --bool1=off # bool is true, bool1 is false
129$ ./app --uint64=64 # uint64 is 64
130$ ./app --string="a string" # string is "a string"
131$ ./app --string "a string" # string is "a string"
132$ ./app --string string # string is "string"
133$ ./app --string= --int=1 # string is an empty string, int is 1
134$ ./app --list=val1 --list=val2 --list=val3 # list argument example
135$ ./app --slist=val1:val2:val3 # list argument example
136$ ./app --int=0x40 --uint64=0x400 # int is 64, uint64 is 1024
137$ ./app --int=1 false -1 "list1 list2 list3" # tail arguments example
138$ ./app --double 3.14 --bool off -- arg1 --arg2=1 --arg3=false # remainder arguments example
139```
140In the tail arguments example, `false` is a boolean value, `-1` is integer value and `str1` and `str2` is a string value. List may not be a tail argument. Positional values are verified the same way as regular values. The only difference is that its names are ignored in an input string, but position matters.
141In the remainder arguments example, all literals coming after `--` will go to remainder and can be obtained by `GetRemainder()` function.
142
143How to add tail arguments:
144```c++
145 panda::PandArgParser pa_parser;
146 pa_parser.EnableTail();
147 // now pab will be processed as a positional argument
148 if (!pa_parser.PushBackTail(&pab)) {
149 std::cout << pa_parser.GetErrorString();
150 }
151 if (!pa_parser.Parse(argc, argv)) {
152 std::cout << pa_parser.GetErrorString();
153 }
154```
155