From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Dale Mellor Newsgroups: gmane.lisp.guile.bugs Subject: bug#40723: [PATCH 4/4] (ice-9 getopt-long): update commentary and doc-strings Date: Sun, 19 Apr 2020 18:47:52 +0100 Organization: DM Bespoke Computer Solutions Ltd Message-ID: <447ec67a70d0d6c8929244c05d76a40f43ba29c4.camel@rdmp.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="71952"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Evolution 3.30.5-1.1 To: 40723@debbugs.gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Sun Apr 19 21:02:18 2020 Return-path: Envelope-to: guile-bugs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jQFCs-000Iat-5p for guile-bugs@m.gmane-mx.org; Sun, 19 Apr 2020 21:02:18 +0200 Original-Received: from localhost ([::1]:46652 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQFCr-0001vj-8B for guile-bugs@m.gmane-mx.org; Sun, 19 Apr 2020 15:02:17 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42824 helo=eggs1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jQFCg-0001iB-DA for bug-guile@gnu.org; Sun, 19 Apr 2020 15:02:07 -0400 Original-Received: from Debian-exim by eggs1p.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jQFCe-0000OL-VU for bug-guile@gnu.org; Sun, 19 Apr 2020 15:02:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34432) by eggs1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jQFCe-0000O5-Jb for bug-guile@gnu.org; Sun, 19 Apr 2020 15:02:04 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jQFCe-0005zS-I0 for bug-guile@gnu.org; Sun, 19 Apr 2020 15:02:04 -0400 X-Loop: help-debbugs@gnu.org 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 X-Debbugs-Original-To: bug-guile@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.158732287422922 (code B ref -1); Sun, 19 Apr 2020 19:02:04 +0000 Original-Received: (at submit) by debbugs.gnu.org; 19 Apr 2020 19:01:14 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 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-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 X-Received-From: 209.51.188.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Original-Sender: "bug-guile" Xref: news.gmane.io gmane.lisp.guile.bugs:9723 Archived-At: >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