Cli

Cli module: parse argv-style command-line arguments into typed values.

Public API: Cli.flag(long, help) : FlagSpec (boolean, optional) Cli.value_flag(long, help) : FlagSpec (value-taking, optional) Cli.flag_with(long, short, arity, default, required, help) : FlagSpec Cli.parse(specs, argv) : Result(ParsedArgs, CliError) Cli.get_string(parsed, long) : Option(String) Cli.get_string_or(parsed, long, default) : String Cli.get_int(parsed, long) : Option(Int) Cli.get_bool(parsed, long) : Bool Cli.positional(parsed) : List(String) Cli.error_message(err) : String Cli.help_text(program_name, specs) : String

Types

typeFlagArityFlagArity = BoolFlag | ValueFlag#

typeFlagSpecFlagSpec = {#

typeCliErrorCliError#

typeParsedArgsParsedArgs = {#

Functions

fnerror_messageerror_message(err : CliError) : String#

Render a CliError as a one-line, user-facing message.

Examples

    march> Cli.error_message(UnknownFlag("bogus"))
    "unknown flag: --bogus"

fnflagflag(long : String, help : String) : FlagSpec#

Build a boolean flag spec (no short form, optional, defaults to unset/false).

Examples

    march> let spec = Cli.flag("verbose", "Enable verbose output")
    march> spec.long
    "verbose"

fnflag_withflag_with(long : String, short : Option(String), arity : FlagArity, default : Option(String), required : Bool, help : String) : FlagSpec#

Build a fully custom flag spec.

Examples

    march> let spec = Cli.flag_with("port", Some("p"), ValueFlag, Some("4000"), true, "Port to listen on")
    march> spec.required
    true

fnget_boolget_bool(parsed : ParsedArgs, long : String) : Bool#

Read a boolean flag's value. Absent means false.

Examples

    march> let parsed = Cli.parse([Cli.flag("v", "")], [])
    march> match parsed do | Ok(p) -> Cli.get_bool(p, "v") | Err(_) -> true end
    false

fnget_intget_int(parsed : ParsedArgs, long : String) : Option(Int)#

Read a flag's value parsed as Int. None if unset OR if set but not a valid integer (mirrors Env.get_int's "fail safely" behavior) — this does not consult FlagSpec.default, same as get_string.

Examples

    march> let parsed = Cli.parse([Cli.value_flag("port", "")], ["--port", "8080"])
    march> match parsed do | Ok(p) -> Cli.get_int(p, "port") | Err(_) -> None end
    Some(8080)

fnget_stringget_string(parsed : ParsedArgs, long : String) : Option(String)#

Look up a flag's raw string value from the parsed args. Returns None if the flag was never supplied — this does not consult FlagSpec.default; use get_string_or for the common "just give me a default" case.

Examples

    march> let parsed = Cli.parse([Cli.value_flag("name", "")], ["--name", "x"])
    march> match parsed do | Ok(p) -> Cli.get_string(p, "name") | Err(_) -> None end
    Some("x")

fnget_string_orget_string_or(parsed : ParsedArgs, long : String, default : String) : String#

Look up a flag's raw string value, falling back to default if unset.

Examples

    march> let parsed = Cli.parse([Cli.value_flag("name", "")], [])
    march> match parsed do | Ok(p) -> Cli.get_string_or(p, "name", "anon") | Err(_) -> "?" end
    "anon"

fnhelp_texthelp_text(program_name : String, specs : List(FlagSpec)) : String#

Render --help-style usage text: a Usage: line followed by one block per flag (long/short forms, help text, and required/default annotation).

Examples

    march> String.contains(Cli.help_text("myapp", [Cli.flag("v", "verbose")]), "Usage: myapp [OPTIONS]")
    true

fnparseparse(specs : List(FlagSpec), argv : List(String)) : Result(ParsedArgs, CliError)#

Parse argv against specs. Long flags are --name value / --flag (boolean); short flags are -n value / -f (boolean); anything not flag-shaped is a positional argument. Unknown flags, a value flag missing its value, and an unmet required: true spec all return Err.

Examples

    march> Result.is_ok(Cli.parse([Cli.value_flag("name", "")], ["--name", "x"]))
    true

fnpositionalpositional(parsed : ParsedArgs) : List(String)#

Return the positional (non-flag) arguments, in the order given.

Examples

    march> let parsed = Cli.parse([], ["a", "b"])
    march> match parsed do | Ok(p) -> Cli.positional(p) | Err(_) -> [] end
    ["a", "b"]

fnvalue_flagvalue_flag(long : String, help : String) : FlagSpec#

Build a value-taking flag spec (no short form, optional, no default).

Examples

    march> let spec = Cli.value_flag("output", "Output file path")
    march> spec.long
    "output"