unofficial mirror of guix-patches@gnu.org 
 help / color / mirror / code / Atom feed
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




  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).