From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4648 invoked from network); 30 Mar 1999 09:35:59 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 30 Mar 1999 09:35:59 -0000 Received: (qmail 8327 invoked by alias); 30 Mar 1999 09:35:30 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 5983 Received: (qmail 8320 invoked from network); 30 Mar 1999 09:35:26 -0000 Date: Tue, 30 Mar 1999 11:35:20 +0200 (MET DST) Message-Id: <199903300935.LAA07161@beta.informatik.hu-berlin.de> From: Sven Wischnowsky To: zsh-workers@sunsite.auc.dk Subject: PATCH: manual for example completion This puts a description of the example completion system into the docs. I've put it into its own file because I think it's already big enough for that. In the manual this comes after the modules-section, at the very end. Most of the text is taken from the `README' file and the comments in the helper functions. In some cases I added some more comments and in at least one place I had to correct what I took from `README'. I don't think that I'll support `README' any longer. Bye Sven diff -u Doc/Zsh/compsys.yo Doc/Zsh/compsys.yo --- Doc/Zsh/compsys.yo Tue Mar 30 11:25:31 1999 +++ Doc/Zsh/compsys.yo Tue Mar 30 11:20:26 1999 @@ -0,0 +1,701 @@ +texinode(Completion System)()(Zsh Modules)(Top) +chapter(Completion System) +cindex(completion, system) +cindex(completion, programmable) +cindex(completion, controlling) +sect(Description) + +This describes the example implementation for the new completion +system. It consists of two scripts and a couple of other files that +define shell functions, residing in the tt(Completion) directory and +its sub-directories of the main distribution directory. + +The intended use is to copy all the files you need into a directory +of your account and then start the intialisation process. Which files +are always needed and which files are optional is described in the +following sections. + +startmenu() +menu(Initialisation) +menu(Control Functions) +menu(Completion Functions) +endmenu() + +texinode(Initialisation)(Control Functions)()(Completion System) +sect(Initialisation) + +The script tt(compinit), when sourced with `tt(source .../compinit)' +or `tt(. .../compinit)', will define a few utility functions, make all +files defining shell functions for completion automatically loaded, +and will then re-bind all keys that do completion to use the new system. + +subsect(Arguments) + +Since finding out which files should be made automatically autoloaded +can be quite expensive, it is recommended to create a file containing +executable shell code doing everything tt(compinit) would +normally do automatically. To simplify this, the second script, +tt(compdump)' is provided. Whenever this is sourced, a file, +called `var(dumpfile)' is created containing the shell code needed to +set up everything needed for the completion system. To simplify this +even further, the tt(compinit) file accepts the option +`tt(-d)'. If this is given, tt(compdump) is automatically called +after everything is set up. On later invocations of tt(compinit) +with the option given, it will only search the files that have to be +made autoloaded if something has changed and will otherwise just +source the var(dumpfile). The name of the var(dumpfile) can be given +to tt(compinit) as an argument. If this is not given, a default +name will be chosen. + +Whenever the setup for the completion system changes, the script +tt(compdump) can be source by hand, but if tt(compinit) is +sourced with the `tt(-d)' option this will only be needed if one of +the files for completion has been renamed. If only the number of files +to use for completion has changed, this will be detected by +tt(compinit) and it will then automatically create a new +var(dumpfile). + +subsect(Autoloaded files) + +To have the files used for completion automatically autoloaded the +tt(fpath/FPATH) parameter has to contain the directory in which they +are stored. As a convention the names of these files start with an +underscore. 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 has to describe what to do with the file by +starting with 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 looked for are: + +startitem() +item(tt(#compdef) var(names...))( +In this case the file will be made autoloaded and the function defined +in it will be called when completing for one of the contexts or +commands whose var(names) are given. Internally this uses the function +tt(compdef) described below. +) +item(tt(#compdef -p) var(pattern))( +This will make the file be made autoloaded and the function will be +called when completing for a command whose name matches the given +var(pattern). Not 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). The var(style) given has to be the name of one of +the builtin widgets that do 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). + +Such a tag line will create a widget behaving like the builtin widget +given by var(style) and bind it to all var(key-sequences) given. If +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 +used as completion functions directly but should be loaded +automatically when invoked. +) +enditem() + +In each of these cases, no white space is allowed between the `tt(#)' +and the name of the tag. + +subsect(Functions) + +The tt(compinit) file defines the follwing functions that may +also be used 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...))( +In the first form makes the completion system call the given +var(function) be called when completing for the contexts or commands +whose var(names) are given. If the tt(-n) option is given, the +var(function) will only be called for contexts or commands for which +there was no previous definition. These definitions can be deleted +by giving the tt(-d) option as in the second form. + +The third form makes the var(function) be called for all commands +whose name matches the var(pattern). + +The fourth form defines a widget with the same name as the +var(function) and makes it be called for each of the +var(key-sequences). 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) autoloaded. +) +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)'. To set configuration +values, one can either set directly as in +`tt(compconfig[completer]=_complete)' after sourcing +tt(compinit), 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 +one 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 keys doing +completion to newly created widgets that all cal the supplied widget +function tt(_main_complete). This function acts as a wrapper calling +the so-called completer functions that generate the matches. If it is +called with arguments, these are taken as the names of completer +functions that should be called. If no arguments are given, the set of +functions to try is taken from the configuration key +tt(completer). For example if you want to use normal completion and +correction if that doesn't generate any matches, you can do + +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 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 example completer functions are contained in the +distribution: + +startitem() +item(tt(_complete))( +This completer generates all possible completions for the current +settings of the special completion parameters and the completion +functions defined using the tt(compdef) function explained above. + +To complete arguments of commands it uses the utility function +tt(_normal), for other contexts it directly looks up the definition +(given by calls to tt(compdef) or implicitly by automatically +autoloaded files with `tt(#compdef)' tags). + +The names of the special contexts supported are: + +startitem() +item(tt(-equal-))( +for completion after an equal sign +) +item(tt(-tilde-))( +for completion after a tilde (`tt(~)') character +) +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 with braces +(`tt(${...})') +) +enditem() + +The example system has a default implementation 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 +a number of errors. The resulting list of corrected and completed +strings is then presented to the user. The intended use of this +completer function is to try it after the normal tt(_complete) +completer by setting: + +indent(nofill( +tt(compconf completer=_complete:_approximate))) + +This will give you normal completion and correcting completion 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 +supported configuration keys: + +startitem() +item(tt(approximate_accept))( +This should be set to the number of errors the correction code should +accept. The completer will consecutively try to generate completions +by allowing one error, two errors, and so on, until the maximum number +of errors given by this key has been tried or possible completions +were generated. + +If the value for this key contains a lower- or upper-case `tt(n)', the +completer function will preferably use the 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. Also, with a value of `tt(0n)', no correcting +completion will be attempted, unless a numeric argument is given. +But if the value contains `tt(n)' or `tt(N)' and a exclamation mark +(`tt(!)'), this completer will var(not) try to generate corrected +completions when given a numeric argument. +) +item(tt(approximate_original))( +This key is used to specify if the original string on which correcting +completion was attempted should 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 +immediatly, but conecutive completion attempts will cycle through the +corrected strings. If the value for this key contains the sub-string +`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 sub-string `tt(always)', +the original string will always be included, whereas normally it is +included only if more than one possible correction was generated. +) +item(tt(approximate_prompt))( +This can be set to a string that should 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))( +This completer function uses tt(_approximate), but makes it generate +only corrected strings, var(not) completed and corrected strings. The +fact that this completer uses only the configuration keys with the +`tt(correct)' prefix allows one to give different values to be used +with correction and correcting completion. For example, with: + +indent(nofill(tt( + compconf completer=_complete:_correct:_approximate + compconf correct_accept='2n!' approximate_accept=3n))) + +correction will accept up to two errors. If a numeric argument is +given, correction will not be used, but correcting completion will +and it 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 one the command line and +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) options. + +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 the key has any other non-empty string as +its value, this completer will first try to generate matches without +inserted a `tt(*)', and then with the `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 given 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 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 ommand line, +replacing the original string. However, if this key is set to an +non-empty string, the user can cycle through the expansion as in a +menucompletion. Unless the value contains the sub-string `tt(only)', +the user will still be offered all expansions at once as one of the +strings to insert in the command line. Also, if the value contains the +sub-string `tt(last)', the string with all expansion will be offered +last, whereas normally it is offered as the first string to +insert. Finally, if the value contains the sub-string `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 sub-string +`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 immediatly). +) +item(tt(expand_prompt))( +This may be set to a string that should be displayed before the +possible expansions. This is given 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 only listing should be done, 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 completion was called +on 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 use +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) + +The tt(Core) directory contains several utility functions that may be +interesting to use when writing completion functions. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention to return 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 to complete for normal commands, i.e. 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. The function to complete after the +pre-command specifiers such as tt(nohup), for example calls this +function after removing the first word from the tt(words) array and +decrementing the tt(CURRENT) parameter. + +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 by simple setting this parameter to any value. +) +item(tt(_multi_parts))( +This functions gets two arguments: a separator character and an +array. As usual for the completion code, the array may be given as the +name of an array parameter or as 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 te 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 gives them to the +tt(compadd) builtin. +) +item(tt(_sep_parts))( +This function gets alternatingly arrays and separators as +arguments. With this, it completes the strings consisting of different +parts, separated by the separator characters. Before and after these +separators the strings from the arrays are completed. The arrays may +be given as the names of array parameters or literally as a 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 gives 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 example completion +system to complete filenames. The advantage over the builtin +completion functions is that it allows to complete partial paths. For +example, the string `tt(/u/i/s/sig)' may be completed to +`tt(/usr/include/sys/signal.h)'. To be able to use this for all cases +where the completion of filenames is needed it supports the options +`tt(-/)', `tt(-f)', `tt(-g)', and `tt(-W)' known from the tt(compctl) +and tt(compgen) builtins. Additionally, the `tt(-F)' option from the +tt(compadd) builtin is supported, giving direct control over which +filenames should normally be ignored as done by the tt(fignore) +parameter for normal completion. + +The function tt(_files) calls tt(_path_files) with all arguments it +got 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 given 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 given 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) functions. + +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))( +Unlike the other utility functions, this function resides in the +tt(Base) directory of the example completion system because it is not +used by the core of the system itself. + +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 tries +to automatically 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 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 bracket or parentheses, 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)' \) +tt( '*=FILE*' '_files' \) +tt( '*=DIR*' '_files -/'))) + +This makes `tt(yes)' and `tt(no)' 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)'. Note that 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, though. + +This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)' +options which are given 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. +) +item(tt(_match_test))( +This function is called at the beginning of functions that do matching in +shell code with one argument: the name of the calling function. It +should test the value of `tt($compstate[matcher])' and return non-zero +if the calling function should try to generate matches for the global +match specification in use. + +If you have a global match specification with more than one set of patterns +you may want to modify this function to return non-zero for all of your +match specifications and modify the function tt(_match_pattern) to build the +pattern to use in the calling function. +) +item(tt(_match_pattern))( +This function is called from functions that do matching whenever they +need to build a pattern that is used to match possible completions. +It gets the name of the calling function and two names of parameters +as arguments. The first one is used in the calling function to build +the pattern used for matching possible completions. The content of this +parameter on entry to this function is the string taken from the line. +Here it should be changed to a pattern that matches words as the match +specifications currently in use do. + +In the calling function this pattern may be changed again or used only +in parts. The second parameter whose name is given as the third argument +allows to give pattern flags like `tt(LPAR()#l)tt(RPAR())' that are to +be used whenever matching is done. + +As an example, if you have global match specifications like: + +indent(nofill( +tt(compctl -M 'm:{a-z}={A-Z}' 'm:{a-z}={A-Z} r:|[.-]=* r:|=*'))) + +This function should look like: + +indent(nofill( +tt(eval "${3}='(#l)'") +tt([[ compstate[matcher] -eq 2 ]] && eval "$2='${(P)2:gs/./*./:gs/-/*-/}'"))) + +The first line makes sure that matching is done case-insensitively as +specified by `tt(m:{a-z}={A-Z})'. The second line replaces dots and hyphens +in the given string by patterns matching any characters before them, +like the `tt(r:|[.-]=* r:|=*)'. To make this work, the function `_match_test' +would have to be changed to `tt(LPAR()LPAR() compstate[matcher] <= 2 RPAR()RPAR())'. + +When correction is used (see above), you probably don't want to set +matching flags here as that may make the results slightly +unpredictable. For this, change the line above to: + +indent(nofill( +tt([[ compstate[matcher] -lt 0 ]] && eval "${3}='(#l)'"))) + +The default implementation of this function is empty. +) +enditem() + +Apart from the functions explained, the tt(Base) sub-directory +contains functions to complete for the special contexts listed +above. Normally users may want to use all of these function, probably +editing some of them. + +Also, the tt(Builtins) sub-directory contains completion functions for +all shell builtin commands, the tt(User) sub-directory contains +example functions for several standard Unix commands, and the +tt(Commands) sub-sirectory contains examples for specialised +completion functions bound to keys. diff -u od/Zsh/compwid.yo Doc/Zsh/compwid.yo --- od/Zsh/compwid.yo Mon Mar 29 11:49:11 1999 +++ Doc/Zsh/compwid.yo Mon Mar 29 13:30:58 1999 @@ -664,3 +664,9 @@ 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 -u od/Zsh/guide.yo Doc/Zsh/guide.yo --- od/Zsh/guide.yo Mon Mar 29 11:49:11 1999 +++ Doc/Zsh/guide.yo Mon Mar 29 15:10:20 1999 @@ -31,6 +31,7 @@ menu(Programmable Completion) menu(Completion Widgets) menu(Zsh Modules) +menu(Completion System) --- Indices --- diff -u od/Zsh/intro.yo Doc/Zsh/intro.yo --- od/Zsh/intro.yo Mon Mar 29 11:49:12 1999 +++ Doc/Zsh/intro.yo Mon Mar 29 13:28:38 1999 @@ -23,6 +23,7 @@ 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 -u od/Zsh/modules.yo Doc/Zsh/modules.yo --- od/Zsh/modules.yo Mon Mar 29 11:49:13 1999 +++ Doc/Zsh/modules.yo Mon Mar 29 13:36:20 1999 @@ -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 -u od/Zsh/seealso.yo Doc/Zsh/seealso.yo --- od/Zsh/seealso.yo Mon Mar 29 11:49:13 1999 +++ Doc/Zsh/seealso.yo Mon Mar 29 13:29:06 1999 @@ -11,6 +11,7 @@ zmanref(zshbuiltins), zmanref(zshcompctl), zmanref(zshcompwid), +zmanref(zshcompsys), zmanref(zshexpn), zmanref(zshmisc), zmanref(zshmodules), diff -u od/Makefile.in Doc/Makefile.in --- od/Makefile.in Tue Mar 30 11:26:10 1999 +++ Doc/Makefile.in Tue Mar 30 11:29:22 1999 @@ -38,7 +38,7 @@ .SUFFIXES: .yo .1 # man pages to install -MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 \ +MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 zshcompsys.1 \ zshexpn.1 zshmisc.1 zshmodules.1 \ zshoptions.1 zshparam.1 zshzle.1 zshall.1 @@ -48,7 +48,7 @@ Zsh/compat.yo Zsh/compctl.yo Zsh/cond.yo Zsh/exec.yo Zsh/expn.yo \ Zsh/filelist.yo Zsh/files.yo Zsh/func.yo Zsh/grammar.yo Zsh/guide.yo \ Zsh/index.yo Zsh/intro.yo Zsh/invoke.yo Zsh/jobs.yo Zsh/metafaq.yo \ -Zsh/modules.yo Zsh/mod_cap.yo Zsh/compwid.yo \ +Zsh/modules.yo Zsh/mod_cap.yo Zsh/compwid.yo Zsh/compsys.yo \ Zsh/mod_clone.yo Zsh/mod_comp1.yo Zsh/mod_compctl.yo Zsh/mod_deltochar.yo \ Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_stat.yo \ Zsh/mod_zle.yo Zsh/options.yo \ @@ -114,6 +114,8 @@ zshcompctl.1: Zsh/compctl.yo zshcompwid.1: Zsh/compwid.yo + +zshcompsys.1: Zsh/compsys.yo zshexpn.1: Zsh/expn.yo diff -u od/zsh.yo Doc/zsh.yo --- od/zsh.yo Tue Mar 30 11:26:11 1999 +++ Doc/zsh.yo Mon Mar 29 13:27:18 1999 @@ -66,6 +66,7 @@ ifnzman(includefile(Zsh/compctl.yo)) ifnzman(includefile(Zsh/compwid.yo)) ifnzman(includefile(Zsh/modules.yo)) +ifnzman(includefile(Zsh/compsys.yo)) ifzshall(\ def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\ CMT() @@ -78,6 +79,7 @@ source(zshcompctl) source(zshcompwid) source(zshmodules) +source(zshcompsys) manpage(ZSHALL)(1)(date())(zsh version()) )\ ifzman(includefile(Zsh/filelist.yo)) diff -u Doc/zshcompsys.yo Doc/zshcompsys.yo --- Doc/zshcompsys.yo Tue Mar 30 11:26:36 1999 +++ Doc/zshcompsys.yo Mon Mar 29 13:28:07 1999 @@ -0,0 +1,3 @@ +manpage(ZSHCOMPSYS)(1)(date())(zsh version()) +manpagename(zshcompsys)(zsh completion system) +includefile(Zsh/compsys.yo) -- Sven Wischnowsky wischnow@informatik.hu-berlin.de