Zsh Mailing List Archive
Messages sorted by:
Re: PATCH: list units in brackets at the end of completion group descriptions
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?
> +++ b/Completion/Base/Utility/_numbers
> @@ -0,0 +1,87 @@
> +# 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.
> +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
> +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.
> +Allow negative numbers. This is implied if the range includes a negative.
> +Allow decimal numbers.
> +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
> +example(zstyle ':completion:*:unit-suffixes' format '%x%(r::,)')
> This can be used to complete the names of shell options. It provides a
Messages sorted by: