((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/getopt-long" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "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")) (section 2 "getopt-long" (p "Command-line option parsing.") (toc) (section 3 "Description" (p "The " (tt "getopt-long") " library implements command line option parsing, in the spirit of the GNU C library function " (tt "getopt_long") ".  Both long and short options are supported.") (p "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.")) (section 3 "Command-line option grammar" (p "The option grammar is an s-expression of the form:") (pre "((OPTION-NAME [DOCSTRING] \n              (PROPERTY VALUE) ...) \n  ...)") (p "Each " (tt "OPTION-NAME") " should be a symbol.  Given this grammar, " (tt "getopt-long") " will then accept a command-line option named " (tt "--OPTION-NAME") ".") (p "If " (tt "[DOCSTRING]") " is provided, it must be a string containing a brief description of the option.") (p "Each option can have the following (PROPERTY VALUE) pairs:") (dl (dt (tt "(single-char CHAR)")) (dd "Accept " (tt "-CHAR") " as a single-character equivalent to " (tt "--OPTION") ".  This is how to specify traditional Unix-style flags. ") (dt (tt "(required BOOL)")) (dd "If " (tt "BOOL") " is true, the option is required. " (tt "getopt-long") " will raise an error if it is not found in the list of arguments.") (dt (tt "(value FLAG)")) (dd "If " (tt "FLAG") " is " (tt "#t") ", the option requires a value; if it is " (tt "#f") ", it does not.") (dt (tt "(value (REQUIRED \"name\") [(PROPERTY VALUE) ...])")) (dd "the option requires a value and the name is used by the usage procedure.") (dt (tt "(value (OPTIONAL \"name\") [(PROPERTY VALUE) ...])")) (dd "the option may appear with or without a named value.")) (p "In addition, the following properties can be defined for a value:") (dl (dt (tt "(predicate FUNC)")) (dd "If the option accepts a value (i.e. you specified " (tt "(REQUIRED ...)") " or " (tt "(OPTIONAL ...)") " for this option), then " (tt "getopt-long") " will apply " (tt "FUNC") " to the value, and throw an exception if the result is " (tt "#f") ".  " (tt "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.") (dt (tt "(transformer FUNC)")) (dd "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.")) (p "The " (tt "(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.")) (section 3 "Library Procedures" (p (tt "getopt-long") " is a procedure for parsing command-line arguments in a manner consistent with GNU programs.") (p (tt "usage") " is a procedure that creates help strings given a grammar for the command-line arguments.") (def (sig (procedure "(getopt-long ARGS GRAMMAR [UNKNOWN-OPTION-HANDLER] [LONG-OPTION-VALUE-CSET])" (id getopt-long))) (p "Parse the arguments " (tt "ARGS") " according to the argument list grammar " (tt "GRAMMAR") ".") (p (tt "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 " (tt "program-arguments") " procedure returns a list of this form.") (p "In " (tt "ARGS") ", single-character options may be combined, in the usual Unix fashion: " (tt "(\"-x\" \"-y\")") " is equivalent to " (tt "(\"-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:") (pre "    ((apples    (single-char #\\a))\n     (blimps    (single-char #\\b) (value #t))\n     (catalexis (single-char #\\c) (value #t)))") (p "the following argument lists would be acceptable:") (pre "  (\"-a\" \"-b\" \"bang\" \"-c\" \"couth\")     (\"bang\" and \"couth\" are the values\n                                       for \"blimps\" and \"catalexis\")\n  (\"-ab\" \"bang\" \"-c\" \"couth\")         (same)\n  (\"-ac\" \"couth\" \"-b\" \"bang\")         (same)\n  (\"-abc\" \"couth\" \"bang\")             (an error, since `-b' is not the\n                                       last option in its combination)") (p "If an option's value is optional, then " (tt "getopt-long") " decides whether it has a value by looking at what follows it in " (tt "ARGS") ".  If the next element is does not appear to be an option itself, then that element is the option's value.") (p "The value of a long option can can only follow the option name, separated by an `=' character.") (p "If the option \"--\" appears in " (tt "ARGS") ", argument parsing stops there; subsequent arguments are returned as ordinary arguments, even if they resemble options.  So, in the argument list:") (pre "       (\"--apples\" \"Granny Smith\" \"--\" \"--blimps\" \"Goodyear\")") (p (tt "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.") (p "The " (tt "getopt-long") " function returns an association list in which the key is an option name --- one of the symbols from " (tt "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.") (p "There is a special item in the returned alist with a key " (tt "'@") ": this is the list of arguments that are not options or option values.") (p "Optional keyword argument " (tt "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.") (p "Optional keyword argument " (tt "LONG-OPTION-VALUE-CSET") " is a SRFI-14 character set that specifies all valid characters in an option value. This argument defaults to:") (highlight scheme " (char-set-union char-set:letter+digit \n                   char-set:punctuation\n                  (char-set #\\_ #\\^ #\\$ #\\= #\\space))") (p "By default, " (tt "getopt-long") " throws an exception if:") (ul (li "it finds an unrecognized property in GRAMMAR") (li "it finds an unrecognized option in ARGS") (li "a required option is omitted") (li "an option that requires an argument doesn't get one") (li "an option that doesn't accept an argument does get one (this can only happen using the long option " (tt "--opt=value") " syntax) ") (li "an option predicate fails")))) (section 3 "Examples" (highlight scheme " (define grammar\n  `((lockfile-dir \"location of the lock file\"   ; <-- example for docstring\n                  (required #t)\n                  (value #t)\n                  (single-char #\\k)\n                  (value (required DIR)\n                         (predicate ,directory?)))\n \n    (verbose (required #f)\n             (single-char #\\v)\n             (value #f))\n \n    (x-includes (single-char #\\x)\n             (value #t))\n \n    (rnet-server (single-char #\\y)\n                 (value (required SERVER)\n                 (predicate ,string?)))\n    ))\n \n  (getopt-long '(\"my-prog\" \"-vk\" \"/tmp\" \"foo1\" \"--x-includes=/usr/include\"\n                 \"--rnet-server=lamprod\" \"--\" \"-fred\" \"foo2\" \"foo3\")\n    grammar)")) (section 3 "Version History" (ul (li "1.17 Make help display of optional arguments consistent with other getopt implementations [thanks to Vasilij Schneidermann]") (li "1.16 Added configurable option value character set [thanks to evhan]") (li "1.0 Initial Release"))) (section 3 "License" (p "The " (tt "getopt-long") " library was written by Thien-Thi Nguyen for Guile Scheme.") (p (tt "getopt-long") " was ported to Chicken Scheme by Ivan Raikov.") (pre "Copyright (C) 1998, 2001, 2006 Free Software Foundation,\nInc.\n\nThis program is free software: you can redistribute it and/or\nmodify it under the terms of the GNU Lesser General Public License\nas published by the Free Software Foundation, either version 3 of\nthe License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\nGeneral Public License for more details.\n\nA full copy of the Lesser GPL license can be found at\n<http://www.gnu.org/licenses/>."))))