(index ("args:make-option" 0) ("args:parse" 2182) ("args:help-options" 3760) ("args:usage" 4188) ("args:width" 4536) ("args:separator" 5139) ("args:indent" 5299) ("args:ignore-unrecognized-options" 5480) ("args:accept-unrecognized-options" 5656))
(def (sig (syntax "(args:make-option (OPTION-NAME ...) ARG-DATA DOCSTRING [BODY])" (id args:make-option))) (p "Make an " (tt "args:option") " record, suitable for passing to " (tt "args:parse") ".") (p (tt "OPTION-NAME ...") " is a sequence of short or long option names. They must be literal symbols; single-character symbols become short options, and longer symbols become long options. So " (tt "(args:make-option (c cookie) ...)") " specifies a short option " (tt "-c") " and long option " (tt "--cookie") ". Under the hood, " (tt "(c cookie)") " becomes " (tt "'(#\\c \"cookie\")") ", as expected by SRFI 37's " (tt "OPTION") ".") (p (tt "ARG-DATA") " is either a pair " (tt "(ARG-TYPE ARG-NAME)") " or a plain keyword " (tt "ARG-TYPE") ". " (tt "ARG-TYPE") " is a keyword that specifies whether the option takes an argument:") (table (@ (class "symbol-table")) (tr (td "#:required") (td "Argument is required")) "\n" (tr (td "#:optional") (td "Argument is optional")) "\n" (tr (td "#:none") (td "No argument (actually, any other value than #:required or #:optional is interpreted as #:none)"))) (p (tt "ARG-NAME") ", if provided, is a string specifying the name of the argument. This name is used in the help text produced by args:usage.") (p (tt "DOCSTRING") " is the help text.") (p (tt "BODY") " is an optional sequence of statements executed when this option is encountered.  " (tt "BODY") " is an option-processor as defined in SRFI 37, and has access to the variables " (tt "OPT") " (the current #<option>), " (tt "NAME") " (the option name) and " (tt "ARG") " (argument value).") (p "Behind the scenes, " (tt "BODY") " is wrapped in code which adds the current option " (tt "NAME") " and its argument " (tt "ARG") " to the final options alist. So, simply leave " (tt "BODY") " blank and options will be collected for you.") (p "When the option takes no argument (is of type " (tt "#:none") ") then ARG is " (tt "#t") ", turning it into a boolean.  On the other hand, when the option takes an optional argument that is omitted, then " (tt "ARG") " is " (tt "#f") "; so to set a default of " (tt "foo") ", one may say in the body:") (pre "(set! arg (or arg \"foo\")) "))
(def (sig (procedure "(args:parse ARGS OPTIONS-LIST [OPTIONALS])" (id args:parse))) (p "Parse " (tt "ARGS") ", a list of command-line arguments given as strings, and return two values: an alist of option names (symbols) and their values, and a list of operands (non-option arguments).") (p "Operands are returned in order, but options are returned in reverse order. Duplicate options are retained in the options alist, so this lets " (tt "assq") " find the " (i "last") " occurrence of any duplicate option on the command line. A (name . value) pair is added for each alias of every option found, so any alias is a valid lookup key.") (p (tt "OPTIONS-LIST") " is a list of accepted options, each created by args:make-option.") (p (tt "OPTIONALS") " is an optional sequence of keywords and values:") (table (@ (class "symbol-table")) (tr (td "#:operand-proc " (tt "PROC")) (td "calls " (tt "PROC") " for each operand, with arguments " (tt "OPERAND") " " (tt "OPTIONS") " " (tt "OPERANDS") ".  PROC must return the next seeds, " (tt "(values OPTIONS OPERANDS)") ".")) "\n" (tr (td "#:unrecognized-proc " (tt "PROC")) (td "calls " (tt "PROC") " for each unrecognized option, with arguments " (tt "OPTION") " " (tt "NAME") " " (tt "ARG") " " (tt "OPTIONS") " " (tt "OPERANDS")))) (p "The default operand-proc is a no-op, and the default unrecognized-proc issues an error message and calls the help option's processor. See the args-fold documentation for usage information and an explanation of the procedure arguments; " (tt "OPTIONS") " and " (tt "OPERANDS") " are seed values."))
(def (sig (parameter "(args:help-options [default: (\"help\" #\\h #\\?)])" (id args:help-options))) (p "List of option names (strings or single characters, as in SRFI 37) to be considered 'help' options, in order of preference. " (tt "args:parse") " uses this to select a help option from the option list it is passed. This is currently used only for unrecognized options, for which the help option is automatically invoked."))
(def (sig (procedure "(args:usage OPTION-LIST)" (id args:usage))) (p "Generate a formatted list of options from " (tt "OPTION-LIST") ", and return a string suitable for embedding into help text. The single string consists of multiple lines, with a newline at the end of each line. Thus, a typical use would be " (tt "(print (args:usage opts)).")))
(def (sig (parameter "(args:width [default: 25])" (id args:width))) (p "Width of the left (option) column. We don't automatically format this column based on the length of the longest option, but you can set its width manually.") (p "The formatter maintains at least 2 spaces between the option keys and the option docstrings. If there is not enough space, the docstring will start on the next line. The 2 spaces of padding are included in " (tt "args:width") ".  The indent does not get counted in " (tt "args:width") ". So the docstrings always begin at column " (tt "args:indent + args:width") "."))
(def (sig (parameter "(args:separator [default: \", \"])" (id args:separator))) (p "The string separator inserted between multiple options on the same line."))
(def (sig (parameter "(args:indent [default: 1])" (id args:indent))) (p "Number of spaces to indent the options from the left. This is not considered to be part of `args:width`."))
(def (sig (procedure "(args:ignore-unrecognized-options)" (id args:ignore-unrecognized-options))) (p "Silently ignore unrecognized options, and omit from the options alist."))
(def (sig (procedure "(args:accept-unrecognized-options)" (id args:accept-unrecognized-options))) (p "Silently add unrecognized options to the options alist."))
