diff options
Diffstat (limited to 'runtime/doc/usr_41.txt')
| -rw-r--r-- | runtime/doc/usr_41.txt | 135 |
1 files changed, 76 insertions, 59 deletions
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 41948f577e..4cba5a33d0 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -41,6 +41,12 @@ prefer. And you can use any colon command in it (commands that start with a specific file type. A complicated macro can be defined by a separate Vim script file. You can think of other uses yourself. + If you are familiar with Python, you can find a comparison between + Python and Vim script here, with pointers to other documents: + https://gist.github.com/yegappan/16d964a37ead0979b05e655aa036cad0 + And if you are familiar with JavaScript: + https://w0rp.com/blog/post/vim-script-for-the-javascripter/ + Let's start with a simple example: > :let i = 1 @@ -93,6 +99,8 @@ and the value of the variable i. Since i is one, this will print: Then there is the ":let i += 1" command. This does the same thing as ":let i = i + 1". This adds one to the variable i and assigns the new value to the same variable. +Note: this is how it works in legacy Vim script, which is what we discuss in +this file. The example was given to explain the commands, but would you really want to make such a loop, it can be written much more compact: > @@ -107,21 +115,29 @@ if you are impatient. FOUR KINDS OF NUMBERS -Numbers can be decimal, hexadecimal, octal or binary. A hexadecimal number -starts with "0x" or "0X". For example "0x1f" is decimal 31. An octal number -starts with a zero. "017" is decimal 15. A binary number starts with "0b" or -"0B". For example "0b101" is decimal 5. Careful: don't put a zero before a -decimal number, it will be interpreted as an octal number! - The ":echo" command always prints decimal numbers. Example: > +Numbers can be decimal, hexadecimal, octal or binary. + +A hexadecimal number starts with "0x" or "0X". For example "0x1f" is decimal +31. + +An octal number starts with "0o", "0O" or a zero and another digit. "0o17" is +decimal 15. Using just a zero prefix is not supported in Vim9 script. + +A binary number starts with "0b" or "0B". For example "0b101" is decimal 5. + +A decimal number is just digits. Careful: don't put a zero before a decimal +number, it will be interpreted as an octal number in legacy script! + +The ":echo" command always prints decimal numbers. Example: > - :echo 0x7f 036 + :echo 0x7f 0o36 < 127 30 ~ A number is made negative with a minus sign. This also works for hexadecimal, octal and binary numbers. A minus sign is also used for subtraction. Compare this with the previous example: > - :echo 0x7f -036 + :echo 0x7f -0o36 < 97 ~ White space in an expression is ignored. However, it's recommended to use it @@ -129,7 +145,7 @@ for separating items, to make the expression easier to read. For example, to avoid the confusion with a negative number above, put a space between the minus sign and the following number: > - :echo 0x7f - 036 + :echo 0x7f - 0o36 ============================================================================== *41.2* Variables @@ -319,9 +335,9 @@ Grouping is done with parentheses. No surprises here. Example: > :echo (10 + 5) * 2 < 30 ~ -Strings can be concatenated with ".". Example: > +Strings can be concatenated with ".." (see |expr6|). Example: > - :echo "foo" . "bar" + :echo "foo" .. "bar" < foobar ~ When the ":echo" command gets multiple arguments, it separates them with a @@ -488,9 +504,9 @@ So far the commands in the script were executed by Vim directly. The very powerful way to build commands and execute them. An example is to jump to a tag, which is contained in a variable: > - :execute "tag " . tag_name + :execute "tag " .. tag_name -The "." is used to concatenate the string "tag " with the value of variable +The ".." is used to concatenate the string "tag " with the value of variable "tag_name". Suppose "tag_name" has the value "get_cmd", then the command that will be executed is: > @@ -506,7 +522,7 @@ This jumps to the first line and formats all lines with the "=" operator. To make ":normal" work with an expression, combine ":execute" with it. Example: > - :execute "normal " . normal_commands + :execute "normal " .. normal_commands The variable "normal_commands" must contain the Normal mode commands. Make sure that the argument for ":normal" is a complete command. Otherwise @@ -523,12 +539,12 @@ If you don't want to execute a string but evaluate it to get its expression value, you can use the eval() function: > :let optname = "path" - :let optval = eval('&' . optname) + :let optval = eval('&' .. optname) A "&" character is prepended to "path", thus the argument to eval() is "&path". The result will then be the value of the 'path' option. The same thing can be done with: > - :exe 'let optval = &' . optname + :exe 'let optval = &' .. optname ============================================================================== *41.6* Using functions @@ -848,6 +864,7 @@ Insert mode completion: *completion-functions* complete_check() check if completion should be aborted complete_info() get current completion information pumvisible() check if the popup menu is displayed + pum_getpos() position and size of popup menu if visible Folding: *folding-functions* foldclosed() check for a closed fold at a specific line @@ -1127,7 +1144,7 @@ Example: > : let n = n + len(split(getline(lnum))) : let lnum = lnum + 1 : endwhile - : echo "found " . n . " words" + : echo "found " .. n .. " words" :endfunction You can call this function with: > @@ -1140,7 +1157,7 @@ It will be executed once and echo the number of words. range, with the cursor in that line. Example: > :function Number() - : echo "line " . line(".") . " contains: " . getline(".") + : echo "line " .. line(".") .. " contains: " .. getline(".") :endfunction If you call this function with: > @@ -1164,11 +1181,11 @@ so on. The variable "a:0" contains the number of extra arguments. :function Show(start, ...) : echohl Title - : echo "start is " . a:start + : echo "start is " .. a:start : echohl None : let index = 1 : while index <= a:0 - : echo " Arg " . index . " is " . a:{index} + : echo " Arg " .. index .. " is " .. a:{index} : let index = index + 1 : endwhile : echo "" @@ -1576,10 +1593,10 @@ Another useful mechanism is the ":finally" command: > :let tmp = tempname() :try - : exe ".,$write " . tmp - : exe "!filter " . tmp + : exe ".,$write " .. tmp + : exe "!filter " .. tmp : .,$delete - : exe "$read " . tmp + : exe "$read " .. tmp :finally : call delete(tmp) :endtry @@ -1600,7 +1617,7 @@ Here is a summary of items that apply to Vim scripts. They are also mentioned elsewhere, but form a nice checklist. The end-of-line character depends on the system. For Unix a single <NL> -character is used. For Windows <CR><LF> is used. This is important when +character is used. For Windows <CR><NL> is used. This is important when using mappings that end in a <CR>. See |:source_crnl|. @@ -1887,9 +1904,9 @@ for this mapping, but the user might already use it for something else. To allow the user to define which keys a mapping in a plugin uses, the <Leader> item can be used: > - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 22 map <unique> <Leader>a <Plug>TypecorrAdd; -The "<Plug>TypecorrAdd" thing will do the work, more about that further on. +The "<Plug>TypecorrAdd;" thing will do the work, more about that further on. The user can set the "mapleader" variable to the key sequence that he wants this mapping to start with. Thus if the user has done: > @@ -1905,15 +1922,15 @@ already happened to exist. |:map-<unique>| But what if the user wants to define his own key sequence? We can allow that with this mechanism: > - 21 if !hasmapto('<Plug>TypecorrAdd') - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 21 if !hasmapto('<Plug>TypecorrAdd;') + 22 map <unique> <Leader>a <Plug>TypecorrAdd; 23 endif -This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only +This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only defines the mapping from "<Leader>a" if it doesn't. The user then has a chance of putting this in his vimrc file: > - map ,c <Plug>TypecorrAdd + map ,c <Plug>TypecorrAdd; Then the mapped key sequence will be ",c" instead of "_a" or "\a". @@ -1930,8 +1947,8 @@ prepending it with "s:". We will define a function that adds a new typing correction: > 30 function s:Add(from, correct) - 31 let to = input("type the correction for " . a:from . ": ") - 32 exe ":iabbrev " . a:from . " " . to + 31 let to = input("type the correction for " .. a:from .. ": ") + 32 exe ":iabbrev " .. a:from .. " " .. to .. 36 endfunction @@ -1943,15 +1960,15 @@ function (without the "s:"), which is again another function. <SID> can be used with mappings. It generates a script ID, which identifies the current script. In our typing correction plugin we use it like this: > - 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add .. 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> Thus when a user types "\a", this sequence is invoked: > - \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add() + \a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add() -If another script would also map <SID>Add, it would get another script ID and +If another script also maps <SID>Add, it will get another script ID and thus define another mapping. Note that instead of s:Add() we use <SID>Add() here. That is because the @@ -1992,9 +2009,9 @@ difference between using <SID> and <Plug>: To make it very unlikely that other plugins use the same sequence of characters, use this structure: <Plug> scriptname mapname In our example the scriptname is "Typecorr" and the mapname is "Add". - This results in "<Plug>TypecorrAdd". Only the first character of - scriptname and mapname is uppercase, so that we can see where mapname - starts. + We add a semicolon as the terminator. This results in + "<Plug>TypecorrAdd;". Only the first character of scriptname and + mapname is uppercase, so that we can see where mapname starts. <SID> is the script ID, a unique identifier for a script. Internally Vim translates <SID> to "<SNR>123_", where "123" can be any @@ -2036,7 +2053,7 @@ a few lines to count the number of corrections: > 30 function s:Add(from, correct) .. 34 let s:count = s:count + 1 - 35 echo s:count . " corrections now" + 35 echo s:count .. " corrections now" 36 endfunction First s:count is initialized to 4 in the script itself. When later the @@ -2069,21 +2086,21 @@ Here is the resulting complete example: > 18 \ synchronization 19 let s:count = 4 20 - 21 if !hasmapto('<Plug>TypecorrAdd') - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 21 if !hasmapto('<Plug>TypecorrAdd;') + 22 map <unique> <Leader>a <Plug>TypecorrAdd; 23 endif - 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add 25 26 noremenu <script> Plugin.Add\ Correction <SID>Add 27 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> 29 30 function s:Add(from, correct) - 31 let to = input("type the correction for " . a:from . ": ") - 32 exe ":iabbrev " . a:from . " " . to + 31 let to = input("type the correction for " .. a:from .. ": ") + 32 exe ":iabbrev " .. a:from .. " " .. to 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif 34 let s:count = s:count + 1 - 35 echo s:count . " corrections now" + 35 echo s:count .. " corrections now" 36 endfunction 37 38 if !exists(":Correct") @@ -2122,7 +2139,7 @@ Here is a simple example for a plugin help file, called "typecorr.txt": > 6 There are currently only a few corrections. Add your own if you like. 7 8 Mappings: - 9 <Leader>a or <Plug>TypecorrAdd + 9 <Leader>a or <Plug>TypecorrAdd; 10 Add a correction for the word under the cursor. 11 12 Commands: @@ -2260,13 +2277,13 @@ To make sure mappings will only work in the current buffer use the > command. This needs to be combined with the two-step mapping explained above. An example of how to define functionality in a filetype plugin: > - if !hasmapto('<Plug>JavaImport') - map <buffer> <unique> <LocalLeader>i <Plug>JavaImport + if !hasmapto('<Plug>JavaImport;') + map <buffer> <unique> <LocalLeader>i <Plug>JavaImport; endif - noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc> + noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc> |hasmapto()| is used to check if the user has already defined a map to -<Plug>JavaImport. If not, then the filetype plugin defines the default +<Plug>JavaImport;. If not, then the filetype plugin defines the default mapping. This starts with |<LocalLeader>|, which allows the user to select the key(s) he wants filetype plugin mappings to start with. The default is a backslash. @@ -2283,12 +2300,12 @@ plugin for the mail filetype: > " Add mappings, unless the user didn't want this. if !exists("no_plugin_maps") && !exists("no_mail_maps") " Quote text by inserting "> " - if !hasmapto('<Plug>MailQuote') - vmap <buffer> <LocalLeader>q <Plug>MailQuote - nmap <buffer> <LocalLeader>q <Plug>MailQuote + if !hasmapto('<Plug>MailQuote;') + vmap <buffer> <LocalLeader>q <Plug>MailQuote; + nmap <buffer> <LocalLeader>q <Plug>MailQuote; endif - vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR> - nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR> + vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR> + nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR> endif Two global variables are used: @@ -2331,7 +2348,7 @@ should be undone. Set the b:undo_ftplugin variable to the commands that will undo the settings in your filetype plugin. Example: > let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" - \ . "| unlet b:match_ignorecase b:match_words b:match_skip" + \ .. "| unlet b:match_ignorecase b:match_words b:match_skip" Using ":setlocal" with "<" after the option name resets the option to its global value. That is mostly the best way to reset the option value. @@ -2452,17 +2469,17 @@ The following example shows how it's done: > map <F19> :call BufNetWrite('something')<CR> let s:did_load = 1 - exe 'au FuncUndefined BufNet* source ' . expand('<sfile>') + exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>') finish endif function BufNetRead(...) - echo 'BufNetRead(' . string(a:000) . ')' + echo 'BufNetRead(' .. string(a:000) .. ')' " read functionality here endfunction function BufNetWrite(...) - echo 'BufNetWrite(' . string(a:000) . ')' + echo 'BufNetWrite(' .. string(a:000) .. ')' " write functionality here endfunction |