ArgOptional

Documentation

API Reference

ArgOptional

Description

Register an optional value option. Target keeps its prior value if the option doesn’t appear – initialise with the default you want.

Usage example (from documentation)

  u32 timeout = 30;
  ArgOptional(&p, NULL, "--timeout", &timeout, "connection timeout in seconds");

Success

Appends an ARG_ROLE_OPTIONAL spec to the parser; the target is overwritten only if the option appears on the command line.

Failure

LOG_FATAL if parser is NULL, if target resolves to an unsupported type (ARG_KIND_INVALID), or if both short_ and long_ are NULL.

Usage example (Cross-references)

Usage examples (Cross-references)

In ArgParse.c:70:

    
        u32 timeout = 30;
        ArgOptional(&p, NULL, "--timeout", &timeout, "seconds");
    
        char  *argv[] = {(char *)"prog"};

In ArgParse.c:86:

    
        u32 timeout = 30;
        ArgOptional(&p, NULL, "--timeout", &timeout, "seconds");
    
        char  *argv[] = {(char *)"prog", (char *)"--timeout", (char *)"5"};

In ArgParse.c:208:

    
        u32 n = 0;
        ArgOptional(&p, NULL, "--n", &n, "count");
    
        char  *argv[] = {(char *)"prog", (char *)"--n=12345"};

In ArgParse.c:224:

    
        i64 v = 0;
        ArgOptional(&p, NULL, "--v", &v, "v");
    
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"-42"};

In ArgParse.c:240:

    
        f64 ratio = 1.0;
        ArgOptional(&p, NULL, "--ratio", &ratio, "r");
    
        char  *argv[] = {(char *)"prog", (char *)"--ratio=2.5"};

In ArgParse.c:256:

    
        Str name = StrInit(&a);
        ArgOptional(&p, NULL, "--name", &name, "n");
    
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"alice"};

In ArgParse.c:327:

    
        u32 n = 0;
        ArgOptional(&p, NULL, "--n", &n, "");
    
        char  *argv[] = {(char *)"prog", (char *)"--n", (char *)"abc"};

In ArgParse.c:343:

    
        u8 v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
    
        char  *argv[] = {(char *)"prog", (char *)"--v=256"};

In ArgParse.c:378:

        DefaultAllocator a = DefaultAllocatorInit();
        ArgParse         p = ArgParseInit("prog", NULL, &a);
        ArgOptional(&p, NULL, "--enable", out, "toggle");
        char  *argv[] = {(char *)"prog", (char *)"--enable", (char *)text};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:412:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        bool             v = true;
        ArgOptional(&p, NULL, "--enable", &v, "toggle");
        char  *argv[] = {(char *)"prog", (char *)"--enable", (char *)"maybe"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:533:

        i16              lo = 0;
        i16              hi = 0;
        ArgOptional(&p, NULL, "--lo", &lo, "lo");
        ArgOptional(&p, NULL, "--hi", &hi, "hi");
        char  *argv[] = {(char *)"prog", (char *)"--lo=-32768", (char *)"--hi=32767"};

In ArgParse.c:534:

        i16              hi = 0;
        ArgOptional(&p, NULL, "--lo", &lo, "lo");
        ArgOptional(&p, NULL, "--hi", &hi, "hi");
        char  *argv[] = {(char *)"prog", (char *)"--lo=-32768", (char *)"--hi=32767"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:547:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        i16              v = 5;
        ArgOptional(&p, NULL, "--v", &v, "v");
        char  *argv[] = {(char *)"prog", (char *)"--v=32768"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:671:

        ArgPositional(&p, "source", &src, "src file");
        ArgRequired(&p, "-l", "--listen", &listen, "host:port");
        ArgOptional(&p, NULL, "--timeout", &timeout, "secs");
        ArgFlag(&p, "-v", "--verbose", &verbose, "be loud");

In ArgParse.c:805:

    
        Zstr mode = NULL;
        ArgOptional(&p, NULL, "--mode", &mode, "");
    
        // "      --mode <MODE>" width = 19, widest, pad to 21.

In ArgParse.c:931:

        DefaultAllocator a = DefaultAllocatorInit();
        ArgParse         p = ArgParseInit("prog", NULL, &a);
        ArgOptional(&p, NULL, "--n", out, "count");
        char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};
        *rc          = ArgParseRun(&p, 3, argv);

In ArgParse.c:942:

        DefaultAllocator a = DefaultAllocatorInit();
        ArgParse         p = ArgParseInit("prog", NULL, &a);
        ArgOptional(&p, NULL, "--n", out, "count");
        char *argv[] = {(char *)"prog", (char *)"--n", (char *)text};
        *rc          = ArgParseRun(&p, 3, argv);

In ArgParse.c:1051:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u8               v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=200"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1065:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u8               v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=255"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1079:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u16              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=65535"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1093:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u16              v = 9;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=65536"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1108:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u32              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=70000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1122:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u32              v = 11;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=4294967296"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1136:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u64              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=5000000000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1151:

        Str              name = StrInit(&a);
        StrPushBackMany(&name, "stale");
        ArgOptional(&p, NULL, "--name", &name, "n");
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"bob"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:1166:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        Zstr             s = NULL;
        ArgOptional(&p, NULL, "--name", &s, "n");
        char  *argv[] = {(char *)"prog", (char *)"--name", (char *)"carol"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:1180:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        i16              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=-5"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1195:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        i16              v = 7;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"zzz"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:1209:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        i32              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=-100000"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1223:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        i32              v = 13;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"nope"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:1238:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        f32              v = 0;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v=2.5"};
        ArgRun rc     = ArgParseRun(&p, 2, argv);

In ArgParse.c:1252:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        f32              v = 9;
        ArgOptional(&p, NULL, "--v", &v, "");
        char  *argv[] = {(char *)"prog", (char *)"--v", (char *)"xyz"};
        ArgRun rc     = ArgParseRun(&p, 3, argv);

In ArgParse.c:1436:

        ArgParse         p = ArgParseInit("prog", NULL, &a);
        u32              t = 0;
        ArgOptional(&p, NULL, "--timeout", &t, "secs");
        Str  help = StrInit(&a);
        bool got  = capture_help_file(&p, &help);

In ArgParse.c:1933:

        Zstr hostname = NULL;
        ArgRequired(&p, "-l", "--listen", &listen, "host:port to listen on");
        ArgOptional(&p, NULL, "--timeout", &timeout, "connection timeout");
        ArgFlag(&p, "-v", "--verbose", &verbose, "verbose logging");
        ArgPositional(&p, "hostname", &hostname, "name to resolve");

Last updated on July 1, 2026

ArgKind ArgParse