7

I had installed Janus with my MacVim setup. In order to learn about how vim scripts work, I've been reading through the vimrc file that Janus uses, and I don't understand how the author of this is using functions. For example, here's one of the functions in the vimrc:

function s:setupWrapping()
  set wrap
  set wrapmargin=2
  set textwidth=72
endfunction

Now, according to the Defining a function section of the vim manual, 'Function names must begin with a capital letter.' According to the Local mappings and functions section of the manual, 'When defining a function in a script, "s:" can be prepended to the name to make it local to the script.' However, there's no mention of being able to begin a function name with a lower case letter when specifying its scope as local to the script.

So, is the function as written syntactically incorrect but works anyway, or is it syntactically correct but I can't find the documentation that says so?

Chuck
  • 4,662
  • 2
  • 33
  • 55

2 Answers2

8

As I understand it, the rule about capitalizing function names is intended to avoid conflicts with vim's built-in functions. There's no possibility of conflict from script-local functions, so it seems reasonable that the restriction would not apply to them, since you must always prefix them with their namespace qualifier.

ZyX corrected me in the comments, pointing out that, contradictory to an earlier revision of this answer, vim does not allow buffer-scope functions to be declared. You can declare a global function with a name like b:function_name, or for that matter _:function_name, but this is confusing and probably a terrible idea, for reasons mentioned in the comments.

Functions declared within a dictionary do not need to be capitalized.

Buffer-scope Funcrefs, and presumably other Funcrefs outside of global or function-level scope ("local" Funcrefs) do not need to be capitalized. But they have limited usefulness anyway, since a Funcref must reference either a global or script-scope function (the latter being syntactically awkward) or a dictionary function; in the latter case you have to call it with call(funcref, args, dict).

But anyway, you're looking for documentation, so I did a :helpgrep capital and found these nuggets of wisdom:

E704: A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:".

E124: « Define a new function by the name {name}. The name must be made of alphanumeric characters and '_', and must start with a capital or "s:" (see above). » The "see above" pointer refers to the sections user-functions and local-function, which provide more detail but don't mention anything about the non-capitalization of script-scope functions. user-functions mentions that The function name must start with an uppercase letter, to avoid confusion with builtin functions.

It may be that the strict rule of always starting a function name with a capital was true before the advent of other scopes, of which script scope seems to have been the first, or at least the first capable of including function declarations. I'm guessing that the parts of the manual which assert such a rule have just not been updated to reflect the state of modern vim.

intuited
  • 23,174
  • 7
  • 66
  • 88
  • Thanks very much. I figured that the reason was to avoid built-in function conflicts and that specifying that a function is local scoped negates that need, but wanted to make sure that this was vim's documented behavior before I tried to use the feature. – Chuck May 29 '11 at 04:50
  • There are no buffer-local functions. And there are really no script-local functions: `s:` just gets replaced with `{SID}_`, but function is still global. You can manually define function like `1_exampleFunction` even outside first sourced script. – ZyX May 29 '11 at 09:19
  • You can define anonymous functions that are not accessible without a function reference (so you will have to use a debugger if this reference is stored only in script-local variable as such variables are really script-local), but with disadvantage of having `dict` attribute set. It is the only way to define buffer-local function. – ZyX May 29 '11 at 09:22
  • And, third, you can define function named `_:_`: `{letter}:{name}` has nothing to do with scopes. `s:` is replaced and that's all. I do not know why this was implemented and I can't find this fact in documentation, so I suggest you not to use this in scripts. – ZyX May 29 '11 at 09:24
  • @ZyX: Yeah, that is pretty strange. This is why I thought that buffer-local functions existed: I didn't notice that the `b:Testing` function I'd declared was actually a global function. I agree that it's probably not a good idea to declare such a function — it might be possible only because of a parser bug. Anyway, the letter following the `:` doesn't have to be capitalized. – intuited May 29 '11 at 16:05
  • @ZyX: Sometimes I declare a function in scripts that I'm developing that just does `return eval(a:0)`. This makes it possible to access script-scope variables from outside of the script context. – intuited May 29 '11 at 16:09
  • @ZyX: Err, make that `return eval(a:1)`. – intuited May 29 '11 at 16:27
  • @intuited: I do it in both my frameworks: `execute frawor#Setup(...)` in addition to other things declares `s:Eval` function (which is then used to get script id and sometimes in a mappings where script-local variables are not accessible otherwise). You can as well put somewhere a `s:` dictionary thus grunting access to all script-local variables. – ZyX May 29 '11 at 19:34
  • About calling a dictionary function: in addition to `call(dict.name, [args], dict)` `dict.name(args)` also works. For buffer-local function references it will be `b:.name(args)` (note the dot). You may even define a function in the following fashion: `function b:name(args)` is global definition, `function b:.name(args)` is buffer-local anonymous function. – ZyX May 29 '11 at 19:37
  • One remark that forbids using anonymous functions as lambdas: anonymous functions **are global**! They just have a name that is an unsigned integer written as string and I don't know what will happen if number of created anonymous functions will be greater then greatest integer. This does not disable the fact that neither of `42(args)`, `call(function(42), [args], {})` or `call(function('42'), [args], {})` works. – ZyX May 29 '11 at 19:42
  • Some time ago there was a bug that you can assign a function reference to `g:.input` and it will override built-in `input()` function. It is fixed now (it was me who noticed it as most of my plugins define exactly no non-anonymous functions, so I was interested in what I can do with them). There is still one disadvantage: you can't use anonymous functions with `sort()`. – ZyX May 29 '11 at 19:52
  • @ZyX: Right, because they have to be supplied with a dictionary. Similar problem for things like command completion. I guess if you want to do that you can generate your own "anonymous" function by incrementing a numeric suffix to some prefix. Really nasty, but I guess it would work. Actual first-class functions would be really nice, but they don't seem to be anywhere on the features votes list, at least not last I checked. It seems like improved Python integration might make the question moot, anyway — that was very near the top of the list. – intuited May 29 '11 at 23:57
-3

I suppose you'll never know if there's documentation but you can't find it.

However, I looked at Derek Wyatt's vimrc file on his blog and he consistently uses a capital first letter in function names.

This just proves, only, that he's read the manual too.

pavium
  • 14,808
  • 4
  • 33
  • 50