ArgParseInit
Description
Create a parser. The name and about pointers are borrowed – they must outlive the parser (string literals are the typical case). The -h / --help flag is registered lazily on the first ArgParseRun / ArgParseHelp call.
Two call shapes, like StrInit / VecInitT: ArgParseInit(name, about) – uses the surrounding Scope’s allocator. ArgParseInit(name, about, alloc) – explicit allocator.
Success
Yields an initialized parser. The specs Vec is empty; add specs with ArgParseAddPositional / etc.
Failure
Cannot fail at construction; first allocator OOM surfaces from later spec-Vec growth.
Usage example (Cross-references)
Usage examples (Cross-references)
- In
Resolve.c:23:
Zstr hostname = NULL;
ArgParse ap = ArgParseInit("resolve", "look up a hostname via /etc/hosts and DNS");
ArgPositional(&ap, "hostname", &hostname, "name to resolve");- In
Beam.c:389:
Zstr upstream_spec = NULL;
ArgParse ap = ArgParseInit("beam", "small reverse-proxy");
ArgRequired(&ap, "-l", "--listen", &listen_spec, "host:port to listen on");
ArgRequired(&ap, "-u", "--upstream", &upstream_spec, "upstream host:port");- In
ArgParse.c:19:
static bool test_required_long_space(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:35:
static bool test_required_long_equals(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:51:
static bool test_required_short(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:67:
static bool test_optional_default_preserved(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 timeout = 30;- In
ArgParse.c:83:
static bool test_optional_overrides_default(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 timeout = 30;- In
ArgParse.c:99:
static bool test_flag_presence(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool verbose = false;- In
ArgParse.c:115:
static bool test_flag_absence(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool verbose = false;- In
ArgParse.c:131:
static bool test_count_repeated(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 verbose = 0;- In
ArgParse.c:147:
static bool test_count_bundled(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 verbose = 0;- In
ArgParse.c:163:
static bool test_positional_order(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr src = NULL;- In
ArgParse.c:181:
static bool test_positional_with_interleaved_flag(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr src = NULL;- In
ArgParse.c:205:
static bool test_type_inferred_u32(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 n = 0;- In
ArgParse.c:221:
static bool test_type_inferred_i64_negative(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i64 v = 0;- In
ArgParse.c:237:
static bool test_type_inferred_f64(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
f64 ratio = 1.0;- In
ArgParse.c:253:
static bool test_type_inferred_str(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Str name = StrInit(&a);- In
ArgParse.c:274:
static bool test_missing_required(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:290:
static bool test_missing_positional(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr src = NULL;- In
ArgParse.c:308:
static bool test_unknown_option(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool v = false;- In
ArgParse.c:324:
static bool test_invalid_value_for_type(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 n = 0;- In
ArgParse.c:340:
static bool test_u8_overflow(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u8 v = 0;- In
ArgParse.c:356:
static bool test_too_many_positionals(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr x = NULL;- In
ArgParse.c:377:
static bool run_bool_value(Zstr text, bool *out) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
ArgOptional(&p, NULL, "--enable", out, "toggle");
char *argv[] = {(char *)"prog", (char *)"--enable", (char *)text};- In
ArgParse.c:410:
// pre-existing target value must be left untouched.
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool v = true;
ArgOptional(&p, NULL, "--enable", &v, "toggle");- In
ArgParse.c:428:
static bool test_count_u8_target(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u8 n = 0;
ArgCount(&p, "-v", "--verbose", &n, "v");- In
ArgParse.c:441:
static bool test_count_u16_target(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u16 n = 0;
ArgCount(&p, "-v", "--verbose", &n, "v");- In
ArgParse.c:454:
static bool test_count_u64_target(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u64 n = 0;
ArgCount(&p, "-v", "--verbose", &n, "v");- In
ArgParse.c:473:
// parse must error rather than read past argv.
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;
ArgRequired(&p, "-l", "--listen", &listen, "host:port");- In
ArgParse.c:487:
// A boolean flag takes no value; "--verbose=1" must be rejected.
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool v = false;
ArgFlag(&p, "-v", "--verbose", &v, "v");- In
ArgParse.c:500:
static bool test_count_rejects_inline_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 n = 0;
ArgCount(&p, "-v", "--verbose", &n, "v");- In
ArgParse.c:515:
// it must error rather than silently treat "lX" as bundled flags.
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;
ArgRequired(&p, "-l", "--listen", &listen, "host:port");- In
ArgParse.c:530:
// fail. Covers the range-check predicate in parse_signed.
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i16 lo = 0;
i16 hi = 0;- In
ArgParse.c:545:
static bool test_signed_boundary_overflow_rejected(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i16 v = 5;
ArgOptional(&p, NULL, "--v", &v, "v");- In
ArgParse.c:562:
static bool test_double_dash_separator(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cat", NULL, &a);
Zstr file = NULL;- In
ArgParse.c:586:
static bool test_help_returns_help_code(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", "test prog", &a);
Zstr required = NULL;- In
ArgParse.c:663:
static bool test_a1_full_layout(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", "test prog", &a);
Zstr src = NULL;- In
ArgParse.c:703:
static bool test_a1_no_about_no_options(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:736:
static bool test_a1_positionals_section(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr from = NULL;- In
ArgParse.c:773:
static bool test_a1_short_only_flag(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool quiet = false;- In
ArgParse.c:802:
static bool test_a1_empty_help_padding(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr mode = NULL;- In
ArgParse.c:834:
static bool test_a1_render_cap_is_64(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool flags[70] = {0};- In
ArgParse.c:930:
static bool run_u32(Zstr text, u32 *out, ArgRun *rc) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
ArgOptional(&p, NULL, "--n", out, "count");
char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};- In
ArgParse.c:941:
static bool run_u64(Zstr text, u64 *out, ArgRun *rc) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
ArgOptional(&p, NULL, "--n", out, "count");
char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};- In
ArgParse.c:1049:
static bool test_a2_store_u8_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u8 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1063:
static bool test_a2_store_u8_boundary(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u8 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1077:
static bool test_a2_store_u16_boundary(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u16 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1091:
static bool test_a2_store_u16_overflow(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u16 v = 9;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1106:
static bool test_a2_store_u32_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1120:
static bool test_a2_store_u32_overflow(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 v = 11;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1134:
static bool test_a2_store_u64_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u64 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1148:
static bool test_a2_store_str_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Str name = StrInit(&a);
StrPushBackMany(&name, "stale");- In
ArgParse.c:1164:
static bool test_a2_store_zstr_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr s = NULL;
ArgOptional(&p, NULL, "--name", &s, "n");- In
ArgParse.c:1178:
static bool test_a2_store_i16_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i16 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1193:
static bool test_a2_store_i16_rejects_garbage(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i16 v = 7;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1207:
static bool test_a2_store_i32_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i32 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1221:
static bool test_a2_store_i32_rejects_garbage(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
i32 v = 13;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1236:
static bool test_a2_store_f32_value(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
f32 v = 0;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1250:
static bool test_a2_store_f32_rejects_garbage(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
f32 v = 9;
ArgOptional(&p, NULL, "--v", &v, "");- In
ArgParse.c:1268:
static bool test_a2_metavar_uppercased(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, "-l", "--listen", &v, "addr");- In
ArgParse.c:1284:
static bool test_a2_metavar_hyphen_to_underscore(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, NULL, "--read-only", &v, "mode");- In
ArgParse.c:1300:
static bool test_a2_metavar_skips_double_dash(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, NULL, "--port", &v, "p");- In
ArgParse.c:1316:
static bool test_a2_metavar_short_only_fallback(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, "-x", NULL, &v, "x");- In
ArgParse.c:1332:
static bool test_a2_metavar_digits_passthrough(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, NULL, "--ip6", &v, "x");- In
ArgParse.c:1349:
static bool test_a2_metavar_z_uppercased(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, NULL, "--gzip", &v, "x");- In
ArgParse.c:1366:
static bool test_a2_metavar_a_uppercased(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, NULL, "--abc", &v, "x");- In
ArgParse.c:1385:
static bool test_a2_left_positional_brackets(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr s = NULL;
ArgPositional(&p, "source", &s, "from");- In
ArgParse.c:1400:
static bool test_a2_left_short_and_long(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, "-l", "--listen", &v, "addr");- In
ArgParse.c:1416:
static bool test_a2_left_full_option_line(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr v = NULL;
ArgRequired(&p, "-l", "--listen", &v, "addr");- In
ArgParse.c:1434:
static bool test_a2_left_long_only_pads_short(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 t = 0;
ArgOptional(&p, NULL, "--timeout", &t, "secs");- In
ArgParse.c:1450:
static bool test_a2_left_flag_has_no_metavar(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool f = false;
ArgFlag(&p, "-v", "--verbose", &f, "v");- In
ArgParse.c:1470:
static bool test_a2_left_width_drives_padding(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool aa = false;
Zstr bb = NULL;- In
ArgParse.c:1510:
static bool test_a3_run_argc_zero_is_ok(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
ArgRun rc = ArgParseRun(&p, 0, NULL);- In
ArgParse.c:1528:
static bool test_a3_inline_value_flag_name_terminated(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:1550:
static bool test_a3_find_short_matches_correct_spec(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool aflag = false;- In
ArgParse.c:1577:
static bool test_a3_bundle_invalid_char_errors(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 verbose = 0;- In
ArgParse.c:1598:
static bool test_a3_bundle_lookup_key_terminated(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 verbose = 0;- In
ArgParse.c:1618:
static bool test_a3_bundle_flag_stores_true(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool f = false;- In
ArgParse.c:1643:
static bool test_a3_flag_bundle_accepted(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool f = false;- In
ArgParse.c:1664:
static bool test_a3_bundle_then_missing_required(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
u32 verbose = 0;- In
ArgParse.c:1688:
static bool test_a3_short_only_option_registers(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool v = false;- In
ArgParse.c:1711:
static bool test_a3_option_without_any_name_aborts(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
bool v = false;- In
ArgParse.c:1737:
static bool test_mut_help_role_drives_options_tag(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("cp", NULL, &a);
Zstr from = NULL;- In
ArgParse.c:1818:
static bool test_blind_too_many_positionals_message(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr x = NULL;- In
ArgParse.c:1843:
static bool test_blind_missing_required_message(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
Zstr listen = NULL;- In
ArgParse.c:1870:
static bool test_blind_flag_name_too_long_boundary(void) {
DefaultAllocator a = DefaultAllocatorInit();
ArgParse p = ArgParseInit("prog", NULL, &a);
// Build "--" + 126 'a' = 128-char long name, then register it.
- In
ArgParse.c:1926:
Allocator *adbg = ALLOCATOR_OF(&dbg);
ArgParse p = ArgParseInit("prog", "an about line", adbg);
Zstr listen = NULL;
Last updated on