std/argparse

CLI argument parsing with typed flags, positional args, and auto-generated help text.

from "std/argparse" import { ArgParser, ParsedArgs, newParser }

Quick start

from "std/argparse" import { newParser, ArgParser, ParsedArgs }

fn main(): i32 {
    var parser = newParser("greet", "A greeting tool")
    parser.addRequired("name", "n", "Name to greet")
    parser.addBool("loud", "l", "Shout the greeting")
    parser.addOptionalPositional("title", "Optional title prefix")

    let args = parser.parse()
    let name = args.getString("name")

    if args.getBool("loud") {
        print($"HELLO, {name}!")
    } else {
        print($"Hello, {name}")
    }

    return 0
}

$ greet --name Alice --loud
HELLO, Alice!

$ greet --help
greet - A greeting tool

usage: greet [options] [title]

arguments:
  <title>                     Optional title prefix

options:
  -n, --name <value>          Name to greet (required)
  -l, --loud                  Shout the greeting
  -h, --help                  Show this help message

Define flags, call parse(), access typed values. --help is generated automatically. Missing required flags print an error with usage.

Types

FlagDef

struct FlagDef {
    long: string,
    short: string,
    description: string,
    required: bool,
    isBool: bool,
    isI64: bool,
}

PositionalDef

struct PositionalDef {
    name: string,
    description: string,
    required: bool,
}

ArgEntry

struct ArgEntry {
    key: string,
    value: string,
}

ArgParser

struct ArgParser {
    name: string,
    description: string,
    flags: Vec<FlagDef>,
    positionals: Vec<PositionalDef>,
}

Methods

addString

fn addString(parser: &ArgParser, long: string, short: string, description: string)

Register an optional string flag (e.g. --output, -o).

addRequired

fn addRequired(parser: &ArgParser, long: string, short: string, description: string)

Register a required string flag. Parsing fails if omitted.

addBool

fn addBool(parser: &ArgParser, long: string, short: string, description: string)

Register a boolean flag. Present = true, absent = false.

addI64

fn addI64(parser: &ArgParser, long: string, short: string, description: string, defaultVal: i64)

Register an integer flag with a default value. The value is validated as numeric at parse time.

addPositional

fn addPositional(parser: &ArgParser, name: string, description: string)

Register a required positional argument.

addOptionalPositional

fn addOptionalPositional(parser: &ArgParser, name: string, description: string)

Register an optional positional argument.

enableTrailingArgs

fn enableTrailingArgs(parser: &mut ArgParser)

Stop flag parsing after the first positional argument. All remaining arguments are collected as positionals without interpretation. Useful for runtimes and wrappers where flags before the command are yours, and everything after belongs to the child process.

The -- separator is always supported regardless of this setting — arguments after -- are never parsed as flags.

var parser = newParser("node-milo", "JS runtime")
parser.addBool("version", "v", "Print version")
parser.addOptionalPositional("script", "Script to run")
parser.enableTrailingArgs()
let args = parser.parse()
// node-milo script.js --foo  →  --foo lands in args.positional, not parsed as a flag

helpText

fn helpText(parser: &ArgParser): string

Generate a formatted help/usage string.

parse

fn parse(parser: &ArgParser, args: Vec<string>): Result<ParsedArgs>

Parse a vector of CLI arguments against the registered flags and positionals.

ParsedArgs

struct ParsedArgs {
    entries: Vec<ArgEntry>,
}

Methods

getString

fn getString(args: &ParsedArgs, key: &string): Option<string>

Get a string value by flag name or positional name.

getI64

fn getI64(args: &ParsedArgs, key: &string): Option<i64>

Get a value parsed as i64.

getU16

fn getU16(args: &ParsedArgs, key: &string): Option<u16>

Get a value parsed as u16.

getBool

fn getBool(args: &ParsedArgs, key: &string): bool

Returns true if the boolean flag was present.

has

fn has(args: &ParsedArgs, key: &string): bool

Check whether a key exists in the parsed results.

Functions

newParser

fn newParser(name: string, description: string): ArgParser

Create a new argument parser with the given program name and description.