[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.1-101-gc382f58

[Neil Jerram]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=c382f58943a80cc9467695b3f2399407bcf7e1bf

The branch, stable-2.0 has been updated
       via  c382f58943a80cc9467695b3f2399407bcf7e1bf (commit)
       via  7a582ca155eb59083149840b76c3fcebbbdedfe4 (commit)
      from  153c4a4afa4ca3ae6020a0d5ec34bbe62a62c568 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit c382f58943a80cc9467695b3f2399407bcf7e1bf
Author: Neil Jerram <address@hidden>
Date:   Thu May 26 22:02:16 2011 +0100

    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.

commit 7a582ca155eb59083149840b76c3fcebbbdedfe4
Author: Neil Jerram <address@hidden>
Date:   Thu May 26 21:30:05 2011 +0100

    Remove unused script-getopt.texi
    
    * doc/ref/Makefile.am (guile_TEXINFOS): Remove script-getopt.texi.
    
    * doc/ref/script-getopt.texi: Deleted.  This file wasn't included in
      the manual, and its content is now duplicated identically in
      scheme-scripts.texi.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/Makefile.am          |    1 -
 doc/ref/mod-getopt-long.texi |   26 ++++++++++-
 doc/ref/script-getopt.texi   |   93 ------------------------------------------
 3 files changed, 23 insertions(+), 97 deletions(-)
 delete mode 100644 doc/ref/script-getopt.texi

diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am
index 0359380..2ccf7dd 100644
--- a/doc/ref/Makefile.am
+++ b/doc/ref/Makefile.am
@@ -67,7 +67,6 @@ guile_TEXINFOS = preface.texi                 \
                 api-deprecated.texi            \
                 scheme-using.texi              \
                 indices.texi                   \
-                script-getopt.texi             \
                 data-rep.texi                  \
                 repl-modules.texi              \
                 srfi-modules.texi              \
diff --git a/doc/ref/mod-getopt-long.texi b/doc/ref/mod-getopt-long.texi
index 3d753df..1740215 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}
 
address@hidden {Scheme Procedure} getopt-long args grammar
address@hidden {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 @address@hidden syntax).
 An option predicate fails.
 @end itemize
 
address@hidden: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}
diff --git a/doc/ref/script-getopt.texi b/doc/ref/script-getopt.texi
deleted file mode 100644
index c7bb0d4..0000000
--- a/doc/ref/script-getopt.texi
+++ /dev/null
@@ -1,93 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
address@hidden   Free Software Foundation, Inc.
address@hidden See the file guile.texi for copying conditions.
-
address@hidden Command Line Handling
address@hidden Handling Command Line Options and Arguments
-
address@hidden This chapter was written and contributed by Martin Grabmueller.
-
-The ability to accept and handle command line arguments is very
-important when writing Guile scripts to solve particular problems, such
-as extracting information from text files or interfacing with existing
-command line applications.  This chapter describes how Guile makes
-command line arguments available to a Guile script, and the utilities
-that Guile provides to help with the processing of command line
-arguments.
-
-When a Guile script is invoked, Guile makes the command line arguments
-accessible via the procedure @code{command-line}, which returns the
-arguments as a list of strings.
-
-For example, if the script
-
address@hidden
-#! /usr/local/bin/guile -s
-!#
-(write (command-line))
-(newline)
address@hidden example
-
address@hidden
-is saved in a file @file{cmdline-test.scm} and invoked using the command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
-is
-
address@hidden
-("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
address@hidden example
-
-If the script invocation includes a @code{-e} option, specifying a
-procedure to call after loading the script, Guile will call that
-procedure with @code{(command-line)} as its argument.  So a script that
-uses @code{-e} doesn't need to refer explicitly to @code{command-line}
-in its code.  For example, the script above would have identical
-behaviour if it was written instead like this:
-
address@hidden
-#! /usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
-  (write args)
-  (newline))
address@hidden example
-
-(Note the use of the meta switch @code{\} so that the script invocation
-can include more than one Guile option: @xref{The Meta Switch}.)
-
-These scripts use the @code{#!} POSIX convention so that they can be
-executed using their own file names directly, as in the example command
-line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}.  But they
-can also be executed by typing out the implied Guile command line in
-full, as in:
-
address@hidden
-$ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
address@hidden example
-
address@hidden
-or
-
address@hidden
-$ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
address@hidden example
-
-Even when a script is invoked using this longer form, the arguments that
-the script receives are the same as if it had been invoked using the
-short form.  Guile ensures that the @code{(command-line)} or @code{-e}
-arguments are independent of how the script is invoked, by stripping off
-the arguments that Guile itself processes.
-
-A script is free to parse and handle its command line arguments in any
-way that it chooses.  Where the set of possible options and arguments is
-complex, however, it can get tricky to extract all the options, check
-the validity of given arguments, and so on.  This task can be greatly
-simplified by taking advantage of the module @code{(ice-9 getopt-long)},
-which is distributed with Guile, @xref{getopt-long}.
-
address@hidden Local Variables:
address@hidden TeX-master: "guile.texi"
address@hidden End:


hooks/post-receive
-- 
GNU Guile