Viml commands

From wikinotes


:help user-commands

" syntax:
"     command [{attrs}] {name} {instructions}

command MyFunc :call MyFunc()


Define number of parameters that may be accepted

-nargs=0    No arguments are allowed (the default)
-nargs=1    Exactly one argument is required, it includes spaces
-nargs=*    Any number of arguments are allowed (0, 1, or many),
            separated by white space
-nargs=?    0 or 1 arguments are allowed
-nargs=+    Arguments must be supplied, but any number are allowed
function! Blah(arg)
    echo a:arg

command -nargs=1 Blah :call Blah('<args>')  " <args> is all args as string
command -nargs=* Blah :call Blah(<f-args>)  " <f-args> is arguments as a list of strs
:Blah 'abc'   " run command 'Blah'

Parameter Completion

:help command-complete

        -complete=arglist       file names in argument list
        -complete=augroup       autocmd groups
        -complete=buffer        buffer names
        -complete=behave        :behave suboptions
        -complete=color         color schemes
        -complete=command       Ex command (and arguments)
        -complete=compiler      compilers
        -complete=cscope        :cscope suboptions
        -complete=dir           directory names
        -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=locale        locale names (as output of locale -a)
        -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=shellcmd      Shell command
        -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}

  \ -complete=customlist,ListUsers
  \ -nargs=1
  \ Login :call Login(<args>)

function+ ListUsers(arg_lead, cmd_line, cursor_pos)
    return s:autocomplete_from_list(["you", "me", "other"], a:arg_lead, a:cmd_line, a:cursor_pos)

function! s:autocomplete_from_list(choices, arg_lead, cmd_line, cursor_pos)
    " if no characters, all allow options
    if (a:arg_lead =~ '\v^\s*$')
        return a:choices

    " if characters typed, complete specific to typed
    let l:completions = []
    for l:item in a:choices
        if (l:item =~ '^' . a:arg_lead . '.*')
            let l:completions = add(l:completions, l:item)
    return l:completions

Selection Ranges

Functions and commands both have a special syntax to handle accepting visual selection ranges.

function! PrintSelectedLines() range
    echom getline(a:firstline, a:lastline)  " array of selected lines

command -range PrintSelectedLines <line1>,<line2>call PrintSelectedLines()

<Plug> commands

SO: how to execute plug commands
why you should use plug

<Plug> is designed for use within plugins.

  • define the modes the command is available in
  • define multiple keybindings for the same action

Defining Plug commands

" define function, to be called
function Foo()
    " ...

" define a command, available within insert
inoremap <silent> <Plug>Foo <C-R>=Foo()<CR>

" map that command
inoremap <c-j> <Plug>Foo

Calling Plug commands

" run function
exec "normal \<Plug>function"

" bind command for function
command MyCommand  silent exec "normal \<Plug>(my-command)"