From unknown Sun Aug 17 00:57:51 2025 X-Loop: help-debbugs@gnu.org Subject: bug#40723: [PATCH 4/4] (ice-9 getopt-long): update commentary and doc-strings Resent-From: Dale Mellor Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Sun, 19 Apr 2020 19:02:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 40723 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch To: 40723@debbugs.gnu.org X-Debbugs-Original-To: bug-guile@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.158732287422922 (code B ref -1); Sun, 19 Apr 2020 19:02:04 +0000 Received: (at submit) by debbugs.gnu.org; 19 Apr 2020 19:01:14 +0000 Received: from localhost ([127.0.0.1]:45972 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jQFBp-0005xY-Fc for submit@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 ) id 1jQEVf-0004pE-BW for submit@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 ) id 1jQEVe-0005sn-3s for bug-guile@gnu.org; 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 ) id 1jQEVd-0006es-Fd for bug-guile@gnu.org; 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 ) id 1jQEVc-0006cr-Vh for bug-guile@gnu.org; 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 ) id 1jQE2q-0002Xn-Uh for bug-guile@gnu.org; Sun, 19 Apr 2020 17:47:53 +0000 Message-ID: <447ec67a70d0d6c8929244c05d76a40f43ba29c4.camel@rdmp.org> From: Dale Mellor 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@rdmp.org; 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-Mailman-Approved-At: Sun, 19 Apr 2020 15:01:09 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) >From 6acbbb37a2f9a1968fcdbc8f3be3c805d28ef901 Mon Sep 17 00:00:00 2001 From: Dale Mellor 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 From debbugs-submit-bounces@debbugs.gnu.org Tue May 12 09:05:23 2020 Received: (at control) by debbugs.gnu.org; 12 May 2020 13:05:23 +0000 Received: from localhost ([127.0.0.1]:54564 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jYUb5-0007RC-HM for submit@debbugs.gnu.org; Tue, 12 May 2020 09:05:23 -0400 Received: from eggs.gnu.org ([209.51.188.92]:41986) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jYUb4-0007Qy-73 for control@debbugs.gnu.org; Tue, 12 May 2020 09:05:22 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:40227) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jYUay-0007Zn-WB for control@debbugs.gnu.org; Tue, 12 May 2020 09:05:17 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=41870 helo=ribbon) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jYUay-0001hx-AT for control@debbugs.gnu.org; Tue, 12 May 2020 09:05:16 -0400 Date: Tue, 12 May 2020 15:05:15 +0200 Message-Id: <87a72db8xg.fsf@gnu.org> To: control@debbugs.gnu.org From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: control message for bug #40719 MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) merge 40719 40723 quit From debbugs-submit-bounces@debbugs.gnu.org Sun Aug 02 06:43:27 2020 Received: (at control) by debbugs.gnu.org; 2 Aug 2020 10:43:27 +0000 Received: from localhost ([127.0.0.1]:41779 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k2BSh-0001Uz-1E for submit@debbugs.gnu.org; Sun, 02 Aug 2020 06:43:27 -0400 Received: from rdmp.org ([52.19.174.175]:36166) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k2BSf-0001Un-QO for control@debbugs.gnu.org; Sun, 02 Aug 2020 06:43:26 -0400 Received: from [127.0.0.1] (helo=localhost) by rdmp.org with esmtp (Exim 4.92) (envelope-from ) id 1k2BSa-0005us-4z for control@debbugs.gnu.org; Sun, 02 Aug 2020 10:43:20 +0000 Message-ID: <0ca636036e23abf21b9725753051f9cf88ac5f30.camel@rdmp.org> Subject: From: Dale Mellor To: control Date: Sun, 02 Aug 2020 11:43:19 +0100 Organization: DM Bespoke Computer Solutions Ltd Content-Type: text/plain User-Agent: Evolution 3.30.5-1.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 4.9 (++++) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: close 40719 Content analysis details: (4.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.9 SPF_HELO_SOFTFAIL SPF: HELO does not match SPF record (softfail) 2.0 BLANK_SUBJECT Subject is present but empty 0.0 TVD_SPACE_RATIO No description available. 1.0 PDS_TONAME_EQ_TOLOCAL_VSHORT Very short body and From looks like 2 different emails X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 3.9 (+++) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: close 40719 Content analysis details: (3.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail) 0.9 SPF_HELO_SOFTFAIL SPF: HELO does not match SPF record (softfail) -1.0 MAILING_LIST_MULTI Multiple indicators imply a widely-seen list manager 2.0 BLANK_SUBJECT Subject is present but empty 0.0 TVD_SPACE_RATIO No description available. 1.0 PDS_TONAME_EQ_TOLOCAL_VSHORT Very short body and From looks like 2 different emails close 40719