= Vimscript Functions =

<<TableOfContents>>

----



== Example ==

Source a file like:

{{{
function HelloWorld()
  echom "Hello, World!"
endfunction
}}}

Or run the following in an interactive `vim(1)` session:

{{{
:function HelloWorld()
:  echom "Hello, World!"
:endfunction
}}}

----



== Definition ==

A function is defined with the `:function` command. Function names ''must'' begin with an uppercase letter.

If a function is defined within a scope, it may begin with a lwoercase letter. Best practice is to always use an uppercase letter anyway.



=== Arguments ===

A function that takes no arguments can be defined like:

{{{
:function Foo()
:  echom "Foo"
:endfunction
}}}

A function that takes an argument can be defined like:

{{{
:function Bar(bar)
:  echom a:bar
:endfunction
}}}

Note the `a:` scope on references to the argument. The argument is otherwise referenced by name.

Note also that the `a:` scope is immutable.

A function that takes any number of arguments can be defined like:

{{{
:function Baz(...)
:  echom a:0
:  echom a:1
:endfunction
}}}

The elipses (`...`) capture zero or more arguments. Note that the captured arguments are referenced by index like `a:0`.

These argument specifications can be mixed. A function that takes two or more arguments could be defined with `:function Ham(spam, eggs, ...)`.



=== Return Values ===

If a function does not return explicitly, it returns 0. This can lead to tricky logic bugs, especially when functions are used in boolean checks.

{{{
:if TextwidthIsTooWide()
:  echom "WARNING: Wide text!"
:endif
}}}

On the other hand, it can also make writing functions with a boolean return value simpler. Only the true cases have to be checked and returned explicitly; the false cases will pass through and implicitly return 0.

{{{
:function TextwidthIsTooWide()
:  if &l:textwidth ># 80
:    return 1
:  endif
:endfunction
}}}

----



== Usage ==

A function can be called explicitly, like:

{{{
:call Function()
}}}

In this case, the return value is thrown away.

To call a function and immediately print the return value (as though it were a constructed message), try:

{{{
:function HelloWorld()
:  return "Hello, World!"
:endfunction
:echom HelloWorld()
}}}



----
CategoryRicottone