From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: 43159@debbugs.gnu.org
Subject: [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that.
Date: Wed, 02 Sep 2020 14:24:34 -0400 [thread overview]
Message-ID: <87r1rk595p.fsf@gmail.com> (raw)
In-Reply-To: <20200901204136.21375-1-ludo@gnu.org> ("Ludovic \=\?utf-8\?Q\?Cou\?\= \=\?utf-8\?Q\?rt\=C3\=A8s\=22's\?\= message of "Tue, 1 Sep 2020 22:41:35 +0200")
Ludovic Courtès <ludo@gnu.org> writes:
> This changes 'guix help' to print a short synopsis for each command and
> to group commands by category.
[...]
> diff --git a/guix/scripts.scm b/guix/scripts.scm
> index 8534948892..013b775818 100644
> --- a/guix/scripts.scm
> +++ b/guix/scripts.scm
> @@ -34,7 +34,10 @@
> #:use-module (srfi srfi-19)
> #:use-module (srfi srfi-37)
> #:use-module (ice-9 match)
> - #:export (args-fold*
> + #:export (synopsis
> + category
> + define-command
> + args-fold*
> parse-command-line
> maybe-build
> build-package
> @@ -50,6 +53,30 @@
> ;;;
> ;;; Code:
>
> +;; Syntactic keywords.
> +(define synopsis 'command-synopsis)
> +(define category 'command-category)
Are these definition really necessary/useful? I would have thought
having category and synopsis understood as literals in the
define-command syntax was enough?
> +(define-syntax define-command
> + (syntax-rules (category synopsis)
> + "Define the given command as a procedure along with its synopsis and,
> +optionally, its category. The synopsis becomes the docstring of the
> +procedure, but both the category and synopsis are meant to be read (parsed) by
> +'guix help'."
> + ;; The (synopsis ...) form is here so that xgettext sees those strings as
> + ;; translatable.
> + ((_ (name . args)
> + (synopsis doc) body ...)
> + (define (name . args)
> + doc
> + body ...))
> + ((_ (name . args)
> + (category _)
> + (synopsis doc) body ...)
> + (define (name . args)
> + doc
> + body ...))))
> +
> (define (args-fold* args options unrecognized-option-proc operand-proc . seeds)
> "A wrapper on top of `args-fold' that does proper user-facing error
> reporting."
> diff --git a/guix/scripts/archive.scm b/guix/scripts/archive.scm
> index f3b86fba14..8796774a01 100644
> --- a/guix/scripts/archive.scm
> +++ b/guix/scripts/archive.scm
> @@ -355,7 +355,10 @@ output port."
> ;;; Entry point.
> ;;;
>
> -(define (guix-archive . args)
> +(define-command (guix-archive . args)
> + (category advanced)
It'd be helpful if the category was an enum to keep the set of
categories focused and helpful.
[...]
> --- a/guix/scripts/weather.scm
> +++ b/guix/scripts/weather.scm
> @@ -495,7 +495,9 @@ SERVER. Display information for packages with at least THRESHOLD dependents."
> ;;; Entry point.
> ;;;
>
> -(define (guix-weather . args)
> +(define-command (guix-weather . args)
> + (synopsis "report on the available of pre-built package binaries")
^ availability
[...]
> +(define (source-file-command file)
> + "Read FILE, a Scheme source file, and return either a <command> object based
> +on the 'define-command' top-level form found therein, or #f if FILE does not
> +contain a 'define-command' form."
> + (define command-name
> + (match (string-split file #\/)
> + ((_ ... "guix" "scripts" name)
> + (list (file-sans-extension name)))
> + ((_ ... "guix" "scripts" first second)
> + (list first (file-sans-extension second)))))
It'd be better if an else clause threw an informative error, especially
since the restriction on file name is not otherwise documented.
> + ;; The strategy here is to parse FILE. This is much cheaper than a
> + ;; technique based on run-time introspection where we'd load FILE and all
> + ;; the modules it depends on.
Interesting! Have you measure it? I would have thought loading a couple
optimized byte code modules could have been nearly as fast as parsing
files manually. If so, I think it'd be preferable to use introspection
rather than implement a custom parser.
> + (call-with-input-file file
> + (lambda (port)
> + (let loop ()
> + (match (read port)
> + (('define-command _ ('synopsis synopsis)
> + _ ...)
> + (command command-name synopsis 'main))
> + (('define-command _
> + ('category category) ('synopsis synopsis)
> + _ ...)
> + (command command-name synopsis category))
> + ((? eof-object?)
> + #f)
> + (_
> + (loop)))))))
> +
[...]
> + (define (display-commands commands)
> + (let* ((names (map (lambda (command)
> + (string-join (command-name command)))
> + commands))
> + (max-width (reduce max 0 (map string-length names))))
You can drop reduce and use (max (map string-length names)) instead.
Maxim
next prev parent reply other threads:[~2020-09-02 18:29 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-01 20:35 [bug#43159] [PATCH 0/2] Make 'guix help' helpful Ludovic Courtès
2020-09-01 20:41 ` [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that Ludovic Courtès
2020-09-01 20:41 ` [bug#43159] [PATCH 2/2] ui: '--help' output links to <https://guix.gnu.org/help/> Ludovic Courtès
2020-09-02 18:27 ` Maxim Cournoyer
2020-09-02 18:24 ` Maxim Cournoyer [this message]
2020-09-03 13:41 ` [bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that Ludovic Courtès
2020-09-11 18:58 ` Maxim Cournoyer
2020-09-13 13:03 ` Ludovic Courtès
2020-09-13 23:33 ` Maxim Cournoyer
2020-09-07 12:56 ` [bug#43159] [PATCHES v2] " Ludovic Courtès
2020-09-10 10:34 ` bug#43159: " Ludovic Courtès
2020-09-10 10:55 ` [bug#43159] " Ricardo Wurmus
2020-09-02 8:06 ` [bug#43159] [PATCH 0/2] Make 'guix help' helpful Efraim Flashner
2020-09-02 9:50 ` Ludovic Courtès
2020-09-02 11:09 ` Efraim Flashner
2020-09-03 16:40 ` zimoun
2020-09-07 12:58 ` Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87r1rk595p.fsf@gmail.com \
--to=maxim.cournoyer@gmail.com \
--cc=43159@debbugs.gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).