diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/compctl.yo | 3 | ||||
| -rw-r--r-- | Doc/Zsh/compsys.yo | 691 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 94 | ||||
| -rw-r--r-- | Doc/Zsh/guide.yo | 1 | ||||
| -rw-r--r-- | Doc/Zsh/intro.yo | 1 | ||||
| -rw-r--r-- | Doc/Zsh/modules.yo | 2 | ||||
| -rw-r--r-- | Doc/Zsh/seealso.yo | 1 | ||||
| -rw-r--r-- | Doc/Zsh/zle.yo | 6 |
8 files changed, 796 insertions, 3 deletions
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo index f494ec5f9..7b672dd68 100644 --- a/Doc/Zsh/compctl.yo +++ b/Doc/Zsh/compctl.yo @@ -449,7 +449,8 @@ be shown if there was at least one match added for the explanation string. The sequences tt(%B), tt(%b), tt(%S), tt(%s), tt(%U), and tt(%u) specify -output attributes (bold, standout, and underline) as in prompts. +output attributes (bold, standout, and underline) and tt(%{...%}) can +be used to include literal escape sequences as in prompts. ) item(tt(-Y) var(explanation))( Identical to tt(-X), except that the var(explanation) first undergoes diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo new file mode 100644 index 000000000..632cb3195 --- /dev/null +++ b/Doc/Zsh/compsys.yo @@ -0,0 +1,691 @@ +texinode(Completion System)()(Zsh Modules)(Top) +chapter(Completion System) +cindex(completion, system) +cindex(completion, programmable) +cindex(completion, controlling) +sect(Description) + +This describes the shell code for the new completion system. It consists +of two scripts and a few other files that define shell functions. +The shell functions which implement completion behaviour and which may +be bound to keystrokes, are referred to as `widgets'. All are contained +in the following subdirectories of the tt(Completion) directory of the main +distribution directory. + +startitem() +item(tt(Core))( +The core scripts and functions. You will certainly need these, though will +probably not need to alter them. The contents of this directory is +described in more detail below. +) +item(tt(Base))( +Other functions you will almost certainly want if you are going to use +any of the standard completion functions. You may want to edit some of +these files. +) +item(tt(Builtins))( +Functions for completing arguments of shell builtin commands. +) +item(tt(User))( +Functions for completing arguments of external commands and suites of +commands. They may need modifying for your system. +) +item(tt(Commands))( +Functions which implement special types of completion to be bound to +keystrokes rather than called by context. +) +enditem() + +You should decide which files you will be using and copy them to a +directory (or multiple directories) of your own which should appear in your +tt($fpath) variable so that the functions can be autoloaded. + +startmenu() +menu(Initialisation) +menu(Control Functions) +menu(Completion Functions) +endmenu() + +texinode(Initialisation)(Control Functions)()(Completion System) +sect(Initialisation) + +To initialise the system, the script tt(compinit) should be sourced with +`tt(source )var(<path>)tt(/compinit)' or +`tt(. )var(<path>)tt(/compinit)'. This will define a few utility functions, +arrange for all the necessary shell functions to be autoloaded, and will +then re-bind all keys that do completion to use the new system. + +subsect(Arguments) + +To speed up the running of tt(compinit), it can be made to produce a dumped +configuration which will be read in on future invocations. The easiest way +to do this is by adding the option tt(-d) whenever tt(compinit) is sourced. +In this case the dumped file will have the same name as the sourced file, +but with tt(.dump) appended to the end; alternatively, an explicit file +name can be given following the tt(-d). On the next call to tt(compinit +-d), the dumped file will be read instead. + +If the number of completion files changes, tt(compinit) will recognise this +and produce a new dump file. However, if the name of a function or the +arguments in the first line of a tt(#compdef) funcion (as described below) +change, it is easiest to delete the dump file by hand so that the next time +tt(compinit) will re-create it. + +The dumping is actually done by another script, tt(compdump), but you will +only need to source this yourself if you change the configuration +(e.g. using tt(compdef)) and then want to dump the new one. The name of +the old dumped file will be remembered for this. + +subsect(Autoloaded files) + +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the tt(fpath/FPATH) +parameter must contain the directory in which they are stored. When +tt(compinit) is sourced, it searches all such files accessible via +tt(fpath/FPATH) and reads the first line of each of them. This line should +contain one of the tags described below. Files whose first line does not +start with one of these tags are not considered to be part of the +completion system and will not be treated specially. + +The tags are: + +startitem() +item(tt(#compdef) var(names...))( +The file will be made autoloadable and the function defined +in it will be called when completing var(names), each of which is +either the name of a command whose arguments are to be completed or one of +a number of special contexts in the form tt(-)var(context)tt(-) described +below for the tt(_complete) function. +) +item(tt(#compdef -p) var(pattern))( +The file will be made autoloadable and the function defined in it will be +called when completing for a command whose name matches the given +var(pattern) (a standard globbing pattern). Note that only one +var(pattern) may be given. +) +item(tt(#compdef -k) var(style key-sequences...))( +This can be used bind special completion functions to the +var(key-sequences). It creates a widget behaving like the builtin widget +var(style), which must be one of those that perform completion, namely +tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete), +tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete), +tt(menu-expand-or-complete), or tt(reverse-menu-complete). + +The widget is then bound to all the var(key-sequences) given, if any: when +one of the var(key-sequences) is typed, the function in the file will +be invoked to generate the matches. The widget created has the same +name as the file and can also be bound to other keys using tt(bindkey) +as usual. +) +item(tt(#autoload))( +This is used for files defining utility function that are not to be +called directly as completion functions but should be loaded automatically +when invoked. Typically they are to be called from within one of the +completion functions. +) +enditem() + +Note that the tt(#) is part of the tag name and no white space is allowed +after it. The tt(#compdef) tags use the tt(compdef) function defined +below; the main difference is that the name of the function is supplied +implicitly. + +subsect(Functions) + +The tt(compinit) file defines the following functions, which may +also be called directly by the user. + +startitem() +xitem(tt(compdef) [ tt(-an) ] var(function names...)) +xitem(tt(compdef -d) var(names...)) +xitem(tt(compdef -p) [ tt(-a) ] var(function pattern)) +item(tt(compdef -k) [ tt(-a) ] var(function style key-sequences...))( +The first form tells the completion system to call the given +var(function) when completing for the contexts or commands +whose var(names) are given: this is like the tt(#compdef) tag. If the +tt(-n) option is given, any existing completion behaviour for particular +contexts or commands will not be altered. These definitions can be deleted +by giving the tt(-d) option as in the second form. + +The third form is similar to the first, but var(function) will be called +for all commands whose name matches the var(pattern); this is like the +tt(#compdef -p) function tag. + +The fourth form defines a widget with the same name as the var(function) +which will be called for each of the var(key-sequences); this is like the +tt(#compdef -k) tag. The function should generate the completions needed +and will otherwise behave like the builtin widget whose name is given as +the var(style) argument. The widgets usable for this are: +tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete), +tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete), +tt(menu-expand-or-complete), and tt(reverse-menu-complete). + +In each of the forms supporting it the tt(-a) option makes the +var(function) autoloadable (exactly equivalent to +tt(autoload )var(function)). +) +xitem(tt(compconf) var(definitions...)) +xitem(tt(compconf)) +item(tt(compconf) [ tt(-l) ] var(keys...))( +Several aspects of the completion system can be configured by the +user. The configuration values are stored under the keys described +below in the associative array `tt(compconfig)'. After sourcing +tt(compinit), configuration values can either be set directly as in +`tt(compconfig[completer]=_complete)' or by calling this utility function. + +Each var(definition) may be either a simple `var(key)', which sets this +key in the tt(compconfig) array to an empty string, or of the form +`var(key=value)' which stores the `var(value)' under key `var(key)'. + +Since the completion system also uses the array for internal purposes, +you should not set all values at once by doing `tt(compconfig=(...))'. + +In the second form (without arguments), this function lists all keys +and their values. If given the tt(-l) option as its first argument, as +in the last form, the other arguments are taken as names of keys and +the values of these keys are printed one per line. +) +enditem() + +texinode(Control Functions)(Completion Functions)(Initialisation)(Completion System) +sect(Control Functions) + +The initialisation script tt(compinit) re-binds all the keys which perform +completion to newly created widgets that all call the supplied widget +function tt(_main_complete). This function acts as a wrapper calling +the so-called `completer' functions that generate matches. If +tt(_main_complete) is +called with arguments, these are taken as the names of completer +functions to be called in the order given. If no arguments are given, the +set of functions to try is taken from the colon-separated list in the +configuration key tt(completer). For example, to use normal +completion and correction if that doesn't generate any matches: + +indent( +nofill(tt(compconf completer=_complete:_correct)) +) + +after sourcing tt(compinit). The default value for this configuration key +set up in tt(compinit) is `tt(_complete)', i.e. normally only ordinary +completion is tried. The tt(_main_complete) function uses the return value +of the completer functions to decide if other completers should be +called. If the return value is zero, no other completers are tried and the +tt(_main_complete) function returns. + +The following completer functions are contained in the distribution (users +may write their own): + +startitem() +item(tt(_complete))( +This completer generates all possible completions in a context-sensitive +manner, i.e. using the tt(compdef) function +explained above and the current settings of all special parameters. + +To complete arguments of commands, tt(_complete) uses the utility function +tt(_normal), which is in turn responsible for finding the particular +function; it is described below. Various contexts of the form +tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are +handled specially. These are: + +startitem() +item(tt(-equal-))( +for completion after an equal sign, other than one occurring in a +shell-variable assignment. +) +item(tt(-tilde-))( +for completion after a tilde (`tt(~)') character, but before a slash. +) +item(tt(-redirect-))( +for completion after a redirection operator. +) +item(tt(-math-))( +for completion inside mathematical contexts, such as +`tt(LPAR()LPAR())...tt(RPAR()RPAR())'. +) +item(tt(-subscript-))( +for completion inside subscripts. +) +item(tt(-value-))( +for completion on the right hand side of an assignment. +) +item(tt(-array-value-))( +for completion on the right hand side of an array-assignment +(`tt(foo=LPAR()...RPAR())'). +) +item(tt(-condition-))( +for completion inside conditions (`tt([[...]])'). +) +item(tt(-parameter-))( +for completing the name of a parameter expansion (`tt($...)'). +) +item(tt(-brace-parameter-))( +for completing the name of a parameter expansion within braces +(`tt(${...})'). +) +item(tt(-first-))( +for adding completions before any other other completion functions are +tried (similar to the `tt(-T)' flag of tt(compctl)); if this +function sets the tt(_compskip) parameter to any value, the completion +system will not call any other function to generate matches. +) +item(tt(-default-))( +for generating completions when no special completion function is used +(similar to the `tt(-D)' option of tt(compctl)). +) +item(tt(-command-))( +for completing in a command position (as with the `tt(-C)' option of +tt(compctl)). +) +enditem() + +Default implementations are supplied for each of these +contexts, in most cases named after the context itself +(e.g. completion for the `tt(-tilde-)' context is done by the function +named `tt(_tilde)'). +) +item(tt(_approximate))( +This completer function uses the tt(_complete) completer to generate +a list of strings for the context the cursor is currently in, allowing +you to specify a maximum number of errors: see the description of +approximate matching in +ifzman(\ +zmanref(zshexpn) +)\ +ifnzman(\ +noderef(Filename Generation) +)\ +for how errors are +counted. The resulting list of corrected and completed strings is then +presented to the user. The intended use of this completer function is to +try after the normal tt(_complete) completer by setting: + +indent( +nofill(tt(compconf completer=_complete:_approximate)) +) + +This will give correcting completion if and only if +normal completion doesn't yield any possible completions. When +corrected completions are found, the completer will normally start +menucompletion allowing you to cycle through these strings. + +The exact behavior of this completer can be changed by using the +following configuration keys: + +startitem() +item(tt(approximate_accept))( +This should be set to the number of errors the correction code should +accept. The completer will try to generate completions by first allowing +one error, then two errors, and so on, until either a match +was found or the maximum number of errors given by this key has +been reached. + +If the value for this key contains a lower- or upper-case `tt(n)', the +completer function will take any numeric argument as the +maximum number of errors allowed. For example, with + +indent( +nofill(tt(compconf approximate_accept=2n)) +) + +two errors will be allowed if no numeric argument is given. However, +with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six +errors are accepted. Hence with a value of `tt(0n)', no correcting +completion will be attempted unless a numeric argument is given. + +If the value contains `tt(n)' or `tt(N)' and a exclamation mark +(`tt(!)'), tt(_approximate) will var(not) try to generate corrected +completions when given a numeric argument, so in this case the number given +should be greater than zero. For example, `tt(2n!)' specifies that +correcting completion with two errors will usually be performed, but if a +numeric argument is given, correcting completion will not be performed. +) +item(tt(approximate_original))( +This key is used to specify whether the original string on which correcting +completion was attempted is to be included in the list of possible +corrections. If it is set to any non-empty string, the original string +will be offered when cycling through the completions. Normally it will +appear as the first string, so that the command line does not change +immediately; consecutive completion attempts will cycle through the +corrected strings. If the value for this key contains the substring +`tt(last)', the original string will be the last one in the list, so +that it appears just before wrapping around to the first corrected +string again. Also, if the value contains the substring `tt(always)', +the original string will always be included; normally it is +included only if more than one possible correction was generated. +) +item(tt(approximate_prompt))( +This can be set to a string to be displayed on top of the +corrected strings generated when cycling through them. This string +may contain the control sequences `tt(%n)', `tt(%B)', etc. known from +the `tt(-X)' option of tt(compctl). Also, the sequence `tt(%e)' will +be replaced by the number of errors accepted to generate the corrected +strings. +) +item(tt(approximate_insert))( +If this is set to a string starting with `tt(unambig)', the code will try +to insert a usable unambiguous string in the command line instead of +always cycling through the corrected strings. If such a unambiguous +string could be found, the original string is not used, independent of +the setting of tt(approximate_original). If no sensible string could be +found, one can cycle through the corrected strings as usual. +) +enditem() + +If any of these keys is not set, but the the same key with the prefix +`tt(correct)' instead of `tt(approximate)' is set, that value will be +used. The forms beginning with `tt(correct)' are also used by the +tt(_correct) completer function. + +The keys with the `tt(approximate)' prefix have no default values, but +tt(compinit) defines default values for tt(correct_accept) (which +is set to `tt(2n)'), and tt(correct_prompt). +) +item(tt(_correct))( +Generate corrections (but not completions) for the current word; this is +similar to spell-checking. This calls tt(_approximate), but only the +configuration parameters beginning tt(correct_) are used. + +For example, with: + +indent(tt( +nofill(compconf completer=_complete:_correct:_approximate) +nofill(compconf correct_accept='2n!' approximate_accept=3n)) +) + +correction will accept up to two errors. If a numeric argument is +given, correction will not be performed, but correcting completion will be, +and will accept as many errors as given by the numeric argument. +Without a numeric argument, first correction and then correcting +completion will be tried, with the first one accepting two errors +and the second one accepting three errors. + +This completer function is intended to be used without the +tt(_approximate) completer or, as in the example, just before +it. Using it after the tt(_approximate) completer is useless since +tt(_approximate) will at least generate the corrected strings +generated by the tt(_correct) completer -- and probably more. +) +item(tt(_match))( +This completer is intended to be used after the tt(_complete) +completer. It allows one to give patterns on the command line and +to complete all strings metching these patterns from the set of possible +completions for the context the cursor is in, without having to set +the tt(GLOB_COMPLETE) option. + +Normally this will be done by taking the pattern from the line, +inserting a `tt(*)' at the cursor position and comparing the resulting +pattern with the possible completions generated. However, if the +configuration key tt(match_original) has a value of `tt(only)', no +`tt(*)' will be inserted. If tt(match_original) has any other non-empty +string as its value, this completer will first try to generate matches +without, then with a `tt(*)' inserted at the cursor position. +) +item(tt(_expand))( +This completer function does not really do completion, but instead +checks if the word on the command line is eligible for expansion and, +if it is, gives detailed control over how this expansion is done. When +using this, one should not use the tt(expand-or-complete) widget, but +instead use tt(complete-word), as otherwise tt(expand-or-complete) +will expand the string on the line before the completion widget is +called. Also, this completer should be called before the tt(_complete) +completer function. + +Control over how the expanded string will be treated is possible with the +following configuration keys: + +startitem() +item(tt(expand_substitute))( +If this is unset or set to the empty string, the code will first try +to expand all substitutions in the string (such as +`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an +non-empty string it should be an expression usable inside a `tt($((...)))' +arithmetical expression. In this case, expansion of substitutions will +be done if the expression evaluates to `tt(1)'. For example, with + +indent( +nofill(tt(compconf expand_substitute='NUMERIC != 1')) +) + +substitution will be performed only if given an explicit numeric +argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'. +) +item(tt(expand_glob))( +If this is unset or set to an empty string, globbing will be attempted +on the word resulting from substitution or the original string. The +values accepted for this key are the same as for tt(expand_substitute). +) +item(tt(expand_menu))( +If this is unset or set to the empty string, the words resulting from +expansion (if any) will simply be inserted in the command line, +replacing the original string. However, if this key is set to a +non-empty string, the user can cycle through the expansion as in +menucompletion. Unless the value contains the substring `tt(only)', +the user will still be offered all expansions at once as one of the +strings to insert in the command line; normally, this possibility is +offered first, but if the value contains the +substring `tt(last)', it is offered last. Finally, if the value contains +the substring `tt(sort)', the expansions will be sorted alphabetically, +normally they are kept in the order the expansion produced them in. +) +item(tt(expand_original))( +If this is set to an non-empty string, the original string from the +line will be included in the list of strings the user can cycle +through as in a menucompletion. If the value contains the substring +`tt(last)', the original string will appear as the last string, with +other values it is inserted as the first one (so that the command line +does not change immediately). +) +item(tt(expand_prompt))( +This may be set to a string that should be displayed before the +possible expansions. This is passed to the `tt(-X)' option of +tt(compadd) and thus may contain the control sequences `tt(%n)', +`tt(%B)', etc. Also, the sequence `tt(%o)' in this string will be +replaced by the original string. +) +enditem() + +None of these configuration keys has a default value. +) +item(tt(_list))( +This completer allows one to delay the insertion of matches until +completion is attempted a second time without the word on the line +being changed. On the first attempt, only the list of matches will be +shown. Configuration keys understood are: + +startitem() +item(tt(list_condition))( +If this key is unset or set to the empty string, the insertion of +matches will be delayed unconditionally. If this value is set, it +should be set to an expression usable inside a `tt($((...)))' +arithmetical expression. In this case, delaying will be done if the +expression evaluates to `tt(1)'. For example, with + +indent( +nofill(tt(compconf list_condition='NUMERIC != 1')) +) + +delaying will be done only if given an explicit numeric argument +other than `tt(1)'. +) +item(tt(list_word))( +To find out if listing should be performed on its own, the code normally +compares the contents of the line with the contents the line had at the +time of the last invocation. If this key is set to an non-empty string, +comparison is done using only the current word. So if it is set, +attempting completion on a word equal to the one when completion was called +the last time will not delay the generation of matches. +) +enditem() +) +item(tt(_menu))( +This completer is a simple example function implemented to show how +menucompletion can be done in shell code. It should be used as the +first completer and has the effect of making the code perform +menucompletion. Note that this is independent of the setting of the +tt(MENU_COMPLETE) option and does not work with the other +menucompletion widgets such as tt(reverse-menu-complete), or +tt(accept-and-menu-complete). +) +enditem() + +texinode(Completion Functions)()(Control Functions)(Completion System) +sect(Utility Functions) + +Descriptions follow for utility functions that may be +useful when writing completion functions. Most of these reside in the +tt(Core) subdirectory except where noted. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention of returning zero if they +generated completions and non-zero if no matching completions could be +added. + +startitem() +item(tt(_compalso))( +This function looks up the definitions for the context and command +names given as arguments and calls the handler functions for them if +there is a definition (given with the tt(compdef) function). For +example, the function completing inside subscripts might use +`tt(_compalso -math-)' to include the completions generated for +mathematical environments. +) +item(tt(_normal))( +This function is used for normal command completion. If +completion is attempted on the first word, command names are +completed. Otherwise, the arguments are completed by calling the +functions defined for this command, including those functions defined +for patterns matching the command name. This function can also be +called by other completion functions if they have to complete a range +of words as a separate command. For example, the function to complete after +the pre-command specifiers such as tt(nohup) removes the first word from +the tt(words) array, decrements the tt(CURRENT) parameter, then calls this +function. + +When calling a function defined for a pattern, this function also +checks if the parameter tt(_compskip) is set. If it was set by the +function called, no further completion functions are called. With this +one can write a pattern completion function that keeps other functions +from being tried simply by setting this parameter to any value. +) +item(tt(_multi_parts))( +This functions gets two arguments: a separator character and an +array. As usual, the array may be either the +name of an array parameter or a literal array in the form +`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white +space in parentheses). With these arguments, this function will +complete to strings from the array where the parts separated by the +separator character are completed independently. For example, the +tt(_tar) function from the distribution caches the pathnames from the +tar file in an array and then calls this function to complete these +names in the way normal filenames are completed by the +tt(_path_files) function. + +Like other utility functions, this function accepts the `tt(-V)', +`tt(-J)', and `tt(-X)' options with an argument and passes them to the +tt(compadd) builtin. +) +item(tt(_sep_parts))( +This function gets as arguments alternating arrays and separators. +The arrays specify completions for parts of strings to be separated by the +separators. The arrays may be the names of array parameters or +a quoted list of words in parentheses. For example, with the array +`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will +complete the string `tt(f)' to `tt(foo)' and the string `tt(b@n)' to +`tt(bar@news)'. + +This function passes the `tt(-V)', `tt(-J)', and `tt(-X)' options and +their arguments to the tt(compadd) builtin used to add the matches. +) +item(tt(_path_files) and tt(_files))( +The function tt(_path_files) is used throughout the shell code +to complete filenames. The advantage over the builtin +completion functions is that it allows completion of partial paths. For +example, the string `tt(/u/i/s/sig)' may be completed to +`tt(/usr/include/sys/signal.h)'. The options `tt(-/)', `tt(-f)', `tt(-g)', +and `tt(-W)' are available as for the tt(compctl) +and tt(compgen) builtins; tt(-f) is the default. Additionally, the `tt(-F)' +option from the tt(compadd) builtin is supported, giving direct control +over which filenames should be ignored as done by the tt(fignore) +parameter in normal completion. + +The function tt(_files) calls tt(_path_files) with all the arguments +it was passed and, if that generated no matches, call tt(_path_files) again +without any tt(-g) or tt(-/) option, thus generating all filenames. + +These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)', `tt(-P)', +`tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options from the +tt(compadd) builtin. + +Finally, the tt(_path_files) function supports one configuration key: +tt(path_expand). If this is set to any non-empty string, the partially +typed path from the line will be expanded as far as possible even if +trailing pathname components can not be completed. +) +item(tt(_parameters))( +This should be used to complete parameter names if you need some of the +extra options of tt(compadd). It first tries to complete only non-local +parameters. All arguments are passed unchanged to the tt(compadd) builtin. +) +item(tt(_options))( +This can be used to complete option names. The difference to the +`tt(-o)' option of tt(compgen) is that this function uses a matching +specification that ignores a leading `tt(no)', ignores underscores and +allows the user to type upper-case letters, making them match their +lower-case counterparts. All arguments passed to this function are +propagated unchanged to the tt(compgen) builtin. +) +item(tt(_set_options) and tt(_unset_options))( +These functions complete only set or unset options, with the same +matching specification used in the tt(_options) function. + +Note that you need to uncomment a few lines in the tt(_main_complete) +function for these functions to work properly. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs. +) +item(tt(_long_options))( +This function resides in the tt(Base) subdirectory of the example +completion system because it is not used by the core system. + +This function is used to complete long options for commands that +support the `tt(--help)' option as, for example, most of the GNU +commands do. For this it invokes the command from the line with the +`tt(--help)' option and then parses the output to find possible option +names. Note that this means that you should be careful to make sure +that this function is not called for a command that does not support +this option. + +For options that get an argument after a `tt(=)', the function also +automatically tries to find out what should be completed as the argument. +The possible completions for option-arguments can be described with +the arguments to this function. This is done by giving pairs of +patterns and actions as consecutive arguments. The actions specify +what should be done to complete arguments of those options whose +description match the pattern. The action may be a list of words in +brackets or in parentheses, separated by spaces. A list in square brackets +denotes possible values for an optional argument, a list in parentheses +gives words to complete for mandatory arguments. If the action does +not start with a square bracket or parenthesis, it should be the name of a +command (probably with arguments) that should be invoked to complete +after the equal sign. Example: + +indent( +nofill(tt(_long_options '*\*' '(yes no)' \)) +nofill(tt( '*=FILE*' '_files' \)) +nofill(tt( '*=DIR*' '_files -/')) +) + +Here, `tt(yes)' and `tt(no)' will be completed as the argument of +options whose description ends in a star, file names for options that +contain the substring `tt(=FILE)' in the description, and paths for +options whose description contains `tt(=DIR)'. In fact, the last two +patterns are not needed since this function always completes files +for option descriptions containing `tt(=FILE)' and paths for option +descriptions that contain `tt(=DIR)' or `tt(=PATH)'. These builtin +patterns can be overridden by patterns given as arguments, however. + +This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)' +options which are passed unchanged to `tt(compadd)'. Finally, it +accepts the option `tt(-t)'; if this is given, completion is only done +on words starting with two hyphens. +) +enditem() diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo index 7d7e688b0..0a626f4e1 100644 --- a/Doc/Zsh/compwid.yo +++ b/Doc/Zsh/compwid.yo @@ -186,6 +186,18 @@ 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), @@ -193,6 +205,62 @@ 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 @@ -268,7 +336,8 @@ 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) ]) -item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])( +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 @@ -437,6 +506,23 @@ 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 @@ -596,3 +682,9 @@ 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))\ +. diff --git a/Doc/Zsh/guide.yo b/Doc/Zsh/guide.yo index 96e12fc58..81347da1f 100644 --- a/Doc/Zsh/guide.yo +++ b/Doc/Zsh/guide.yo @@ -31,6 +31,7 @@ menu(Zsh Line Editor) menu(Programmable Completion) menu(Completion Widgets) menu(Zsh Modules) +menu(Completion System) --- Indices --- diff --git a/Doc/Zsh/intro.yo b/Doc/Zsh/intro.yo index f619f82fe..b3d4887b1 100644 --- a/Doc/Zsh/intro.yo +++ b/Doc/Zsh/intro.yo @@ -23,6 +23,7 @@ list(em(zshzle) Zsh command line editing) list(em(zshcompctl) Zsh completion control) list(em(zshcompwid) Zsh completion widgets) list(em(zshmodules) Zsh loadable modules) +list(em(zshcompsys) Zsh completion system) ifzshone(\ list(em(zshall) Meta-man page containing all of the above) )\ diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo index 97c420eed..63894076b 100644 --- a/Doc/Zsh/modules.yo +++ b/Doc/Zsh/modules.yo @@ -1,4 +1,4 @@ -texinode(Zsh Modules)()(Completion Widgets)(Top) +texinode(Zsh Modules)(Completion System)(Completion Widgets)(Top) chapter(Zsh Modules) cindex(modules) sect(Description) diff --git a/Doc/Zsh/seealso.yo b/Doc/Zsh/seealso.yo index 5231e8828..924663651 100644 --- a/Doc/Zsh/seealso.yo +++ b/Doc/Zsh/seealso.yo @@ -11,6 +11,7 @@ ifzshone(\ zmanref(zshbuiltins), zmanref(zshcompctl), zmanref(zshcompwid), +zmanref(zshcompsys), zmanref(zshexpn), zmanref(zshmisc), zmanref(zshmodules), diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index bd91f0efa..c4809b02d 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -139,6 +139,12 @@ The part of the buffer that lies to the right of the cursor position. If it is assigned to, only that part of the buffer is replaced, and the cursor remains between the old tt($LBUFFER) and the new tt($RBUFFER). ) +vindex(PREBUFFER) +item(tt(PREBUFFER) (scalar))( +In a multi-line input at the secondary prompt, this read-only parameter +contains the contents of the lines before the one the cursor is +currently in. +) vindex(WIDGET) item(tt(WIDGET) (scalar))( The name of the widget currently being executed. |