Skip to content

Arguments

Tsukini edited this page Oct 4, 2026 · 1 revision

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.

Table of Contents

ArgParser

ArgParser(binary = "[None]", description = "..."), the binary and description are used by the help.

Flags

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).

Options

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

Usages

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.

Parsing

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()).

Hooks

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().

Example

#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;
}

Settings

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

Setting

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"];)

Casts

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.

Example

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"];

Errors

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

Clone this wiki locally