diff options
Diffstat (limited to 'Doc/Zsh')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 691 | ||||
| -rw-r--r-- | Doc/Zsh/compwid.yo | 428 |
2 files changed, 1119 insertions, 0 deletions
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 new file mode 100644 index 000000000..2cb12e2c2 --- /dev/null +++ b/Doc/Zsh/compwid.yo @@ -0,0 +1,428 @@ +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 reseton each function exit to +the values they had when the function was entered. + +startitem() +item(tt(argv))( +The positional parameters are set to the arguments on the command line +when the widget function is invoked from the completion code. +) +item(tt(CURRENT))( +This is the number of the current word, i.e. the word the cursor is +currently on in the tt(argv) array. +) +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 in a command position, e.g. in the first word on the +command line +) +item(tt(argument))( +when completing an argument for a command +) +item(tt(redirect))( +when completing after a redirection operator; in this case the +positional parameters contain not only the arguments but also the +command name itself as the first element +) +item(tt(condition))( +when completing inside a `tt([[)...tt(]])' conditional expressing; in +this case the positional parameters are set to the words inside the +conditional expressions +) +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; in case of an +array value the positional parameters are set to the words in +parentheses +) +item(tt(subscript))( +when completing inside a parameter expansion subscript +) +enditem() +) +item(tt(COMMAND))( +In most cases this is set to name of the command for which completion +is tried. When completing after a redirection operator it contains the +string forming that operator. Also, when completing in the value of a +parameter assignment or in a parameter subscript it is set to the name +of the parameter. +) +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(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 parameter is set to the +number of the specification string which is currently used. +) +enditem() + +texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets) +sect(Builtin Commands) +startitem() +findex(complist) +item(tt(complist) 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(complist) and the +global matching specifications given to the tt(compctl) builtin +command. +) +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(-W) var(file-prefix) ]) +xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ]) +xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ]) +item([ tt(-M) var(match-spec) ] [ 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 supported flags are: + +startitem() +item(tt(-P) var(prefix))( +The same as for tt(compctl) and tt(complist), 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 +... +) +item(tt(-s) var(hidden-suffix))( +... +) +item(tt(-i) var(ignored-prefix))( +... +) +item(tt(-J) var(name))( +As for tt(compctl) and tt(complist) 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(-q))( +This flag has the same meaning as for tt(compctl) and tt(complist), +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(complist) 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(complist) 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(complist) this flag instructs the completion +code not to quote any metacharacters in the words when inserting them +in the command line. +) +item(tt(-m))( +Normally the matches added by tt(compadd) will not be compared with +what is already on the line. If this flag is given, this comparison is +performed as usual and the match specifications given with the tt(-M) +option to tt(compadd) and the global match specifications defined with +tt(compctl) will be used. This means that probably not all the word +given will be stored as matches since some of them may not match the +string on the 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(complist) +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 to one of the calls to tt(compadd) and the +option tt(AUTO_MENU) is set, the completion code will immediatly +switch to menucompletion. +) +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() +) +item(tt(compcall) [ tt(-TD) ])( + +This allows one to use completion definitions given with the +tt(compctl) builtin from within completion widgets. It makes +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. +) +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. + +The following condition codes are made available inside completion +widgets: + +startitem() +item(tt(-prefix) var(string))( +true if the content of tt(PREFIX) starts with var(string) +) +item(tt(-iprefix) var(string))( +like tt(-prefix), but the var(string) is removed from tt(PREFIX) and +added to tt(IPREFIX) +) +item(tt(-position) var(beg) [ var(end) ])( +true if tt(CURRENT) is equal to var(beg) or, if var(end) is given, +equal to or greater than var(beg) and equal to or less than var(end); +both of var(beg) and var(end) may be arithmetic expressions, if they +are less than zero the number of words in tt(argv) are added to them +before comparing them to tt(CURRENT); thus, tt(-1) is the last word, +tt(-2) is the word before that and so on +) +item(tt(-word) var(index) var(string))( +true if the word number var(index) in tt(argv) is equal to +var(string); again, var(index) may be negative, counting backwards +) +item(tt(-mword) var(index) var(pattern))( +like tt(-word) but using pattern matching +) +item(tt(-current) var(offset) var(string))( +like tt(-word) but var(offset) is relative to the value of +tt(CURRENT) +) +item(tt(-mcurrent) var(offset) var(pattern))( +like tt(-current) but using pattern matching +) +item(tt(-string) [ var(number) ] var(string))( +true if the current word contains var(string); anything up to the last +occurrence of this string will be ingnored by removing it from +tt(PREFIX) and adding it to tt(IPREFIX); if var(number) is given, +anything up to the var(number)'th occurrence of the var(string) will +be ignored; again, var(nmuber) may be any arithmetic expression and +negative values count backward +) +item(tt(-class) [ var(number) ] var(class))( +like tt(-string) but the var(class) is used as a character class so +that anything up to and including the last or the var(number)'th +occurrence of any character from the string var(class) is ignored +) +item(tt(-words) var(min) [ var(max) ])( +true if the number of words is equal to var(min); if var(max) is +given, it is true if the number of words is equal to or greater than +var(min) and equal to or less than var(max) +) +item(tt(-after) var(string))( +true if the cursor is after a word that is equal to var(string) +) +item(tt(-mafter) var(pattern))( +like tt(-after) but using pattern matching +) +item(tt(-between) var(string1) var(string2))( +true if the cursor is after a word that is equal to var(string1), if +there is also a word that is equal to va(string2), this is true only +if the cursor is before it +) +item(tt(-mbetween) var(pattern1) var(pattern2))( +like tt(-between) but using pattern matching +) +item(tt(-nmatches) var(number))( +true if the the value of tt(NMATCHES) is equal to var(number) +) +item(tt(-matcher) var(number))( +true if the value of tt(MATCHER) is equal to var(number) +) +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() { complist -H 0 '' }))) + +In this the function will complete words from the history matching the +current word. |