Module: sys.optparse

Source: ./sys/optparse.reef

Overview

sys.optparse - hierarchical CLI option parser (clap-style)

Cells returned by bool_flag / int_flag / string_flag / arg / rest are the same objects parse fills. See docs/superpowers/specs/2026-08-25-sys-optparse-design.md.

Types

Status (enum)

Variants:

  • OkParsed
  • OkHelp
  • OkVersion
  • Err(ParseError)

ParseError (enum)

Variants:

  • UnknownFlag(string)
  • InvalidFlag(string)
  • MissingValue(string)
  • InvalidValue(string, string)
  • MissingFlag(string)
  • UnknownCommand(string)
  • MissingCommand
  • GlobalMisplaced(string)
  • MissingArg(string)
  • UnexpectedArg(string)

TokenKind (enum)

Variants:

  • TokEndOpts
  • TokLong
  • TokShort
  • TokInvalid
  • TokPositional

Token

Fields:

Name Type
kind TokenKind
raw string
name string
short_ch char
has_eq bool
eq_value string

FlagApply (enum)

Variants:

  • Applied(int)
  • Failed(ParseError)

IntParse

Fields:

Name Type
ok bool
value int

ParseState

Fields:

Name Type
argv [string]
help_seen bool
version_seen bool
parse_root Command

ChildFind

Fields:

Name Type
ok bool
child Command

DeclSlot (enum)

Variants:

  • DeclBool(int)
  • DeclInt(int)
  • DeclString(int)

BoolFlag

Fields:

Name Type
long_name string
short_name char
help string
value bool
default_value bool
present bool
required bool

IntFlag

Fields:

Name Type
long_name string
short_name char
help string
value int
default_value int
present bool
required bool

StringFlag

Fields:

Name Type
long_name string
short_name char
help string
value string
default_value string
present bool
required bool

Arg

Fields:

Name Type
arg_name string
value string
present bool

Rest

Fields:

Name Type
values [string]

Command

Fields:

Name Type
name string
about_text string
version_str string
children [Command]
bools [BoolFlag]
ints [IntFlag]
strings [StringFlag]
pos_args [Arg]
rest_cell Rest
has_rest bool
args_closed bool
invoked Command
path string
parse_root_name string
decls [DeclSlot]

Functions

fn command(name: string): Command

fn program(): string

fn argc(): int

fn argv_get(index: int): option.Option[string]

0.9.2 C16: None for an out-of-range index.

This returned "" for an index past the end, but "" is a perfectly legal argv element -- prog "" passes one -- so "no such argument" and "an empty argument" were indistinguishable.

fn argv_get_or(index: int, default: string): string

*_or: lookup, or the caller default. Pairs with the Option getter above, which stays the source of truth. A PRESENT value always wins -- including the ones C16 made distinguishable from absent -- because substituting the default for a real value would reinstate the sentinel collision C16 removed.

fn format(e: ParseError): string

fn classify(tok: string): Token

fn parse_int_operand(s: string): IntParse

fn apply_bool_cell(cmd: Command, idx: int, t: Token, i: int): FlagApply

fn apply_int_cell(cmd: Command, idx: int, t: Token, argv: [string], i: int): FlagApply

fn apply_string_cell(cmd: Command, idx: int, t: Token, argv: [string], i: int): FlagApply

fn apply_long(cmd: Command, t: Token, argv: [string], i: int): FlagApply

fn apply_short(cmd: Command, t: Token, argv: [string], i: int): FlagApply

fn apply_positional(cmd: Command, raw: string, i: int): FlagApply

fn finish_leaf(cmd: Command): Status

fn flag_option_syntax(short: char, long_name: string, hint: string): string

fn widen_usage_col(w: int, syntax: string): int

fn usage_col_width(cmd: Command): int

fn commands_name_width(cmd: Command): int

fn command_path(ancestors: [Command], leaf: Command): string

fn finish_help(cmd: Command, state: ParseState, ancestors: [Command]): Status

fn finish_version(state: ParseState): Status

fn version_builtin_ok(state: ParseState, ancestors: [Command]): bool

fn is_version_token(tok: string): bool

fn command_has_long(cmd: Command, name: string): bool

fn command_has_short(cmd: Command, ch: char): bool

fn command_has_token_flag(cmd: Command, t: Token): bool

fn rewrite_unknown(tok: string, ancestors: [Command]): ParseError

fn maybe_misplaced(e: ParseError, ancestors: [Command]): ParseError

fn find_child(cmd: Command, name: string): ChildFind

fn walk(cmd: Command, state: ParseState, i: int, ancestors: [Command]): Status

fn parse_select(cmd: Command, state: ParseState, start: int, ancestors: [Command]): Status

fn parse_leaf(cmd: Command, state: ParseState, start: int, ancestors: [Command]): Status

Procedures

proc abort_decl(msg: string)

proc check_command_name(name: string)

proc check_flag_decl(cmd: Command, name: string, short: char)

proc reset_command(c: Command)

proc print_option_line(syntax: string, help: string, width: int)

proc print_decl_option(cmd: Command, slot: DeclSlot, w: int)

proc mark_invoked(cmd: Command, state: ParseState, ancestors: [Command])

Generated by reefc doc