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

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Oliver Kiddle wrote on Mon, Nov 22, 2021 at 22:24:36 +0100:
> Attached is an updated version of the patch from 49532 to add a helper
> for completing numbers with unit suffixes and for separating out
> defaults, ranges and units in descriptions.

It looks like some documentation is duplicated between top of the file
and the manual.  Recommend to de-duplicate, otherwise the two copies
will inveitably get out of sync with each other.

Maybe mention the addition of _numbers in NEWS?

Cheers,

Daniel


> +++ b/Completion/Base/Utility/_numbers
> @@ -0,0 +1,87 @@
> +#autoload
> +
> +# Usage: _numbers [compadd options] [-t tag] [-f|-N] [-u units] [-l min] [-m max] \
> +#                 [-d default] ["description"] [unit-suffix...]
> +
> +#   -t : specify a tag (defaults to 'numbers')
> +#   -u : indicate the units, e.g. seconds
> +#   -l : lowest possible value
> +#   -m : maximum possible value
> +#   -d : default value
> +#   -N : allow negative numbers (implied by range including a negative)
> +#   -f : allow decimals (float)
> +
> +# For a unit-suffix, an initial colon indicates a unit that asserts the default
> +# otherwise, colons allow for descriptions, e.g:
> +
> +#   :s:seconds m:minutes h:hours
> +
> +# unit-suffixes are not sorted by the completion system when listed
> +# Specify them in order of magnitude, this tends to be ascending unless
> +# the default is of a higher magnitude, in which case, descending.
> +# So for, example
> +#   bytes kB MB GB
> +#   s ms us ns
> +# Where the compadd options include matching control or suffixes, these
> +# are applied to the units
> +
> +# For each unit-suffix, the format style is looked up with the
> +# unit-suffixes tag and the results concatenated. Specs used are:
> +#   x : the suffix
> +#   X : suffix description
> +#   d : indicate suffix is for the default unit
> +#   i : list index
> +#   r : reverse list index
> +# The latter three of these are useful with ternary expressions.
> +
> +# _description is called with the x token set to make the completed
> +# list of suffixes available to the normal format style
> +++ b/Doc/Zsh/compsys.yo
> @@ -4496,8 +4496,22 @@ not contain an explanation string to be displayed above the matches.
⋮
> @@ -4773,6 +4787,69 @@ checked.  If it is set completion is terminated at that point even if
>  no matches have been found.  This is the same effect as in the
>  tt(-first-) context.
>  )
> +findex(_numbers)
> +item(tt(_numbers) [ var(option) ... ] [ var(description) ] [ var(suffix) ... ])(
> +This can be used where a number is followed by a suffix to indicate the units.
> +The unit suffixes are completed and can also be included in the description
> +used when completion is invoked for the preceding number.
> +
> +In addition to common tt(compadd) options, tt(_numbers) accepts the following
> +options:
> +
> +startitem()
> +item(tt(-t) var(tag))(
> +Specify a tag to use instead of the default of tt(numbers).
> +)
> +item(tt(-u) var(units))(
> +Indicate the default units for the number, e.g. tt(bytes).
> +)
> +item(tt(-l) var(min))(
> +Specify the lowest possible value for the number.
> +)
> +item(tt(-m) var(max))(
> +Specify the highest possible value for the number.
> +)
> +item(tt(-d) var(default))(
> +Specify the default value.
> +)
> +item(tt(-N))(
> +Allow negative numbers.  This is implied if the range includes a negative.
> +)
> +item(tt(-f))(
> +Allow decimal numbers.
> +)
> +enditem()
> +
> +Where a particular suffix represents the default units for a number, it
> +should be prefixed with a colon.  Additionally, suffixes can be followed
> +by a colon and a description.  So for example, the following allows the
> +age of something to be specified, either in seconds or with an optional
> +suffix with a longer unit of time:
> +
> +example(_numbers -u seconds age :s:seconds m:minutes h:hours d:days)
> +
> +It is typically helpful for units to be presented in order of magnitude
> +when completed.  To facilitate this, the order in which they are given
> +is preserved.
> +
> +When the tt(format) style is looked up with the tt(descriptions) tag or
> +the tag specified with tt(-t), the list of suffixes is available as a
> +`tt(%x)' escape sequence. This is in addition to the usual sequences
> +documented under the tt(format) style. The form this list takes can also
> +be configured. To this end, the tt(format) style is first looked up with
> +the tag tt(unit-suffixes). The retrieved format is applied to each
> +suffix in turn and the results are then concatenated to form the
> +completed list. For the tt(unit-suffixes) format, `tt(%x)' expands to
> +the individual suffix and `tt(%X)' to its description. tt(%d)' indicates
> +a default suffix and can be used in a condition. The index and reverse
> +index are set in `tt(%i)' and `tt(%r)' respectively and are useful for
> +text included only with the first and last suffixes in the list. So for
> +example, the following joins the suffixes together as a comma-separated
> +list:
> +
> +example(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)')
> +)
> +
>  findex(_options)
>  item(tt(_options))(
>  This can be used to complete the names of shell options.  It provides a
>