diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2011-05-26 22:02:16 +0100 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2011-05-26 22:02:16 +0100 |
commit | c382f58943a80cc9467695b3f2399407bcf7e1bf (patch) | |
tree | 671b10372daa92383143527572c2a8904981b957 | |
parent | 7a582ca155eb59083149840b76c3fcebbbdedfe4 (diff) | |
download | guile-c382f58943a80cc9467695b3f2399407bcf7e1bf.tar.gz |
Doc for getopt-long's new stop-at-first-non-option option
* doc/ref/mod-getopt-long.texi (getopt-long): Mention optional keyword
parameters.
(getopt-long Reference): Document #:stop-at-first-non-option.
-rw-r--r-- | doc/ref/mod-getopt-long.texi | 26 |
1 files changed, 23 insertions, 3 deletions
diff --git a/doc/ref/mod-getopt-long.texi b/doc/ref/mod-getopt-long.texi index 3d753df67..17402151a 100644 --- a/doc/ref/mod-getopt-long.texi +++ b/doc/ref/mod-getopt-long.texi @@ -13,8 +13,9 @@ The @code{(ice-9 getopt-long)} module exports two procedures: @itemize @bullet @item @code{getopt-long} takes a list of strings --- the command line -arguments --- and an @dfn{option specification}. It parses the command -line arguments according to the option specification and returns a data +arguments --- an @dfn{option specification}, and some optional keyword +parameters. It parses the command line arguments according to the +option specification and keyword parameters, and returns a data structure that encapsulates the results of the parsing. @item @@ -254,7 +255,7 @@ as ordinary argument strings. @node getopt-long Reference @subsection Reference Documentation for @code{getopt-long} -@deffn {Scheme Procedure} getopt-long args grammar +@deffn {Scheme Procedure} getopt-long args grammar [#:stop-at-first-non-option #t] Parse the command line given in @var{args} (which must be a list of strings) according to the option specification @var{grammar}. @@ -290,6 +291,13 @@ value, and throw an exception if it returns @code{#f}. @var{func} should be a procedure which accepts a string and returns a boolean value; you may need to use quasiquotes to get it into @var{grammar}. @end table + +The @code{#:stop-at-first-non-option} keyword, if specified with any +true value, tells @code{getopt-long} to stop when it gets to the first +non-option in the command line. That is, at the first word which is +neither an option itself, nor the value of an option. Everything in the +command line from that word onwards will be returned as non-option +arguments. @end deffn @code{getopt-long}'s @var{args} parameter is expected to be a list of @@ -323,6 +331,18 @@ happen using the long option @code{--opt=@var{value}} syntax). An option predicate fails. @end itemize +@code{#:stop-at-first-non-option} is useful for command line invocations +like @code{guile-tools [--help | --version] [script [script-options]]} +and @code{cvs [general-options] command [command-options]}, where there +are options at two levels: some generic and understood by the outer +command, and some that are specific to the particular script or command +being invoked. To use @code{getopt-long} in such cases, you would call +it twice: firstly with @code{#:stop-at-first-non-option #t}, so as to +parse any generic options and identify the wanted script or sub-command; +secondly, and after trimming off the initial generic command words, with +a script- or sub-command-specific option grammar, so as to process those +specific options. + @node option-ref Reference @subsection Reference Documentation for @code{option-ref} |