comp.txt Creates custom completion functions
==============================================================================
CONTENTS comp-contents
1. Intro comp-intro
2. Functionality provided comp-functionality
2.1. Functions comp-functions
3. Models comp-models
4. Argument descriptions comp-listdescription
5. Options comp-options
==============================================================================
1. Intro comp-intro
This plugin makes creating custom completion functions much easier.
Features:
∙ Ability to get variants from list and from dictionary keys
∙ Ability to get variants from custom function
∙ Allows modifying the completion description
Plugin requires chk, stuf and load plugins.
==============================================================================
2. Functionality provided comp-functionality
This plugin provides only two functions: one that creates completion function
and one that removes it. Both functions are available from dictionary returned
by load-func-getfunctions function.
------------------------------------------------------------------------------
2.1. Functions comp-functions
All following functions are accessed via dictionary returned by
load-func-getfunctions function.
ccomp({funcname}, {model}) comp-func-ccomp
Create a new completion function. {funcname} must be unique, but its
only purpose is to provide a way to delete last reference to {model}
when plugin is un- or reloaded. See comp-models for description of
{model} argument.
delcomp({funcname}) comp-func-delcomp
Delete reference to {model} that was created by comp-func-ccomp
function.
==============================================================================
3. Models comp-models
Completion model is a dictionary that contains required `model' key and some
additional keys depending on the value of the `model' key. Possible models
(`model' key values):
actions comp-model-actions
Optional keys: actions :: { {action}: {model} }
allowtrun :: Bool
Defines a completion for command that looks like this: >
Command action1 some_argument
Command action2 some_argument some_other argument
Command action3
...
<
Each value defines a model for the corresponding key which represents
the action name. Key `allowtrun' describes whether actions can be
truncated (they can by default).
simple comp-model-simple
Optional keys: arguments :: [{ListDescription}]
Defines a completion for command that takes a list of arguments, for
each possible arguments a {ListDescription} must be defined. See
comp-listdescription for details.
words comp-model-words
Required keys: words :: {ListDescription}
Defines a completion for command that takes a list of arguments that
are not connected with each other, for every argument
a {ListDescription} from words key is used. See comp-listdescription
for details.
pref comp-model-pref
Optional keys: arguments :: [{ListDescription}]
prefix :: { {prefix}: {ListDescription} }
preflist :: [{prefix}]
omitpresent :: Bool
allowtrun :: Bool
altpref :: [{prefix}]
Defines a completion for command that takes a list of arguments,
followed by prefixed arguments. Example: >
Command print columns 3
Command print buffer %
" The following commands are assumed to be equal
Command print buffer % columns 3
Command print columns 3 buffer %
<
Key `argument' is handled just like in comp-model-simple. Key
`prefix' describes prefixes and corresponding arguments. Key
`omitpresent' describes whether completion of already present prefixes
should be omitted. Key `preflist' lists prefixes that can take
multiple values. Key `allowtrun' describes whether prefixes can be
truncated (they can by default). Key `altpref' lists `alternating'
prefixes (prefixes that can appear either as `prefix', `noprefix' or
`prefix value' (latter is possible only if it is present in `prefix'
key)).
comp-model-inputactions comp-model-inputsimple
comp-model-inputwords comp-model-inputpref
input{model} comp-model-input
Like {model}, but for use in input() completion.
comp-model-insertactions comp-model-insertsimple
comp-model-insertwords comp-model-insertpref
insert{model} comp-model-insert
Like {model}, but for use in insert mode completion (see
complete()). For insert-mode models additional key is allowed:
`start': it defines where completed word starts and is either a string
starting with `_', regular expression or function reference.
If `start' key is a function reference, it must take current line
contents (string, not including part starting from the cursor
position) and return column number which will be passed as a first
argument to complete() function. If this function will return
something other then positive integer, then completion will be aborted
and nothing will be completed.
If `start' key is a regular expression (which must not start with `_',
use /\%( if you need to have `_' at the start of regular
expression), then match() with current line contents (not including
part starting from the cursor position, so /$ will match before
cursor position) as a first argument and this regex as a second must
give starting column (first argument to complete()). If match()
fails, then completion will be aborted and nothing will be completed.
Value of `start' key may be also one of the following strings:
String Description
_cword Complete word before the cursor. Considers words that
contains only blank characters to be empty. It is the default
behavior if `start' key was not specified.
_cWORD Complete WORD before the cursor. Considers WORDs that
contains only blank characters to be empty.
_cfile Complete filename before the cursor.
There are also two additional keys that are valid for any model: argsplitregex
and escape. Key `argsplitregex' must contain a regular expression which will
be passed to split() when plugin will try to split current line into an
arguments list. Default value: '\(\\\@<!\(\\.\)*\\\)\@<! ' (splits on
non-escaped spaces). Note that for insert-mode completion `start' has an
advantage over `argsplitregex', so the last word is determined by it and won't
be split. Key `escape' determines, whether completion list will be escaped by
fnameescape() function (2), using escape() with `\\|\" \n' as a second
argument (1) or not escaped at all (0). Default value: 1 for normal
(command-line) models, 0 for input and insert models.
==============================================================================
4. Argument descriptions comp-listdescription
Argument description is a list that contains two item: first is the type of
description and second is description argument:
Type Argument and description
list List comp-descr-list
Take possible variants from the specified list.
keyof Dictionary comp-descr-keyof
Take possible variants from the list of keys of the specified
dictionary.
file String comp-descr-file
Take possible variants from the list of files created by zsh-like
completion function. {Argument} is a string with the following form: >
([drwW])*(.{ext})*(/{regex})*
< This string consist of the following atoms:
1. One or more characters that describe type of the file: `d' stands
for `directory', `r' for `readable file' (but not readable
directory), `w' for `writeable file', `W' for `writeable file or
directory'. Note that directories will always be completed, even if
both `d' and `W' are absent. Use `d' if you want to complete only
directories.
2. .{ext} describes extension of the files. It may appear more then
once. Note that {ext} may contain escaped dot, so if you need to
complete gzipped tar archives, you can use `.tar\.gz.tgz'.
Extensions are matched case insensitively.
3. /{regex} describes regular expression which must be matched by file
name. By default, regex is matched case insensitively, but you may
use /\C.
Note: `W.tar.7z/\.\(zip\|rar\)$' means the following: complete
writeable files (`W') that end with `\.tar' (`.tar'), `.7z'
(.7z), `.zip' or `.rar' (`/\.\(zip\|rar\)$')
([drwW] AND (.{ext1} OR .{ext2} OR ...
OR /{regex1} OR /{regex2} OR ...)).
Note: You may use `=file' instead of `file' as a type of argument
description. Equality sign enables strict matching: if it is not
enabled, then absense of matches will disable filter, otherwise
it will complete nothing.
file! {Check} comp-descr-file!
Like file, but resulting file list is filtered through
chk-func-checkargument. If there are no matches, {Argument} is
ignored. For example, argument description ["file", ".txt"] and
["file!", ["regex", '\.txt$']] are just the same, but first version is
faster.
Note: You may use `=file!' instead of `file!' as a type of argument
description. Equality sign enables strict matching: if it is not
enabled, then absense of matches will disable filter, otherwise
it will complete nothing.
func Function reference comp-descr-func
Take possible variants from the returned value of a function provided
as {Argument} called with an only argument: {ArgLead}. This function
must return a list of Strings, all values that are not Strings are
ignored. Note that comp.vim will filter resulting list for you, so you
do not need to care about it.
func! Function reference comp-descr-func!
Like comp-descr-func, but without any filtering.
merge [{ListDescription}] comp-descr-merge
Merge lists of possible values obtained after processing all
{ListDescription}s.
first [{ListDescription}] comp-descr-first
Process {ListDescription}s given in {Argument}, return first non-empty
list of possible values or empty list if all descriptions gave an
empty list.
==============================================================================
5. Options comp-options
TrailingSeparator :: Bool comp-opt-TrailingSeparator
If this option is present and is true (default), then comp-descr-file
and comp-descr-file! add path separator at the end of each directory
name.
vim: ft=help:tw=78