GNU bug report logs - #40723
[PATCH 4/4] (ice-9 getopt-long): update commentary and doc-strings

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: guile; Reported by: Dale Mellor <guile-qf1qmg@HIDDEN>; Keywords: patch; merged with #40719, #40720, #40721, #40722; dated Sun, 19 Apr 2020 19:02:04 UTC; Maintainer for guile is bug-guile@HIDDEN.
Merged 40719 40720 40721 40722 40723. Request was from Ludovic Courtès <ludo@HIDDEN> to control <at> debbugs.gnu.org. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 19 Apr 2020 19:01:14 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Apr 19 15:01:14 2020
Received: from localhost ([127.0.0.1]:45972 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1jQFBp-0005xY-Fc
	for submit <at> debbugs.gnu.org; Sun, 19 Apr 2020 15:01:14 -0400
Received: from lists.gnu.org ([209.51.188.17]:44952)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jQEVf-0004pE-BW
 for submit <at> debbugs.gnu.org; Sun, 19 Apr 2020 14:17:40 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:34080 helo=eggs1p.gnu.org)
 by lists.gnu.org with esmtp (Exim 4.90_1)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jQEVe-0005sn-3s
 for bug-guile@HIDDEN; Sun, 19 Apr 2020 14:17:39 -0400
X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on eggs.gnu.org
X-Spam-Level: **
X-Spam-Status: No, score=2.2 required=5.0 tests=RDNS_DYNAMIC, SPF_HELO_SOFTFAIL,
 SPF_SOFTFAIL,URIBL_BLOCKED autolearn=no autolearn_force=no
 version=3.4.2
Received: from Debian-exim by eggs1p.gnu.org with spam-scanned (Exim 4.90_1)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jQEVd-0006es-Fd
 for bug-guile@HIDDEN; Sun, 19 Apr 2020 14:17:37 -0400
Received: from ec2-52-19-174-175.eu-west-1.compute.amazonaws.com
 ([52.19.174.175]:45792 helo=rdmp.org)
 by eggs1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <guile-qf1qmg@HIDDEN>)
 id 1jQEVc-0006cr-Vh
 for bug-guile@HIDDEN; Sun, 19 Apr 2020 14:17:37 -0400
Received: from [127.0.0.1] (helo=localhost) by rdmp.org with esmtp (Exim 4.92)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jQE2q-0002Xn-Uh
 for bug-guile@HIDDEN; Sun, 19 Apr 2020 17:47:53 +0000
Message-ID: <447ec67a70d0d6c8929244c05d76a40f43ba29c4.camel@HIDDEN>
Subject: [PATCH 4/4] (ice-9 getopt-long): update commentary and doc-strings
From: Dale Mellor <guile-qf1qmg@HIDDEN>
To: bug-guile@HIDDEN
Date: Sun, 19 Apr 2020 18:47:52 +0100
Organization: DM Bespoke Computer Solutions Ltd
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.30.5-1.1 
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Received-SPF: softfail client-ip=52.19.174.175;
 envelope-from=guile-qf1qmg@HIDDEN; helo=rdmp.org
X-detected-operating-system: by eggs1p.gnu.org: Genre and OS details not
 recognized.
X-Received-From: 52.19.174.175
X-Spam-Score: 0.3 (/)
X-Debbugs-Envelope-To: submit
X-Mailman-Approved-At: Sun, 19 Apr 2020 15:01:09 -0400
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.7 (/)

From 6acbbb37a2f9a1968fcdbc8f3be3c805d28ef901 Mon Sep 17 00:00:00 2001
From: Dale Mellor <guile-qf1qmg@HIDDEN>
Date: Sun, 19 Apr 2020 18:01:06 +0100
Subject: [PATCH 4/4] (ice-9 getopt-long): update commentary and doc-strings

Emphasise importance of predicate part of specification of options with
optional values.  Minor clarifications elsewhere.  Update copyright
years and authorship.

* module/ice-9/getopt-long.scm: Small changes only in non-code parts of
  source file.
---
 module/ice-9/getopt-long.scm | 117 +++++++++++++++++++++--------------
 1 file changed, 71 insertions(+), 46 deletions(-)

diff --git a/module/ice-9/getopt-long.scm b/module/ice-9/getopt-long.scm
index 4c920cbe5..699e646c4 100644
--- a/module/ice-9/getopt-long.scm
+++ b/module/ice-9/getopt-long.scm
@@ -1,5 +1,8 @@
-;;; Copyright (C) 1998, 2001, 2006, 2009, 2011 Free Software Foundation, Inc.
-;;;
+;;;; getopt-long.scm --- long options processing   -*- scheme -*-
+;;;;
+;;;; Copyright (C) 1998, 2001, 2006, 2009, 2011, 2020
+;;;;                                            Free Software Foundation, Inc.
+;;;;
 ;;;; This library 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
@@ -12,54 +15,59 @@
 ;;;; 
 ;;;; You should have received a copy of the GNU Lesser General Public
 ;;;; License along with this library; if not, write to the Free Software
-;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+;;;; 02110-1301 USA
 
-;;; Author: Russ McManus (rewritten by Thien-Thi Nguyen)
+;;; Author: Russ McManus
+;;;         Rewritten by Thien-Thi Nguyen
+;;;         Rewritten by Dale Mellor 2020-04-14
 
 ;;; Commentary:
 
 ;;; This module implements some complex command line option parsing, in
-;;; the spirit of the GNU C library function `getopt_long'.  Both long
+;;; 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.
+;;; options they want to process using a grammar, rather than some ad
+;;; hoc procedure.  The grammar makes the option descriptions easy to
+;;; read.
 ;;;
-;;; `getopt-long' is a procedure for parsing command-line arguments in a
-;;; manner consistent with other GNU programs.  `option-ref' is a procedure
-;;; that facilitates processing of the `getopt-long' return value.
+;;; ‘getopt-long’ is a procedure for parsing command-line arguments in a
+;;; manner consistent with other GNU programs.  ‘option-ref’ is a procedure
+;;; that facilitates processing of the ‘getopt-long’ return value.
 
 ;;; (getopt-long ARGS GRAMMAR)
 ;;; 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
+;;; name of the program, and 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.
+;;; ‘program-arguments’ procedure returns a list of this form.
 ;;;
 ;;; GRAMMAR is a list of the form:
 ;;; ((OPTION (PROPERTY VALUE) ...) ...)
 ;;;
-;;; Each OPTION should be a symbol.  `getopt-long' will accept a
-;;; command-line option named `--OPTION'.
+;;; Each OPTION should be a symbol.  ‘getopt-long’ will accept a
+;;; command-line option named ‘--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
+;;;   (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 ARGS.
 ;;;   (value BOOL) --- If BOOL is #t, the option accepts a value; if
 ;;;		it is #f, it does not; and if it is the symbol
-;;;		`optional', the option may appear in ARGS with or
+;;;		‘optional’, the option may appear in ARGS with or
 ;;;		without a value.
 ;;;   (predicate FUNC) --- If the option accepts a value (i.e. you
-;;;		specified `(value #t)' for this option), then getopt
-;;;		will apply FUNC to the value, and throw an exception
-;;;		if it returns #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 GRAMMAR.
+;;;		specified ‘(value #t)’ or ‘(value 'optional)’ for this
+;;;		option), then getopt will apply FUNC to the value, and
+;;;		will not take the value if it returns #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 GRAMMAR.
 ;;;
 ;;; The (PROPERTY VALUE) pairs may occur in any order, but each
 ;;; property may occur only once.  By default, options do not have
@@ -79,16 +87,22 @@
 ;;;                                         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.
+;;; 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, and passes a
+;;; predicate if given, then that element is taken to be the option's
+;;; value.  Note that predicate functions are invaluable in this respect
+;;; for differentiating options and option values, and in the case of
+;;; options with optional values, PREDICATES REALLY SHOULD BE GIVEN.  If
+;;; an option is supposed to take a numerical value, then
+;;; ‘string->number’ can be used as the predicate; this will also allow
+;;; negative values to be used, which would ordinarily be regarded as
+;;; bad options causing the module, and the application consuming it, to
+;;; bail out with an immediate exit to the operating system.
 ;;;
 ;;; The value of a long option can appear as the next element in ARGS,
-;;; or it can follow the option name, separated by an `=' character.
+;;; or it can follow the option name, separated by an ‘=’ character.
 ;;; Thus, using the same grammar as above, the following argument lists
 ;;; are equivalent:
 ;;;   ("--apples" "Braeburn" "--blimps" "Goodyear")
@@ -99,27 +113,30 @@
 ;;; subsequent arguments are returned as ordinary arguments, even if
 ;;; they resemble options.  So, in the argument list:
 ;;;         ("--apples" "Granny Smith" "--" "--blimp" "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 "--blimp" and "Goodyear" as
-;;; ordinary argument strings.
+;;; ‘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 "--blimp" and "Goodyear" as ordinary
+;;; argument strings.  The first "--" argument itself will *not* appear
+;;; in the ordinary arguments list, although the occurrence of
+;;; subsequent ones will.
 ;;;
-;;; The `getopt-long' function returns the parsed argument list as an
+;;; The ‘getopt-long’ function returns the parsed argument list as an
 ;;; assocation list, mapping option names --- the symbols from GRAMMAR
 ;;; --- onto their values, or #t if the option does not accept a value.
 ;;; Unused options do not appear in the alist.
 ;;;
-;;; All arguments that are not the value of any option are returned
-;;; as a list, associated with the empty list.
+;;; All arguments that are not the value of any option are returned as a
+;;; list, associated with the empty list in the above returned
+;;; association.
 ;;;
-;;; `getopt-long' throws an exception if:
+;;; ‘getopt-long’ throws an exception if:
 ;;; - it finds an unrecognized property in GRAMMAR
-;;; - the value of the `single-char' property is not a character
+;;; - the value of the ‘single-char’ property is not a character
 ;;; - 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)
+;;;   only happen using the long option ‘--opt=value’ syntax)
 ;;; - an option predicate fails
 ;;;
 ;;; So, for example:
@@ -147,9 +164,10 @@
 
 ;;; (option-ref OPTIONS KEY DEFAULT)
 ;;; Return value in alist OPTIONS using KEY, a symbol; or DEFAULT if not
-;;; found.  The value is either a string or `#t'.
+;;; found.  The return is either a string or ‘#t’, or whatever DEFAULT
+;;; is.
 ;;;
-;;; For example, using the `getopt-long' return value from above:
+;;; For example, using the ‘getopt-long’ return value from above:
 ;;;
 ;;; (option-ref (getopt-long ...) 'x-includes 42) => "/usr/include"
 ;;; (option-ref (getopt-long ...) 'not-a-key! 31) => 31
@@ -447,7 +465,7 @@
             (return  (append (reverse processed) args)))
         ;else
           (loop  (list (cdr args)  (cons A processed))))))))))
-         
+
 
 
 ;;  Check that all the rules inherent in the /specs/ are fulfilled by
@@ -523,7 +541,10 @@
 
 (define* (getopt-long program-arguments option-desc-list
                       #:key stop-at-first-non-option)
-  "Process options, handling both long and short options, similar to
+  "- Scheme Procedure: getopt-long PROGRAM-ARGUMENTS OPTION-DESC-LIST
+                                 [#:stop-at-first-non-option]
+
+Process options, handling both long and short options, similar to
 the glibc function 'getopt_long'.  PROGRAM-ARGUMENTS should be a value
 similar to what (program-arguments) returns.  OPTION-DESC-LIST is a
 list of option descriptions.  Each option description must satisfy the
@@ -552,7 +573,8 @@ or option values.
     By default, options are not required, and option values are not
 required.  By default, single character equivalents are not supported;
 if you want to allow the user to use single character options, you need
-to add a `single-char' clause to the option description."
+to add a ‘single-char’ clause to the option description."
+
   (with-fluids ((%program-name (car program-arguments)))
     (let* ((specs   (map parse-option-spec option-desc-list))
            (options  (extract-options
@@ -566,8 +588,11 @@ to add a `single-char' clause to the option description."
 
 
 (define (option-ref options key default)
-  "Return value in alist OPTIONS using KEY, a symbol; or DEFAULT if not found.
-The value is either a string or `#t'."
+  "- Scheme Procedure: option-ref OPTIONS KEY DEFAULT
+      Return value in alist OPTIONS (as returned from getopt-long),
+      using KEY, a symbol; or DEFAULT if not found.  The value is either
+      a string or ‘#t’, or whatever DEFAULT is."
   (or (assq-ref options key) default))
 
+
 ;;; getopt-long.scm ends here
-- 
2.20.1






Acknowledgement sent to Dale Mellor <guile-qf1qmg@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-guile@HIDDEN. Full text available.
Report forwarded to bug-guile@HIDDEN:
bug#40723; Package guile. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Tue, 12 May 2020 13:15:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.