Wiki
Download
Manual
Eggs
API
Tests
Bugs
show
edit
You can edit this page using
wiki syntax
for markup.
Article contents:
[[tags: eggs]] == getopt-long Command-line option parsing. [[toc:]] === Description The {{getopt-long}} library implements command line option parsing, in the spirit of the GNU C library function {{getopt_long}}. Both long and short options are supported. The theory is that people should be able to constrain the set of options they want to process using a grammar, rather than some arbitrary structure. The grammar makes the option descriptions easy to read. === Repository This egg is hosted on the CHICKEN Subversion repository: [[https://anonymous@code.call-cc.org/svn/chicken-eggs/release/6/getopt-long|https://anonymous@code.call-cc.org/svn/chicken-eggs/release/6/getopt-long]] If you want to check out the source code repository of this egg and you are not familiar with Subversion, see [[/egg-svn-checkout|this page]]. === Command-line option grammar The option grammar is an s-expression of the form: ((OPTION-NAME [DOCSTRING] (PROPERTY VALUE) ...) ...) Each {{OPTION-NAME}} should be a symbol. Given this grammar, {{getopt-long}} will then accept a command-line option named {{--OPTION-NAME}}. An option whose name is a single character, such as {{v}}, is a short option: it is accepted as {{-v}}, and has no long form. If {{[DOCSTRING]}} is provided, it must be a string containing a brief description of the option. It is used by {{usage}}. Each option can have the following (PROPERTY VALUE) pairs: ; {{(single-char CHAR)}} : Accept {{-CHAR}} as a single-character equivalent to {{--OPTION}}. This is how to specify traditional Unix-style flags. ; {{(required BOOL)}} : If {{BOOL}} is true, the option is required. {{getopt-long}} will raise an error if it is not found in the list of arguments. ; {{(multiple BOOL)}} : If {{BOOL}} is true, the option may be given several times, and {{make-option-dispatch}} returns the list of all its values. ; {{(value FLAG)}} : If {{FLAG}} is {{#t}}, the option requires a value; if it is {{#f}}, it does not. ; {{(value (required NAME) [(PROPERTY VALUE) ...])}} : The option requires a value. {{NAME}}, a symbol or string, names the value in the text made by {{usage}}. ; {{(value (optional NAME) [(PROPERTY VALUE) ...])}} : The option may appear with or without a value. In addition, the following properties can be defined for a value: ; {{(predicate FUNC)}} : {{getopt-long}} applies {{FUNC}} to the value given on the command line, and throws an exception if the result is {{#f}}. {{FUNC}} should be a procedure which accepts a string and returns a boolean value; you may need to use quasiquotes to get it into the grammar. ; {{(transformer FUNC)}} : {{getopt-long}} applies {{FUNC}} to the string given on the command line, and puts the result in the list of parsed options in place of the string. ; {{(default VALUE)}} : For an option with an optional value, the value to use when the option is given without one; without a default, the value is then {{#t}}. The default is passed through the transformer. When the option is not given at all, it does not appear in the result. The {{(PROPERTY VALUE)}} pairs may occur in any order, but each property may occur only once. By default, options do not have single-character equivalents, are not required, may be given only once, and do not take values. === Library Procedures {{getopt-long}} is a procedure for parsing command-line arguments in a manner consistent with GNU programs. {{make-option-dispatch}} gives convenient access to the result. {{usage}} is a procedure that creates help strings given a grammar for the command-line arguments. <procedure>(getopt-long ARGS GRAMMAR #!key UNKNOWN-OPTION-HANDLER LONG-OPTION-VALUE-CSET)</procedure> Parse the arguments {{ARGS}} according to the argument list grammar {{GRAMMAR}}. {{ARGS}} should be a list of strings containing the arguments that were passed to the program on the command line, without the name of the program. The {{command-line-arguments}} procedure returns a list of this form. In {{ARGS}}, single-character options may be combined, in the usual Unix fashion: {{("-x" "-y")}} is equivalent to {{("-xy")}}. If an option accepts values, then it must be the last option in the combination; the value is the next argument. So, for example, using the following grammar: ((apples (single-char #\a)) (blimps (single-char #\b) (value #t)) (catalexis (single-char #\c) (value #t))) the following argument lists would be acceptable: ("-a" "-b" "bang" "-c" "couth") ("bang" and "couth" are the values for "blimps" and "catalexis") ("-ab" "bang" "-c" "couth") (same) ("-ac" "couth" "-b" "bang") (same) ("-abc" "couth" "bang") (an error, since `-b' is not the last option in its combination) If an option's value is optional, then {{getopt-long}} decides whether it has a value by looking at what follows it in {{ARGS}}. If the next element does not appear to be an option itself, then that element is the option's value. The value of a long option can only follow the option name, separated by an `=' character: {{("--blimps=bang")}}. {{("--blimps" "bang")}} is an error when the value is required; when it is optional, "bang" is an ordinary argument and the option is given without a value. If the option "--" appears in {{ARGS}}, argument parsing stops there; subsequent arguments are returned as ordinary arguments, even if they resemble options. So, in the argument list: ("--apples" "Granny Smith" "--" "--blimps" "Goodyear") {{getopt-long}} will recognize the `apples' option, and return "Granny Smith" as an ordinary argument since `apples' takes no value, but it will not recognize the `blimps' option; it will return the strings "--blimps" and "Goodyear" as ordinary argument strings. A lone "-" is not an option. By convention it stands for the standard input or output, so {{getopt-long}} returns it as an ordinary argument, and accepts it as the value of an option. With the grammar above: ("-a" "-") ("-" is an ordinary argument) ("-b" "-" "input") ("-" is the value of "blimps") ("--blimps=-" "input") (same) An argument that starts with a single "-" followed by a character that is not an option letter, such as "-5", is reported as an unrecognized option. {{getopt-long}} returns two values. The first is an association list from option names --- the symbols from {{GRAMMAR}} --- to their values: the value given on the command line (after the transformer, if any), or {{#t}} for an option without a value. An option given several times has one entry per occurrence, the most recent first. Options that were not given are not present. The first item of the list has the key {{@}}: it is the list of arguments that are not options or option values, in order. The second value is the result of the unknown option handler, or {{()}} when all options were recognized. Keyword argument {{unknown-option-handler:}} is a procedure that receives as an argument a list of the names of all options that were given as input but were unrecognized by the grammar, as strings without their dashes. The default unknown option handler raises an error. Keyword argument {{long-option-value-cset:}} is a SRFI-14 character set that specifies all valid characters in the value of a long option. It defaults to {{default-long-option-value-cset}}; use {{char-set:full}} to accept any value. By default, {{getopt-long}} throws an exception if: * it finds an unrecognized property in GRAMMAR * it finds an unrecognized option in ARGS, including an argument such as {{-5}} in which a single "-" is followed by a character that is not an option letter * a required option is omitted * an option that requires an argument doesn't get one * an option that doesn't accept an argument does get one (this can only happen using the long option {{--opt=value}} syntax) * an option predicate fails * the value of a long option contains a character outside {{LONG-OPTION-VALUE-CSET}} <procedure>(make-option-dispatch OPTIONS GRAMMAR)</procedure> Returns a procedure that takes an option name and returns its value in {{OPTIONS}}, the first value returned by {{getopt-long}} for {{GRAMMAR}}: * for {{@}}, the list of ordinary arguments; * for an option with {{(multiple #t)}}, the list of its values, the most recent first, or {{()}}; * for any other option, its value, the most recent one if it was given several times, or {{#f}} if it was not given. <procedure>(usage GRAMMAR)</procedure> Returns a string describing the options of {{GRAMMAR}}, one per line, with their docstrings: -k, --lockfile-dir=DIR location of the lock file -v, --verbose print more messages --level[=N] level of detail An option with an optional value shows it in brackets. The layout is controlled by three parameters: <parameter>width</parameter> The width of the column of option names (default 25). Longer option names are cut to this width, so it should be larger than the longest. <parameter>separator</parameter> The text between the short and long forms of an option (default {{", "}}). <parameter>indent</parameter> The number of spaces before each line (default 1). <constant>default-long-option-value-cset</constant> The characters accepted in the value of a long option by default: <enscript highlight=scheme> (char-set-union char-set:letter+digit char-set:punctuation (char-set #\_ #\^ #\$ #\= #\space)) </enscript> <parameter>long-option-value-quoting</parameter> If true, the value of a long option may be written in double quotes, in which any character is allowed and {{\"}} and {{\\}} stand for a double quote and a backslash: {{--name="a b"}}. The default is {{#f}}. === Examples <enscript highlight=scheme> (import (chicken file posix) (chicken process-context) getopt-long) (define grammar `((lockfile-dir "location of the lock file" (required #t) (single-char #\k) (value (required DIR) (predicate ,directory?))) (verbose "print more messages" (single-char #\v)) (x-includes "directory of X headers" (single-char #\x) (multiple #t) (value (required DIR))) (rnet-server "name of the server" (single-char #\y) (value (required SERVER))) (level "level of detail" (value (optional N) (default 3) (transformer ,string->number))) (help "show this help" (single-char #\h)))) (getopt-long '("-vk" "/tmp" "foo1" "-x" "/usr/include" "--x-includes=/opt/include" "--rnet-server=lamprod" "--level" "--" "-fred" "foo2") grammar) ;; => ((@ "foo1" "-fred" "foo2") ;; (level . 3) ;; (rnet-server . "lamprod") ;; (x-includes . "/opt/include") ;; (x-includes . "/usr/include") ;; (lockfile-dir . "/tmp") ;; (verbose . #t)) ;; () </enscript> A program usually looks its options up with {{make-option-dispatch}}. With the same arguments as above given on the command line: <enscript highlight=scheme> (define opt (make-option-dispatch (getopt-long (command-line-arguments) grammar) grammar)) (when (opt 'help) (print "Usage: prog [OPTION ...] FILE ...") (print (usage grammar)) (exit 0)) (opt 'x-includes) ; => ("/opt/include" "/usr/include") (opt 'lockfile-dir) ; => "/tmp" (opt '@) ; => ("foo1" "-fred" "foo2") </enscript> === Version History * 4.1 Treat a lone "-" as an ordinary argument that may be the value of an option * 4.0 Ported to CHICKEN 6 [thanks to Daniel Ziltener] * 1.18 Ported to CHICKEN 5 [thanks to Vasilij Schneidermann] * 1.17 Make help display of optional arguments consistent with other getopt implementations [thanks to Vasilij Schneidermann] * 1.16 Added configurable option value character set [thanks to evhan] * 1.0 Initial Release === License The {{getopt-long}} library was written by Thien-Thi Nguyen for Guile Scheme. {{getopt-long}} was ported to Chicken Scheme by Ivan Raikov. Copyright (C) 1998, 2001, 2006 Free Software Foundation, Inc. This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A full copy of the Lesser GPL license can be found at <http://www.gnu.org/licenses/>.
Description of your changes:
I would like to authenticate
Authentication
Username:
Password:
Spam control
What do you get when you subtract 12 from 24?