Subject: CLI: short-name option with optional argument

From: zimoun <[email-masked]>
Date: Wed, 08 Sep 2021 14:38:40 +0200

Hi,

The help says, for example:

--8<---------------cut here---------------start------------->8---
  -I, --list-installed[=REGEXP]
                         list installed packages matching REGEXP
  -A, --list-available[=REGEXP]
                         list available packages matching REGEXP
--8<---------------cut here---------------end--------------->8---

and the manual also says:

--8<---------------cut here---------------start------------->8---
‘--list-installed[=REGEXP]’
‘-I [REGEXP]’
     List the currently installed packages in the specified profile,

[...]

‘--list-available[=REGEXP]’
‘-A [REGEXP]’
     List packages currently available in the distribution for this
--8<---------------cut here---------------end--------------->8---

which is not true.  The ’REGEXP’ is not optional when using the
short-name option.  For instance, consider:

    $ guix package -I -p ~/.guix-profile
    guix package: error: /home/simon/.guix-profile: extraneous argument

    $ guix package -A -p ~/.guix-profile
    guix package: error: /home/simon/.guix-profile: extraneous argument

And compare with:

    $ guix package --list-installed -p ~/.guix-profile
    $ guix package --list-available -p ~/.guix-profile

Here, the issue is illustrated with 2 options but it happens for all the
options allowing an optional-argument *and* a short-name.  Exhaustive
list:
        guix gc:
          -C, --collect-garbage[=MIN]
          -d, --delete-generations[=PATTERN]

        guix package:
          -u, --upgrade[=REGEXP]
          -l, --list-generations[=PATTERN]
          -d, --delete-generations[=PATTERN]
          -I, --list-installed[=REGEXP]
          -A, --list-available[=REGEXP]

        guix pull:
          -l, --list-generations[=PATTERN]
          -d, --delete-generations[=PATTERN]

        guix weather:
          -c, --coverage[=COUNT]

        guix publish:
          -C, --compression[=METHOD:LEVEL]
          -r, --repl[=PORT]      créer le serveur REPL sur le PORT

And “guix {system,import,git}” needs some special care. :-)

The issue is that the semantic of short-name of optional argument is
ambiguous considering all the other rules.

All is correctly documented, for instance see SRFI-37 [1].  What is
missing is the corner case: how to deal with short-name option with
optional argument?  There is 2 incompatible rules.  The choice of the
Guile implementation leads to break the permutation rule for the
short-name with optional argument and maintain consistency with the
space between flag and argument.  Another choice is to break the
consistency with the space between flag and argument and so it does not
break the permutation rule; as with the Git example of '-S[<keyid>],
--gpg-sign[=<keyid>]'.

Using optional argument with short-option names is unusual, AFAIK.  And
for sure, there is an ambiguity; as we are seeing here. :-) However, the
only mention of that is in the commentaries of Guile implementation of
srfi-37 [2].

--8<---------------cut here---------------start------------->8---
;;; `required-arg?' and `optional-arg?' are mutually exclusive
;;; booleans and indicate whether an argument must be or may be
;;; provided.  Besides the obvious, this affects semantics of
;;; short-options, as short-options with a required or optional
;;; argument cannot be followed by other short options in the same
;;; program-arguments string, as they will be interpreted collectively
;;; as the option's argument.
--8<---------------cut here---------------end--------------->8---

Well, using short-option with optional-argument is not recommended by
POSIX [3], neither GNU [4] (if I understand well).

The question is what do we do?  For reference, the issue had been
reported by bug#40549 [5].

The short-name option with no argument is handy, for instance:

  $ guix package -A | cut -f1 | grep cuirass
  $ guix weather $(guix package -I | cut -f1)

but breaking the permutation is *really* annoying; especially when using
a lot of profiles.

Therefore, I propose:

 1) remove the short-name with optional argument; keep the long-name
 with optional argument

2) add a short-name without argument; for example ’-I’ meaning
’--list-installed’ with the current default REGEXP.

WDYT?

All the best,
simon

1: <https://srfi.schemers.org/srfi-37/srfi-37.html>
2: <http://git.savannah.gnu.org/cgit/guile.git/tree/module/srfi/srfi-37.scm#n51>
3: <https://pubs.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap12.html#tag_12_02>
4: <https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html>
5: <<http://issues.guix.gnu.org/40549>