Re: PATCH: list units in brackets at the end of completion group descriptions

[Oliver Kiddle <opk@zsh.org>]

On 2 Nov, Jun T wrote:
> > Units are nearly always only applicable on the end of numbers. So how
> > about we add _numbers as a helper function to take care of completing
> > unit suffixes.

> I thought I could improve _head/_tail by using _numbers, but these
> command (and maybe some others) accept a '+' sign before the number
> (in addition to '-'). So either let _numbers accept '+' if the option -N
> is given, or add another option, say -P, to make it accept '+'.

I'd avoid -P because it's a common compadd option. zparseopts doesn't
appear to cope with -+ so we'd need to pick another letter. In the
case of head and tail an initial + does have an actual meaning and
it's useful to have the description saying "start at the specified
byte/line". So I'm not sure it's especially useful to add. You can
always do compset -P '+' first.

_head and _tail actually take the approach of completing digits 0-9 with
no suffix. I'm not sure how useful that is - perhaps for someone who
loves menu completion. For head and tail, someone may want to set the
fake style to prime them with specific values such as $(( LINES - 1 ))
and $(( LINES/2 - 1 )). Completing 0-9 gets in the way of that.

Do you see an issue with the behaviour of the following:
  local alts
  [[ -z $PREFIX ]] && alts=( 'sign:sign:((-\:"print all but the last specified bytes/lines" +\:"print the first specified bytes/lines (default)"))' )
  compset -P '+'
  alts+=( 'numbers: :_numbers number b\:512 K\:1024 KB\:1000 M\:1024\^2 MB\:1000\^2 G\:1024\^3 GB\:1000\^3 T\:1024\^4 TB\:1000\^4' )
  _alternative $alts

> > I've used %m for units (measurement
> > - u is taken for underline), %r for range (e.g 1-30), %o for default
> > (otherwise - d is taken), %x for the list of suffixes (s is taken) and
> > %h for the unadorned description (heading).
> (snip)
> > Corresponding to these are uppercase forms for use with the zformat
> > conditional. This allows, e.g. %(M. %F{28}(%m%)%f.) for adding the units
> > conditionally.
>
> As you know, %(M is equivalent to %0(M. We need to use %2(M here since
> > +  (( $#units )) && formats+=( m:${units[2]} M:${#units} ) desc+=" ($units[2])"
> ${#units} is 2 if option -u is given (and 0 otherwise).
> For %R %O %X and %H we need to use %1(R etc.
> At least we need to set M to 1 as others.

My intention was for it to be 1 like the others. I had started out with
them all like that - $#range etc - and changed them to 1 later. Units
somehow got missed so thanks for spotting that. I had initially given
some thought to whether we might be able to do some sort of alignment,
e.g. right aligning the suffixes but zformat isn't really up to that.

> Or is it better to set them to 0 so that %(M etc. works?

The absence of any M: spec is treated as 0, unfortunately. In this case
M: is only there as a way to flag that an m: spec is present. So we end
up needing to use the else condition or the literal 1:

  either %(M.. (%m)) or %1(M. (%m).)

I don't like that much either. Perhaps we should add an option to
zformat so that we can simply use $(m. %(m).) with no need for the
uppercase spec.

Currently that would do math evaluation on whatever is used in the m:
spec and defaults to 0. An option to zformat would not be backward
compatible for the format style (not that we ever used the feature but
someone might). A different spec form such as m+:$units would still
suffer from the problem that in the absence of the spec %(m. would
give you the true branch. Any thoughts or ideas? Or should we just stick
with M:1 and needing the else branch or a 1.

> This works fine (some users may feel it too complicated, but I think it is
> unavoidable).

The formats look worse to read than when constructing them. Many users
just install a "theme" and will never see this anyway. And as you say,
it's probably unavoidable.

> Isn't it better to use some default format if the format style is not set for
> the unit-suffixes tag? Maybe '%(d.%U.)%x%(d.%u.)%(r..|)' ?

Yes, probably. The main reason I didn't do that was because it forces me
to come up with a default format. I'll take your suggestion.

> I guess most of the users just set the format style for the descriptions tag to
> '%B%d%b'. Currently %d gives 'header (unit) [default]'. I guess some (many?)
> users also want to see the possible suffixes before they start typing the
> number. But since () and [] are already used the only possibility would be {},
> like '{k|M|G|T}' But some users may not understand that this is a list of
> possible suffixes. Probably it is enough to show an example format, such as
> '%B%d%(X.{%x}.)%b', in the document?

If we do want to include it, braces are probably best in terms of people
being able to guess correctly at their meaning. Daniel's point about
locality aside, I also prefer them at the end because I think of them as
a sort of lookahead. And there may be scope for other forms of lookahead
syntax hints in the future. I don't have a strong opinion on it but I'm
inclined to just leave them out for now. If someone wants to add them, I
won't object.

Your example is at least a short and understandable example even if it
doesn't divide things up with bold for the header, italics for the units
and a lighter colour for the suffixes. I'll see if it can fit in in the
documentation.

> > This _numbers function takes quite a few options. Should we allow a way
> > to configure how a range is presented - this hardcodes a dash separating
> > min and max and has no way to indicate for decimal numbers whether the
> > min and max values are inclusive?
>
> I think we need not to indicate that min/max is inclusive.
> For the '-' (dash) as a separator: if min/max is negative it would look like
> '-5--2'. But I guess negative min/max are quite rare and maybe we don't
> need to care about such cases. Or we could use '[-5,-2]' (a mathematical
> notation for a closed interval), but it may be confused with the default value.

Negative maximums are probably not common in practice. The mathematical
notation includes things like (0,1] which I find too jarring. Given
something like (0<x<=1) or Rust-style 0..=1, I at least don't need to
check wikipedia to know which side is inclusive.

If someone really wants commas or some unicode like … then we could
add a style later. The same goes for non-inclusive bounds and whatever
formatting mess is needed to allow different notations.

> There are typos here. The two lines should be

I'll include these when I send an updated patch with documentation.

Thanks for taking a look at this, picking out the mistakes and for the
thoughtful comments.

Oliver