← Index

x/sys/opts

Command-line parsing against a declaration of flags and valued options, on the Opts class.

Class Opts

The command line, parsed against a declaration: a list of flags that stand alone and a list that take an argument. Clusters, attached and separated values, –long, –long=value and – are all understood, so a caller does not re-derive them. Answers a record the other methods read.

(Opts parse flags values argv)

Parse argv against the declaration. Options may appear before or after operands (as getopt permutes); a caller whose operands can look like flags – echo(1) – wants parse-leading instead. The first undeclared option is remembered rather than raised, so the caller chooses the wording and the exit status.

Parameters:

• flags : LIST — Options that stand alone, as “-r” or “–verbose”
• values : LIST — Options that take an argument
• argv : LIST — The arguments to parse

Returns: ALIST — ((on . LIST) (values . ALIST) (operands . LIST) (unknown . ANY))

Examples:

(Opts value (Opts parse () (list "-k") (list "-k2")) "-k") => "2"
(Opts unknown (Opts parse (list "-a") () (list "-z"))) => "-z"

(Opts parse-leading flags values argv)

Parse as (Opts parse) does, but STOP at the first operand: everything after it is an operand too, whatever it looks like. This is what echo(1) needs – echo hi -n prints hi -n – and what a guard checking only the leading tokens wants.

Parameters:

• flags : LIST — Options that stand alone
• values : LIST — Options that take an argument
• argv : LIST — The arguments to parse

Returns: ALIST — ((on . LIST) (values . ALIST) (operands . LIST) (unknown . ANY))

Examples:

(Opts operands (Opts parse-leading (list "-n") () (list "hi" "-n"))) => ("hi" "-n")

(Opts on? opts flag)

Was this flag given, in any spelling it has? True for a flag that stands alone AND for one that takes an argument – the question is presence, not kind, and a caller that had to know which list a flag landed in would be re-deriving the declaration it already made.

Parameters:

• opts : ALIST — A parsed command line
• flag : STRING — The flag to ask about

Returns: BOOL — True when the flag was present

Examples:

(Opts on? (Opts parse (list "-v") () (list "-v")) "-v") => #t
(Opts on? (Opts parse () (list "-m") (list "-m" "700")) "-m") => #t
(Opts on? (Opts parse (list "-v") () ()) "-v") => #f

(Opts value opts flag . default)

The argument this flag carried – the LAST one, when it was given more than once. Answers the default (or nil) when the flag was absent.

Parameters:

• opts : ALIST — A parsed command line
• flag : STRING — The value-taking flag
• default : ANY — Answered when the flag was absent; nil when omitted

Returns: ANY — The argument, or the default

Examples:

(Opts value (Opts parse () (list "-t") (list "-t" ",")) "-t") => ","
(Opts value (Opts parse () (list "-w") ()) "-w" "6") => "6"

(Opts values opts flag)

EVERY argument this flag carried, in the order given – what grep -e one -e two needs. Empty when the flag was absent.

Parameters:

• opts : ALIST — A parsed command line
• flag : STRING — The value-taking flag

Returns: LIST — The arguments, in order

Examples:

(Opts values (Opts parse () (list "-e") (list "-e" "a" "-e" "b")) "-e") => ("a" "b")

(Opts operands opts)

The arguments that were not options, nor an option’s argument, in the order given.

Parameters:

• opts : ALIST — A parsed command line

Returns: LIST — The operands

Examples:

(Opts operands (Opts parse () (list "-o") (list "-o" "out" "in"))) => ("in")

(Opts unknown opts)

The first option the declaration did not name, or nil when every one was known. A caller refuses on this rather than letting an unread flag pass for a filename.

Parameters:

• opts : ALIST — A parsed command line

Returns: ANY — The offending token, or nil

Examples:

(Opts unknown (Opts parse (list "-a") () (list "-az"))) => "-az"

(Opts %member? x xs)

Is this string in the list?

Parameters:

• x : STRING — Needle
• xs : LIST — Haystack

Returns: BOOL — True when present

(Opts %option? tok)

Could this token be an option?

Parameters:

• tok : STRING — A command-line token

Returns: BOOL — True for -x, -xy, –long; false for -, -5 and plain words

Examples:

(Opts %option? "-5") => #f

(Opts %walk flags values argv leading)

The parser proper: answers the record the accessors read.

Parameters:

• flags : LIST — Standalone options
• values : LIST — Value-taking options
• argv : LIST — Arguments
• leading : BOOL — Stop at the first operand?

Returns: ALIST — ((on . LIST) (values . ALIST) (operands . LIST) (unknown . ANY))

(Opts %long-split tok)

Split –name=value into its pair.

Parameters:

• tok : STRING — A –name=value token

Returns: PAIR — (–name . value)

(Opts %long-value? tok values)

Is this –name=value for a declared value option?

Parameters:

• tok : STRING — A token
• values : LIST — Value-taking options

Returns: BOOL — True when it is

(Opts %cluster tok flags values more)

Split a cluster into the options it names.

Parameters:

• tok : STRING — A clustered token
• flags : LIST — Standalone options
• values : LIST — Value-taking options
• more : LIST — The arguments after this token

Returns: ANY — (ON VALUES () REST), or nil when a letter is undeclared