diff options
Diffstat (limited to 'Completion/README')
| -rw-r--r-- | Completion/README | 359 |
1 files changed, 3 insertions, 356 deletions
diff --git a/Completion/README b/Completion/README index bf677066a..dbfb50534 100644 --- a/Completion/README +++ b/Completion/README @@ -1,356 +1,3 @@ -The subdirectories contain code for the new function-based completion -system. Broadly speaking, this uses shell functions defined for each -command to determine how the arguments of a command should be completed. - -You should copy all the files you need or want to a directory of your own, -which should be included in your autoload path as defined by $fpath. Then -in your .zshrc you should source the file which appears here in -Core/compinit. It is recommnded that you use the -d option, which outputs -a file containing the necessary variables, bindkeys etc., making later -loading much faster. For example, - [[ -f ~/completion/compinit ]] && . ~/completion/compinit -d -The name of the file to use may be given as an extra argument. - -This will rebind any keys which do completion to use the new system. -For more detailed instructions, including how to add new completions, see -the top of Core/compinit. For information about how to configure the code, -see the section below. - -The subdirectories contain: - -Core: - The basic functions and files to be sourced. You will certainly need - these, and will most likely not want to alter them --- if you do, it - would probably help to give your version a different name. The files - are: - compinit - As already described, this is not a function, but is sourced once - (with the `source' or `.' commands) to set up the completion system. - compdump - This dumps the completions status for faster initialisation. The - easiest way of doing this is to use the -d option to compinit rather - than calling compdump directly. - _approximate - A completer function that does correcting completion. - _compalso - Utility for calling a function to add additional completions to an - already existing set. - _complete - The main completer function that generates the completions by calling - the context and command specific functions. - _correct - A completer function that attempts correction on the word from the - line. Unlike _approximate this does only correction, not completion. - _expand - A completer function for expanding the word on the line. - _files - A frontend to _path_files which will default to any old file if the - specified file was not found. - _list - A completer function that allows showing only a list on the first - TAB and insert completions on the second one. - _match - A completer function that temporarily swicthes on pattern matching - when comparing the string from the line with possible completions. - _main_complete - The main entry point called by the key bindings which compinit sets - up (the main `completion widget' in zsh jargon). This mainly calls - completer functions like _complete, either those given as arguments - or (if it is called without arguments) those from the completer - configuration key (see below). - _multi_parts - Utility for completion parts of words given a separator character and - a list of words. - _normal - The function called by _main_complete to handle the most common - cases, such as completing a command name or its arguments. This - function dispatches to the various other functions for individual - commands. (Actually, the system is fairly context-sensitive, so - it is wider than just command+argument.) - _options - Utility to complete option names, allowing the optional `no' prefix - and correctly handling upper case letters and underscores. - _parameters - This can be used to complete parameter names if you need some of the - options of compadd not supported by compgen. - _path_files - The function usually called to complete filenames and directories. It - replaces the standard -f, -g and -/ options for the basic completion - commands: it can do various extra tricks, such as expanding a whole - path at once, e.g. F/C/C/_p<TAB> -> Functions/Completion/Core/_path_files - _sep_parts - Utility used for completing words with multiple separate parts, such as - `<user>@<host>' - _set_options - _unset_options - These can be used to complete only set or unset options. For this to - work, you'll have to un-comment a few lines in _main_complete. -Base: - You will almost certainly want these files, too, which handle standard - tasks like completing files. However, you may want to edit them for - your own particular setup. Files are: - _command_names - This handles completion of the command word, i.e. the first thing - on the command line. You may want to alter this, for example, - to complete parameters to assign to. - _condition - This handles completing inside [[ ... ]] . - _default - This handles completion of command arguments when no special function - exists. Usually this means completing files, but you can modify this - as you wish. - _long_options - This handles options beginning with `--', as in many GNU commands. - The command must accept the --help option to list the possible options. - __long_options can also take arguments to help it decide what to - complete as the value of the option. Note that this is potentially - dangerous because the command from the line will be called with the - --help option and hence could cause damage if used with a command - that does not support it. - _match_pattern - _match_test - These are used by Base/_path_files (and hence also Base/_files) - and Base/_sep_parts for file completion with control over - matching (whether to complete case-insensitively, or to allow - insertion before `.', etc.) See _match_test for instructions. - Note _path_files expects these files to be present. - _precommand - Allows completion when the first word on the line has to be ignored, - for example `noglob ...' should ignore the noglob and just complete - as if it wasn't there. Add other such commands to the top line. - _redirect - Completes after `<' or `>': this version calls _files. - _subscript - For completion in subscripts of parameters, e.g $foo[...]. - _vars - Completion for commands which need variables (so this could also be in - the Builtins directory), but also in math environments such as ((...)). - _tilde - Completion after `~', defaults to user names and named directories. - _equal - Completion after `=', normally command and alias names are used. - _parameter - _brace_parameter - For completion inside parameter expansions ($... and ${...). -Builtins: - Define completions for various shell builtins. The top line of each file - says which builtins they apply to; in many cases you can guess from the - name. Note in particular that _zftp defines completions for all commands - beginning `zf', not just for the module command zftp. This is only - really useful if you use zftp with the zf* function suite (zfopen, zfget, - ...). -User: - This contains a pot pourri of completions for various external commands. - Not all will work unmodified on your system. -Commands: - These functions define separate completion commands which do not use - the usual context information, and hence have to be bound separately - to keys. As they appear, they have bindings which you can change or - delete by altering the top line of the file. To bind a function - (strictly speaking, the corresponding completion widget) yourself - after completion is loaded, use `bindkey '<key-string>' <_function_name>'. - The files are: - _correct_filename, bound to \C-xc - Correct the word under the cursor as a filename. This is significantly - more powerful than the standard \e$ (spell-word) binding. - _most_recent_file, bound to \C-xm - Insert the name of the most recent file matching the pattern - so far on the command line. - - -Configuration - -You can configure several aspects of the completion functions and the -overall completion behavior using the compconf shell function defined -in compinit. This function gets any number of arguments of the form -`key=value', where `key' is one of the keys described below and `value' -is any string. Most configuration keys are defined by the completer -functions. - -The completion widget function _main_complete currently understands -one configuration key: - - completer - This should be set to the names of the functions to generate the - matches separated by colons. E.g. with - - compconf completer=_complete:_correct:_approximate - - the code will first try normal completion. If that doesn't yield - any matches, correction is tried and if that doesn't yield - anything either, correcting completion is attempted. - -The keys understood by the _approximate completer function are: - - approximate_accept - This should be set to a number, specifying the maximum number - of errors that should be accepted. If the string also contains - a `n' or `N', the code will use the numeric argument as the - maximum number of errors if a numeric argument was given. If no - numeric argument was given, the number from the value of this - key will be used. E.g. with `compconf approximate_accept=2n' two - errors will be accepted, but if the user gives another number - with the numeric argument, this will be prefered. Also, with - `compconf approximate_accept=0n', normally no correction will be - tried, but if a numeric argument is given, automatic correction - will be used. On the other hand, if the string contains an `!' - and a `n' or `N', correction is not attempted if a numeric - argument is given. Once the number of errors to accept is - determined, the code will repeatedly try to generate matches by - allowing one error, two errors, and so on. Independent of the - number of errors the user wants to accept, the code will allow - only fewer errors than there are characters in the string from - the line. - - approximate_original - This value is used to determine if the original string should - be included in the list (and thus be presented to the user when - cycling through the corrections). If it is set to any non-empty - value, the original string will be offered. If it contains the - sub-string `last', the original string will appear as the last - string when cycling through the corrections, otherwise it will - appear as the first one (so that the command line does not - change immediately). Also, if the value contains the sub-string - `always', the original string will always be included, whereas - normally it is included only if more than one possible - correction was generated. - - approximate_prompt - This can be set to a string that should be printed before the - list of corrected strings when cycling through them. This string - may contain the control sequences `%n', `%B', etc. known from - the `-X' option of `compctl'. Also, the sequence `%e' will be - replaced by the number of errors accepted to generate the - corrected strings. - - approximate_insert - If this is set to a string starting with `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 - `approximate_original'. If no sensible string could be found, - one can cycle through the corrected strings as usual. - -If any of these keys is not set, but the the same key with the -prefix `correct' instead of `approximate' is set, that value will -be used. The forms beginning with `correct' are also used by the -_correct completer function, and this function uses only them, not -the ones starting with `approximate'. This allows one to give -different value to be used with correction and correcting -completion. For example, with: - - 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. - -The _match completer function, which allows to give patterns on the -command line and complete all strings matching it from the set of -possible completions, understands the following key: - - match_original - If this is set to a `only', pattern matching will only be tried - with the string from the line. If it is set to any other non-empty - string, the original pattern will be tried first and if that yields - no completions, matching will be tried again with a `*' inserted - at the cursor position. If this key is not set or set to an empty - string, matching will only be attempted with the `*' inserted. - -The _expand completer allows one to do expansion on the word from the -line. Note that you may either want to use the configuration keys or -not use this completer at all if you also use the _match completer -because the _expand completer will otherwise expand patterns before -they are seen by the _match completer. -Configuration keys supported are: - - 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 $(...) and - ${...}). If this is set to an non-empty string it should be - an expression usable inside a $[...] arithmetical expression. - In this case, expansion of substitutions will be done if the - expression evaluates to `1'. For example, with - - compconf expand_substitute='NUMERIC != 1' - - substitution will be performed only if given an explicit numeric - argument other than `1', as by typing ESC 2 TAB. - - 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. - - 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 `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 `last', the string with all expansion will - be offered first, whereas normally it is offered as the last string - to insert. Finally, if the value contains the sub-string `sort', - the expansions will be sorted alphabetically, normally they are - kept in the order the expansion produced them in. - - 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 - `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). - - expand_prompt - This may be set to a string that should be displayed before the - possible expansions. This is given to the -X option and thus may - contain the control sequences `%n', `%B', etc. Also, the sequence - `%o' in this string will be replaced by the original string. - -The _list 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: - - list_condition - If this key is unset or set to the empty string, this completer - will delay the insertion of matches unconditionally. However, - if this value is set, it should be set to an expression usable - inside a $[...] arithmetical expression. In this case, delaying - will be done if the expression evaluates to `1'. - For example, with - - compconf list_condition='NUMERIC != 1' - - delaying will be done only if given an explicit numeric argument - other than `1'. - - 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. - -For more information about what the completers do, see the files -containing them (_complete, _correct, _approximate, _match, and -_expand in the Core directory). - -The _path_files function used to complete filenames has one -configuration key: - - path_expand - If this is set to a 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. +The subdirectories contain code for a shell-based system of command-line +completion. This is considerably more powerful than the old `compctl' +method. For details, see the compsys(1) manual page (`man zshcompsys'). |