Customizing Command Completion in Vim with Custom Functions

*:command-completion* *E179* *E180* *E181* *:command-complete* By default, the arguments of user defined commands do not undergo completion. However, by specifying one or the other of the following attributes, argument completion can be enabled: -complete=arglist file names in argument list -complete=augroup autocmd groups -complete=breakpoint |:breakadd| suboptions -complete=buffer buffer names -complete=color color schemes -complete=command Ex command (and arguments) -complete=compiler compilers -complete=diff_buffer diff buffer names -complete=dir directory names -complete=dir_in_path directory names in |'cdpath'| -complete=environment environment variable names -complete=event autocommand events -complete=expression Vim expression -complete=file file and directory names -complete=file_in_path file and directory names in |'path'| -complete=filetype filetype names |'filetype'| -complete=function function name -complete=help help subjects -complete=highlight highlight groups -complete=history |:history| suboptions -complete=keymap keyboard mappings -complete=locale locale names (as output of locale -a) -complete=lua Lua expression |:lua| -complete=mapclear buffer argument -complete=mapping mapping name -complete=menu menus -complete=messages |:messages| suboptions -complete=option options -complete=packadd optional package |pack-add| names -complete=runtime file and directory names in |'runtimepath'| -complete=scriptnames sourced script names -complete=shellcmd Shell command -complete=shellcmdline First is a shell command and subsequent ones are filenames. The same behavior as |:!cmd| -complete=sign |:sign| suboptions -complete=syntax syntax file names |'syntax'| -complete=syntime |:syntime| suboptions -complete=tag tags -complete=tag_listfiles tags, file names are shown when CTRL-D is hit -complete=user user names -complete=var user variables -complete=custom,{func} custom completion, defined via {func} -complete=customlist,{func} custom completion, defined via {func} If you specify completion while there is nothing to complete (-nargs=0, the default) then you get error *E1208* . Note: That some completion methods might expand environment variables. Custom completion ~ *:command-completion-custom* *:command-completion-customlist* *E467* *E468* It is possible to define customized completion schemes via the "custom,{func}" or the "customlist,{func}" completion argument. The {func} part should be a function with the following signature: > :function {func}(ArgLead, CmdLine, CursorPos) The function need not use all these arguments. The function should provide the completion candidates as the return value. For the "custom" argument, the function should return the completion candidates one per line in a newline separated string. For the "customlist" argument, the function should return the completion candidates as a Vim List. Non-string items in the list are ignored. The function arguments are: ArgLead the leading portion of the argument currently being completed on CmdLine the entire command line CursorPos the cursor position in it (byte index) The function may use these for determining context. For the "custom" argument, it is not necessary to filter candidates against the (implicit pattern in) ArgLead. Vim will filter the candidates with its regexp engine after function return, and this is probably more efficient in most cases. If 'wildoptions' contains "fuzzy", then the candidates will be filtered using |fuzzy-matching|. For the "customlist" argument, Vim will not filter the returned completion candidates and the user supplied function should filter the candidates. The following example lists user names to a Finger command > :com -complete=custom,ListUsers -nargs=1 Finger !finger <args> :fun ListUsers(A,L,P) : return system("cut -d: -f1 /etc/passwd") :endfun The following example completes filenames from the directories

This section explains how to enable and customize command argument completion in Vim using the `-complete` attribute. It lists various built-in completion types (e.g., files, buffers, commands, options) and details how to create custom completion schemes using `custom,{func}` or `customlist,{func}`. It describes the function signature required for custom completion functions, the arguments passed to them (ArgLead, CmdLine, CursorPos), and the format of the return value (newline-separated string for `custom` and a Vim List for `customlist`). It also mentions how Vim filters candidates and provides an example of listing user names for a Finger command.