GNU Info
(zsh.info)Special Parameters
Special Parameters
==================
Inside completion widgets, and any functions called from them, some
parameters have special meaning; outside these functions they are not
special to the shell in any way. These parameters are used to pass
information between the completion code and the completion widget. Some
of the builtin commands and the condition codes use or change the
current values of these parameters. Any existing values will be hidden
during execution of completion widgets; except for compstate, the
parameters are reset on each function exit (including nested function
calls from within the completion widget) to the values they had when
the function was entered.
CURRENT
This is the number of the current word, i.e. the word the cursor is
currently on in the words array. Note that this value is only
correct if the ksharrays option is not set.
IPREFIX
Initially this will be set to the empty string. This parameter
functions like PREFIX; it contains a string which precedes the one
in PREFIX and is not considered part of the list of matches.
Typically, a string is transferred from the beginning of PREFIX to
the end of IPREFIX, for example:
IPREFIX=${PREFIX%%\=*}=
PREFIX=${PREFIX#*=}
causes the part of the prefix up to and including the first equal
sign not to be treated as part of a matched string. This can be
done automatically by the compset builtin, see below.
ISUFFIX
As IPREFIX, but for a suffix that should not be considered part of
the matches; note that the ISUFFIX string follows the SUFFIX
string.
PREFIX
Initially this will be set to the part of the current word from the
beginning of the word up to the position of the cursor; it may be
altered to give a common prefix for all matches.
QIPREFIX
This parameter is read-only and contains the quoted string up to
the word being completed. E.g. when completing `"foo', this
parameter contains the double quote. If the -q option of compset
is used (see below), and the original string was `"foo bar' with
the cursor on the `bar', this parameter contains `"foo '.
QISUFFIX
Like QIPREFIX, but containing the suffix.
SUFFIX
Initially this will be set to the part of the current word from the
cursor position to the end; it may be altered to give a common
suffix for all matches. It is most useful when the option
COMPLETE_IN_WORD is set, as otherwise the whole word on the
command line is treated as a prefix.
compstate
This is an associative array with various keys and values that the
completion code uses to exchange information with the completion
widget. The keys are:
all_quotes
The -q option of the compset builtin command (see below)
allows a quoted string to be broken into separate words; if
the cursor is on one of those words, that word will be
completed, possibly invoking `compset -q' recursively. With
this key it is possible to test the types of quoted strings
which are currently broken into parts in this fashion. Its
value contains one character for each quoting level. The
characters are a single quote or a double quote for strings
quoted with these characters and a backslash for strings not
starting with a quote character. The first character in the
value always corresponds to the innermost quoting level.
context
This will be set by the completion code to the overall context
in which completion is attempted. Possible values are:
array_value
when completing inside the value of an array parameter
assignment; in this case the words array contains the
words inside the parentheses.
brace_parameter
when completing the name of a parameter in a parameter
expansion beginning with ${.
command
when completing for a normal command (either in command
position or for an argument of the command).
condition
when completing inside a `[[...]]' conditional
expression; in this case the words array contains only
the words inside the conditional expression.
math
when completing in a mathematical environment such as a
`((...))' construct.
parameter
when completing the name of a parameter in a parameter
expansion beginning with $ but not ${.
redirect
when completing after a redirection operator.
subscript
when completing inside a parameter subscript.
value
when completing the value of a parameter assignment.
exact
Controls the behaviour when the REC_EXACT option is set. It
will be set to accept if an exact match would be accepted,
and will be unset otherwise.
If it was set when at least one match equal to the string on
the line was generated, the match is accepted.
exact_string
The string of an exact match if one was found, otherwise
unset.
ignored
The number of words that were ignored because they matched
one of the patterns given with the -F option to the compadd
builtin command.
insert
This controls the manner in which a match is inserted into
the command line. On entry to the widget function, if it is
unset the command line is not to be changed; if set to
unambiguous, any prefix common to all matches is to be
inserted; if set to automenu-unambiguous, the common prefix
is to be inserted and the next invocation of the completion
code may start menu completion (due to the AUTO_MENU option
being set); if set to menu or automenu menu completion will
be started for the matches currently generated (in the latter
case this will happen because the AUTO_MENU is set). The
value may also contain the string `tab' when the completion
code would normally not really do completion, but only insert
the TAB character.
On exit it may be set to any of the values above (where
setting it to the empty string is the same as unsetting it),
or to a number, in which case the match whose number is given
will be inserted into the command line. Negative numbers
count backward from the last match (with `-1' selecting the
last match) and out-of-range values are wrapped around, so
that a value of zero selects the last match and a value one
more than the maximum selects the first. Unless the value of
this key ends in a space, the match is inserted as in a menu
completion, i.e. without automatically appending a space.
Both menu and automenu may also specify the the number of the
match to insert, given after a colon. For example, `menu:2'
says to start menu completion, beginning with the second
match.
Note that a value containing the substring `tab' makes the
matches generated be ignored and only the TAB be inserted.
Finally, it may also be set to all, which makes all matches
generated be inserted into the line.
insert_positions
When the completion system inserts an unambiguous string into
the line, there may be multiple places where characters are
missing or where the character inserted differs from at least
one match. The value of this key contains a colon separated
list of all these positions, as indexes into the command line.
last_prompt
If this is set to a non-empty string for every match added,
the completion code will move the cursor back to the previous
prompt after the list of completions has been displayed.
Initially this is set or unset according to the
ALWAYS_LAST_PROMPT option.
list
This controls whether or how the list of matches will be
displayed. If it is unset or empty they will never be
listed; if its value begins with list, they will always be
listed; if it begins with autolist or ambiguous, they will be
listed when the AUTO_LIST or LIST_AMBIGUOUS options
respectively would normally cause them to be.
If the substring force appears in the value, this makes the
list be shown even if there is only one match. Normally, the
list would be shown only if there are at least two matches.
The value contains the substring packed if the LIST_PACKED
option is set. If this substring is given for all matches
added to a group, this group will show the LIST_PACKED
behavior. The same is done for the LIST_ROWS_FIRST option
with the substring rows.
Finally, if the value contains the string explanations, only
the explanation strings, if any, will be listed and if it
contains messages, only the messages (added with the -x
option of compadd) will be listed. If it contains both
explanations and messages both kinds of explanation strings
will be listed. It will be set appropriately on entry to a
completion widget and may be changed there.
list_lines
This gives the number of lines that are needed to display the
full list of completions. Note that to calculate the total
number of lines to display you need to add the number of
lines needed for the command line to this value, this is
available as the value of the BUFFERLINES special parameter.
list_max
Initially this is set to the value of the LISTMAX parameter.
It may be set to any other value; when the widget exits this
value will be used in the same way as the value of LISTMAX.
nmatches
The number of matches generated and accepted by the
completion code so far.
old_insert
On entry to the widget this will be set to the number of the
match of an old list of completions that is currently
inserted into the command line. If no match has been
inserted, this is unset.
As with old_list, the value of this key will only be used if
it is the string keep. If it was set to this value by the
widget and there was an old match inserted into the command
line, this match will be kept and if the value of the insert
key specifies that another match should be inserted, this
will be inserted after the old one.
old_list
This is set to yes if there is still a valid list of
completions from a previous completion at the time the widget
is invoked. This will usually be the case if and only if the
previous editing operation was a completion widget or one of
the builtin completion functions. If there is a valid list
and it is also currently shown on the screen, the value of
this key is shown.
After the widget has exited the value of this key is only
used if it was set to keep. In this case the completion code
will continue to use this old list. If the widget generated
new matches, they will not be used.
parameter
The name of the parameter when completing in a subscript or
in the value of a parameter assignment.
pattern_insert
Normally this is set to menu, which specifies that menu
completion will be used whenever a set of matches was
generated using pattern matching. If it is set to any other
non-empty string by the user and menu completion is not
selected by other option settings, the code will instead
insert any common prefix for the generated matches as with
normal completion.
pattern_match
Locally controls the behaviour given by the GLOB_COMPLETE
option. Initially it is set to `*' if and only if the option
is set. The completion widget may set it to this value, to
an empty string (which has the same effect as unsetting it),
or to any other non-empty string. If it is non-empty,
unquoted metacharacters on the command line will be treated
as patterns; if it is `*', then additionally a wildcard `*'
is assumed at the cursor position; if it is empty or unset,
metacharacters will be treated literally.
Note that the matcher specifications given to the compadd
builtin command are not used if this is set to a non-empty
string.
quote
When completing inside quotes, this contains the quotation
character (i.e. either a single quote, a double quote, or a
backtick). Otherwise it is unset.
quoting
When completing inside single quotes, this is set to the
string single; inside double quotes, the string double;
inside backticks, the string backtick. Otherwise it is unset.
redirect
The redirection operator when completing in a redirection
position, i.e. one of <, >, etc.
restore
This is set to auto before a function is entered, which
forces the special parameters mentioned above (words,
CURRENT, PREFIX, IPREFIX, SUFFIX, and ISUFFIX) to be restored
to their previous values when the function exits. If a
function unsets it or sets it to any other string, they will
not be restored.
to_end
Specifies the occasions on which the cursor is moved to the
end of a string when a match is inserted. On entry to a
widget function, it may be single if this will happen when a
single unambiguous match was inserted or match if it will
happen any time a match is inserted (for example, by menu
completion; this is likely to be the effect of the
ALWAYS_TO_END option).
On exit, it may be set to single as above. It may also be
set to always, or to the empty string or unset; in those
cases the cursor will be moved to the end of the string
always or never respectively. Any other string is treated as
match.
unambiguous
This key is read-only and will always be set to the common
(unambiguous) prefix the completion code has generated for
all matches added so far.
unambiguous_cursor
This gives the position the cursor would be placed at if the
common prefix in the unambiguous key were inserted, relative
to the value of that key. The cursor would be placed before
the character whose index is given by this key.
unambiguous_positions
This contains all positions where characters in the
unambiguous string are missing or where the character
inserted differs from at least one of the matches. The
positions are given as indexes into the string given by the
value of the unambiguous key.
vared
If completion is called while editing a line using the vared
builtin, the value of this key is set to the name of the
parameter given as an argument to vared. This key is only
set while a vared command is active.
words
This array contains the words present on the command line
currently being edited.
automatically generated by info2www version 1.2.2.9