You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for [[/eggref/5/getopt-long|the CHICKEN 5 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-5.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[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. === 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}}. If {{[DOCSTRING]}} is provided, it must be a string containing a brief description of the option. 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. ; {{(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 and the name is used by the usage procedure. ; {{(value (OPTIONAL "name") [(PROPERTY VALUE) ...])}} : the option may appear with or without a named value. In addition, the following properties can be defined for a value: ; {{(predicate FUNC)}} : If the option accepts a value (i.e. you specified {{(REQUIRED ...)}} or {{(OPTIONAL ...)}} for this option), then {{getopt-long}} will apply {{FUNC}} to the value, and throw 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)}} : If the option accepts a value, then getopt will apply FUNC to the string provided on the command line, and put the resulting value in the list of parsed options returned by getopt-long. 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, and do not take values. === Library Procedures {{getopt-long}} is a procedure for parsing command-line arguments in a manner consistent with GNU programs. {{usage}} is a procedure that creates help strings given a grammar for the command-line arguments. <procedure>(getopt-long ARGS GRAMMAR [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. Its first element should be the name of the program; subsequent elements should be the arguments that were passed to the program on the command line. The {{program-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 is does not appear to be an option itself, then that element is the option's value. The value of a long option can can only follow the option name, separated by an `=' character. 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 as having the value "Granny Smith", but it will not recognize the `blimp' option; it will return the strings "--blimps" and "Goodyear" as ordinary argument strings. The {{getopt-long}} function returns an association list in which the key is an option name --- one of the symbols from {{GRAMMAR}} --- and each key is associated either with a single value (if the named option has been given once), or with a list of values (if the option was given multiple times). Options that were not given are not present. There is a special item in the returned alist with a key {{'@}}: this is the list of arguments that are not options or option values. Optional keyword argument {{UNKNOWN-OPTION-HANDLER}} is a procedure that receives as an argument a list of all options that were given as input but were unrecognized by the grammar. The default unknown option handler raises an error. Optional keyword argument {{LONG-OPTION-VALUE-CSET}} is a SRFI-14 character set that specifies all valid characters in an option value. This argument defaults to: <enscript highlight=scheme> (char-set-union char-set:letter+digit char-set:punctuation (char-set #\_ #\^ #\$ #\= #\space)) </enscript> By default, {{getopt-long}} throws an exception if: * it finds an unrecognized property in GRAMMAR * it finds an unrecognized option in ARGS * 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 === Examples <enscript highlight=scheme> (define grammar `((lockfile-dir "location of the lock file" ; <-- example for docstring (required #t) (value #t) (single-char #\k) (value (required DIR) (predicate ,directory?))) (verbose (required #f) (single-char #\v) (value #f)) (x-includes (single-char #\x) (value #t)) (rnet-server (single-char #\y) (value (required SERVER) (predicate ,string?))) )) (getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include" "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3") grammar) </enscript> === Version History * 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

Spam control

What do you get when you subtract 4 from 1?