argz.nu

argz — a small, dependency-free command-line argument parser for NURL.

Clap-shaped but deliberately tiny: boolean flags, value options (--name X and --name=X), short aliases (-n), a -- end-of-options separator, positional arguments, and an auto-generated --help body.

This package lives in the NURL registry (it is NOT part of the core stdlib): every CLI wants argument parsing, but the shape of a parser is opinionated enough that it belongs to the ecosystem, not the language.

Surface: ( argz_new prog about ) → Argz ( argz_flag p long short help ) → v bool flag (--long / -short) ( argz_opt p long short help ) → v value option (--long V) ( argz_parse p argv ) → ! ArgzMatch ArgzErr ( argz_has m long ) → b flag/option present? ( argz_value m long ) → ?String value of an option (borrows) ( argz_positionals m ) → ( Vec String ) (borrows) ( argz_help p ) → String rendered usage text ( argz_err_name e ) → s ( argz_free p ) / ( argz_match_free m ) → v

short may be empty (""), meaning the spec has no short alias. Option values and positionals returned by the accessors BORROW the match's storage — do not free them; argz_match_free owns the whole match.

API

: ArgSpec

: ArgSpec {
    String long        // canonical name, without the leading "--"
    String short       // single letter without the leading "-"; "" = none
    i takes_value      // 1 = consumes a value, 0 = boolean flag
    String help        // one-line description for --help
}

: Argz

: Argz {
    String prog
    String about
    ( Vec ArgSpec ) specs
}

: ArgzMatch

: ArgzMatch {
    ( Vec String ) names    // long name of each flag/option that was seen
    ( Vec String ) values   // parallel to names; "" for boolean flags
    ( Vec String ) rest     // positional arguments, in order
}

: | ArgzErr

: | ArgzErr {
    ArgzUnknownFlag      // a --flag / -f not registered with the parser
    ArgzMissingValue     // a value option appeared with no value after it
}

@ argz_err_name ArgzErr e → s

@ argz_new s prog s about → Argz

@ argz_flag Argz p s long s short s help → v

@ argz_opt Argz p s long s short s help → v

@ argz_parse Argz p ( Vec String ) argv → !ArgzMatch ArgzErr

@ argz_has ArgzMatch m s long → b

@ argz_value ArgzMatch m s long → ?String

@ argz_positionals ArgzMatch m → ( Vec String )

@ argz_help Argz p → String

@ argz_free Argz p → v

@ argz_match_free ArgzMatch m → v