vim functions with script scope

Question

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?

Answer 1

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.