Vimscript function

Like most programming languages, Vimscript supports functions. Let's look at how to create functions, and then we'll talk about their quirks.

Execute the following command:

:function meow()

You might think that this will define the meow Unfortunately, that's not the case, we've dropped into one of Vimscript's pits.

Vimscript functions without scope restrictions must begin with a capital letter!

Even if you're really limiting the scope of the function (we'll talk about it in a while), you'd better start with a capital letter. Most Vimscript program apes do this, so don't make an exception.

ok, it's time to define a function carefully. Execute the following command:

:function Meow()
:  echom "Meow!"
:endfunction

This time Vim happily defines a function. Let's try running it:

:call Meow()

Unsurprisingly, Vim shows Meow!

Let's try to get it back to a value. Execute the following command:

:function GetMeow()
:  return "Meow String!"
:endfunction

Now try this command:

:echom GetMeow()

Vim will call this function and pass the result to echom showing Meow String!

Call the function

As we've seen, there are two different ways to call functions in Vimscript.

Use the call command when you want to call a function call Follow these commands:

:call Meow()
:call GetMeow()

The first function outputs Meow! but the second does not have any output. When you use call the return value is discarded, so this method is only useful if the function has side effects.

The second method is to call the function in the expression. Y ou don't need call time, you just need to refer to the name of the function. Execute the following command:

:echom GetMeow()

As we've seen, this calls GetMeow passes the return value to echom

Implicit return

Execute the following command:

:echom Meow()

This will show two lines: Meow! a nd 0 T he first obviously comes Meow inside echom T he second tells us that if a Vimscript function does not return a value, it implicitly returns 0 . S ee what we can do with that. Follow these commands:

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

This function relates to many important concepts we learned earlier:

• if statement
• Use the option as a variable
• Access option variables in a specific scope
• Case-sensitive comparisons

If you're new to the above, it's a good idea to go through the first few chapters.

Now we've defined a function that tells us if textwidth buffer is 'too wide'. (Because the 80-character limit applies to any code file other than HTML)

Now let's use it. Execute the following command:

:set textwidth=80
:if TextwidthIsTooWide()
:  echom "WARNING: Wide text!"
:endif

What have we done here?

• At first we set the global textwidth to 80
• Then we run an if statement to determine TextwidthIsTooWide() is true.
• Because the condition is not if statement body (including inside and outside the function) is not executed.

Since we did not explicitly return a value, Vim returns 0 from the function that represents 'falsy'. T ry changing it. Run the following command:

:setlocal textwidth=100
:if TextwidthIsTooWide()
:  echom "WARNING: Wide text!"
:endif

This time if the function executes its statement 1 and if manually executes the statement body of it.

Practice

Read :help :call T he content about Scope is currently ignored. H ow many arguments can you pass to a function? Surprised, isn't it?

Read :help E124 Natural Segment and find out what characters you can use to name functions. C an I underline it? W hat about Dashes? A ccented characters? U nicode symbol? If you read the document or don't know, try it.

Read :help return W hat is the abbreviation for this command ("short form")? ( I said you shouldn't use it) Is it within your expectations? If not, why not?