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 -> Functions/Completion/Core/_path_files _sep_parts Utility used for completing words with multiple separate parts, such as `@' _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 '' <_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.