Write your own Vim function

Tip 32 Printable Monobook Previous Next

created 2001 · complexity advanced · author slimzhao · version 5.7

---

Here are some quick rules for writing Vim script, compared with the C language and the bash shell.

A function name must start with an uppercase letter

hex2dec is invalid
Hex2dec is valid

C and bash allow both lowercase and uppercase.

However, Vim 7 :help autoload plugins allow an exception: they authorize lowercase functions like my#library#foo(), my#library#_internal(), etc.

How to reference function parameters

fu! Hex2dec(var1, var2)
  let str=a:var1
  let str2=a:var2

You must prefix a parameter name with "a:" (argument).

A function cannot change a parameter (let a:var1=1 is invalid).

In C, "a:" is not used, and a parameter is writable.

See :help a:1

How to implement a variable number of parameters

fu! Hex2dec(fixedparam, ...)

• a:0 is the number of extra parameters "..." used to call the function.
• a:1 is the first extra parameter.

For example:

:call Hex2dec("asdf", 4,5,6)

gives a:0 = 3, a:1 = 4, a:2 = 5, a:3 = 6.

See :help a:0 and also :help a:000

How to call a variadic function from another variadic function

Since Vim 7, iIt's possible thanks to :help function() and :help :call:

function! Hex2DecWrapper(...)
  let params = ['asdf'] + a:000
  :call call (function('Hex2Dec'), params)
endfunction

Where is the vim-library?

Vim has its own function library, see :help functions

Can I use the += or ++ operators?

• += exists in Vim since version 7.0
• ++ does not

How to use a variable

let var1=value
let var2=var1

Same as C, except you must use the let keyword.

See :help :let, and :help expression

Can any ex-mode command be used in a function?

Yes — each line can be an ex command.

Can a function call itself (recurse)?

Yes — but be careful to avoid an infinite loop.

Can a function call another function?

Yes — just like C.

Calling a function that returns nothing requires to call this function with :help :call. When a function returns something, the result can be used as any :help expression or ignored via :help :call.

Must I compile the function?

No, you needn't and you can't.

In Vim, enter the following command to source your script:

:so filename_containing_script

Now you can call the function.

If wanted, the ':so' (source) statement can be in your vimrc file.

Does Vim have integer or float or other data types?

No. Like Perl, the type of a Vim variable is determined by its context.

let a=1
let a=a."asdf"
echo a    (displays '1asdf')
let a=1
let a=a+2
echo a    (displays '3')

Must I append a ';' to every statement?

No, never do that.

If you want to combine several statements in a single line, use '|'.

';' is required in C, and optional in bash for each statement in a line.

References

• :help :function
• :help a:1
• :help expression
• :help functions

See also

• :help script
• :help autoload to write Vim library plugins
• :help script-local to hide functions in scripts
• A wiki book about Vim scripting