[bug#43159] [PATCH 1/2] scripts: Use 'define-command' and have 'guix help' use that.

[Maxim Cournoyer]

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