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?
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.
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.
Related
The exact problem: I have a source in C++ and I need to replace a symbol name to some other name. However, I need that this replace the symbol only, not accidentally the same looking word in comments or text in "".
The source information what particular language section it is, is enough defined in the syntax highlighting rules. I know they can fail sometimes, but let's state this isn't a problem. I need some way to walk through all found occurrences of the phrase, then check in which section it is found, and if it's text or comment, this phrase should be skipped. Otherwise the replacement should be done either immediately, or by asking first, depending on well known c flag.
What I imagine would be at least theoretically possible is:
Having a kinda "callback" when doing substitution (called for each phrase found, and requesting the answer whether to substitute or not), or extract the list of positions where the phrase has been found, then iterate through all of them
Extract the name of the current "hi-linked" syntax highlighting rule, which is used to color the text at given position
Is it at all possible within the current features of vim?
Yes, with a :help sub-replace-expression, you can evaluate arbitrary expressions in the replacement part of :substitute. Vim's synID() and synstack() functions allow you to get the current syntax element.
Luc Hermitte has an implementation that omits replacement inside strings, here. You can easily adapt this to your use case.
With the help of my ingo-library plugin, you can define a short predicate function, e.g. matching comments and constants (strings, numbers, etc.):
function! CommentOrConstant()
return ingo#syntaxitem#IsOnSyntax(getpos('.'), '^\%(Comment\|Constant\)$')
endfunction
My PatternsOnText plugin now provides a :SubstituteIf command that works like :substitute, but also takes a predicate expression. With that, it's very easy to do a replacement anywhere except in comments or constants:
:%SubstituteIf/pattern/replacement/g !CommentOrConstant()
I am reading Learn Vim Script the Hard Way and hit something that confused me whilst doing the exercise to convert the folding functions to script local ones.
I tried to go this:
setlocal foldexpr=<SID>GetPotionFold(v:lnum)
and renamed all the functions to start with s:
To my surprise this didn't work and every line had a fold level of 0? It works if I put GetPotionFold into the global scope. Do you have to use a globally scoped function when assigning it to a option? Why?
The <SID> can be used in a mapping or menu, unfortunately not in an option. (This is a shortcoming in the implementation.)
You'd either have to translate it into the actual <SNR>NNN_ prefix (there's an s:SID() example function at :help <SID>), or use a different scope that is accessible from outside the script that defines the function. It's commendable that you want to avoid clobbering the global function namespace, as this is prone to name clashes.
A nice trick is using the autoload function prefix; it doesn't just work in autoload scripts, but can also be used elsewhere, e.g. in plugin scripts. Just prepend the script's name, and you'll have a function that can be invoked from anywhere, but scoped to the script's name:
:function! MyScriptName#GetPotionFold(lnum)
...
:setlocal foldexpr=MyScriptName#GetPotionFold(v:lnum)
Adding to the previous answer, you could define the function s:SID() to determine the script number as in the help documentation and then use execute to set the fold expression as following:
exe "setlocal foldexpr=<SNR>" . s:SID() . "_GetPotionFold(v:lnum)"
I have two question about understand those vim script. please give some help,
Question 1:
I download a.vim plugin, and i try to read this plugin, how to understand the below variable definition? the first line I can understand, but the second line, I don't know exactly "g:alternateExtensions_{'aspx.cs'}" means.
" E.g. let g:alternateExtensions_CPP = "inc,h,H,HPP,hpp"
" let g:alternateExtensions_{'aspx.cs'} = "aspx"
Question 2:
how to understand "SID" before the function name, using like below function definition and function call.
function! <SID>AddAlternateExtensionMapping(extension, alternates)
//omit define body
call <SID>AddAlternateExtensionMapping('h',"c,cpp,cxx,cc,CC")
call <SID>AddAlternateExtensionMapping('H',"C,CPP,CXX,CC")
thanks for you kindly help.
let g:alternateExtensions_{'aspx.cs'} = "aspx"
That is an inline expansion of a Vimscript expression into a variable name, a rather obscure feature that is rarely used since Vim version 7. See :help curly-braces-names for details. It is usually used to interpolate a variable, not a string literal like here ('aspx.cs'). Furthermore, this here yields an error, because periods are forbidden in variable names. Newer plugins would use a List or Dictionary variable, but those data types weren't available when a.vim was written.
To avoid polluting the function namespace, plugin-internal functions should be script-local, i.e. have the prefix s:. To invoke these from a mapping, the special <SID> prefix has to be used instead of s:, because <SID> internally gets translated into something that keeps the script's ID, whereas the pure s:, when executed as part of the mapping, has lost its association to the script that defined it.
Some plugin authors don't fully understand this unfortunate and accidental complexity of Vim's scoping implementation either, and they put the <SID> prefix also in front of the function name (which works, too). Though it's slightly more correct and recommended to write it like this:
" Define and invoke script-local function.
function! s:AddAlternateExtensionMapping(extension, alternates)
...
call s:AddAlternateExtensionMapping('h',"c,cpp,cxx,cc,CC")
" Only in a mapping, the special <SID> prefix is actually necessary.
nmap <Leader>a :call <SID>AddAlternateExtensionMapping('h',"c,cpp,cxx,cc,CC")
<SID> is explained in :help <SID>:
When defining a function in a script, "s:" can be prepended to the name to
make it local to the script. But when a mapping is executed from outside of
the script, it doesn't know in which script the function was defined. To
avoid this problem, use "<SID>" instead of "s:". The same translation is done
as for mappings. This makes it possible to define a call to the function in
a mapping.
When a local function is executed, it runs in the context of the script it was
defined in. This means that new functions and mappings it defines can also
use "s:" or "<SID>" and it will use the same unique number as when the
function itself was defined. Also, the "s:var" local script variables can be
used.
That number is the one you see on the left when you do :scriptnames, IIRC.
So here's my problem. I've gotten exuberant ctags working with Vim, and it works great, most of the time. One thing that still irks me though is whenever I try to search for a function that is named the same as some variable name. I sometimes get the right tag on the first try, sometimes not. Then after I pull up the list of alternate tags with :tselect, it comes up with a list of tags for both function definitions or variable definitions/assignments. (I'm in PHP so definitions and assignments are syntactically indistinguishable).
However, I notice that there's a column labeled 'kind' that has a value of 'f' or 'v', for function and variable, respectively. I can't seem to find a whole lot of information about this field, it seems like it may not be exactly standardized or widely used. My question is: can you filter tag results in Vim by "kind"?
Ideally, the default would be to search the whole tags file, but by specifying some extra flag, you could search a specific ('f' or 'v') kind only.
This is such a small problem for me as it doesn't come up THAT often, but sometimes it's the small problems that really annoy you.
You can certainly generate ctag files with any combination of php-kinds that you want (see the ouput of the command ctags --list-kinds.)
If you feel it's worth the effort you can make a vim function tagkind and bind it to a command. The tagkind function can overwrite the current tags vim variable to point at only the tag file with the kinds that you are interested in and call :tag. Optionally, it can store the previous version of the tags variable and restore it after this one call.
Unfortunately, I don't know of anyway other than this. Perhaps someone else would know.
I generate python ctags with --python-kinds=-i to exclude tags for import statements (which are useless). Maybe you could generate with --php-kinds=-v and drop a class of tags completely.
You can read :help tag-priority. Apparently the "highest-priority" tag is chosen based on some hard-coded logic.
fzf with fzf.vim has a :Tags (for the whole project) and :BTags for the current file option that generates ctags on the fly.
An issue raised on the plugin 'Skip tag kinds in :BTags and :Tags' gives the following code that you can use to only generated tags for a particular kind. I've modified the below so that it should only search for the PHP f kind.
command! BTagsEnhanced
\ call fzf#vim#buffer_tags(<q-args>, [
\ printf('ctags -f - --sort=no --php-kinds=f --excmd=number --language-force=%s %s', &filetype, expand('%:S'))], {})
Note as per my comment on the question, there is a potential Vim tagfinder.vim plugin via a blog post on Vim and Ctags: Finding Tag Definitions. But I haven't tried it.
I'd like to highlight variables in my (Maple-code, but doesn't matter much) code which are global for routines.
e.g. I have
global_var1:=1;
global_var2:=2;
...
some_proc:=proc()
local local_var1, global_var2;
local_var1:=1;
local_var2:=local_var1*global_var1+global_var2;
end proc;
I want to highlight global_var1 inside of some_proc() in this example. Obviously the naming is not so trivial in general as in the example.
Can I use ctags to do this?
It depends on ctags. With some languages it is unable to extract local variables (viml), with other languages, it doesn't detect all local variables (C++). Hence, the first thing you'll have to do is to see what ctags can do for your language (Maple).
The other difficulty is to restrict the highlighting to one specific function, and to stay synchronized every time newlines are inserted to the edited file. I know no easy way to do this -- may be with a vim syntax region that starts at local.*{global-name} and ends at end proc to neutralize the highlighting of all global variables?
One task that'll be much more easier would be to highlight variable masking, i.e. highlight global_var2 at the point in the function where it is declared local. Alas, it's not what you're looking for.