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#41127: [PATCH 2/2] doc: Explain the *command-line-processor* module in texinfo. Date: Thu, 07 May 2020 17:33:13 +0100 Organization: DM Bespoke Computer Solutions Ltd Message-ID: References: <9066a0d4437b09b02aa12c3d91dcefd607aa1e03.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="48671"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Evolution 3.30.5-1.1 To: 41127@debbugs.gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane-mx.org@gnu.org Thu May 07 18:34:09 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 1jWjTL-000CVb-La for guile-bugs@m.gmane-mx.org; Thu, 07 May 2020 18:34:07 +0200 Original-Received: from localhost ([::1]:42080 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jWjTK-0002Ca-Ls for guile-bugs@m.gmane-mx.org; Thu, 07 May 2020 12:34:06 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44028) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jWjTG-0002CP-E9 for bug-guile@gnu.org; Thu, 07 May 2020 12:34:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60490) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jWjTG-0000kk-4W for bug-guile@gnu.org; Thu, 07 May 2020 12:34:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jWjTG-0004Y4-02 for bug-guile@gnu.org; Thu, 07 May 2020 12:34:02 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: <9066a0d4437b09b02aa12c3d91dcefd607aa1e03.camel@rdmp.org> Resent-From: Dale Mellor Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Thu, 07 May 2020 16:34:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41127 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 41127-submit@debbugs.gnu.org id=B41127.158886920117403 (code B ref 41127); Thu, 07 May 2020 16:34:01 +0000 Original-Received: (at 41127) by debbugs.gnu.org; 7 May 2020 16:33:21 +0000 Original-Received: from localhost ([127.0.0.1]:43803 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jWjSa-0004Wc-Ge for submit@debbugs.gnu.org; Thu, 07 May 2020 12:33:21 -0400 Original-Received: from ec2-52-19-174-175.eu-west-1.compute.amazonaws.com ([52.19.174.175]:46348 helo=rdmp.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jWjSZ-0004WO-4k for 41127@debbugs.gnu.org; Thu, 07 May 2020 12:33:19 -0400 Original-Received: from [127.0.0.1] (helo=localhost) by rdmp.org with esmtp (Exim 4.92) (envelope-from ) id 1jWjST-0001D7-DX for 41127@debbugs.gnu.org; Thu, 07 May 2020 16:33:13 +0000 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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:9748 Archived-At: * doc/ref/Makefile.am: introduce mod-command-line-processor.texi * doc/ref/mod-command-line-processor.texi: new file * doc/ref/guile.texi: changed flow of docs * doc/ref/mod-getopt-long.texi: changed flow of docs * doc/ref/srfi-modules.texi: changed flow of docs --- doc/ref/Makefile.am | 1 + doc/ref/guile.texi | 4 +- doc/ref/mod-command-line-processor.texi | 240 ++++++++++++++++++++++++ doc/ref/mod-getopt-long.texi | 2 +- doc/ref/srfi-modules.texi | 2 +- 5 files changed, 245 insertions(+), 4 deletions(-) create mode 100644 doc/ref/mod-command-line-processor.texi diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 2f4b8ca88..b4b1eda9c 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -90,6 +90,7 @@ guile_TEXINFOS = preface.texi \ libguile-extensions.texi \ api-init.texi \ mod-getopt-long.texi \ + mod-command-line-processor.texi \ statprof.texi \ sxml.texi \ texinfo.texi \ diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index f91d08f63..9afd9b212 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -357,7 +357,7 @@ available through both Scheme and C interfaces. * SLIB:: Using the SLIB Scheme library. * POSIX:: POSIX system calls and networking. * Web:: HTTP, the web, and all that. -* getopt-long:: Command line handling. +* Command Line Processor:: Command line handling. * SRFI Support:: Support for various SRFIs. * R6RS Support:: Modules defined by the R6RS. * R7RS Support:: Modules defined by the R7RS. @@ -381,7 +381,7 @@ available through both Scheme and C interfaces. @include slib.texi @include posix.texi @include web.texi -@include mod-getopt-long.texi +@include mod-command-line-processor.texi @include srfi-modules.texi @include r6rs.texi @include r7rs.texi diff --git a/doc/ref/mod-command-line-processor.texi b/doc/ref/mod-command-line-processor.texi new file mode 100644 index 000000000..cced41fd5 --- /dev/null +++ b/doc/ref/mod-command-line-processor.texi @@ -0,0 +1,240 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 2020 +@c Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node Command Line Processor, SRFI Support, Web, Guile Modules +@section The (ice-9 command-line-processor) Module + +As its name implies, the @code{(ice-9 command-line-processor)} facility +is supposed to be a one-stop shop for dealing with the command line. It +is inspired by the GNU libc's @code{argp} parser, and can be regarded as +a high-level wrapper around the @xref{getopt-long} module. It is +designed to provide two specific features. + +@itemize @bullet +@item +Higher-level (easier to use) abstraction of the command-line user +interface to this application, including available options and program +meta-data. + +@item +Automatic handling of @code{--help}, @code{--version} and @code{--usage} +flags. This means meeting GNU coding standards, and helping to +‘regularize’ the output from these commands. +@end itemize + +The module provides a single syntax extension to the guile language: +@code{process-command-line}. + +@menu +* Command Line Examples:: Examples of use. +* Command Line Reference:: Detailed specification of the procedure. +@end menu + +Also see @xref{Command Line Format} for precise details of allowed +command-line formats. + +@node Command Line Examples, Command Line Reference, Command Line Processor, Command Line Processor +@subsection A Simple Example + +A (silly) program which takes two options, the second of which may +provide a numerical value, might include the following lines. + +@lisp +(use-modules (ice-9 command-line-processor)) + +(process-command-line (command-line) + application "my-app" + option (--option -o "the first option") + option (--test=3 -t "another option" string->number)) + +(when --option (do-something)) +(when --test (display --test) (newline)) +@end lisp + +@noindent +and then the program could be called with command lines like + +@example +$ ./my-app -o +@end example + +@noindent +or + +@example +$ ./my-app --option -t 4 file-1 file-2 +@end example + +@subsection GNU Mcron + +For realistic code, here is the first line of executable code GNU's +@code{mcron} program has (the @code{%} tokens are filled in by the build +system). + +@lisp +(process-command-line (command-line) + application "mcron" + version "%VERSION%" + usage "[OPTIONS ...] [FILES ...]" + help-preamble + "Run unattended jobs according to instructions in the FILES... " + "(‘-’ for standard input), or use all the files in ~/.config/cron " + "(or the deprecated ~/.cron) with .guile or .vixie extensions.\n" + "Note that --daemon and --schedule are mutually exclusive." + option (--daemon -d "run as a daemon process") + option (--schedule=8 -s string->number + "display the next N (or 8) jobs that will be run," + "and then exit") + option (--stdin=guile short-i (λ (in) (or (string=? in "guile") + (string=? in "vixie"))) + "format of data passed as standard input or file " + "arguments, 'guile' or 'vixie' (default guile)") + help-postamble + "Mandatory or optional arguments to long options are also mandatory or " + "optional for any corresponding short options." + bug-address "%PACKAGE_BUGREPORT%" + copyright "2003, 2006, 2014, 2020 Free Software Foundation, Inc." + license GPLv3) +@end lisp + +@noindent +after which there are four new variable bindings in the present +namespace: literally, @code{--daemon}, @code{--stdin}, @code{--schedule} +and @code{--!} (the latter holds all the command-line arguments that did +not partake in option processing) whose values depend on the specific +command-line options the end user furnished... except that if the user +had typed + +@example +$ mcron --help +@end example + +@noindent +they would be greeted with + +@example +Usage: mcron [OPTIONS ...] [FILES ...] +Run unattended jobs according to instructions in the FILES... +(`-' for standard input), or use all the files in ~/.config/cron +(or the deprecated ~/.cron) with .guile or .vixie extensions. + +Note that --daemon and --schedule are mutually exclusive. + + -d, --daemon run as a daemon process + -s[N], --schedule[=N] display the next N (or 8) jobs that will be run, + and then exit + -i[N], --stdin[=N] format of data passed as standard input or file + arguments, 'guile' or 'vixie' (default guile) + -h, --help display this help and exit + -V, --version output version information and exit + -u, --usage show brief usage summary + +Mandatory or optional arguments to long options are also mandatory or +optional for any corresponding short options. + +Send bug reports to bug-mcron@@gnu.org. +@end example + +@noindent +and the program would immediately have exited. + +@node Command Line Reference, , Command Line Examples, Command Line Processor +@subsection process-command-line + +@deffn {Scheme Procedure} process-command-line COMMAND-LINE SPECIFICATION +Process the @var{COMMAND-LINE} according to the application +@var{SPECIFICATION}. + +@var{COMMAND-LINE} is a list of strings, such as that returned from the +core @code{(command-line)} function: the first string is the name of the +command being run, and the rest are the space-separated tokens that +followed the command on the command line. + +@var{SPECIFICATION} is a form holding a space-separated mix of selection +words followed by their respective declarations. The selection words +are @code{application}, @code{author}, @code{bug-address}, +@code{copyright}, @code{help-preamble}, @code{help-postamble}, +@code{license}, @code{option}, @code{usage} and @code{version}, and can +appear in any order. + +@table @asis +@item @code{application} +should be followed by a string: the name of the application with +possibly the package name in parentheses afterwards. This may appear +zero or one times, but ideally should be present. +@item @code{author} +should be followed by a string giving the name of one of the packageʼs +authors. This selection word can be repeated as many times as necessary +to provide the names of all authors. +@item @code{bug-address} +should be followed by a string giving the URL of a contact-point for +sending bug reports, such as an e-mail address or web address of +bug-tracking system interface. This can appear zero or one times. +@item @code{copyright} +should be followed by a string containing a list of years and an entity +to whom the copyright is assigned. This may be repeated to list other +assignees. +@item @code{help-preamble} +should be followed by a number of strings which make up a short +paragraph of text displayed before a full list of the available program +options. +@item @code{help-postamble} +like the preamble, this is followed by strings which make up a paragraph +of text, shown after the list of options. +@item @code{license} +can be followed by one of the words ‘GPLv3’ [this is currently the only +standard choice implemented], or else a string which briefly gives out +the terms of the license. Can appear zero or one times. +@item @code{option} +is followed by an option declaration, described below. You can specify +any number of options. +@item @code{usage} +is followed by a string describing the usage of the application on one +line. This can appear zero or one times, but ideally should be present. +@item @code{version} +is followed by a string providing the current version number of this +program. This item may appear zero or one times. +@end table + +The ‘option’ declaration is followed by another form bracketed by +parentheses and holding a space-separated mix of declarations (order +irrelevant). + +@itemize @bullet +@item +A word beginning with two hyphens, an optional exclamation point, +alphabetic letters (intermixed with digits, underscore and hyphens), an +optional equals sign, and an optional further word. There must be +exactly one of these, and that determines the long name of the option. +An exclamation point indicates that the option MUST appear on the +command line, an equals indicates that the option MUST have a value +unless it is followed in the specification by a value, in which case the +value on the command-line is optional and the one in the specification +will be taken as the default when not given on the command line. +@item +A word comprised of one hyphen and one letter. There can be exactly +zero or one of these, and it declares that the option has this short +form available on the command-line. As a very special exception: if you +want to use @code{-i} as an option, it must be specified with the +identifier @code{short-i} (a naked @emph{-i} is read as a complex +number); ditto @code{short-I} for @code{-I}. +@item +A number of strings which are catenated together to provide a short, +succinct description of the option. These strings should be +approximately half the width of a page, i.e. about 40 characters. +@item +A function which will be used as a predicate to decide if a value is +allowable for this option. There should be zero or one of these. +@end itemize + +For the precise presentation of options on the command-line, the reader +should refer to the @xref{Command Line Format}, part of the description +of the @xref{getopt-long} module, which underlies the present one. + +@end deffn + + +@include mod-getopt-long.texi diff --git a/doc/ref/mod-getopt-long.texi b/doc/ref/mod-getopt-long.texi index cf043418f..663935a44 100644 --- a/doc/ref/mod-getopt-long.texi +++ b/doc/ref/mod-getopt-long.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@node getopt-long +@node getopt-long, SRFI Support, Command Line Processor @section The (ice-9 getopt-long) Module The @code{(ice-9 getopt-long)} facility is designed to help parse diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index fd190799c..703f4c31d 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. -@node SRFI Support +@node SRFI Support, R6RS Support, Command Line Processor, Guile Modules @section SRFI Support Modules @cindex SRFI -- 2.20.1