Repository navigation
Arguments
Note
Section _Arguments (group _Handling) · Namespace utils::arguments · Headers utils/arguments/
Two tools: ArgParser checks and parses argc / argv against the usages of the program, Settings stores typed settings (any type) and converts strings to the right type.
ArgParser(binary = "[None]", description = "..."), the binary and description are used by the help.
setFlag<force>(id, {short, flag, long, env}, options, description, unlimited = false, ignore_case = false)
| Part | Matched as | Example |
|---|---|---|
short |
-<short> (combinable: -va) |
"n" -> -n
|
flag |
-<flag> |
"num" -> -num
|
long |
--<long> (also --long=value) |
"number" -> --number
|
env |
environment variable read when the flag is missing | "APP_NUMBER" |
An empty string disables a part. options is the ordered list of the values of the flag, {name, mandatory, check}; unlimited = true reads values until one fails its check (the flag needs at least one option).
Positional arguments:
| Method | Description |
|---|---|
setOption<force>(id, name, description) |
exact option: the argument must be name (ex: a sub command run) |
setOption<force>(id, name, check, description) |
free option validated by check
|
setUsage<force>(id, name, ordered, {{id, mandatory}, ...}, description): a usage lists the flags / options it allows and the mandatory ones. With ordered = true the order of the arguments matters. setDefaultUsage() adds the special usage default that allows every flag.
| Method | Description |
|---|---|
removeUsage(s), removeOption(s), removeFlag(s)
|
Remove by id (unknown id: warning on std::cerr) |
resetUsages(), resetOptions(), resetFlags()
|
Remove everything of a kind |
getUsages(), getOptions(), getFlags(), getBinary(), getDescription()
|
Getters |
Note
The set* methods refuse to override an existing id (Override), set*<true> overrides it.
parse(argc, argv, failsafe = false) or parse(std::vector<std::string>, failsafe) returns the usages compliant with the arguments (ParsedUsages = std::vector<ParsedUsage>):
struct ParsedUsage {
std::string id; // usage id
std::vector<std::tuple<std::string, bool, std::vector<std::string>>> arguments; // <id, option(true) | flag(false), values>
};-h, -help, --help call the help hook then throw NoneException(Exit) (disabled by disableHelp()).
Check hooks have the signature std::optional<std::string>(const std::string&): std::nullopt = valid, a string = the error message.
| Hook | Accepts |
|---|---|
defaultBoolParsingHook |
0, 1, false, true
|
defaultInt32ParsingHook |
a std::int32_t
|
defaultSizetParsingHook |
a std::size_t
|
defaultDoubleParsingHook |
a double
|
defaultFileParsingHook |
a readable file |
defaultDirectoryParsingHook |
a readable directory |
defaultWritableParsingHook |
a readable and writable path |
defaultTrueParsingHook |
anything |
The help display is defaultHelpHook(parser), replaced with setHelpHook(hook), back with resetHelpHook(), displayed with help().
#define _Arguments
#include <utils/utils.hpp>
int main(int argc, char* argv[])
{
utils::arguments::ArgParser parser("app", "Process some numbers");
parser.setFlag("number", {"n", "num", "number", "APP_NUMBER"}, {{"value", true, utils::arguments::defaultInt32ParsingHook}}, "A number");
parser.setFlag("verbose", {"v", "", "verbose", ""}, {}, "Verbose mode");
parser.setUsage("main", "main", false, {{"number", true}, {"verbose", false}}, "Main usage");
try {
for (const auto& [id, arguments]: parser.parse(argc, argv))
for (const auto& [arg, isOption, values]: arguments)
std::cout << id << ": " << arg << " " << values.size() << " value(s)" << std::endl;
} catch (const utils::exception::IException& e) {
if (e.isNone()) return 0; // -h
std::cerr << e.formated() << std::endl;
return 1;
}
return 0;
}A map id -> Setting (lookup with a std::string_view without copy).
| Method | Description |
|---|---|
add(id, value) |
Add a setting, Override if the id exists |
set<force = true>(id, value) |
Add or replace (edit in place) |
get<T>(id) |
Reference on the value (BadCast when the type differs) |
get(id), at(id), operator[](id)
|
The Setting itself (UnknownId when missing) |
contains(id) |
Is the id set |
remove<failsafe = false>(id) |
Remove (UnknownId when missing, nothing with failsafe) |
clear() |
Remove everything |
autoCast<force = false>(id, string) |
Detect the type of the string, store the converted value, return the CastType
|
cast<CastType, force = false>(id, string) |
Convert the string to the given type and store it |
| Method | Description |
|---|---|
get<T>() |
Value as T (BadCast when it isn't a T) |
is<T>() |
Is the stored value a T
|
assign(value) |
Replace the value (any type) |
operator T() |
Implicit conversion (int n = settings["n"];) |
CastType |
C++ type | Detected by autoCast
|
|---|---|---|
None |
std::string |
anything else |
Bool |
bool |
true, false, t, f (any case) |
Int32 / Int64
|
std::int32_t / std::int64_t
|
negative integers |
UInt32 / UInt64
|
std::uint32_t / std::uint64_t
|
positive integers |
Float64 / Float128
|
float64_t / float128_t
|
decimals (Float128 when out of the double range) |
Path |
std::filesystem::path |
strings with a /
|
Byte, Int8, Int16, UInt8, UInt16, Float16, Float32
|
std::byte, fixed size integers, floats |
only with cast
|
Char8, Char16, Char32, WChar
|
char8_t, char16_t, char32_t, wchar_t
|
only with cast (a character or a code point) |
U8String, U16String, U32String, WString
|
std::u8string, std::u16string, std::u32string, std::wstring
|
only with cast (from UTF-8) |
Warning
The conversions check the range: "300" cast to UInt8 throws BadCast, a value out of the float16 range throws OutOfBounds.
utils::arguments::Settings settings;
settings.add("name", std::string("server"));
settings.autoCast("port", "4242"); // UInt32
settings.cast<utils::arguments::CastType::Path>("root", "/srv/www");
settings.get<std::uint32_t>("port") += 1; // edit in place
std::filesystem::path root = settings["root"];| Code | When |
|---|---|
ArgumentsNumber |
argv is empty |
NoCompliantUsage |
No usage matches the arguments |
UnknownFlag |
Unknown flag |
FlagOptionsNumber, FlagOption
|
Missing / invalid value of a flag |
OptionsNumber, Option, OptionIngored
|
Missing / invalid / unexpected option |
DuplicatedFlag, FlagCombinaison
|
Flag given twice, invalid combination |
ArgParserHook |
A hook threw |
Exit (NoneException) |
The help was displayed |
Override, UnknownId, BadCast, OutOfBounds, InvalidArgument
|
Settings |
Home · Installing · Usage · Tools Preview · Sections · Workflow (CI-CD)
libutils is licensed under MIT (the synced algorithms under CC BY-NC-SA 4.0).