texinode(Completion Widgets)(Zsh Modules)(Programmable Completion)(Top)
chapter(Completion Widgets)
cindex(completion, widgets)
cindex(completion, programmable)
cindex(completion, controlling)
sect(Description)
Completion widgets are defined using the tt(-C) option to the tt(zle)
builtin command provided by the tt(zle) module (see
ifzman(zmanref(zshzle))\
ifnzman(noderef(The zle Module))\
). For example, the invocation:

indent(nofill(
tt(zle -C complete expand-or-complete completer)))

defines a widget named tt(complete). If this widget is bound to a key
using the tt(bindkey) builtin command defined in the tt(zle) module
(see 
ifzman(zmanref(zshzle))\
ifnzman(noderef(Zsh Line Editor))\
) typing that key will make the completion code call the shell
function tt(completer). This function is responsible for generating
the possible matches using the builtins described below. Once the
function returns, the completion code takes over control again and
treats the matches the way the builtin widget tt(expand-or-complete)
would do it. For this second argument, the name of any of the builtin
widgets that handle completions can be given, i.e. it may be any of
tt(complete-word), tt(expand-or-complete),
tt(expand-or-complete-prefix), tt(menu-complete),
tt(menu-expand-or-complete), tt(reverse-menu-complete),
tt(list-choices), or tt(delete-char-or-list).

startmenu()
menu(Special Parameters)
menu(Builtin Commands)
menu(Condition Codes)
menu(Examples)
endmenu()

texinode(Special Parameters)(Builtin Commands)()(Completion Widgets)
sect(Special Parameters)

Inside completion widgets some parameters have special meaning. They
will be used inside the widget function and other shell functions
called from it. Outside of these function they are not special to the
shell in any way.

The parameters are used to give information about the internal state
from the completion code to the completion widget and can be set to
give information to the completion code from the completion
widget. Some of the builtin commands and the condition codes use or
change the current values of these parameters. While the completion
widget is active, these parameters are reset on each function exit to
the values they had when the function was entered.

startitem()
item(tt(words))(
This array contains the words from the line.
)
item(tt(CURRENT))(
This is the number of the current word, i.e. the word the cursor is
currently on in the tt(words) array. Note that this value is only
correct, if the tt(ksharrays) options is not set.
)
item(tt(PREFIX))(
This should be set to that part of the current word that should be
taken as the string every possible match has to begin with. 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. When 
)
item(tt(IPREFIX))(
When a part of the current word should not be considered part of the
matches, this part should be taken from the tt(PREFIX) parameter and
appended to this parameter. This will initially be set to the empty
string when called from the completion code.
)
item(tt(SUFFIX))(
This should be set to that part of the current word that should be
taken as the string every possible match has to end with. The
completion code sets this to the part of the current word from the
cursor position to the end.
)
item(tt(ISUFFIX))(
Like tt(IPREFIX), but for a suffix that should not be considered part
of the matches.
)
item(tt(compstate))(
This is an associative array with various keys and values the
completion uses to give informtaion to the completion widget and to
get information regarding the further processing from it. The keys
are:

startitem()
item(tt(context))(
This will be set by the completion code to the overall context
completion is attempted in. Possible values are:

startitem()
item(tt(command))(
when completing for a normal command (in a command position or for an
argument)
)
item(tt(redirect))(
when completing after a redirection operator
)
item(tt(condition))(
when completing inside a `tt([[)...tt(]])' conditional expressing; in
this case the tt(words) array contains the words inside the
conditional expression
)
item(tt(math))(
when completing in a mathematical environment such as a
`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct
)
item(tt(value))(
when completing the value of a parameter assignment
)
item(tt(array_value))(
when completing inside the value of an array parameter assignment; in
this case the tt(words) array contains the words inside the parentheses
)
item(tt(subscript))(
when completing inside a parameter subscript
)
item(tt(parameter))(
when the name of a parameter in a parameter expansion
)
item(tt(brace_parameter))(
when the name of a parameter in a parameter expansion that started
with tt(${)
)
enditem()
)
item(tt(parameter))(
The name of the parameter when completing in a subscript or in the
value of a parameter assignment.
)
item(tt(redirect))(
The redirection operator when completing in a redirection position.
)
item(tt(quoting))(
If completion is done inside single quotes, this is set to the string
tt(single). When completing inside double quotes this is set to
tt(double). When completing inside backticks it is set to tt(backtick).
Otherwise it is unset.
)
item(tt(quote))(
When completing inside quotes, this contains the quotation character
(i.e. either a single quote, a double quote, or a backtick).
)
item(tt(nmatches))(
This is always set to the number of matches generated and accepted by
the completion code so far.
)
item(tt(matcher))(
When completion is used with a global match specification (i.e. a
tt(compctl) with only a tt(-M) option), this contains the
number of the specification string which is currently used.
)
item(tt(matcher_string))(
This is set to the global match specification string currently used.
)
item(tt(total_matchers))(
The total number of global match specifications.
)
item(tt(restore))(
This is set to tt(auto) before a function is entered. If a function
unsets it or sets it to any other string, the special parameters
mentioned above (tt(words), tt(CURRENT), tt(PREFIX), tt(IPREFIX), and
tt(SUFFIX)) will not be restored to their previous values when the
function exits as is normally done.
)
item(tt(list))(
On entry to the completion widget this will be unset, if the set of
matches generated will not be listed. It is set to tt(list),
tt(autolist), or tt(ambiguous) if the matches will always be listed,
if they will be listed due to tt(AUTO_LIST) being set, or if they will 
be listed if there is no unambiguous string to insert and
tt(LIST_AMBIGUOUS) is set, respectively. Inside the completion widget
it may be set to any of these values to make the completion code as if 
the appropriate options had been set.
)
item(tt(force_list))(
If the value for the tt(list) key is tt(ambiguous), the list will
normally be shown only if there are at least two matches in the
list. Setting tt(force_list) to an non-empty string makes the list be
shown even if there is only one match.
)
item(tt(list_max))(
Initially this is set to the value of the tt(LISTMAX) parameter.
Completion widgets may set it to any other numeric value and the value 
stored at when the widget finishes will be used in the same way the
value of tt(LISTMAX) is used.
)
item(tt(last_prompt))(
If this is set to an non-empty string, the completion code will move
the cursor back to the previous prompt after the list of completions
has been displayed. Initially this is set depending on the setting of
the tt(ALWAYS_LAST_PROMPT) option.
)
item(tt(insert))(
This will be unset by the completon code if the contents of the
command line will not be changed. It is set to tt(unambiguous),
tt(menu), or tt(automenu) if a common unambiguous string will be
inserted or if the first match will be inserted and menu completion
will be started (due to tt(MENU_COMPLETE) or tt(AUTO_MENU) being set), 
respectively.

On exit it may be set to any of the values above with the obvious
result or to a number or a string of the form
`var(group):var(match)'. If it is set to a number the match whose
number is given will be inserted in the command line. A string like
`tt(2:4)' specifies which match from which group should be
inserted. In this example the fourth match of the second group is
inserted. All groups and matches are number from one upwards. In the
value of this key, negative numbers count backward from the last match 
or group (with `tt(-1)' selecting the last match or group) and values
out of the range from one to the number of matches or groups are
wrapped around (so that a value of zero selects the last match and a
value equal to the number of matches or groups plus one selects the
first one).
)
item(tt(to_end))(
On entry to the completion widget this is set to tt(single) if the
cursor would be moved to the end of the word only if completion
generated only one match and that is inserted into the line. Depending 
on the original position of the cursor and the setting of the option
tt(ALWAYS_TO_END) this may also be set to the string tt(match) if the
cursor would be moved to the end if a whole match would be inserted
(either if there is only one match or if menucompletion is used).

The value of this key after the completion widget exits will be used
to determin when the cursor will be moved to the end of the string
inserted into the line. If it is unset or set to the empty string, the 
cursor will never be moved to the end. If it is set to tt(single), it
will be moved to the end only if completion generated only one
match. A value of tt(always) says to move the cursor always to the end 
(even with normal completion when an unambiguous string is inserted),
and any other value says to move the cursor to the end when a full
match is inserted (a single match or the first match when using
menucompletion).
)
item(tt(old_list))(
This is set to tt(yes) if there is still a valid list of completions
from a previous completion at the time the widget is invoked. Such a
list exists if it was generated by the previous key press. If the list 
is also shown on the screen, the value of this key is tt(shown).

After the widget has exited the value of this key is only used if it
was set to tt(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.
)
item(tt(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 in the command
line. If no match has been inserted, this is unset.

As with tt(old_list), the value of this key will only be used if it is 
the string tt(keep). If it was set to this value by the widget and
there was an old match inserted in the line, this match will be kept
and if the value of the tt(insert) key says that another match should
be inserted, this will be inserted after the old one.
)
item(tt(exact))(
This is set to tt(accept) if an exact match would be accepted by the
completion code due to tt(REC_EXACT) being set or it is unset if an
exact match would not be accepted.
)
item(tt(exact_string))(
This is set to the string of an exact match if one was found and unset 
otherwise.
)
item(tt(pattern_match))(
If the option tt(GLOB_COMPLETE) is set, this is initially set to
`tt(*)' and unset otherwise. If the completion widget sets it to a
`tt(*)', the completion code will from then on behave as if
tt(GLOB_COMPLETE) is set, i.e. if the strings in tt(PREFIX) and
tt(SUFFIX) contain unquoted metacharacters, they will be treated as
patterns. If the string is set to any other non-empty string, the
strings will be treated as patterns but the code will not automatically
insert a star at the cursor position.
)
item(tt(pattern_insert))(
Normally this is set to tt(menu) which means that menu-completion will be
used whenever the matches were generated using pattern matching. If this
is set to any other non-empty string by the user and menu-completion is
not selected by other option settings, the code will insert an
unambiguous string for the generated matches as with normal completion.
)
item(tt(unambiguous))(
This key is read-only and will always be set to the unambiguous string
the completion code has generated for all matches added so far.
)
item(tt(unambiguous_cursor))(
This gives the position the cursor would be placed at when the
unambiguous string would be inserted, relative to the value of the
tt(unambiguous) key. The cursor would be placed before the character
whise index is given by this key.
)
enditem()
)
enditem()

texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
sect(Builtin Commands)
startitem()
findex(compgen)
item(tt(compgen) var(flags ...))(

Generate matches according to the given var(flags) which can be any of 
the option flags supported by the tt(compctl) builtin command (see
ifzman(zmanref(zshcompctl))\
ifnzman(noderef(Programmable Completion))\
) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K)
flag, the function given as argument to it can not access the command
line with the tt(read) builtin command.

The matches will be generated in the same way as if the completion code
generated them directly from a tt(compctl)-definition with the same
flags. The completion code will consider only those matches as
possible completions that match the prefix and suffix from the special 
parameters desribed above. These strings will be compared with the
generated matches using the normal matching rules and any matching
specifications given with the tt(-M) flag to tt(compgen) and the
global matching specifications given to the tt(compctl) builtin
command.

The return value can be used to test if matches were added. It is zero 
if at least one match was added and non-zero otherwise.
)
xitem(tt(compadd) [ tt(-qQfnUam) ] [ tt(-F) var(array) ])
xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
xitem([ tt(-W) var(file-prefix) ])
xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
item([ tt(--) ] [ var(words) ... ])(

This builtin command can be used to add matches and directly control
all the information the completion code stores with each possible
match. The return value is zero if at least one match was added and
non-zero if no matches were added.

The completion code breaks the string to complete into six fields in
the order: 

indent(
var(<ipre><apre><hpre><word><hsuf><asuf><isuf>)
)

The first field
is an ignored prefix taken from the line, the contents of the
tt(IPREFIX) parameter plus the string given with the tt(-i)
option. With the tt(-U) option given, only the string from the tt(-i)
option is used. The field var(<apre>) is a optional prefix string that 
should automatically be added by the completion code, this is what can 
be gievn with the tt(-P) option. The var(<hpre>) field is a string
that is considered part of the match but that should not be shown when 
listing completions, it is given with the tt(-p) option. E.g. for
functions that do filename generation, one might want to use this for
a common path prefix. var(<word>) is the part of the match that should 
appear in the list of completions, one of the tt(words) given at the
end. The field var(<hsuf>) is like var(<hpre>) but gives a suffix that 
should be matched but will not be listed. Finally, var(<asuf>) is the
suffix given with tt(-S) that should automatically be added by the
completion code and var(<isuf>) is like var(<ipre>), but taken from
the tt(ISUFFIX) parameter and the tt(-I) option.

The supported flags are:

startitem()
item(tt(-P) var(prefix))(
The same as for tt(compctl) and tt(compgen), it gives a string that
should be inserted before the given words when they are completed. The
string given is not considered to be part of the match.
)
item(tt(-S) var(suffix))(
Like tt(-P) but gives a string that has to be inserted after the match.
)
item(tt(-p) var(hidden-prefix))(
This gives a string that should be inserted in the line before the
match but that should not appear in the list of matches. Unless the
tt(-U) option is given, the string on the line has to match this
string.
)
item(tt(-s) var(hidden-suffix))(
Like `tt(-p)', but gives a string to insert after the match.
)
item(tt(-i) var(ignored-prefix))(
This gives a string to insert into the command line just before any
string given with the `tt(-P)' option. Without `tt(-P)' the string is
inserted before the string given with `tt(-p)' or directly before the
match.
)
item(tt(-I) var(ignored-suffix))(
Like tt(-i), but gives an ignored suffix.
)
item(tt(-J) var(name))(
As for tt(compctl) and tt(compgen) this gives the name of the group
of matches the words should be stored in.
)
item(tt(-V) var(name))(
Like tt(-J) but naming a unsorted group.
)
item(tt(-X) var(explanation))(
The var(explanation) string will be printed with the list of matches,
as for tt(compctl -X).
)
item(tt(-q))(
This flag has the same meaning as for tt(compctl) and tt(compgen),
too. It makes the suffix given with tt(-S) be automatically removed if 
the next character typed is a blank or does not insert anything or if
the suffix consists of only one character and the next character typed 
is the same character.
)
item(tt(-r) var(remove-chars))(
This makes the suffix given with tt(-S) be automatically removed if
the next character typed inserts one of the characters given in the
var(remove-chars). This string is parsed as a characters class with
the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")'
removes the suffix if the next character typed inserts one of the
lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if 
the next character typed inserts anything but a digit. One extra
backslash sequence is understood in this string: `tt(\-)' stands for
all characters that insert nothing. Thus `tt(-S "=" -q)' is the same
as `tt(-S "=" -r "= \t\n\-")'.
)
item(tt(-R) var(remove-func))(
For the cases where one wants to remove suffix and the tt(-r) option
does not give enough control, this option can be used. It stores the
name of the shell function var(remove-func) in the matches. If one of
the matches is finally accepted and the tt(-S)-suffix inserted, this
function will be called after the next character typed. It gets the
length of the suffix as its argument and can use the special
parameters available in zle widgets (see
ifzman(zmanref(zshzle))\
ifnzman(noderef(Zsh Line Editor))\
) to analyse and modify the command line.
)
item(tt(-f))(
If this flag is given, the matches build are marked as being the names 
of files. They need not be actual filenames, though. But if they are
and the option tt(LIST_TYPES) is set, the characters describing the
types of the files in the completion lists will be shown. This also
makes a slash automatically be added when the name of a directory is
completed.
)
item(tt(-W) var(file-prefix))(
This option has the same meaning as for the tt(compctl) and
tt(compgen) builtin commands. Here, however, only one string may be
given, not an array. This string is used as a pathname that will be
prepended to the given words and the prefix given with the tt(-p)
option to perform the file-tests when showing completion
listings. Hence it is only useful if combined with the tt(-f) flag,
since the tests will only be performed if that flag is given.
)
item(tt(-a))(
When used by tt(compctl) or tt(compgen) the completion code normally
builds two sets of matches: the normal one where words with one of the 
suffixes in the array parameter tt(fignore) are not considered
possible matches, and the alternate set where the words excluded
from the first set are stored. Normally only the matches in the first
set are used. But if this set is empty, the words from the alternate
set are used.

The tt(compadd) builtin does not use tt(fignore) parameter and
normally stores all words in the first set. With the tt(-a)-flag
given, however, they are all stored in the alternate set unless this
flag is overridden by the tt(-F) option.
)
item(tt(-F) var(array))(
This can be used to give an array containing suffixes like the
tt(fignore) parameter. Words with one of these suffixes are stored in
the alternate set of matches and words without one of these suffixes
are stored in the normal set.

The var(array) may be the name of an array parameter or a list of
literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If
the name of an array is given, the elements of the array are taken as
the suffixes.
)
item(tt(-Q))(
As for tt(compctl) and tt(compgen) this flag instructs the completion 
code not to quote any metacharacters in the words when inserting them
in the command line.
)
item(tt(-M) var(match-spec))(
This option allows one to give local match specifications with the
same meaning and format as for the tt(compctl) and tt(compgen)
builtin commands. Note that they will only be used if the tt(-m) is
given, too.
)
item(tt(-n))(
Words added with tt(compadd) with this flag will be used as possible
matches as usual but they not appear in the completion listing.
)
item(tt(-U))(
If this flag is given, all words given will be accepted, no matching
will be done by the completion code. Normally this is used in
functions that do the matching themselves.

Note that with tt(compadd) this option does not automatically turn on
menu completion if tt(AUTO_LIST) is set as the same options for the
tt(compctl) and tt(compgen) builtin command do.
)
item(tt(-O) var(array))(
If this option is given, the var(words) are em(not) added to the set of
possible completions. Instead, matching is done as usual and all
var(words) given as arguments that are matched will be stored in the
array parameter whose name is given as var(array).
)
item(tt(-A) var(array))(
Like the tt(-O) option this keeps the var(words) from being stored as
possible completions. The matching words are instead stored in the array
parameter given as var(array). In difference to the tt(-O) option this
does not store the unchanged var(words) given as arguments, but instead
the strings the completion code generated while matching. For example,
with a matching specification of `tt(-M "L:|no=")', the string `tt(nof)'
on the line and the string `tt(foo)' as one of the var(words), this option
will make the string `tt(nofoo)' be stored in the array, whereas the tt(-O)
option stores the `tt(foo)' originally given.
)
item(tt(-), tt(--))(
This flag ends the list of flags and options. All arguments after it
will be taken as the words to use as matches even if they begin with
hyphens.
)
enditem()
)
xitem(tt(compset -p) var(number))
xitem(tt(compset -P) [ var(number) ] var(pattern))
xitem(tt(compset -s) var(number))
xitem(tt(compset -S) [ var(number) ] var(pattern))
xitem(tt(compset -n) var(begin) [ var(end) ])
item(tt(compset -p) var(beg-pat) [ var(end-pat) ])(
This builtin allows to easily modify the special parameters and at
the same time, to do tests on their values.

The options are:

startitem()
item(tt(-p) var(number))(
If the contents of the tt(PREFIX) parameter is longer than var(number)
characters, the first var(number) characters are removed from it and
appended to the contents of the tt(IPREFIX) parameter.
)
item(tt(-P) [ var(number) ] var(pattern))(
If the value of the tt(PREFIX) parameter begins with anything that
matches the var(pattern), the matched portion is removed from
tt(PREFIX) and appended to tt(IPREFIX).

Without the optional var(number), the longest match is taken, but
if var(number) is given, anything up to the var(number)'th match is
moved. If the var(number) is negative, the var(number)'th longest
match is moved. For example, if tt(PREFIX) contains the string
`tt(a=b=c)' doing tt(compset -P '*\=') will move the string `tt(a=b=)' 
into the tt(IPREFIX) parameter, but tt(compset -P 1 '*\=') moves only
the string `tt(a=)'.
)
item(tt(-s) var(number))(
Like tt(-p), but prepend the last var(number) characters from the
parameter tt(SUFFIX) to the contents of the parameter tt(ISUFFIX).
)
item(tt(-S) [ var(number) ] var(pattern))(
Like tt(-P), but matching from the end of tt(SUFFIX) and moving the
matched portion into the parameter tt(ISUFFIX).
)
item(tt(-n) var(begin) [ var(end) ])(
If the current word position as specified by the parameter tt(CURRENT) 
is greater than or equal to var(begin), anything up to the
var(begin)'th word is removed from the tt(words) array and the value
of the parameter tt(CURRENT) is decremented by var(begin).

If the optional var(end) is given, the modification is done only if
the current word position is also less than or equal to var(end). In
this case, the words from position var(end) onwards are removed from
the tt(words) array, too.

Both of these numbers may be negative to make them count backwards
from the last element of the tt(words) array.
)
item(tt(-N) var(beg-pat) [ var(end-pat) ])(
If one of the elements of the tt(words) array up to the one at the
index given by the value of the parameter tt(CURRENT) matches the
pattern var(beg-pat), all elements up to the matching one are removed
from the tt(words) array and the value of tt(CURRENT) is changed to
point to the same word in the changed array.

If the optional pattern var(end-pat) is also given and there is an
element in the tt(words) array matching this pattern, the parameters
are modified only if the index of this word is higher than the one
given by the tt(CURRENT) parameter (meaning that the matching word has 
to be after the cursor). In this case, the words from the word
matching tt(end-pat) onwards are also removed from the tt(words)
array. If tt(words) contains no word matching var(end-pat), the
testing and modification is done as if it were not given.
)
enditem()

In all of these cases the return value is zero if the test succeded
and the parameters were modified, and non-zero otherwise. This allows
one to use this builtin in tests as in:

indent(
tt(if compset -P '*\='; then ...)
)

Which makes anything up to and including the last equal sign be
ignored by the completion code.
)
item(tt(compcall) [ tt(-TD) ])(

This allows one to use completion definitions given with the
tt(compctl) builtin from within completion widgets. It makes the
completion code complete the current word according to the
tt(compctl)s defined. Normally only tt(compctl)s given for specific
commands are used. To make the code use the completion flags given to
the tt(-T) option of tt(compctl), one can give the tt(-T) flag to
tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
default completion flags given to tt(compctl) with the tt(-D) option
be used.

The return value can be used to test if a matching tt(compctl)
definition was found. It is non-zero if a tt(compctl) was found and
zero otherwise.
)
enditem()

texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
sect(Condition Codes)

Inside completion widgets not only the builtin commands described
above can be used, but also some additional condition codes. These
work on the special parameters and can be used to easily build
completion functions that generate different matches depending on the
strings on the line. All of these condition codes perform tests also
done by the tt(compset) builtin, but they don't modify the contents of 
the special parameters.

The following condition codes are made available inside completion
widgets:

startitem()
item(tt(-prefix) [ var(number) ] var(pattern))(
true if the test for the tt(-P) option of tt(compset) would succeed
)
item(tt(-suffix) [ var(number) ] var(pattern))(
true if the test for the tt(-S) option of tt(compset) would succeed
)
item(tt(-after) var(beg-pat))(
true if the test of the tt(-N) option with only the var(beg-pat) given 
would succeed
)
item(tt(-between) var(beg-pat end-pat))(
true if the test for the tt(-N) option with both patterns would succeed
)
enditem()

texinode(Examples)()(Condition Codes)(Completion Widgets)
sect(Examples)

The first step is to define the widget:

indent(nofill(
tt(zle -C complete complete-word complete-history)))

Then the widget can be bound to a key using the tt(bindkey) builtin
command:

indent(nofill(
tt(bindkey '^X\t' complete)))

After that the shell function tt(complete-history) will be invoked
after typing control-X and TAB. The function should then generte the
matches, e.g.:

indent(nofill(
tt(complete-history LPAR()RPAR() { compgen -H 0 '' })))

In this the function will complete words from the history matching the 
current word.

For a description of the example completion system from the
distributions, see
ifzman(zmanref(zshcompsys))\
ifnzman(noderef(Completion System))\
.