Viml commands

Basics

:help user-commands

https://vimhelp.org/map.txt.html#user-commands

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

command MyFunc :call MyFunc()

Parameters

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
endfunc

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

https://stackoverflow.com/questions/12636068/vim-plugin-custom-auto-complete-of-params-in-command-mode

: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}

command
  \ -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)
endfunction

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
    endif

    " 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)
        endif
    endfor
    return l:completions
endfunction

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
endfunc

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

<Plug> commands

SO: how to execute plug commands	https://stackoverflow.com/questions/18546533/execute-plug-commands-in-vim
why you should use plug	https://whileimautomaton.net/2008/09/27022735

<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()
    " ...
endfunc

" 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)"