← 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 decl . more)

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 flags given are listed in the order given, a cluster’s letters left to right, so a caller where the later of two flags wins can read it. The first undeclared option is remembered rather than raised, so the caller chooses the wording and the exit status. Given a declaration, a row’s spellings are one option: whichever was given, on? and value answer for all of them.

Parameters:

• decl : ANY — A declaration from (Opts declare), or the list of options that stand alone, as “-r” or “–verbose”
• more : LIST — After a declaration, the arguments; after a list of flags, the options that take an argument and then the arguments

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 on? (Opts parse (Opts declare "t" "" () (list (Opts flag "-q" "--quiet" "Quiet"))) (list "--quiet")) "-q") => #t

(Opts parse-leading decl . more)

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:

• decl : ANY — A declaration, or the options that stand alone
• more : LIST — As for (Opts 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 whether the flag takes an argument, 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 declare name synopsis summary rows . settings)

A command’s options and its help text as ONE declaration: parse reads the rows’ spellings and usage prints the rows, so an option cannot be accepted and undocumented, nor documented and refused. The synopsis is written out rather than generated – busybox’s group and order their options by hand.

Parameters:

• name : STRING — The command’s name, as the Usage: line prints it
• synopsis : STRING — What follows the name on the Usage: line
• summary : ANY — The text under the Usage: line, or nil
• rows : LIST — The rows: (Opts flag …), (Opts arg …), (Opts hidden …), (Opts text …)
• settings : LIST — Pairs: (column . N) sets the description column, (help . #f) turns –help off, (banner . TEXT) leads the text

Returns: ALIST — The declaration parse, help? and usage read

Examples:

(Opts flags (Opts declare "t" "" () (list (Opts flag "-a" "All") (Opts arg "-o" "FILE" "Out")))) => ("-a")

See also: flag arg hidden text usage help?

(Opts flag . words)

A row for an option that stands alone. Every spelling names the same option: (Opts flag “-q” “–quiet” “Quiet”).

Parameters:

• words : LIST — One or more spellings, then the description

Returns: LIST — The row

Examples:

(Opts usage (Opts declare "t" "" () (list (Opts flag "-q" "--quiet" "Quiet")))) => "Usage: t\n\n\t-q,--quiet\tQuiet\n"

(Opts arg . words)

A row for an option that takes an argument: (Opts arg “-o” “FILE” “Output to FILE”).

Parameters:

• words : LIST — One or more spellings, the argument’s name, then the description

Returns: LIST — The row

Examples:

(Opts valued (Opts declare "t" "" () (list (Opts arg "-o" "FILE" "Out")))) => ("-o")

(Opts hidden row)

The row, accepted by parse but left out of usage – for spellings a command takes and does not advertise.

Parameters:

• row : LIST — A flag or value row

Returns: LIST — The row, unlisted

Examples:

(Opts flags (Opts declare "t" "" () (list (Opts hidden (Opts flag "-x" "X"))))) => ("-x")
(Opts usage (Opts declare "t" "" () (list (Opts hidden (Opts flag "-x" "X"))))) => "Usage: t\n"

(Opts text line)

A row that is only text: a continuation line, a heading, or an option row laid out by hand. It declares nothing.

Parameters:

• line : STRING — A line of the help text, printed as written

Returns: LIST — The row

Examples:

(Opts usage (Opts declare "t" "" () (list (Opts text "Options:")))) => "Usage: t\n\nOptions:\n"

(Opts name decl)

The command’s name.

Parameters:

• decl : ALIST — A declaration

Returns: STRING — The name

Examples:

(Opts name (Opts declare "cut" "" () ())) => "cut"

(Opts flags decl)

Every spelling of every option that stands alone, hidden or not.

Parameters:

• decl : ALIST — A declaration

Returns: LIST — The spellings

Examples:

(Opts flags (Opts declare "t" "" () (list (Opts flag "-q" "--quiet" "Quiet") (Opts hidden (Opts flag "-x" "X"))))) => ("-q" "--quiet" "-x")

(Opts valued decl)

Every spelling of every option that takes an argument, hidden or not.

Parameters:

• decl : ALIST — A declaration

Returns: LIST — The spellings

Examples:

(Opts valued (Opts declare "t" "" () (list (Opts arg "-o" "--output" "FILE" "Out")))) => ("-o" "--output")

(Opts help? decl argv)

Is this a request for help: –help as the FIRST argument, and help not turned off? Busybox asks exactly this, before any option is parsed; test, true, false and echo turn it off, since POSIX gives –help no meaning there.

Parameters:

• decl : ALIST — A declaration
• argv : LIST — The arguments

Returns: BOOL — True when the caller should print usage

Examples:

(Opts help? (Opts declare "t" "" () ()) (list "--help")) => #t
(Opts help? (Opts declare "t" "" () ()) (list "-a" "--help")) => #f
(Opts help? (Opts declare "t" "" () () (pair 'help #f)) (list "--help")) => #f

(Opts usage decl)

The help text, laid out as busybox lays its out: the Usage: line, the summary, then a row per listed option – a tab, the spellings and argument, and tabs out to the description column. The column is the first tab stop past the widest option unless (column . N) sets it. The caller chooses the stream and the status.

Parameters:

• decl : ALIST — A declaration

Returns: STRING — The text, ending in a newline

Examples:

(Opts usage (Opts declare "t" "[-a] FILE" "Do it" (list (Opts flag "-a" "All")))) => "Usage: t [-a] FILE\n\nDo it\n\n\t-a\tAll\n"
(Opts usage (Opts declare "t" "FILE" ()  ())) => "Usage: t FILE\n"

(Opts %setting decl key default)

A setting given to declare, or the default.

Parameters:

• decl : ALIST — A declaration
• key : SYMBOL — column, help or banner
• default : ANY — Answered when it was not set

Returns: ANY — The setting

Examples:

(Opts %setting (Opts declare "t" "" () () (pair 'column 24)) 'column 16) => 24
(Opts %setting (Opts declare "t" "" () ()) 'column 16) => 16

(Opts %spellings rows label)

Every spelling of the rows with this label, in order.

Parameters:

• rows : LIST — Rows
• label : SYMBOL — flag or value

Returns: LIST — The spellings

Examples:

(Opts %spellings (list (Opts flag "-a" "A") (Opts arg "-o" "F" "O") (Opts flag "-b" "--big" "B")) 'flag) => ("-a" "-b" "--big")

(Opts %shown rows)

The rows usage lists.

Parameters:

• rows : LIST — Rows

Returns: LIST — The rows not hidden

Examples:

(List length (Opts %shown (list (Opts flag "-a" "A") (Opts hidden (Opts flag "-b" "B"))))) => 1

(Opts %left row)

A row’s left column: its spellings joined by commas, and the argument’s name.

Parameters:

• row : LIST — A flag or value row

Returns: STRING — The text

Examples:

(Opts %left (Opts arg "-o" "--output" "FILE" "Out")) => "-o,--output FILE"
(Opts %left (Opts flag "-q" "Quiet")) => "-q"

(Opts %column rows)

The first tab stop past the widest option.

Parameters:

• rows : LIST — The listed rows

Returns: INTEGER — The column

Examples:

(Opts %column (list (Opts flag "-a" "All"))) => 16
(Opts %column (list (Opts arg "-o" "--output" "FILE" "Out"))) => 32

(Opts %stop col)

The first tab stop past this column.

Parameters:

• col : INTEGER — A column

Returns: INTEGER — The stop

Examples:

(Opts %stop 8) => 16
(Opts %stop 13) => 16

(Opts %line row column)

One row of the help text, without its newline.

Parameters:

• row : LIST — A listed row
• column : INTEGER — The description column

Returns: STRING — The line

Examples:

(Opts %line (Opts flag "-a" "All") 16) => "\t-a\tAll"
(Opts %line (Opts flag "-a" "All") 24) => "\t-a\t\tAll"

(Opts %parse decl more leading)

Parse either form; a declaration’s rows widen each option to all its spellings.

Parameters:

• decl : ANY — A declaration, or the flags
• more : LIST — argv, or the values and argv
• leading : BOOL — Stop at the first operand?

Returns: ALIST — The parsed record

Examples:

(Opts operands (Opts %parse (list "-a") (list () (list "-a" "f")) #f)) => ("f")

(Opts %widen rec rows)

The record with every option given recorded under each of its row’s spellings.

Parameters:

• rec : ALIST — A parsed record
• rows : LIST — The declaration’s rows

Returns: ALIST — The record

Examples:

(Opts on? (Opts %widen (Opts %walk (list "-q") () (list "-q") #f) (list (Opts flag "-q" "--quiet" "Q"))) "--quiet") => #t

(Opts %member? x xs)

Is this string in the list?

Parameters:

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

Returns: BOOL — True when present

Examples:

(Opts %member? "-b" (list "-a" "-b")) => #t
(Opts %member? "-c" (list "-a" "-b")) => #f

(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 %digit-option? tok flags values)

Is this token led by a declared digit option?

Parameters:

• tok : STRING — A command-line token
• flags : LIST — Standalone options
• values : LIST — Value-taking options

Returns: BOOL — True for -4 or -4v when -4 is declared; false otherwise

Examples:

(Opts %digit-option? "-4" (list "-4") ()) => #t
(Opts %digit-option? "-5" (list "-4") ()) => #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))

Examples:

(Opts operands (Opts %walk (list "-n") () (list "a" "-n" "b") #f)) => ("a" "b")
(Opts operands (Opts %walk (list "-n") () (list "a" "-n" "b") #t)) => ("a" "-n" "b")

(Opts %long-split tok)

Split –name=value into its pair.

Parameters:

• tok : STRING — A –name=value token

Returns: PAIR — (–name . value)

Examples:

(Opts %long-split "--width=80") => ("--width" . "80")
(Opts %long-split "--width") => ("--width" . "")

(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

Examples:

(Opts %long-value? "--width=80" (list "--width")) => #t
(Opts %long-value? "--width=80" ()) => #f

(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

Examples:

(Opts %cluster "-nk2" (list "-n") (list "-k") ()) => (("-n") (("-k" . "2")) () ())
(null? (Opts %cluster "-nz" (list "-n") () ())) => #t