Two types of method call

Question

What is the difference between the following two ways of calling a function/method in vimscript?

" This seems to always work
call add (events, e)

" This seems to occasionally work
events->add(e)

For example, with the latter command, it works when running in the command-line, but when running in a function it returns:

E492: Not an editor command: events->add(e)

It seems pretty inconsistent too, because literally the line above it I am doing:

if (all_valid_events->index(e) != -1)   <-- this works   
    events->add(e)                      <-- this fails

Additionally, is there a 'name' for the two different type of function calls? Is one preferred over the other (or why are there two different ways, one of which only works about half of the time?)

Answer 1

See :help method.

Global functions can be called as methods on their first argument. But that only works in an expression.

When :call is used, you need to use normal function syntax.

In Vimscript, functions tyically fit best in expressions, that's probably why the method syntax is only available there. (:call is there if you just need to call a function and ignore the result, but expressions are where functions really shine.)

Recent Vimscript has also introduced :eval, which allows calling a method for its side effects, similarly to :call. From :help :eval:

Evaluate {expr} and discard the result. The expression is supposed to have a side effect, since the resulting value is not used. This is similar to :call but works with any expression.

The method syntax can be really useful when you have 4 or 5 chained function calls. :help method has a good example of that:

mylist->filter(filterexpr)->map(mapexpr)->sort()->join()

Compare that with the equivalent:

join(sort(map(filter(mylist, filterexpr), mapexpr)))

Note that the method syntax was introduced to Vim quite recently (set of patchsets around 8.1.18xx), so if you care about compatibility with older versions of Vim (even as recent as Vim 8.0 or a not fully patched Vim 8.1), you might want to avoid method syntax as it might not be available.