152 lines
75 KiB
HTML
152 lines
75 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>15.9 Command-Line Parsing</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewlink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewselflink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</a></td></tr><tr><td align="right">18 </td><td><a href="running.html" cla
|
||
|
|
<span class="RktVar">flag-clause</span>s.</div></p><p>The <span class="RktVar">name-expr</span>, if provided, should produce a path or string
|
||
|
|
to be used as the program name for reporting errors when the
|
||
|
|
command-line is ill-formed. It defaults to <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">run-file</span><span class="RktPn">)</span>. When a path is provided, only the last element of the
|
||
|
|
path is used to report an error.</p><p>The <span class="RktVar">argv-expr</span>, if provided, must evaluate to a list or a
|
||
|
|
vector of strings. It defaults to
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValLink" data-pltdoc="x">current-command-line-arguments</a></span><span class="RktPn">)</span>.</p><p>The command-line is disassembled into flags, each possibly with
|
||
|
|
flag-specific arguments, followed by (non-flag)
|
||
|
|
arguments. Command-line strings starting with <span class="RktInBG"><span class="hspace"></span><span class="RktIn">-</span><span class="hspace"></span></span> or
|
||
|
|
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">+</span><span class="hspace"></span></span> are parsed as flags, but arguments to flags are never
|
||
|
|
parsed as flags, and integers and decimal numbers that start with
|
||
|
|
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">-</span><span class="hspace"></span></span> or <span class="RktInBG"><span class="hspace"></span><span class="RktIn">+</span><span class="hspace"></span></span> are not treated as flags. Non-flag
|
||
|
|
arguments in the command-line must appear after all flags and the
|
||
|
|
flags’ arguments. No command-line string past the first non-flag
|
||
|
|
argument is parsed as a flag. The built-in <span class="nobreak"><span class="stt">--</span></span> flag signals the
|
||
|
|
end of command-line flags; any command-line string past the <span class="nobreak"><span class="stt">--</span></span>
|
||
|
|
flag is parsed as a non-flag argument.</p><p>A <span class="RktPn">#:multi</span>, <span class="RktPn">#:once-each</span>, <span class="RktPn">#:once-any</span>, or
|
||
|
|
<span class="RktPn">#:final</span> clause introduces a set of command-line flag
|
||
|
|
specifications. The clause tag indicates how many times the flag can
|
||
|
|
appear on the command line:</p><ul><li><p><span class="RktPn">#:multi</span> —<wbr></wbr> Each flag specified in the set can be
|
||
|
|
represented any number of times on the command line; i.e., the flags
|
||
|
|
in the set are independent and each flag can be used multiple times.</p></li><li><p><span class="RktPn">#:once-each</span> —<wbr></wbr> Each flag specified in the set can be
|
||
|
|
represented once on the command line; i.e., the flags in the set are
|
||
|
|
independent, but each flag should be specified at most once. If a
|
||
|
|
flag specification is represented in the command line more than once,
|
||
|
|
the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised.</p></li><li><p><span class="RktPn">#:once-any</span> —<wbr></wbr> Only one flag specified in the set can
|
||
|
|
be represented on the command line; i.e., the flags in the set are
|
||
|
|
mutually exclusive. If the set is represented in the command line
|
||
|
|
more than once, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised.</p></li><li><p><span class="RktPn">#:final</span> —<wbr></wbr> Like <span class="RktPn">#:multi</span>, except that no
|
||
|
|
argument after the flag is treated as a flag. Note that multiple
|
||
|
|
<span class="RktPn">#:final</span> flags can be specified if they have short names; for
|
||
|
|
example, if <span class="nobreak"><span class="stt">-a</span></span> is a <span class="RktPn">#:final</span> flag, then <span class="nobreak"><span class="stt">-aa</span></span> combines
|
||
|
|
two instances of <span class="nobreak"><span class="stt">-a</span></span> in a single command-line argument.</p></li></ul><p>A normal flag specification has four parts:</p><ul><li><p><span class="RktVar">flags</span> —<wbr></wbr> a flag string, or a set of flag strings. If
|
||
|
|
a set of flags is provided, all of the flags are equivalent. Each
|
||
|
|
flag string must be of the form
|
||
|
|
<span class="RktVal">"-</span><span class="RktVar">x</span><span class="RktVal">"</span> or
|
||
|
|
<span class="RktVal">"+</span><span class="RktVar">x</span><span class="RktVal">"</span> for some
|
||
|
|
character <span class="RktVar">x</span>, or
|
||
|
|
<span class="RktVal">"--</span><span class="RktVar">x</span><span class="RktVal">"</span> or
|
||
|
|
<span class="RktVal">"++</span><span class="RktVar">x</span><span class="RktVal">"</span> for some
|
||
|
|
sequence of characters <span class="RktVar">x</span>. An <span class="RktVar">x</span> cannot
|
||
|
|
contain only digits or digits plus a single decimal point, since
|
||
|
|
simple (signed) numbers are not treated as flags. In addition, the
|
||
|
|
flags <span class="RktVal">"--"</span>, <span class="RktVal">"-h"</span>, and <span class="RktVal">"--help"</span> are
|
||
|
|
predefined and cannot be changed.</p></li><li><p><span class="RktVar">id</span>s —<wbr></wbr> identifier that are bound to the flag’s
|
||
|
|
arguments. The number of identifiers determines how many arguments
|
||
|
|
can be provided on the command line with the flag, and the names of
|
||
|
|
these identifiers will appear in the help message describing the
|
||
|
|
flag. The <span class="RktVar">id</span>s are bound to string values in the
|
||
|
|
<span class="RktVar">body</span>s for handling the flag.</p></li><li><p><span class="RktVar">help-spec</span> —<wbr></wbr> a string or sequence of strings that
|
||
|
|
describes the flag. This string is used in the help message generated
|
||
|
|
by the handler for the built-in <span class="nobreak"><span class="stt">-h</span></span> (or <span class="nobreak"><span class="stt">--help</span></span>) flag. A
|
||
|
|
single literal string can be provided, or any number of expressions
|
||
|
|
that produce strings; in the latter case, strings after the first one
|
||
|
|
are displayed on subsequent lines.</p></li><li><p><span class="RktVar">body</span>s —<wbr></wbr> expressions that are evaluated when one of
|
||
|
|
the <span class="RktVar">flags</span> appears on the command line. The flags are parsed
|
||
|
|
left-to-right, and each sequence of <span class="RktVar">body</span>s is evaluated as
|
||
|
|
the corresponding flag is encountered. When the <span class="RktVar">body</span>s are
|
||
|
|
evaluated, the preceding <span class="RktVar">id</span>s are bound to the arguments
|
||
|
|
provided for the flag on the command line.</p></li></ul><p>A flag specification using <span class="RktSym"><a href="if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._~3d~3e%29%29" class="RktStxLink" data-pltdoc="x">=></a></span> escapes to a more general
|
||
|
|
method of specifying the handler and help strings. In this case, the
|
||
|
|
handler procedure and help string list returned by
|
||
|
|
<span class="RktVar">handler-expr</span> and <span class="RktVar">help-expr</span> are used as in the
|
||
|
|
<span class="RktVar">table</span> argument of <span class="RktSym"><a href="Command-Line_Parsing.html#%28def._%28%28lib._racket%2Fcmdline..rkt%29._parse-command-line%29%29" class="RktValLink" data-pltdoc="x">parse-command-line</a></span>.</p><p>A <span class="RktPn">#:usage-help</span> clause inserts text lines immediately after
|
||
|
|
the usage line. Each string in the clause provides a separate line
|
||
|
|
of text.</p><p>A <span class="RktPn">#:help-labels</span> clause inserts text lines into the help table
|
||
|
|
of command-line flags. Each string in the clause provides a separate
|
||
|
|
line of text.</p><p>A <span class="RktPn">#:ps</span> clause inserts text lines at the end of the help
|
||
|
|
output. Each string in the clause provides a separate
|
||
|
|
line of text.</p><p>After the flag clauses, a final clause handles command-line arguments
|
||
|
|
that are not parsed as flags:</p><ul><li><p>Supplying no finish clause is the same as supplying
|
||
|
|
<span class="RktPn">#:args</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktPn">)</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span><span class="RktPn">)</span>.</p></li><li><p>For an <span class="RktPn">#:args</span> finish clause, identifiers in
|
||
|
|
<span class="RktVar">arg-formals</span> are bound to the leftover command-line strings
|
||
|
|
in the same way that identifiers are bound for a <span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span>
|
||
|
|
expression. Thus, specifying a single <span class="RktVar">id</span> (without
|
||
|
|
parentheses) collects all of the leftover arguments into a list. The
|
||
|
|
effective arity of the <span class="RktVar">arg-formals</span> specification determines
|
||
|
|
the number of extra command-line arguments that the user can provide,
|
||
|
|
and the names of the identifiers in <span class="RktVar">arg-formals</span> are used in
|
||
|
|
the help string. When the command-line is parsed, if the number of
|
||
|
|
provided arguments cannot be matched to identifiers in
|
||
|
|
<span class="RktVar">arg-formals</span>, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception is raised. Otherwise,
|
||
|
|
<span class="RktSym">args</span> clause’s <span class="RktVar">body</span>s are evaluated to handle the
|
||
|
|
leftover arguments, and the result of the last <span class="RktVar">body</span> is the
|
||
|
|
result of the <span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span> expression.</p></li><li><p>A <span class="RktPn">#:handlers</span> finish clause escapes to a more general
|
||
|
|
method of handling the leftover arguments. In this case, the values
|
||
|
|
of the expressions are used like the last two to four arguments
|
||
|
|
<span class="RktSym"><a href="Command-Line_Parsing.html#%28def._%28%28lib._racket%2Fcmdline..rkt%29._parse-command-line%29%29" class="RktValLink" data-pltdoc="x">parse-command-line</a></span>.</p></li></ul><p>Example:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">verbose-mode</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">profiling-on</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">optimize-level</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktVal">0</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">link-flags</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._null%29%29" class="RktValLink" data-pltdoc="x">null</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">file-to-compile</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">#:program</span><span class="hspace"> </span><span class="RktVal">"compiler"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">#:once-each</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">[</span><span class="RktPn">(</span><span class="RktVal">"-v"</span><span class="hspace"> </span><span class="RktVal">"--verbose"</span><span class="RktPn">)</span><span class="hspace"> </span><span class
|
||
|
|
an overview of command-line parsing, see the <span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span>
|
||
|
|
form, which provides a more convenient notation for most purposes.</div></p><p>The <span class="RktVar">table</span> argument to this procedural form encodes the
|
||
|
|
information in <span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span>’s clauses, except for the
|
||
|
|
<span class="RktSym">args</span> clause. Instead, arguments are handled by the
|
||
|
|
<span class="RktVar">finish-proc</span> procedure, and help information about non-flag
|
||
|
|
arguments is provided in <span class="RktVar">arg-help-strs</span>. In addition, the
|
||
|
|
<span class="RktVar">finish-proc</span> procedure receives information accumulated while
|
||
|
|
parsing flags. The <span class="RktVar">help-proc</span> and <span class="RktVar">unknown-proc</span>
|
||
|
|
arguments allow customization that is not possible with
|
||
|
|
<span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span>.</p><p>When there are no more flags, <span class="RktVar">finish-proc</span> is called with a
|
||
|
|
list of information accumulated for command-line flags (see below) and
|
||
|
|
the remaining non-flag arguments from the command-line. The arity of
|
||
|
|
<span class="RktVar">finish-proc</span> determines the number of non-flag arguments
|
||
|
|
accepted and required from the command-line. For example, if
|
||
|
|
<span class="RktVar">finish-proc</span> accepts either two or three arguments, then
|
||
|
|
either one or two non-flag arguments must be provided on the
|
||
|
|
command-line. The <span class="RktVar">finish-proc</span> procedure can have any arity
|
||
|
|
(see <span class="RktSym"><a href="procedures.html#%28def._%28%28quote._~23~25kernel%29._procedure-arity%29%29" class="RktValLink" data-pltdoc="x">procedure-arity</a></span>) except <span class="RktVal">0</span> or a list of
|
||
|
|
<span class="RktVal">0</span>s (i.e., the procedure must at least accept one or more
|
||
|
|
arguments).</p><p>The <span class="RktVar">arg-help-strs</span> argument is a list of strings identifying
|
||
|
|
the expected (non-flag) command-line arguments, one for each
|
||
|
|
argument. If an arbitrary number of arguments are allowed, the last
|
||
|
|
string in <span class="RktVar">arg-help-strs</span> represents all of them.</p><p>The <span class="RktVar">help-proc</span> procedure is called with a help string if the
|
||
|
|
<span class="nobreak"><span class="stt">-h</span></span> or <span class="nobreak"><span class="stt">--help</span></span> flag is included on the command line. If an
|
||
|
|
unknown flag is encountered, the <span class="RktVar">unknown-proc</span> procedure is
|
||
|
|
called just like a flag-handling procedure (as described below); it
|
||
|
|
must at least accept one argument (the unknown flag), but it may also
|
||
|
|
accept more arguments. The default <span class="RktVar">help-proc</span> displays the
|
||
|
|
string and exits and the default <span class="RktVar">unknown-proc</span> raises the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span> exception.</p><p>A <span class="RktVar">table</span> is a list of flag specification sets. Each set is
|
||
|
|
represented as a pair of two items: a mode symbol and a list of either
|
||
|
|
help strings or flag specifications. A mode symbol is one of
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">once-each</span>, <span class="RktVal">'</span><span class="RktVal">once-any</span>, <span class="RktVal">'</span><span class="RktVal">multi</span>,
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">final</span>, <span class="RktVal">'</span><span class="RktVal">help-labels</span>, <span class="RktVal">'</span><span class="RktVal">usage-help</span>, or
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">ps</span> with the same meanings as the corresponding clause tags
|
||
|
|
in <span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span>. For the <span class="RktVal">'</span><span class="RktVal">help-labels</span>,
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">usage-help</span> or <span class="RktVal">'</span><span class="RktVal">ps</span> mode, a list of help strings is
|
||
|
|
provided. For the other modes, a list of flag specifications is
|
||
|
|
provided, where each specification maps a number of flags to a single
|
||
|
|
handler procedure. A specification is a list of three items:</p><ul><li><p>A list of strings for the flags defined by the spec. See
|
||
|
|
<span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span> for information about the format of flag
|
||
|
|
strings.</p></li><li><p>A procedure to handle the flag and its arguments when one of
|
||
|
|
the flags is found on the command line. The arity of this handler
|
||
|
|
procedure determines the number of arguments consumed by the flag:
|
||
|
|
the handler procedure is called with a flag string plus the next few
|
||
|
|
arguments from the command line to match the arity of the handler
|
||
|
|
procedure. The handler procedure must accept at least one argument to
|
||
|
|
receive the flag. If the handler accepts arbitrarily many arguments,
|
||
|
|
all of the remaining arguments are passed to the handler. A handler
|
||
|
|
procedure’s arity must either be a number or an
|
||
|
|
<span class="RktSym"><a href="procedures.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._arity-at-least%29%29" class="RktValLink" data-pltdoc="x">arity-at-least</a></span> value.</p><p>The return value from the handler is added to a list that is
|
||
|
|
eventually passed to <span class="RktVar">finish-proc</span>. If the handler returns
|
||
|
|
<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></span></a>, no value is added onto this list. For all
|
||
|
|
non-<a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.6" class="RktModLink Sq" data-pltdoc="x"><span class="nobreak"><span class="RktRes">#<void></span></span></a> values returned by handlers, the order of the
|
||
|
|
values in the list is the same as the order of the arguments on the
|
||
|
|
command-line.</p></li><li><p>A non-empty list for constructing help information for the
|
||
|
|
spec. The first element of the list describes the flag; it can be a
|
||
|
|
string or a non-empty list of strings, and in the latter case, each
|
||
|
|
string is shown on its own line. Additional elements of the main
|
||
|
|
list must be strings to name the expected arguments for the flag. The
|
||
|
|
number of extra help strings provided for a spec must match the
|
||
|
|
number of arguments accepted by the spec’s handler procedure.</p></li></ul><p>The following example is the same as the core example for
|
||
|
|
<span class="RktSym"><a href="Command-Line_Parsing.html#%28form._%28%28lib._racket%2Fcmdline..rkt%29._command-line%29%29" class="RktStxLink" data-pltdoc="x">command-line</a></span>, translated to the procedural form:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="Command-Line_Parsing.html#%28def._%28%28lib._racket%2Fcmdline..rkt%29._parse-command-line%29%29" class="RktValLink" data-pltdoc="x">parse-command-line</a></span><span class="hspace"> </span><span class="RktVal">"compile"</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._current-command-line-arguments%29%29" class="RktValLink" data-pltdoc="x">current-command-line-arguments</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">(</span><span class="RktVal">once-each</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">[</span><span class="RktVal">(</span><span class="RktVal">"-v"</span><span class="hspace"> </span><span class="RktVal">"--verbose"</span><span class="RktVal">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">flag</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">verbose-mode</span><span class="hspace"> </span><span class="RktVal">#t</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">(</span><span class="RktVal">"Compile with verbose messages"</span><span class="RktVal">)</span><span class="RktVal">]</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">[</span><span class="RktVal">(</span><span class="RktVal">"-p"</span><span class="hspace"> </span><span class="RktVal">"--profile"</span><span class="RktVal">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">flag</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">profiling-on</span><span class="hspace"> </span><span class="RktVal">#t</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">(</span><span class="RktVal">"Compile with profiling"</span><span class="RktVal">)</span><span class="RktVal">]</span><span class="RktVal">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">(</span><span class="RktVal">once-any</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVal">[</span><span class="RktVal">(</span><span class="RktVal">"-o"</span><span class="hspace"> </span><span class="RktVal">"--optimize-1"</span><span class="RktVal">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspac
|