Mercurial > vim
changeset 26847:eafb9fd4ec32
Update runtime files
Commit: https://github.com/vim/vim/commit/04fb916684829f6aa12f33f14d0d0023b458f200
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu Dec 30 20:24:12 2021 +0000
Update runtime files
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Fri, 31 Dec 2021 13:30:06 +0100 |
| parents | fbe7e8fa0d2f |
| children | a2335ec31abc |
| files | runtime/doc/builtin.txt runtime/doc/change.txt runtime/doc/eval.txt runtime/doc/filetype.txt runtime/doc/insert.txt runtime/doc/tags runtime/doc/todo.txt runtime/doc/usr_41.txt runtime/syntax/vim.vim |
| diffstat | 9 files changed, 894 insertions(+), 918 deletions(-) [+] |
line wrap: on
line diff
--- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 8.2. Last change: 2021 Dec 27 +*builtin.txt* For Vim version 8.2. Last change: 2021 Dec 28 VIM REFERENCE MANUAL by Bram Moolenaar
--- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1,4 +1,4 @@ -*change.txt* For Vim version 8.2. Last change: 2021 Dec 27 +*change.txt* For Vim version 8.2. Last change: 2021 Dec 29 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1677,7 +1677,8 @@ r Automatically insert the current comme <Enter> in Insert mode. *fo-o* o Automatically insert the current comment leader after hitting 'o' or - 'O' in Normal mode. + 'O' in Normal mode. In case comment is unwanted in a specific place + use CTRL-U to quickly delete it. |i_CTRL-U| *fo-q* q Allow formatting of comments with "gq". Note that formatting will not change blank lines or lines containing
--- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.2. Last change: 2021 Dec 27 +*eval.txt* For Vim version 8.2. Last change: 2021 Dec 28 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1724,9 +1724,9 @@ It is deleted when the tab page is close without the |+windows| feature} *global-variable* *g:var* *g:* -Inside functions global variables are accessed with "g:". Omitting this will -access a variable local to a function. But "g:" can also be used in any other -place if you like. +Inside functions and in |Vim9| script global variables are accessed with "g:". +Omitting this will access a variable local to a function or script. "g:" +can also be used in any other place if you like. *local-variable* *l:var* *l:* Inside functions local variables are accessed without prepending anything. @@ -1736,8 +1736,10 @@ refers to "v:count". Using "l:count" yo same name. *script-variable* *s:var* -In a Vim script variables starting with "s:" can be used. They cannot be -accessed from outside of the scripts, thus are local to the script. +In a legacy Vim script variables starting with "s:" can be used. They cannot +be accessed from outside of the scripts, thus are local to the script. +In |Vim9| script the "s:" prefix can be omitted, variables are script-local by +default. They can be used in: - commands executed while the script is sourced
--- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -1,4 +1,4 @@ -*filetype.txt* For Vim version 8.2. Last change: 2021 Sep 22 +*filetype.txt* For Vim version 8.2. Last change: 2021 Dec 30 VIM REFERENCE MANUAL by Bram Moolenaar @@ -358,12 +358,12 @@ 2. Define your own mapping. Example: > You need to define your own mapping before the plugin is loaded (before editing a file of that type). The plugin will then skip installing the default mapping. - *no_mail_maps* + *no_mail_maps* *g:no_mail_maps* 3. Disable defining mappings for a specific filetype by setting a variable, which contains the name of the filetype. For the "mail" filetype this would be: > :let no_mail_maps = 1 -< *no_plugin_maps* +< *no_plugin_maps* *g:no_plugin_maps* 4. Disable defining mappings for all filetypes by setting a variable: > :let no_plugin_maps = 1 <
--- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -1,4 +1,4 @@ -*insert.txt* For Vim version 8.2. Last change: 2021 Dec 27 +*insert.txt* For Vim version 8.2. Last change: 2021 Dec 29 VIM REFERENCE MANUAL by Bram Moolenaar @@ -84,6 +84,8 @@ CTRL-U Delete all entered characters be line. If there are no newly entered characters and 'backspace' is not empty, delete all characters before the cursor in the current line. + If C-indenting is enabled the indent will be adjusted if the + line becomes blank. See |i_backspacing| about joining lines. *i_CTRL-I* *i_<Tab>* *i_Tab* <Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the @@ -1945,6 +1947,9 @@ When 'autoindent' is on, the indent for previous line. When 'smartindent' or 'cindent' is on, the indent for a line is automatically adjusted for C programs. +'formatoptions' can be set to copy the comment leader when opening a new +line. + 'textwidth' can be set to the maximum width for a line. When a line becomes too long when appending characters a line break is automatically inserted.
--- a/runtime/doc/tags +++ b/runtime/doc/tags @@ -6968,6 +6968,8 @@ g:netrw_win95ftp pi_netrw.txt /*g:netrw_ g:netrw_winsize pi_netrw.txt /*g:netrw_winsize* g:netrw_wiw pi_netrw.txt /*g:netrw_wiw* g:netrw_xstrlen pi_netrw.txt /*g:netrw_xstrlen* +g:no_mail_maps filetype.txt /*g:no_mail_maps* +g:no_plugin_maps filetype.txt /*g:no_plugin_maps* g:rust_bang_comment_leader ft_rust.txt /*g:rust_bang_comment_leader* g:rust_conceal ft_rust.txt /*g:rust_conceal* g:rust_conceal_mod_path ft_rust.txt /*g:rust_conceal_mod_path* @@ -9877,8 +9879,8 @@ type-casting vim9.txt /*type-casting* type-checking vim9.txt /*type-checking* type-inference vim9.txt /*type-inference* type-mistakes tips.txt /*type-mistakes* -typecorr-settings usr_41.txt /*typecorr-settings* -typecorr.txt usr_41.txt /*typecorr.txt* +typecorrect-settings usr_41.txt /*typecorrect-settings* +typecorrect.txt usr_41.txt /*typecorrect.txt* typename() builtin.txt /*typename()* u undo.txt /*u* uganda uganda.txt /*uganda*
--- a/runtime/doc/todo.txt +++ b/runtime/doc/todo.txt @@ -1,4 +1,4 @@ -*todo.txt* For Vim version 8.2. Last change: 2021 Dec 27 +*todo.txt* For Vim version 8.2. Last change: 2021 Dec 30 VIM REFERENCE MANUAL by Bram Moolenaar @@ -41,11 +41,8 @@ browser use: https://github.com/vim/vim/ Once Vim9 is stable: - Add the "vim9script" feature, can use has('vim9script') Remove TODO in vim9.txt -- Change the help to prefer Vim9 syntax where appropriate -- In the generic eval docs, point out the Vim9 syntax where it differs. - Add all the error numbers in a good place in documentation. - Use Vim9 for runtime files. - PR #7497 for autoload/ccomplete.vim Further Vim9 improvements, possibly after launch: - Check performance with callgrind and kcachegrind.
--- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -1,4 +1,4 @@ -*usr_41.txt* For Vim version 8.2. Last change: 2021 Sep 10 +*usr_41.txt* For Vim version 8.2. Last change: 2021 Dec 30 VIM USER MANUAL - by Bram Moolenaar @@ -37,7 +37,8 @@ Your first experience with Vim scripts i it starts up and executes the commands. You can set options to values you prefer. And you can use any colon command in it (commands that start with a ":"; these are sometimes referred to as Ex commands or command-line commands). - Syntax files are also Vim scripts. As are files that set options for a + +Syntax files are also Vim scripts. As are files that set options for a specific file type. A complicated macro can be defined by a separate Vim script file. You can think of other uses yourself. @@ -47,23 +48,25 @@ script file. You can think of other use And if you are familiar with JavaScript: https://w0rp.com/blog/post/vim-script-for-the-javascripter/ +Vim script comes in two flavors: legacy and |Vim9|. Since this help file is +for new users, we'll teach you the newer and more convenient |Vim9| syntax. + +To try out Vim script the best way is to edit a script file and source it. +Basically: > + :edit test.vim + [insert the script lines you want] + :w + :source % + Let's start with a simple example: > - :let i = 1 - :while i < 5 - : echo "count is" i - : let i += 1 - :endwhile + vim9script + var i = 1 + while i < 5 + echo "count is" i + i += 1 + endwhile < - Note: - The ":" characters are not really needed here. You only need to use - them when you type a command. In a Vim script file they can be left - out. We will use them here anyway to make clear these are colon - commands and make them stand out from Normal mode commands. - Note: - You can try out the examples by yanking the lines from the text here - and executing them with :@" - The output of the example code is: count is 1 ~ @@ -71,45 +74,46 @@ The output of the example code is: count is 3 ~ count is 4 ~ -In the first line the ":let" command assigns a value to a variable. The +In the first line the `vim9script` command makes clear this is a new, |Vim9| +script file. That matters for how the rest of the file is used. + +The `var i = 1` command declares the "i" variable and initializes it. The generic form is: > - :let {variable} = {expression} + var {name} = {expression} In this case the variable name is "i" and the expression is a simple value, the number one. - The ":while" command starts a loop. The generic form is: > - - :while {condition} - : {statements} - :endwhile - -The statements until the matching ":endwhile" are executed for as long as the + +The `while` command starts a loop. The generic form is: > + + while {condition} + {statements} + endwhile + +The statements until the matching `endwhile` are executed for as long as the condition is true. The condition used here is the expression "i < 5". This is true when the variable i is smaller than five. Note: If you happen to write a while loop that keeps on running, you can interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows). -The ":echo" command prints its arguments. In this case the string "count is" +The `echo` command prints its arguments. In this case the string "count is" and the value of the variable i. Since i is one, this will print: count is 1 ~ -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. In Vim9 script it's a bit different, see |usr_46.txt|. +Then there is the `i += 1` command. This does the same thing as "i = i + 1", +it adds one to the variable i and assigns the new value to the same variable. 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: > - :for i in range(1, 4) - : echo "count is" i - :endfor - -We won't explain how |:for| and |range()| work until later. Follow the links + for i in range(1, 4) + echo "count is" i + endfor + +We won't explain how `for` and `range()` work until later. Follow the links if you are impatient. @@ -120,32 +124,47 @@ Numbers can be decimal, hexadecimal, oct 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. +An octal number starts with "0o", "0O". "0o17" is decimal 15. 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 0o36 +A decimal number is just digits. Careful: In legacy script don't put a zero +before a decimal number, it will be interpreted as an octal number! + +The `echo` command evaluates its argument and always prints decimal numbers. +Example: > + + 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 -0o36 -< 97 ~ - -White space in an expression is ignored. However, it's recommended to use it -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 - 0o36 +octal and binary numbers: > + + echo -0x7f +< -127 ~ + +A minus sign is also used for subtraction. This can sometimes lead to +confusion. If we put a minus sign before both numbers we get an error: > + + echo -0x7f -0o36 +< E1004: White space required before and after '-' at "-0o36" ~ + +Note: if you are not using a |Vim9| script to try out these commands but type +them directly, they will be executed as legacy script. Then the echo command +sees the second minus sign as subtraction. To get the error, prefix the +command with `vim9cmd`: > + + vim9cmd echo -0x7f -0o36 +< E1004: White space required before and after '-' at "-0o36" ~ + +White space in an expression is often required to make sure it is easy to read +and avoid errors. Such as thinking that the "-0o36" above makes the number +negative, while it is actually seen as a subtraction. + +To actually have the minus sign be used for negation, you can put the second +expression in parenthesis: > + + echo -0x7f (-0o36) ============================================================================== *41.2* Variables @@ -160,27 +179,45 @@ cannot start with a digit. Valid variab LENGTH Invalid names are "foo+bar" and "6var". - These variables are global. To see a list of currently defined variables -use this command: > + +Some variables are global. To see a list of currently defined global +variables type this command: > :let -You can use global variables everywhere. This also means that when the -variable "count" is used in one script file, it might also be used in another -file. This leads to confusion at least, and real problems at worst. To avoid -this, you can use a variable local to a script file by prepending "s:". For -example, one script contains this code: > - - :let s:count = 1 - :while s:count < 5 - : source other.vim - : let s:count += 1 - :endwhile - -Since "s:count" is local to this script, you can be sure that sourcing the -"other.vim" script will not change this variable. If "other.vim" also uses an -"s:count" variable, it will be a different copy, local to that script. More -about script-local variables here: |script-variable|. +You can use global variables everywhere. However, it is easy to use the same +name in two unrelated scripts. Therefore variables declared in a script are +local to that script. For example, if you have this in "script1.vim": > + + vim9script + var counter = 5 + echo counter +< 5 ~ + +And you try to use the variable in "script2.vim": > + + vim9script + echo counter +< E121: Undefined variable: counter ~ + +Using a script-local variable means you can be sure that it is only changed in +that script and not elsewhere. + +If you do want to share variables between scripts, use the "g:" prefix and +assign the value directly, do not use `var`. Thus in "script1.vim": > + + vim9script + g:counter = 5 + echo g:counter +< 5 ~ + +And then in "script2.vim": > + + vim9script + echo g:counter +< 5 ~ + +More about script-local variables here: |script-variable|. There are more kinds of variables, see |internal-variables|. The most often used ones are: @@ -193,79 +230,99 @@ used ones are: DELETING VARIABLES -Variables take up memory and show up in the output of the ":let" command. To -delete a variable use the ":unlet" command. Example: > - - :unlet s:count - -This deletes the script-local variable "s:count" to free up the memory it -uses. If you are not sure if the variable exists, and don't want an error -message when it doesn't, append !: > - - :unlet! s:count - -When a script finishes, the local variables used there will not be -automatically freed. The next time the script executes, it can still use the -old value. Example: > - - :if !exists("s:call_count") - : let s:call_count = 0 - :endif - :let s:call_count = s:call_count + 1 - :echo "called" s:call_count "times" - -The "exists()" function checks if a variable has already been defined. Its -argument is the name of the variable you want to check. Not the variable -itself! If you would do this: > - - :if !exists(s:call_count) - -Then the value of s:call_count will be used as the name of the variable that -exists() checks. That's not what you want. - The exclamation mark ! negates a value. When the value was true, it -becomes false. When it was false, it becomes true. You can read it as "not". -Thus "if !exists()" can be read as "if not exists()". - What Vim calls true is anything that is not zero. Zero is false. - Note: - Vim automatically converts a string to a number when it is looking for - a number. When using a string that doesn't start with a digit the - resulting number is zero. Thus look out for this: > - :if "true" -< The "true" will be interpreted as a zero, thus as false! +Variables take up memory and show up in the output of the `let` command. To +delete a global variable use the `unlet` command. Example: > + + unlet g:counter + +This deletes the global variable "g:counter" to free up the memory it uses. +If you are not sure if the variable exists, and don't want an error message +when it doesn't, append !: > + + unlet! g:counter + +You cannot `unlet` script-local variables in |Vim9| script. You can in legacy +script. + +When a script finishes, the local variables declared there will not be +deleted. Functions defined in the script can use them. Example: +> + vim9script + var counter = 0 + def g:GetCount(): number + s:counter += 1 + return s:counter + enddef + +Every time you call the function it will return the next count: > + :echo g:GetCount() +< 1 ~ +> + :echo g:GetCount() +< 2 ~ + +If you are worried a script-local variable is consuming too much +memory, set it to an empty value after you no longer need it. + +Note: below we'll leave out the `vim9script` line, so we can concentrate on +the relevant commands, but you'll still need to put it at the top of your +script file. STRING VARIABLES AND CONSTANTS So far only numbers were used for the variable value. Strings can be used as well. Numbers and strings are the basic types of variables that Vim supports. -The type is dynamic, it is set each time when assigning a value to the -variable with ":let". More about types in |41.8|. - To assign a string value to a variable, you need to use a string constant. -There are two types of these. First the string in double quotes: > - - :let name = "peter" - :echo name +Example: > + + var name = "Peter" + echo name < peter ~ -If you want to include a double quote inside the string, put a backslash in -front of it: > - - :let name = "\"peter\"" - :echo name -< "peter" ~ +Every variable has a type. Very often, as in this example, the type is +defined by assigning a value. This is called type inference. If you do not +want to give the variable a value yet, you need to specify the type: > + + var name: string + var age: number + ... + name = "Peter" + age = 42 + +If you make a mistake and try to assign the wrong type of value you'll get an +error: > + + age = "Peter" +< E1012: Type mismatch; expected number but got string ~ + +More about types in |41.8|. + +To assign a string value to a variable, you need to use a string constant. +There are two types of these. First the string in double quotes, as we used +already. If you want to include a double quote inside the string, put a +backslash in front of it: > + + var name = "he is \"Peter\"" + echo name +< he is "Peter" ~ To avoid the need for a backslash, you can use a string in single quotes: > - :let name = '"peter"' - :echo name -< "peter" ~ + var name = 'he is "Peter"' + echo name +< he is "Peter" ~ Inside a single-quote string all the characters are as they are. Only the single quote itself is special: you need to use two to get one. A backslash is taken literally, thus you can't use it to change the meaning of the -character after it. - In double-quote strings it is possible to use special characters. Here are -a few useful ones: +character after it: > + + var name = 'P\e''ter''' + echo name +< P\e'ter' ~ + +In double-quote strings it is possible to use special characters. Here are a +few useful ones: \t <Tab> \n <NL>, line break @@ -279,15 +336,17 @@ a few useful ones: The last two are just examples. The "\<name>" form can be used to include the special key "name". - See |expr-quote| for the full list of special items in a string. + +See |expr-quote| for the full list of special items in a string. ============================================================================== *41.3* Expressions -Vim has a rich, yet simple way to handle expressions. You can read the +Vim has a fairly standard way to handle expressions. You can read the definition here: |expression-syntax|. Here we will show the most common items. - The numbers, strings and variables mentioned above are expressions by + +The numbers, strings and variables mentioned above are expressions by themselves. Thus everywhere an expression is expected, you can use a number, string or variable. Other basic items in an expression are: @@ -297,17 +356,17 @@ string or variable. Other basic items i Examples: > - :echo "The value of 'tabstop' is" &ts - :echo "Your home directory is" $HOME - :if @a > 5 - -The &name form can be used to save an option value, set it to a new value, -do something and restore the old value. Example: > - - :let save_ic = &ic - :set noic - :/The Start/,$delete - :let &ic = save_ic + echo "The value of 'tabstop' is" &ts + echo "Your home directory is" $HOME + if @a == 'text' + +The &name form can also be used to set an option value, do something and +restore the old value. Example: > + + var save_ic = &ic + set noic + s/The Start/The Beginning/ + &ic = save_ic This makes sure the "The Start" pattern is used with the 'ignorecase' option off. Still, it keeps the value that the user had set. (Another way to do @@ -327,80 +386,86 @@ mathematics on numbers: The usual precedence is used. Example: > - :echo 10 + 5 * 2 + echo 10 + 5 * 2 < 20 ~ Grouping is done with parentheses. No surprises here. Example: > - :echo (10 + 5) * 2 + echo (10 + 5) * 2 < 30 ~ 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 +When the "echo" command gets multiple arguments, it separates them with a space. In the example the argument is a single expression, thus no space is inserted. -Borrowed from the C language is the conditional expression: +Borrowed from the C language is the conditional expression: > a ? b : c If "a" evaluates to true "b" is used, otherwise "c" is used. Example: > - :let i = 4 - :echo i > 5 ? "i is big" : "i is small" -< i is small ~ + var nr = 4 + echo nr > 5 ? "nr is big" : "nr is small" +< nr is small ~ The three parts of the constructs are always evaluated first, thus you could -see it work as: +see it works as: > (a) ? (b) : (c) ============================================================================== *41.4* Conditionals -The ":if" commands executes the following statements, until the matching -":endif", only when a condition is met. The generic form is: - - :if {condition} +The `if` commands executes the following statements, until the matching +`endif`, only when a condition is met. The generic form is: + + if {condition} {statements} - :endif - -Only when the expression {condition} evaluates to true (non-zero) will the -{statements} be executed. These must still be valid commands. If they -contain garbage, Vim won't be able to find the ":endif". - You can also use ":else". The generic form for this is: - - :if {condition} + endif + +Only when the expression {condition} evaluates to true or one will the +{statements} be executed. If they are not executed they must still be valid +commands. If they contain garbage, Vim won't be able to find the matching +`endif`. + +You can also use `else`. The generic form for this is: + + if {condition} {statements} - :else + else {statements} - :endif - -The second {statements} is only executed if the first one isn't. - Finally, there is ":elseif": - - :if {condition} + endif + +The second {statements} block is only executed if the first one isn't. + +Finally, there is `elseif` + + if {condition} {statements} - :elseif {condition} + elseif {condition} {statements} - :endif - -This works just like using ":else" and then "if", but without the need for an -extra ":endif". - A useful example for your vimrc file is checking the 'term' option and -doing something depending upon its value: > - - :if &term == "xterm" - : " Do stuff for xterm - :elseif &term == "vt100" - : " Do stuff for a vt100 terminal - :else - : " Do something for other terminals - :endif + endif + +This works just like using `else` and then `if`, but without the need for an +extra `endif`. + +A useful example for your vimrc file is checking the 'term' option and doing +something depending upon its value: > + + if &term == "xterm" + # Do stuff for xterm + elseif &term == "vt100" + # Do stuff for a vt100 terminal + else + # Do something for other terminals + endif + +This uses "#" to start a comment, more about that later. LOGIC OPERATIONS @@ -415,168 +480,186 @@ ones: a < b less than a <= b less than or equal to -The result is one if the condition is met and zero otherwise. An example: > - - :if v:version >= 700 - : echo "congratulations" - :else - : echo "you are using an old version, upgrade!" - :endif +The result is true if the condition is met and false otherwise. An example: > + + if v:version >= 700 + echo "congratulations" + else + echo "you are using an old version, upgrade!" + endif Here "v:version" is a variable defined by Vim, which has the value of the Vim -version. 600 is for version 6.0. Version 6.1 has the value 601. This is +version. 600 is for version 6.0, version 6.1 has the value 601. This is very useful to write a script that works with multiple versions of Vim. |v:version| The logic operators work both for numbers and strings. When comparing two strings, the mathematical difference is used. This compares byte values, which may not be right for some languages. - When comparing a string with a number, the string is first converted to a -number. This is a bit tricky, because when a string doesn't look like a -number, the number zero is used. Example: > - - :if 0 == "one" - : echo "yes" - :endif - -This will echo "yes", because "one" doesn't look like a number, thus it is -converted to the number zero. - -For strings there are two more items: - - a =~ b matches with - a !~ b does not match with - -The left item "a" is used as a string. The right item "b" is used as a + +If you try to compare a string with a number you will get an error. + +For strings there are two more useful items: + + str =~ pat matches with + str !~ pat does not match with + +The left item "str" is used as a string. The right item "pat" is used as a pattern, like what's used for searching. Example: > - :if str =~ " " - : echo "str contains a space" - :endif - :if str !~ '\.$' - : echo "str does not end in a full stop" - :endif + if str =~ " " + echo "str contains a space" + endif + if str !~ '\.$' + echo "str does not end in a full stop" + endif Notice the use of a single-quote string for the pattern. This is useful, because backslashes would need to be doubled in a double-quote string and patterns tend to contain many backslashes. -The 'ignorecase' option is used when comparing strings. When you don't want -that, append "#" to match case and "?" to ignore case. Thus "==?" compares -two strings to be equal while ignoring case. And "!~#" checks if a pattern -doesn't match, also checking the case of letters. For the full table see -|expr-==|. +The match is not anchored, if you want to match the whole string start with +"^" and end with "$". + +The 'ignorecase' option is not used when comparing strings. When you do want +to ignore case append "?". Thus "==?" compares two strings to be equal while +ignoring case. For the full table see |expr-==|. MORE LOOPING -The ":while" command was already mentioned. Two more statements can be used -in between the ":while" and the ":endwhile": - - :continue Jump back to the start of the while loop; the +The `while` command was already mentioned. Two more statements can be used in +between the `while` and the `endwhile`: + + continue Jump back to the start of the while loop; the loop continues. - :break Jump forward to the ":endwhile"; the loop is + break Jump forward to the `endwhile`; the loop is discontinued. Example: > - :while counter < 40 - : call do_something() - : if skip_flag - : continue - : endif - : if finished_flag - : break - : endif - : sleep 50m - :endwhile - -The ":sleep" command makes Vim take a nap. The "50m" specifies fifty -milliseconds. Another example is ":sleep 4", which sleeps for four seconds. - -Even more looping can be done with the ":for" command, see below in |41.8|. + while counter < 40 + do_something() + if skip_flag + continue + endif + if finished_flag + break + endif + sleep 50m + --counter + endwhile + +The `sleep` command makes Vim take a nap. The "50m" specifies fifty +milliseconds. Another example is `sleep 4`, which sleeps for four seconds. + +Even more looping can be done with the `for` command, see below in |41.8|. ============================================================================== *41.5* Executing an expression So far the commands in the script were executed by Vim directly. The -":execute" command allows executing the result of an expression. This is a +`execute` command allows executing the result of an expression. This is a 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 + +An example is to jump to a tag, which is contained in a variable: > + + execute "tag " .. tag_name 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: > - :tag get_cmd - -The ":execute" command can only execute colon commands. The ":normal" command + tag get_cmd + +The `execute` command can only execute Ex commands. The `normal` command executes Normal mode commands. However, its argument is not an expression but the literal command characters. Example: > - :normal gg=G - -This jumps to the first line and formats all lines with the "=" operator. - To make ":normal" work with an expression, combine ":execute" with it. + normal gg=G + +This jumps to the first line with "gg" and formats all lines with the "=" +operator and the "G" movement. + +To make `normal` work with an expression, combine `execute` with it. Example: > - :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 + execute "normal " .. count .. "j" + +This will move the cursor "count" lines down. + +Make sure that the argument for `normal` is a complete command. Otherwise Vim will run into the end of the argument and abort the command. For example, -if you start Insert mode, you must leave Insert mode as well. This works: > - - :execute "normal Inew text \<Esc>" - -This inserts "new text " in the current line. Notice the use of the special -key "\<Esc>". This avoids having to enter a real <Esc> character in your -script. +if you start the delete operator, you must give the movement command also. +This works: > + + normal d$ + +This does nothing: > + + normal d + +If you start Insert mode and do not end it with Esc, it will end anyway. This +works to insert "new text": > + + execute "normal inew text" + +If you want to do something after inserting text you do need to end Insert +mode: > + + execute "normal inew text\<Esc>b" + +This inserts "new text" and puts the cursor on the first letter of "text". +Notice the use of the special key "\<Esc>". This avoids having to enter a +real <Esc> character in your script. That is where `execute` with a +double-quote string comes in handy. 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) + var optname = "path" + var optvalue = 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 ============================================================================== *41.6* Using functions Vim defines many functions and provides a large amount of functionality that way. A few examples will be given in this section. You can find the whole -list here: |functions|. - -A function is called with the ":call" command. The parameters are passed in +list below: |function-list|. + +A function is called with the `call` command. The parameters are passed in between parentheses separated by commas. Example: > - :call search("Date: ", "W") + call search("Date: ", "W") This calls the search() function, with arguments "Date: " and "W". The search() function uses its first argument as a search pattern and the second one as flags. The "W" flag means the search doesn't wrap around the end of the file. +Using `call` is optional in |Vim9| script, this works the same way: > + + search("Date: ", "W") + A function can be called in an expression. Example: > - :let line = getline(".") - :let repl = substitute(line, '\a', "*", "g") - :call setline(".", repl) + var line = getline(".") + var repl = substitute(line, '\a', "*", "g") + setline(".", repl) The getline() function obtains a line from the current buffer. Its argument is a specification of the line number. In this case "." is used, which means the line where the cursor is. - The substitute() function does something similar to the ":substitute" -command. The first argument is the string on which to perform the -substitution. The second argument is the pattern, the third the replacement -string. Finally, the last arguments are the flags. - The setline() function sets the line, specified by the first argument, to a + +The substitute() function does something similar to the `substitute` command. +The first argument is the string on which to perform the substitution. The +second argument is the pattern, the third the replacement string. Finally, +the last arguments are the flags. + +The setline() function sets the line, specified by the first argument, to a new string, the second argument. In this example the line under the cursor is replaced with the result of the substitute(). Thus the effect of the three statements is equal to: > @@ -590,8 +673,8 @@ after the substitute() call. FUNCTIONS *function-list* There are many functions. We will mention them here, grouped by what they are -used for. You can find an alphabetical list here: |functions|. Use CTRL-] on -the function name to jump to detailed help on it. +used for. You can find an alphabetical list here: |builtin-function-list|. +Use CTRL-] on the function name to jump to detailed help on it. String manipulation: *string-functions* nr2char() get a character by its number value @@ -1234,9 +1317,9 @@ Various: *various-functions* Vim enables you to define your own functions. The basic function declaration begins as follows: > - :function {name}({var1}, {var2}, ...) - : {body} - :endfunction + def {name}({var1}, {var2}, ...): return-type + {body} + enddef < Note: Function names must begin with a capital letter. @@ -1244,115 +1327,107 @@ begins as follows: > Let's define a short function to return the smaller of two numbers. It starts with this line: > - :function Min(num1, num2) - -This tells Vim that the function is named "Min" and it takes two arguments: -"num1" and "num2". - The first thing you need to do is to check to see which number is smaller: + def Min(num1: number, num2: number): number + +This tells Vim that the function is named "Min", it takes two arguments that +are numbers: "num1" and "num2" and returns a number. + +The first thing you need to do is to check to see which number is smaller: > - : if a:num1 < a:num2 - -The special prefix "a:" tells Vim that the variable is a function argument. + if num1 < num2 + Let's assign the variable "smaller" the value of the smallest number: > - : if a:num1 < a:num2 - : let smaller = a:num1 - : else - : let smaller = a:num2 - : endif + var smaller: number + if num1 < num2 + smaller = num1 + else + smaller = num2 + endif The variable "smaller" is a local variable. Variables used inside a function -are local unless prefixed by something like "g:", "a:", or "s:". +are local unless prefixed by something like "g:", "w:", or "s:". Note: To access a global variable from inside a function you must prepend "g:" to it. Thus "g:today" inside a function is used for the global variable "today", and "today" is another variable, local to the - function. - -You now use the ":return" statement to return the smallest number to the user. + function or the script. + +You now use the `return` statement to return the smallest number to the user. Finally, you end the function: > - : return smaller - :endfunction + return smaller + enddef The complete function definition is as follows: > - :function Min(num1, num2) - : if a:num1 < a:num2 - : let smaller = a:num1 - : else - : let smaller = a:num2 - : endif - : return smaller - :endfunction - -For people who like short functions, this does the same thing: > - - :function Min(num1, num2) - : if a:num1 < a:num2 - : return a:num1 - : endif - : return a:num2 - :endfunction + def Min(num1: number, num2: number): number + var smaller: number + if num1 < num2 + smaller = num1 + else + smaller = num2 + endif + return smaller + enddef + +Obviously this is a verbose example. You can make it shorter by using two +return commands: > + + def Min(num1: number, num2: number): number + if num1 < num2 + return num1 + endif + return num2 + enddef + +And if you remember the conditional expression, you need only one line: > + + def Min(num1: number, num2: number): number + return num1 < num2 ? num1 : num2 + enddef A user defined function is called in exactly the same way as a built-in function. Only the name is different. The Min function can be used like this: > - :echo Min(5, 8) - -Only now will the function be executed and the lines be interpreted by Vim. + echo Min(5, 8) + +Only now will the function be executed and the lines be parsed by Vim. If there are mistakes, like using an undefined variable or function, you will now get an error message. When defining the function these errors are not -detected. - -When a function reaches ":endfunction" or ":return" is used without an -argument, the function returns zero. - -To redefine a function that already exists, use the ! for the ":function" -command: > - - :function! Min(num1, num2, num3) +detected. To get the errors sooner you can tell Vim to compile all the +functions in the script: > + + defcompile + +For a function that does not return anything leave out the return type: > + + def SayIt(text: string) + echo text + enddef + +It is also possible to define a legacy function with `function` and +`endfunction`. These do not have types and are not compiled. They execute +much slower. USING A RANGE -The ":call" command can be given a line range. This can have one of two -meanings. When a function has been defined with the "range" keyword, it will -take care of the line range itself. - The function will be passed the variables "a:firstline" and "a:lastline". -These will have the line numbers from the range the function was called with. -Example: > - - :function Count_words() range - : let lnum = a:firstline - : let n = 0 - : while lnum <= a:lastline - : let n = n + len(split(getline(lnum))) - : let lnum = lnum + 1 - : endwhile - : echo "found " .. n .. " words" - :endfunction - -You can call this function with: > - - :10,30call Count_words() - -It will be executed once and echo the number of words. - The other way to use a line range is by defining a function without the -"range" keyword. The function will be called once for every line in the -range, with the cursor in that line. Example: > - - :function Number() - : echo "line " .. line(".") .. " contains: " .. getline(".") - :endfunction +A line range can be used with a function call. The function will be called +once for every line in the range, with the cursor in that line. Example: > + + def Number() + echo "line " .. line(".") .. " contains: " .. getline(".") + enddef If you call this function with: > :10,15call Number() -The function will be called six times. +The function will be called six times, starting on line 10 and ending on line +15. VARIABLE NUMBER OF ARGUMENTS @@ -1361,43 +1436,50 @@ Vim enables you to define functions that The following command, for instance, defines a function that must have 1 argument (start) and can have up to 20 additional arguments: > - :function Show(start, ...) - -The variable "a:1" contains the first optional argument, "a:2" the second, and -so on. The variable "a:0" contains the number of extra arguments. - For example: > - - :function Show(start, ...) - : echohl Title - : echo "start is " .. a:start - : echohl None - : let index = 1 - : while index <= a:0 - : echo " Arg " .. index .. " is " .. a:{index} - : let index = index + 1 - : endwhile - : echo "" - :endfunction - -This uses the ":echohl" command to specify the highlighting used for the -following ":echo" command. ":echohl None" stops it again. The ":echon" -command works like ":echo", but doesn't output a line break. - -You can also use the a:000 variable, it is a List of all the "..." arguments. -See |a:000|. + def Show(start: string, ...items: list<string>) + +The variable "items" will be a list containing the extra arguments. You can +use it like any list, for example: > + + def Show(start: string, ...items: list<string>) + echohl Title + echo "start is " .. start + echohl None + for index in range(len(items)) + echon " Arg " .. index .. " is " .. items[index] + endfor + echo + enddef + +You can call it like this: > + + Show('Title', 'one', 'two', 'three') +< start is Title Arg 0 is one Arg 1 is two Arg 2 is three ~ + +This uses the `echohl` command to specify the highlighting used for the +following `echo` command. `echohl None` stops it again. The `echon` command +works like `echo`, but doesn't output a line break. + +If you call it with one argument the "items" list will be empty. +`range(len(items))` returns a list with the indexes, what `for` loops over, +we'll explain that further down. LISTING FUNCTIONS -The ":function" command lists the names and arguments of all user-defined +The `function` command lists the names and arguments of all user-defined functions: > :function -< function Show(start, ...) ~ +< def <SNR>86_Show(start: string, ...items: list<string>) ~ function GetVimIndent() ~ function SetSyn(name) ~ -To see what a function does, use its name as an argument for ":function": > +The "<SNR>" prefix means that a function is script-local. |Vim9| functions +wil start with "def" and include argument and return types. Legacy functions +are listed with "function". + +To see what a function does, use its name as an argument for `function`: > :function SetSyn < 1 if &syntax == '' ~ @@ -1405,55 +1487,64 @@ To see what a function does, use its nam 3 endif ~ endfunction ~ +To see the "Show" function you need to include the script prefix, since a +"Show" function can be defined multiple times in different scripts. To find +the exact name you can use `function`, but the result may be a very long list. +To only get the functions matching a pattern you can use the `filter` prefix: +> + + :filter Show function +< def <SNR>86_Show(start: string, ...items: list<string>) ~ +> + :function <SNR>86_Show +< 1 echohl Title ~ + 2 echo "start is " .. start ~ + etc. + DEBUGGING The line number is useful for when you get an error message or when debugging. See |debug-scripts| about debugging mode. - You can also set the 'verbose' option to 12 or higher to see all function + +You can also set the 'verbose' option to 12 or higher to see all function calls. Set it to 15 or higher to see every executed line. DELETING A FUNCTION -To delete the Show() function: > - - :delfunction Show - -You get an error when the function doesn't exist. +To delete the SetSyn() function: > + + :delfunction SetSyn + +Deleting only works for global functions and functions in legacy script, not +for functions defined in a |Vim9| script. + +You get an error when the function doesn't exist or cannot be deleted. FUNCTION REFERENCES Sometimes it can be useful to have a variable point to one function or -another. You can do it with the function() function. It turns the name of a -function into a reference: > - - :let result = 0 " or 1 - :function! Right() - : return 'Right!' - :endfunc - :function! Wrong() - : return 'Wrong!' - :endfunc - : - :if result == 1 - : let Afunc = function('Right') - :else - : let Afunc = function('Wrong') - :endif - :echo call(Afunc, []) +another. You can do it with function reference variable. Often shortened to +"funcref". Example: > + + def Right() + return 'Right!' + enddef + def Wrong() + return 'Wrong!' + enddef + + var Afunc = g:result == 1 ? Right : Wrong + Afunc() < Wrong! ~ +This assumes "g:result" is not one. + Note that the name of a variable that holds a function reference must start with a capital. Otherwise it could be confused with the name of a builtin function. - The way to invoke a function that a variable refers to is with the call() -function. Its first argument is the function reference, the second argument -is a List with arguments. - -Function references are most useful in combination with a Dictionary, as is -explained in the next section. More information about defining your own functions here: |user-functions|. @@ -1463,94 +1554,97 @@ More information about defining your own So far we have used the basic types String and Number. Vim also supports two composite types: List and Dictionary. -A List is an ordered sequence of things. The things can be any kind of value, +A List is an ordered sequence of items. The items can be any kind of value, thus you can make a List of numbers, a List of Lists and even a List of mixed items. To create a List with three strings: > - :let alist = ['aap', 'mies', 'noot'] + var alist = ['aap', 'mies', 'noot'] The List items are enclosed in square brackets and separated by commas. To create an empty List: > - :let alist = [] + var alist = [] You can add items to a List with the add() function: > - :let alist = [] - :call add(alist, 'foo') - :call add(alist, 'bar') - :echo alist + var alist = [] + add(alist, 'foo') + add(alist, 'bar') + echo alist < ['foo', 'bar'] ~ List concatenation is done with +: > - :echo alist + ['foo', 'bar'] -< ['foo', 'bar', 'foo', 'bar'] ~ - -Or, if you want to extend a List directly: > - - :let alist = ['one'] - :call extend(alist, ['two', 'three']) - :echo alist + var alist = ['foo', 'bar'] + alist = alist + ['and', 'more'] + echo alist +< ['foo', 'bar', 'and', 'more'] ~ + +Or, if you want to extend a List with a function: > + + var alist = ['one'] + extend(alist, ['two', 'three']) + echo alist < ['one', 'two', 'three'] ~ -Notice that using add() will have a different effect: > - - :let alist = ['one'] - :call add(alist, ['two', 'three']) - :echo alist +Notice that using `add()` will have a different effect: > + + var alist = ['one'] + add(alist, ['two', 'three']) + echo alist < ['one', ['two', 'three']] ~ -The second argument of add() is added as a single item. +The second argument of add() is added as an item, now you have a nested list. FOR LOOP One of the nice things you can do with a List is iterate over it: > - :let alist = ['one', 'two', 'three'] - :for n in alist - : echo n - :endfor + var alist = ['one', 'two', 'three'] + for n in alist + echo n + endfor < one ~ two ~ three ~ -This will loop over each element in List "alist", assigning the value to +This will loop over each element in List "alist", assigning each value to variable "n". The generic form of a for loop is: > - :for {varname} in {listexpression} - : {commands} - :endfor + for {varname} in {listexpression} + {commands} + endfor To loop a certain number of times you need a List of a specific length. The range() function creates one for you: > - :for a in range(3) - : echo a - :endfor + for a in range(3) + echo a + endfor < 0 ~ 1 ~ 2 ~ Notice that the first item of the List that range() produces is zero, thus the last item is one less than the length of the list. - You can also specify the maximum value, the stride and even go backwards: > - - :for a in range(8, 4, -2) - : echo a - :endfor + +You can also specify the maximum value, the stride and even go backwards: > + + for a in range(8, 4, -2) + echo a + endfor < 8 ~ 6 ~ 4 ~ A more useful example, looping over lines in the buffer: > - :for line in getline(1, 20) - : if line =~ "Date: " - : echo matchstr(line, 'Date: \zs.*') - : endif - :endfor + for line in getline(1, 20) + if line =~ "Date: " + echo line + endif + endfor This looks into lines 1 to 20 (inclusive) and echoes any date found in there. @@ -1560,11 +1654,16 @@ DICTIONARIES A Dictionary stores key-value pairs. You can quickly lookup a value if you know the key. A Dictionary is created with curly braces: > - :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'} + var uk2nl = {one: 'een', two: 'twee', three: 'drie'} Now you can lookup words by putting the key in square brackets: > - :echo uk2nl['two'] + echo uk2nl['two'] +< twee ~ + +If the key does not have special characters, you can use the dot notation: > + + echo uk2nl.two < twee ~ The generic form for defining a Dictionary is: > @@ -1579,9 +1678,9 @@ The possibilities with Dictionaries are for them as well. For example, you can obtain a list of the keys and loop over them: > - :for key in keys(uk2nl) - : echo key - :endfor + for key in keys(uk2nl) + echo key + endfor < three ~ one ~ two ~ @@ -1589,9 +1688,9 @@ over them: > You will notice the keys are not ordered. You can sort the list to get a specific order: > - :for key in sort(keys(uk2nl)) - : echo key - :endfor + for key in sort(keys(uk2nl)) + echo key + endfor < one ~ three ~ two ~ @@ -1600,147 +1699,6 @@ But you can never get back the order in need to use a List, it stores items in an ordered sequence. -DICTIONARY FUNCTIONS - -The items in a Dictionary can normally be obtained with an index in square -brackets: > - - :echo uk2nl['one'] -< een ~ - -A method that does the same, but without so many punctuation characters: > - - :echo uk2nl.one -< een ~ - -This only works for a key that is made of ASCII letters, digits and the -underscore. You can also assign a new value this way: > - - :let uk2nl.four = 'vier' - :echo uk2nl -< {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~ - -And now for something special: you can directly define a function and store a -reference to it in the dictionary: > - - :function uk2nl.translate(line) dict - : return join(map(split(a:line), 'get(self, v:val, "???")')) - :endfunction - -Let's first try it out: > - - :echo uk2nl.translate('three two five one') -< drie twee ??? een ~ - -The first special thing you notice is the "dict" at the end of the ":function" -line. This marks the function as being used from a Dictionary. The "self" -local variable will then refer to that Dictionary. - Now let's break up the complicated return command: > - - split(a:line) - -The split() function takes a string, chops it into whitespace separated words -and returns a list with these words. Thus in the example it returns: > - - :echo split('three two five one') -< ['three', 'two', 'five', 'one'] ~ - -This list is the first argument to the map() function. This will go through -the list, evaluating its second argument with "v:val" set to the value of each -item. This is a shortcut to using a for loop. This command: > - - :let alist = map(split(a:line), 'get(self, v:val, "???")') - -Is equivalent to: > - - :let alist = split(a:line) - :for idx in range(len(alist)) - : let alist[idx] = get(self, alist[idx], "???") - :endfor - -The get() function checks if a key is present in a Dictionary. If it is, then -the value is retrieved. If it isn't, then the default value is returned, in -the example it's '???'. This is a convenient way to handle situations where a -key may not be present and you don't want an error message. - -The join() function does the opposite of split(): it joins together a list of -words, putting a space in between. - This combination of split(), map() and join() is a nice way to filter a line -of words in a very compact way. - - -OBJECT ORIENTED PROGRAMMING - -Now that you can put both values and functions in a Dictionary, you can -actually use a Dictionary like an object. - Above we used a Dictionary for translating Dutch to English. We might want -to do the same for other languages. Let's first make an object (aka -Dictionary) that has the translate function, but no words to translate: > - - :let transdict = {} - :function transdict.translate(line) dict - : return join(map(split(a:line), 'get(self.words, v:val, "???")')) - :endfunction - -It's slightly different from the function above, using 'self.words' to lookup -word translations. But we don't have a self.words. Thus you could call this -an abstract class. - -Now we can instantiate a Dutch translation object: > - - :let uk2nl = copy(transdict) - :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'} - :echo uk2nl.translate('three one') -< drie een ~ - -And a German translator: > - - :let uk2de = copy(transdict) - :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'} - :echo uk2de.translate('three one') -< drei eins ~ - -You see that the copy() function is used to make a copy of the "transdict" -Dictionary and then the copy is changed to add the words. The original -remains the same, of course. - -Now you can go one step further, and use your preferred translator: > - - :if $LANG =~ "de" - : let trans = uk2de - :else - : let trans = uk2nl - :endif - :echo trans.translate('one two three') -< een twee drie ~ - -Here "trans" refers to one of the two objects (Dictionaries). No copy is -made. More about List and Dictionary identity can be found at |list-identity| -and |dict-identity|. - -Now you might use a language that isn't supported. You can overrule the -translate() function to do nothing: > - - :let uk2uk = copy(transdict) - :function! uk2uk.translate(line) - : return a:line - :endfunction - :echo uk2uk.translate('three one wladiwostok') -< three one wladiwostok ~ - -Notice that a ! was used to overwrite the existing function reference. Now -use "uk2uk" when no recognized language is found: > - - :if $LANG =~ "de" - : let trans = uk2de - :elseif $LANG =~ "nl" - : let trans = uk2nl - :else - : let trans = uk2uk - :endif - :echo trans.translate('one two three') -< one two three ~ - For further reading see |Lists| and |Dictionaries|. ============================================================================== @@ -1748,53 +1706,58 @@ For further reading see |Lists| and |Dic Let's start with an example: > - :try - : read ~/templates/pascal.tmpl - :catch /E484:/ - : echo "Sorry, the Pascal template file cannot be found." - :endtry - -The ":read" command will fail if the file does not exist. Instead of + try + read ~/templates/pascal.tmpl + catch /E484:/ + echo "Sorry, the Pascal template file cannot be found." + endtry + +The `read` command will fail if the file does not exist. Instead of generating an error message, this code catches the error and gives the user a nice message. -For the commands in between ":try" and ":endtry" errors are turned into +For the commands in between `try` and `endtry` errors are turned into exceptions. An exception is a string. In the case of an error the string contains the error message. And every error message has a number. In this case, the error we catch contains "E484:". This number is guaranteed to stay the same (the text may change, e.g., it may be translated). -When the ":read" command causes another error, the pattern "E484:" will not +Besides being able to give a nice error message, Vim will also continue +executing commands. Otherwise, once an uncaught error is encountered, +execution will be aborted. + +When the `read` command causes another error, the pattern "E484:" will not match in it. Thus this exception will not be caught and result in the usual error message. You might be tempted to do this: > - :try - : read ~/templates/pascal.tmpl - :catch - : echo "Sorry, the Pascal template file cannot be found." - :endtry - -This means all errors are caught. But then you will not see errors that are -useful, such as "E21: Cannot make changes, 'modifiable' is off". - -Another useful mechanism is the ":finally" command: > - - :let tmp = tempname() - :try - : exe ".,$write " .. tmp - : exe "!filter " .. tmp - : .,$delete - : exe "$read " .. tmp - :finally - : call delete(tmp) - :endtry + try + read ~/templates/pascal.tmpl + catch + echo "Sorry, the Pascal template file cannot be found." + endtry + +This means all errors are caught. But then you will not see an error that +would indicate a completely different problem, such as "E21: Cannot make +changes, 'modifiable' is off". + +Another useful mechanism is the `finally` command: > + + var tmp = tempname() + try + exe ":.,$write " .. tmp + exe "!filter " .. tmp + :.,$delete + exe ":$read " .. tmp + finally + call delete(tmp) + endtry This filters the lines from the cursor until the end of the file through the "filter" command, which takes a file name argument. No matter if the -filtering works, something goes wrong in between ":try" and ":finally" or the -user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is +filtering works, something goes wrong in between `try` and `finally` or the +user cancels the filtering by pressing CTRL-C, the `call delete(tmp)` is always executed. This makes sure you don't leave the temporary file behind. More information about exception handling can be found in the reference @@ -1803,30 +1766,25 @@ manual: |exception-handling|. ============================================================================== *41.10* Various remarks -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 MS-Windows and the like, <CR><NL> is used. This is -important when using mappings that end in a <CR>. See |:source_crnl|. +Here is a summary of items that are useful to know when writing Vim scripts. + +The end-of-line character depends on the system. For Vim scripts it is +recommended to always use the Unix fileformat, this also works on any other +system. That way you can copy your Vim scripts from MS-Windows to Unix and +they still work. See |:source_crnl|. To be sure it is set right, do this +before writing the file: > + + :setlocal fileformat=unix WHITE SPACE Blank lines are allowed and ignored. -Leading whitespace characters (blanks and TABs) are always ignored. The -whitespaces between parameters (e.g. between the "set" and the "cpoptions" in -the example below) are reduced to one blank character and plays the role of a -separator, the whitespaces after the last (visible) character may or may not -be ignored depending on the situation, see below. - -For a ":set" command involving the "=" (equal) sign, such as in: > - - :set cpoptions =aABceFst - -the whitespace immediately before the "=" sign is ignored. But there can be -no whitespace after the "=" sign! +Leading whitespace characters (blanks and TABs) are always ignored. + +Trailing whitespace is often ignored, but not always. One command that +includes it is `map`. To include a whitespace character in the value of an option, it must be escaped by a "\" (backslash) as in the following example: > @@ -1843,81 +1801,84 @@ will issue an error, because it is inter :set nice :set file +|Vim9| script is very picky when it comes to white space. This was done +intentionally to make sure scripts are easy to read and to avoid mistakes. + COMMENTS -The character " (the double quote mark) starts a comment. Everything after +In |Vim9| script the character # starts a comment. Everything after and including this character until the end-of-line is considered a comment and is ignored, except for commands that don't consider comments, as shown in -examples below. A comment can start on any character position on the line. +examples below. A comment can start on any character position on the line, +but not when it is part of the command, e.g. in a string. + +The character " (the double quote mark) starts a comment in legacy script. There is a little "catch" with comments for some commands. Examples: > - :abbrev dev development " shorthand - :map <F3> o#include " insert include - :execute cmd " do it - :!ls *.c " list C files - -The abbreviation 'dev' will be expanded to 'development " shorthand'. The + abbrev dev development # shorthand + map <F3> o#include # insert include + execute cmd # do it + !ls *.c # list C files + +The abbreviation 'dev' will be expanded to 'development # shorthand'. The mapping of <F3> will actually be the whole line after the 'o# ....' including -the '" insert include'. The "execute" command will give an error. The "!" -command will send everything after it to the shell, causing an error for an -unmatched '"' character. - There can be no comment after ":map", ":abbreviate", ":execute" and "!" -commands (there are a few more commands with this restriction). For the -":map", ":abbreviate" and ":execute" commands there is a trick: > - - :abbrev dev development|" shorthand - :map <F3> o#include|" insert include - :execute cmd |" do it +the '# insert include'. The `execute` command will give an error. The `!` +command will send everything after it to the shell, most likely causing an +error. + +There can be no comment after `map`, `abbreviate`, `execute` and `!` commands +(there are a few more commands with this restriction). For the `map`, +`abbreviate` and `execute` commands there is a trick: > + + abbrev dev development|# shorthand + map <F3> o#include|# insert include + execute '!ls *.c' |# do it With the '|' character the command is separated from the next one. And that -next command is only a comment. For the last command you need to do two -things: |:execute| and use '|': > - :exe '!ls *.c' |" list C files +next command is only a comment. The last command, using `execute` is a +general solution, it works for all commands that do not accept a comment or a +'|' to separate the next command. Notice that there is no white space before the '|' in the abbreviation and mapping. For these commands, any character until the end-of-line or '|' is included. As a consequence of this behavior, you don't always see that trailing whitespace is included: > - :map <F4> o#include - -To spot these problems, you can set the 'list' option when editing vimrc -files. + map <F4> o#include + +To spot these problems, you can highlight trailing spaces: > + match Search /\s\+$/ For Unix there is one special way to comment a line, that allows making a Vim -script executable: > +script executable, and it also works in legacy script: > #!/usr/bin/env vim -S echo "this is a Vim script" quit -The "#" command by itself lists a line with the line number. Adding an -exclamation mark changes it into doing nothing, so that you can add the shell -command to execute the rest of the file. |:#!| |-S| - PITFALLS -Even bigger problem arises in the following example: > - - :map ,ab o#include - :unmap ,ab +An even bigger problem arises in the following example: > + + map ,ab o#include + unmap ,ab Here the unmap command will not work, because it tries to unmap ",ab ". This does not exist as a mapped sequence. An error will be issued, which is very -hard to identify, because the ending whitespace character in ":unmap ,ab " is +hard to identify, because the ending whitespace character in `unmap ,ab ` is not visible. And this is the same as what happens when one uses a comment after an 'unmap' command: > - :unmap ,ab " comment + unmap ,ab # comment Here the comment part will be ignored. However, Vim will try to unmap ',ab ', which does not exist. Rewrite it as: > - :unmap ,ab| " comment + unmap ,ab| # comment RESTORING THE VIEW @@ -1925,8 +1886,9 @@ RESTORING THE VIEW Sometimes you want to make a change and go back to where the cursor was. Restoring the relative position would also be nice, so that the same line appears at the top of the window. - This example yanks the current line, puts it above the first line in the -file and then restores the view: > + +This example yanks the current line, puts it above the first line in the file +and then restores the view: > map ,p ma"aYHmbgg"aP`bzt`a @@ -1944,31 +1906,21 @@ What this does: > PACKAGING -To avoid your function names to interfere with functions that you get from -others, use this scheme: -- Prepend a unique string before each function name. I often use an - abbreviation. For example, "OW_" is used for the option window functions. -- Put the definition of your functions together in a file. Set a global - variable to indicate that the functions have been loaded. When sourcing the - file again, first unload the functions. -Example: > - - " This is the XXX package - - if exists("XXX_loaded") - delfun XXX_one - delfun XXX_two - endif - - function XXX_one(a) - ... body of function ... - endfun - - function XXX_two(b) - ... body of function ... - endfun - - let XXX_loaded = 1 +Sometimes you will want to use global variables or functions, so that they can +be used anywhere. A good example is a global variable that passes a +preference to a plugin. To avoid other scripts using the same name, use a +prefix that is very unlikely to be used elsewhere. For example, if you have a +"mytags" plugin, you could use: > + + g:mytags_location = '$HOME/project' + g:mytags_style = 'fast' + +To minimize interference between plugins keep as much as possible local to the +script. |Vim9| script helps you with that, by default functions and variables +are script-local. + +If you split your plugin into parts, you can use `import` and `export` to +share items between those parts. See `:export` for the details. ============================================================================== *41.11* Writing a plugin *write-plugin* @@ -1992,10 +1944,9 @@ NAME First of all you must choose a name for your plugin. The features provided by the plugin should be clear from its name. And it should be unlikely that someone else writes a plugin with the same name but which does something -different. And please limit the name to 8 characters, to avoid problems on -old MS-Windows systems. - -A script that corrects typing mistakes could be called "typecorr.vim". We +different. + +A script that corrects typing mistakes could be called "typecorrect.vim". We will use it here as an example. For the plugin to work for everybody, it should follow a few guidelines. This @@ -2011,7 +1962,6 @@ Let's start with the body of the plugin, 16 iabbrev wnat want 17 iabbrev synchronisation 18 \ synchronization - 19 let s:count = 4 The actual list should be much longer, of course. @@ -2019,6 +1969,18 @@ The line numbers have only been added to in your plugin file! +FIRST LINE +> + 1 vim9script noclear + +You need to use `vimscript` as the very first command. Best is to put it in +the very first line. + +The script we are writing will have a `finish` command to bail out when it is +loaded a second time. To avoid the items defined in the script are lost the +"noclear" argument is used. More info about this at |vim9-reload|. + + HEADER You will probably add new corrections to the plugin and soon have several @@ -2026,64 +1988,63 @@ versions lying around. And when distrib know who wrote this wonderful plugin and where they can send remarks. Therefore, put a header at the top of your plugin: > - 1 " Vim global plugin for correcting typing mistakes - 2 " Last Change: 2000 Oct 15 - 3 " Maintainer: Bram Moolenaar <Bram@vim.org> + 2 # Vim global plugin for correcting typing mistakes + 3 # Last Change: 2021 Dec 30 + 4 # Maintainer: Bram Moolenaar <Bram@vim.org> About copyright and licensing: Since plugins are very useful and it's hardly worth restricting their distribution, please consider making your plugin either public domain or use the Vim |license|. A short note about this near the top of the plugin should be sufficient. Example: > - 4 " License: This file is placed in the public domain. - - -LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save* + 5 # License: This file is placed in the public domain. + + +LINE CONTINUATION AND AVOIDING SIDE EFFECTS *use-cpo-save* In line 18 above, the line-continuation mechanism is used |line-continuation|. Users with 'compatible' set will run into trouble here, they will get an error message. We can't just reset 'compatible', because that has a lot of side -effects. To avoid this, we will set the 'cpoptions' option to its Vim default +effects. Instead, we will set the 'cpoptions' option to its Vim default value and restore it later. That will allow the use of line-continuation and make the script work for most people. It is done like this: > - 11 let s:save_cpo = &cpo + 11 var save_cpo = &cpo 12 set cpo&vim .. - 42 let &cpo = s:save_cpo - 43 unlet s:save_cpo - -We first store the old value of 'cpoptions' in the s:save_cpo variable. At + 42 &cpo = save_cpo + +We first store the old value of 'cpoptions' in the "save_cpo" variable. At the end of the plugin this value is restored. -Notice that a script-local variable is used |s:var|. A global variable could +Notice that "save_cpo" is a script-local variable. A global variable could already be in use for something else. Always use script-local variables for things that are only used in the script. NOT LOADING -It's possible that a user doesn't always want to load this plugin. Or the +It is possible that a user doesn't always want to load this plugin. Or the system administrator has dropped it in the system-wide plugin directory, but a user has his own plugin he wants to use. Then the user must have a chance to -disable loading this specific plugin. This will make it possible: > - - 6 if exists("g:loaded_typecorr") - 7 finish - 8 endif - 9 let g:loaded_typecorr = 1 - -This also avoids that when the script is loaded twice it would cause error -messages for redefining functions and cause trouble for autocommands that are -added twice. - -The name is recommended to start with "loaded_" and then the file name of the -plugin, literally. The "g:" is prepended just to avoid mistakes when using -the variable in a function (without "g:" it would be a variable local to the -function). - -Using "finish" stops Vim from reading the rest of the file, it's much quicker -than using if-endif around the whole file. +disable loading this specific plugin. These lines will make it possible: > + + 7 if exists("g:loaded_typecorrect") + 8 finish + 9 endif + 10 g:loaded_typecorrect = 1 + +This also avoids that when the script is loaded twice it would pointlessly +redefine functions and cause trouble for autocommands that are added twice. + +The name is recommended to start with "g:loaded_" and then the file name of +the plugin, literally. The "g:" is prepended to make the variable global, so +that other places can check whether its functionality is available. Without +"g:" it would be local to the script. + +Using `finish` stops Vim from reading the rest of the file, it's much quicker +than using if-endif around the whole file, since Vim would still need to parse +the commands to find the `endif`. MAPPING @@ -2098,10 +2059,10 @@ item can be used: > 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: > - - let mapleader = "_" +The user can set the "g:mapleader" variable to the key sequence that he wants +plugin mappings to start with. Thus if the user has done: > + + g:mapleader = "_" the mapping will define "_a". If the user didn't do this, the default value will be used, which is a backslash. Then a map for "\a" will be defined. @@ -2131,44 +2092,45 @@ If a script gets longer, you often want can use functions or mappings for this. But you don't want these functions and mappings to interfere with the ones from other scripts. For example, you could define a function Add(), but another script could try to define the same -function. To avoid this, we define the function local to the script by -prepending it with "s:". +function. To avoid this, we define the function local to the script. +Fortunately, in |Vim9| script this is the default. In a legacy script you +would need to prefix the name 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 + 30 def Add(from: string, correct: bool) + 31 var to = input("type the correction for " .. from .. ": ") + 32 exe ":iabbrev " .. from .. " " .. to .. - 36 endfunction - -Now we can call the function s:Add() from within this script. If another -script also defines s:Add(), it will be local to that script and can only -be called from the script it was defined in. There can also be a global Add() -function (without the "s:"), which is again another function. + 36 enddef + +Now we can call the function Add() from within this script. If another +script also defines Add(), it will be local to that script and can only +be called from that script. There can also be a global g:Add() function, +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 .. - 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> + 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<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 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 -mapping is typed by the user, thus outside of the script. The <SID> is -translated to the script ID, so that Vim knows in which script to look for +Note that instead of Add() we use <SID>Add() here. That is because the +mapping is typed by the user, thus outside of the script context. The <SID> +is translated to the script ID, so that Vim knows in which script to look for the Add() function. This is a bit complicated, but it's required for the plugin to work together with other plugins. The basic rule is that you use <SID>Add() in mappings and -s:Add() in other places (the script itself, autocommands, user commands). +Add() in other places (the script itself, autocommands, user commands). We can also add a menu entry to do the same as the mapping: > @@ -2217,13 +2179,16 @@ USER COMMAND Now let's add a user command to add a correction: > 38 if !exists(":Correct") - 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) + 39 command -nargs=1 Correct :call Add(<q-args>, false) 40 endif The user command is defined only if no command with the same name already exists. Otherwise we would get an error here. Overriding the existing user command with ":command!" is not a good idea, this would probably make the user wonder why the command he defined himself doesn't work. |:command| +If it did happen you can find out who to blame with: > + + verbose command Correct SCRIPT VARIABLES @@ -2234,20 +2199,25 @@ with using the same variable name in dif kept as long as Vim is running. And the same variables are used when sourcing the same script again. |s:var| -The fun is that these variables can also be used in functions, autocommands -and user commands that are defined in the script. In our example we can add -a few lines to count the number of corrections: > - - 19 let s:count = 4 +The nice thing about |Vim9| script is that variables are local to the script +by default. You can prepend "s:" if you like, but you do not need to. And +functions in the script can also use the script variables without a prefix. + +Script-local variables can also be used in functions, autocommands and user +commands that are defined in the script. Thus they are the perfect way to +share information between parts of your plugin, without it leaking out. In +our example we can add a few lines to count the number of corrections: > + + 19 var count = 4 .. - 30 function s:Add(from, correct) + 30 def Add(from: string, correct: bool) .. - 34 let s:count = s:count + 1 - 35 echo s:count .. " corrections now" - 36 endfunction - -First s:count is initialized to 4 in the script itself. When later the -s:Add() function is called, it increments s:count. It doesn't matter from + 34 count += 1 + 35 echo "you now have " .. count .. " corrections" + 36 enddef + +"count" is declared and initialized to 4 in the script itself. When later +the Add() function is called, it increments "count". It doesn't matter from where the function was called, since it has been defined in the script, it will use the local variables from this script. @@ -2256,17 +2226,17 @@ THE RESULT Here is the resulting complete example: > - 1 " Vim global plugin for correcting typing mistakes - 2 " Last Change: 2000 Oct 15 - 3 " Maintainer: Bram Moolenaar <Bram@vim.org> - 4 " License: This file is placed in the public domain. - 5 - 6 if exists("g:loaded_typecorr") - 7 finish - 8 endif - 9 let g:loaded_typecorr = 1 - 10 - 11 let s:save_cpo = &cpo + 1 vim9script noclear + 2 # Vim global plugin for correcting typing mistakes + 3 # Last Change: 2021 Dec 30 + 4 # Maintainer: Bram Moolenaar <Bram@vim.org> + 5 # License: This file is placed in the public domain. + 6 + 7 if exists("g:loaded_typecorrect") + 8 finish + 9 endif + 10 g:loaded_typecorrect = 1 + 11 var save_cpo = &cpo 12 set cpo&vim 13 14 iabbrev teh the @@ -2274,7 +2244,7 @@ Here is the resulting complete example: 16 iabbrev wnat want 17 iabbrev synchronisation 18 \ synchronization - 19 let s:count = 4 + 19 var count = 4 20 21 if !hasmapto('<Plug>TypecorrAdd;') 22 map <unique> <Leader>a <Plug>TypecorrAdd; @@ -2283,35 +2253,27 @@ Here is the resulting complete example: 25 26 noremenu <script> Plugin.Add\ Correction <SID>Add 27 - 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> + 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR> 29 - 30 function s:Add(from, correct) - 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" - 36 endfunction + 30 def Add(from: string, correct: bool) + 31 var to = input("type the correction for " .. from .. ": ") + 32 exe ":iabbrev " .. from .. " " .. to + 33 if correct | exe "normal viws\<C-R>\" \b\e" | endif + 34 count += 1 + 35 echo "you now have " .. count .. " corrections" + 36 enddef 37 38 if !exists(":Correct") - 39 command -nargs=1 Correct :call s:Add(<q-args>, 0) + 39 command -nargs=1 Correct call Add(<q-args>, false) 40 endif 41 - 42 let &cpo = s:save_cpo - 43 unlet s:save_cpo + 42 &cpo = save_cpo Line 33 wasn't explained yet. It applies the new correction to the word under the cursor. The |:normal| command is used to use the new abbreviation. Note that mappings and abbreviations are expanded here, even though the function was called from a mapping defined with ":noremap". -Using "unix" for the 'fileformat' option is recommended. The Vim scripts will -then work everywhere. Scripts with 'fileformat' set to "dos" do not work on -Unix. Also see |:source_crnl|. To be sure it is set right, do this before -writing the file: > - - :set fileformat=unix - DOCUMENTATION *write-local-help* @@ -2319,9 +2281,9 @@ It's a good idea to also write some docu when its behavior can be changed by the user. See |add-local-help| for how they are installed. -Here is a simple example for a plugin help file, called "typecorr.txt": > - - 1 *typecorr.txt* Plugin for correcting typing mistakes +Here is a simple example for a plugin help file, called "typecorrect.txt": > + + 1 *typecorrect.txt* Plugin for correcting typing mistakes 2 3 If you make typing mistakes, this plugin will have them corrected 4 automatically. @@ -2336,7 +2298,7 @@ Here is a simple example for a plugin he 13 :Correct {word} 14 Add a correction for {word}. 15 - 16 *typecorr-settings* + 16 *typecorrect-settings* 17 This plugin doesn't have any settings. The first line is actually the only one for which the format matters. It will @@ -2347,7 +2309,7 @@ line up nicely. You can add more tags inside ** in your help file. But be careful not to use existing help tags. You would probably use the name of your plugin in most of -them, like "typecorr-settings" in the example. +them, like "typecorrect-settings" in the example. Using references to other parts of the help in || is recommended. This makes it easy for the user to find associated help. @@ -2360,7 +2322,7 @@ detection snippet in a separate file. I autocommand that sets the filetype when the file name matches a pattern. Example: > - au BufNewFile,BufRead *.foo set filetype=foofoo + au BufNewFile,BufRead *.foo setlocal filetype=foofoo Write this single-line file as "ftdetect/foofoo.vim" in the first directory that appears in 'runtimepath'. For Unix that would be @@ -2375,7 +2337,7 @@ SUMMARY *plugin-special* Summary of special things to use in a plugin: -s:name Variables local to the script. +var name Variable local to the script. <SID> Script-ID, used for mappings and functions local to the script. @@ -2386,9 +2348,9 @@ hasmapto() Function to test if the user <Leader> Value of "mapleader", which the user defines as the keys that plugin mappings start with. -:map <unique> Give a warning if a mapping already exists. - -:noremap <script> Use only mappings local to the script, not global +map <unique> Give a warning if a mapping already exists. + +noremap <script> Use only mappings local to the script, not global mappings. exists(":Cmd") Check if a user command already exists. @@ -2411,19 +2373,20 @@ DISABLING If you are writing a filetype plugin to be used by many people, they need a chance to disable loading it. Put this at the top of the plugin: > - " Only do this when not done yet for this buffer + # Only do this when not done yet for this buffer if exists("b:did_ftplugin") finish endif - let b:did_ftplugin = 1 + b:did_ftplugin = 1 This also needs to be used to avoid that the same plugin is executed twice for the same buffer (happens when using an ":edit" command without arguments). Now users can disable loading the default plugin completely by making a -filetype plugin with only this line: > - - let b:did_ftplugin = 1 +filetype plugin with only these lines: > + + vim9script + b:did_ftplugin = 1 This does require that the filetype plugin directory comes before $VIMRUNTIME in 'runtimepath'! @@ -2443,10 +2406,10 @@ OPTIONS To make sure the filetype plugin only affects the current buffer use the > - :setlocal + setlocal command to set options. And only set options which are local to a buffer (see -the help for the option to check that). When using |:setlocal| for global +the help for the option to check that). When using `:setlocal` for global options or options local to a window, the value will change for many buffers, and that is not what a filetype plugin should do. @@ -2455,14 +2418,14 @@ When an option has a value that is a lis changed an option value already. First resetting to the default value and then changing it is often a good idea. Example: > - :setlocal formatoptions& formatoptions+=ro + setlocal formatoptions& formatoptions+=ro MAPPINGS To make sure mappings will only work in the current buffer use the > - :map <buffer> + map <buffer> command. This needs to be combined with the two-step mapping explained above. An example of how to define functionality in a filetype plugin: > @@ -2487,9 +2450,9 @@ The user must have a chance to disable t without disabling everything. Here is an example of how this is done for a 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 "> " + # Add mappings, unless the user didn't want this. + if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps") + # Quote text by inserting "> " if !hasmapto('<Plug>MailQuote;') vmap <buffer> <LocalLeader>q <Plug>MailQuote; nmap <buffer> <LocalLeader>q <Plug>MailQuote; @@ -2499,8 +2462,8 @@ plugin for the mail filetype: > endif Two global variables are used: -|no_plugin_maps| disables mappings for all filetype plugins -|no_mail_maps| disables mappings for the "mail" filetype +|g:no_plugin_maps| disables mappings for all filetype plugins +|g:no_mail_maps| disables mappings for the "mail" filetype USER COMMANDS @@ -2508,14 +2471,14 @@ USER COMMANDS To add a user command for a specific file type, so that it can only be used in one buffer, use the "-buffer" argument to |:command|. Example: > - :command -buffer Make make %:r.s + command -buffer Make make %:r.s VARIABLES A filetype plugin will be sourced for each buffer of the type it's for. Local -script variables |s:var| will be shared between all invocations. Use local -buffer variables |b:var| if you want a variable specifically for one buffer. +script variables will be shared between all invocations. Use local buffer +variables |b:var| if you want a variable specifically for one buffer. FUNCTIONS @@ -2524,11 +2487,11 @@ When defining a function, this only need plugin will be sourced every time a file with this filetype will be opened. This construct makes sure the function is only defined once: > - :if !exists("*s:Func") - : function s:Func(arg) - : ... - : endfunction - :endif + if !exists("*Func") + def Func(arg) + ... + enddef + endif < UNDO *undo_indent* *undo_ftplugin* @@ -2537,7 +2500,7 @@ When the user does ":setfiletype xyz" th 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<" + b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" \ .. "| unlet b:match_ignorecase b:match_words b:match_skip" Using ":setlocal" with "<" after the option name resets the option to its @@ -2569,14 +2532,14 @@ Summary of special things to use in a fi <LocalLeader> Value of "maplocalleader", which the user defines as the keys that filetype plugin mappings start with. -:map <buffer> Define a mapping local to the buffer. - -:noremap <script> Only remap mappings defined in this script that start +map <buffer> Define a mapping local to the buffer. + +noremap <script> Only remap mappings defined in this script that start with <SID>. -:setlocal Set an option for the current buffer only. - -:command -buffer Define a user command local to the buffer. +setlocal Set an option for the current buffer only. + +command -buffer Define a user command local to the buffer. exists("*s:Func") Check if a function was already defined. @@ -2592,17 +2555,17 @@ load it with the |:compiler| command. T Easiest is to have a look at examples. This command will edit all the default compiler plugins: > - :next $VIMRUNTIME/compiler/*.vim - -Use |:next| to go to the next plugin file. + next $VIMRUNTIME/compiler/*.vim + +Type `:next` to go to the next plugin file. There are two special items about these files. First is a mechanism to allow a user to overrule or add to the default file. The default files start with: > - :if exists("current_compiler") - : finish - :endif - :let current_compiler = "mine" + if exists("g:current_compiler") + finish + endif + g:current_compiler = "mine" When you write a compiler file and put it in your personal runtime directory (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to @@ -2644,8 +2607,9 @@ mean is that it loads quickly the first script to the second time, which only happens when you actually use it. When you always use the functionality it actually gets slower! -Note that since Vim 7 there is an alternative: use the |autoload| -functionality |41.15|. +This uses a FuncUndefined autocommand. Since Vim 7 there is an alternative: +use the |autoload| functionality |41.15|. That will also use |Vim9| script +instead of legacy script that is used here. The following example shows how it's done: > @@ -2718,7 +2682,7 @@ Example: > if !exists('*MyLibFunction') runtime library/mylibscript.vim endif - call MyLibFunction(arg) + MyLibFunction(arg) Here you need to know that MyLibFunction() is defined in a script "library/mylibscript.vim" in one of the directories in 'runtimepath'. @@ -2726,11 +2690,12 @@ Here you need to know that MyLibFunction To make this a bit simpler Vim offers the autoload mechanism. Then the example looks like this: > - call mylib#myfunction(arg) - -That's a lot simpler, isn't it? Vim will recognize the function name and when -it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'. -That script must define the "mylib#myfunction()" function. + mylib#myfunction(arg) + +That's a lot simpler, isn't it? Vim will recognize the function name by the +embedded "#" character and when it's not defined search for the script +"autoload/mylib.vim" in 'runtimepath'. That script must define the +"mylib#myfunction()" function. You can put many other functions in the mylib.vim script, you are free to organize your functions in library scripts. But you must use function names @@ -2740,7 +2705,7 @@ not know what script to load. If you get really enthusiastic and write lots of library scripts, you may want to use subdirectories. Example: > - call netlib#ftp#read('somefile') + netlib#ftp#read('somefile') For Unix the library script used for this could be: @@ -2748,9 +2713,9 @@ For Unix the library script used for thi Where the function is defined like this: > - function netlib#ftp#read(fname) - " Read the file fname through ftp - endfunction + def netlib#ftp#read(fname: string) + # Read the file fname through ftp + enddef Notice that the name the function is defined with is exactly the same as the name used for calling the function. And the part before the last '#' @@ -2758,12 +2723,12 @@ exactly matches the subdirectory and scr You can use the same mechanism for variables: > - let weekdays = dutch#weekdays + var weekdays = dutch#weekdays This will load the script "autoload/dutch.vim", which should contain something like: > - let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag', + var dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag', \ 'donderdag', 'vrijdag', 'zaterdag'] Further reading: |autoload|. @@ -2774,9 +2739,13 @@ Further reading: |autoload|. Vim users will look for scripts on the Vim website: http://www.vim.org. If you made something that is useful for others, share it! -Vim scripts can be used on any system. There might not be a tar or gzip -command. If you want to pack files together and/or compress them the "zip" -utility is recommended. +Another place is github. But there you need to know where to find it! The +advantage is that most plugin managers fetch plugins from github. You'll have +to use your favorite search engine to find them. + +Vim scripts can be used on any system. However, there might not be a tar or +gzip command. If you want to pack files together and/or compress them the +"zip" utility is recommended. For utmost portability use Vim itself to pack scripts together. This can be done with the Vimball utility. See |vimball|.
--- a/runtime/syntax/vim.vim +++ b/runtime/syntax/vim.vim @@ -1,8 +1,8 @@ " Vim syntax file " Language: Vim 8.2 script " Maintainer: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> -" Last Change: December 21, 2021 -" Version: 8.2-20 +" Last Change: December 29, 2021 +" Version: 8.2-23 " URL: http://www.drchip.org/astronaut/vim/index.html#SYNTAX_VIM " Automatically generated keyword lists: {{{1 @@ -19,12 +19,12 @@ syn keyword vimTodo contained COMBAK FIX syn cluster vimCommentGroup contains=vimTodo,@Spell " regular vim commands {{{2 -syn keyword vimCommand contained a ar[gs] argl[ocal] ba[ll] bl[ast] brea[k] buffers ca caf[ter] cbo[ttom] cex[pr] cgete[xpr] cl[ist] cn[ext] colo[rscheme] cons[t] cs d[elete] delel delf[unction] dif[fupdate] difft[his] dli[st] ds[earch] echoc[onsole] em[enu] endw[hile] export filt[er] fo[ld] fu[nction] gvim helpt[ags] iabc[lear] import isp[lit] keepa l[ist] laf[ter] lbel[ow] lcscope lf[ile] lgr[ep] lli[st] lnf[ile] lol[der] lt[ag] lw[indow] menut[ranslate] mkvie[w] nbc[lose] noh[lsearch] ol[dfiles] pa[ckadd] po[p] prof[ile] pta[g] ptr[ewind] py3f[ile] pythonx quita[ll] redraws[tatus] rew[ind] rubyf[ile] sIg sa[rgument] sba[ll] sbr[ewind] scl scscope sfir[st] sgl sic sin sm[ap] snoreme spelld[ump] spellw[rong] srg sta[g] sts[elect] sus[pend] syncbind tabN[ext] tabl[ast] tabr[ewind] tcld[o] tj[ump] tlu tno[remap] tu[nmenu] undol[ist] v vie[w] vne[w] wh[ile] wn[ext] wv[iminfo] xmenu xunme -syn keyword vimCommand contained ab arga[dd] argu[ment] bad[d] bm[odified] breaka[dd] bun[load] cabc[lear] cal[l] cc cf[ile] changes cla[st] cnew[er] com cope[n] cscope debug delep dell diffg[et] dig[raphs] do dsp[lit] echoe[rr] en[dif] ene[w] exu[sage] fin[d] foldc[lose] g h[elp] hi if in iuna[bbrev] keepalt la[st] lan[guage] lbo[ttom] ld[o] lfdo lgrepa[dd] lma lo[adview] lop[en] lua m[ove] mes[sages] mod[e] nbs[tart] nor omapc[lear] packl[oadall] popu[p] profd[el] ptf[irst] pts[elect] py3f[ile] pyx r[ead] redrawt[abline] ri[ght] rundo sIl sal[l] sbf[irst] sc scp se[t] sg sgn sie sip sme snoremenu spelli[nfo] spr[evious] sri star[tinsert] substitutepattern sv[iew] syntime tabc[lose] tabm[ove] tabs tclf[ile] tl[ast] tlunmenu to[pleft] tunma[p] unh[ide] var vim9[cmd] vs[plit] win[size] wp[revious] x[it] xnoreme xunmenu -syn keyword vimCommand contained abc[lear] argd[elete] as[cii] balt bn[ext] breakd[el] bw[ipeout] cabo[ve] cat[ch] ccl[ose] cfdo chd[ir] class cnf[ile] comc[lear] cp[revious] cstag debugg[reedy] deletel delm[arks] diffo[ff] dir doau e[dit] echom[sg] enddef eval f[ile] fina[lly] foldd[oopen] go[to] ha[rdcopy] hid[e] ij[ump] inor j[oin] keepj[umps] lab[ove] lat lc[d] le[ft] lfir[st] lh[elpgrep] lmak[e] loadk lp[revious] luado ma[rk] mk[exrc] mz[scheme] new nore on[ly] pc[lose] pp[op] promptf[ind] ptj[ump] pu[t] py[thon] pyxdo rec[over] reg[isters] rightb[elow] rv[iminfo] sIn san[dbox] sbl[ast] scI scr[iptnames] setf[iletype] sgI sgp sig sir smenu so[urce] spellr[are] sr srl startg[replace] substituterepeat sw[apname] t tabd[o] tabn[ext] tags te[aroff] tlm tm[enu] tp[revious] type unl ve[rsion] vim9s[cript] wN[ext] winc[md] wq xa[ll] xnoremenu xwininfo -syn keyword vimCommand contained abo[veleft] argdo au bd[elete] bo[tright] breakl[ist] cN[ext] cad[dbuffer] cb[uffer] cd cfir[st] che[ckpath] cle[arjumps] cnor comp[iler] cpf[ile] cun def deletep delp diffp[atch] disa[ssemble] doaut ea echon endf[unction] ex files fini[sh] folddoc[losed] gr[ep] helpc[lose] his[tory] il[ist] interface ju[mps] keepp[atterns] lad[dexpr] later lch[dir] lefta[bove] lg[etfile] lhi[story] lmapc[lear] loadkeymap lpf[ile] luafile mak[e] mks[ession] mzf[ile] nmapc[lear] nos[wapfile] opt[ions] pe[rl] pre[serve] promptr[epl] ptl[ast] pw[d] pydo pyxfile red[o] res[ize] ru[ntime] sI sIp sav[eas] sbm[odified] sce scripte[ncoding] setg[lobal] sgc sgr sign sl[eep] smile sor[t] spellr[epall] srI srn startr[eplace] sun[hide] sy tN[ext] tabe[dit] tabnew tc[d] ter[minal] tlmenu tma[p] tr[ewind] u[ndo] unlo[ckvar] verb[ose] vim[grep] w[rite] windo wqa[ll] xmapc[lear] xprop y[ank] -syn keyword vimCommand contained addd arge[dit] bN[ext] bel[owright] bp[revious] bro[wse] cNf[ile] cadde[xpr] cbe[fore] cdo cg[etfile] checkt[ime] clo[se] co[py] con[tinue] cq[uit] cuna[bbrev] defc[ompile] deletl dep diffpu[t] dj[ump] dp earlier el[se] endfo[r] exi[t] filet fir[st] foldo[pen] grepa[dd] helpf[ind] i imapc[lear] intro k lN[ext] laddb[uffer] lb[uffer] lcl[ose] leg[acy] lgetb[uffer] ll lne[xt] loc[kmarks] lr[ewind] lv[imgrep] marks mksp[ell] n[ext] noa nu[mber] ownsyntax ped[it] prev[ious] ps[earch] ptn[ext] py3 pyf[ile] q[uit] redi[r] ret[ab] rub[y] sIc sIr sbN[ext] sbn[ext] scg scriptv[ersion] setl[ocal] sge sh[ell] sil[ent] sla[st] sn[ext] sp[lit] spellr[rare] src srp stj[ump] sunme syn ta[g] tabf[ind] tabo[nly] tch[dir] tf[irst] tln tmapc[lear] try una[bbreviate] uns[ilent] vert[ical] vimgrepa[dd] wa[ll] winp[os] wundo xme xr[estore] z[^.=] -syn keyword vimCommand contained al[l] argg[lobal] b[uffer] bf[irst] br[ewind] bufdo c[hange] caddf[ile] cbel[ow] ce[nter] cgetb[uffer] chi[story] cmapc[lear] col[der] conf[irm] cr[ewind] cw[indow] delc[ommand] deletp di[splay] diffs[plit] dl dr[op] ec elsei[f] endt[ry] exp filetype fix[del] for gui helpg[rep] ia imp is[earch] kee[pmarks] lNf[ile] laddf[ile] lbe[fore] lcs lex[pr] lgete[xpr] lla[st] lnew[er] lockv[ar] ls lvimgrepa[dd] mat[ch] mkv[imrc] nb[key] noautocmd o[pen] p[rint] perld[o] pro ptN[ext] ptp[revious] py3do python3 qa[ll] redr[aw] retu[rn] rubyd[o] sIe sN[ext] sb[uffer] sbp[revious] sci scs sf[ind] sgi si sim[alt] sm[agic] sno[magic] spe[llgood] spellu[ndo] sre[wind] st[op] stopi[nsert] sunmenu sync tab tabfir[st] tabp[revious] tcl th[row] tlnoremenu tn[ext] ts[elect] undoj[oin] up[date] vi[sual] viu[sage] +syn keyword vimCommand contained a ar[gs] argg[lobal] b[uffer] bf[irst] br[ewind] bufdo c[hange] caddf[ile] cbel[ow] ce[nter] cgetb[uffer] chi[story] cmapc[lear] col[der] conf[irm] cr[ewind] cw[indow] delc[ommand] deletp di[splay] diffs[plit] dl dr[op] ec elsei[f] endt[ry] exp filetype fix[del] for gui helpg[rep] ia imp is[earch] kee[pmarks] lNf[ile] laddf[ile] lbe[fore] lcs lex[pr] lgete[xpr] lla[st] lnew[er] lockv[ar] ls lvimgrepa[dd] mat[ch] mkv[imrc] nb[key] noautocmd o[pen] p[rint] perld[o] pro ptN[ext] ptp[revious] py3do python3 qa[ll] redr[aw] retu[rn] rubyd[o] sIe sN[ext] sb[uffer] sbp[revious] sci scs sf[ind] sgi si sim[alt] sm[agic] sno[magic] spe[llgood] spellu[ndo] sre[wind] st[op] stopi[nsert] sunmenu sync tab tabfir[st] tabp[revious] tcl th[row] tlnoremenu tn[ext] ts[elect] undoj[oin] up[date] vi[sual] viu[sage] wh[ile] wn[ext] wv[iminfo] xmenu xunme +syn keyword vimCommand contained ab arga[dd] argl[ocal] ba[ll] bl[ast] brea[k] buffers ca caf[ter] cbo[ttom] cex[pr] cgete[xpr] cl[ist] cn[ext] colo[rscheme] cons[t] cs d[elete] delel delf[unction] dif[fupdate] difft[his] dli[st] ds[earch] echoc[onsole] em[enu] endw[hile] export filt[er] fo[ld] fu[nction] gvim helpt[ags] iabc[lear] import isp[lit] keepa l[ist] laf[ter] lbel[ow] lcscope lf[ile] lgr[ep] lli[st] lnf[ile] lol[der] lt[ag] lw[indow] menut[ranslate] mkvie[w] nbc[lose] noh[lsearch] ol[dfiles] pa[ckadd] po[p] prof[ile] pta[g] ptr[ewind] py3f[ile] pythonx quita[ll] redraws[tatus] rew[ind] rubyf[ile] sIg sa[rgument] sba[ll] sbr[ewind] scl scscope sfir[st] sgl sic sin sm[ap] snoreme spelld[ump] spellw[rong] srg sta[g] sts[elect] sus[pend] syncbind tabN[ext] tabl[ast] tabr[ewind] tcld[o] tj[ump] tlu tno[remap] tu[nmenu] undol[ist] v vie[w] vne[w] win[size] wp[revious] x[it] xnoreme xunmenu +syn keyword vimCommand contained abc[lear] argd[elete] argu[ment] bad[d] bm[odified] breaka[dd] bun[load] cabc[lear] cal[l] cc cf[ile] changes cla[st] cnew[er] com cope[n] cscope debug delep dell diffg[et] dig[raphs] do dsp[lit] echoe[rr] en[dif] ene[w] exu[sage] fin[d] foldc[lose] g h[elp] hi if in iuna[bbrev] keepalt la[st] lan[guage] lbo[ttom] ld[o] lfdo lgrepa[dd] lma lo[adview] lop[en] lua m[ove] mes[sages] mod[e] nbs[tart] nor omapc[lear] packl[oadall] popu[p] profd[el] ptf[irst] pts[elect] py3f[ile] pyx r[ead] redrawt[abline] ri[ght] rundo sIl sal[l] sbf[irst] sc scp se[t] sg sgn sie sip sme snoremenu spelli[nfo] spr[evious] sri star[tinsert] substitutepattern sv[iew] syntime tabc[lose] tabm[ove] tabs tclf[ile] tl[ast] tlunmenu to[pleft] tunma[p] unh[ide] var vim9[cmd] vs[plit] winc[md] wq xa[ll] xnoremenu xwininfo +syn keyword vimCommand contained abo[veleft] argded[upe] as[cii] balt bn[ext] breakd[el] bw[ipeout] cabo[ve] cat[ch] ccl[ose] cfdo chd[ir] class cnf[ile] comc[lear] cp[revious] cstag debugg[reedy] deletel delm[arks] diffo[ff] dir doau e[dit] echom[sg] enddef eval f[ile] fina[lly] foldd[oopen] go[to] ha[rdcopy] hid[e] ij[ump] inor j[oin] keepj[umps] lab[ove] lat lc[d] le[ft] lfir[st] lh[elpgrep] lmak[e] loadk lp[revious] luado ma[rk] mk[exrc] mz[scheme] new nore on[ly] pc[lose] pp[op] promptf[ind] ptj[ump] pu[t] py[thon] pyxdo rec[over] reg[isters] rightb[elow] rv[iminfo] sIn san[dbox] sbl[ast] scI scr[iptnames] setf[iletype] sgI sgp sig sir smenu so[urce] spellr[are] sr srl startg[replace] substituterepeat sw[apname] t tabd[o] tabn[ext] tags te[aroff] tlm tm[enu] tp[revious] type unl ve[rsion] vim9s[cript] wN[ext] windo wqa[ll] xmapc[lear] xprop y[ank] +syn keyword vimCommand contained addd argdo au bd[elete] bo[tright] breakl[ist] cN[ext] cad[dbuffer] cb[uffer] cd cfir[st] che[ckpath] cle[arjumps] cnor comp[iler] cpf[ile] cun def deletep delp diffp[atch] disa[ssemble] doaut ea echon endf[unction] ex files fini[sh] folddoc[losed] gr[ep] helpc[lose] his[tory] il[ist] interface ju[mps] keepp[atterns] lad[dexpr] later lch[dir] lefta[bove] lg[etfile] lhi[story] lmapc[lear] loadkeymap lpf[ile] luafile mak[e] mks[ession] mzf[ile] nmapc[lear] nos[wapfile] opt[ions] pe[rl] pre[serve] promptr[epl] ptl[ast] pw[d] pydo pyxfile red[o] res[ize] ru[ntime] sI sIp sav[eas] sbm[odified] sce scripte[ncoding] setg[lobal] sgc sgr sign sl[eep] smile sor[t] spellr[epall] srI srn startr[eplace] sun[hide] sy tN[ext] tabe[dit] tabnew tc[d] ter[minal] tlmenu tma[p] tr[ewind] u[ndo] unlo[ckvar] verb[ose] vim[grep] w[rite] winp[os] wundo xme xr[estore] z[^.=] +syn keyword vimCommand contained al[l] arge[dit] bN[ext] bel[owright] bp[revious] bro[wse] cNf[ile] cadde[xpr] cbe[fore] cdo cg[etfile] checkt[ime] clo[se] co[py] con[tinue] cq[uit] cuna[bbrev] defc[ompile] deletl dep diffpu[t] dj[ump] dp earlier el[se] endfo[r] exi[t] filet fir[st] foldo[pen] grepa[dd] helpf[ind] i imapc[lear] intro k lN[ext] laddb[uffer] lb[uffer] lcl[ose] leg[acy] lgetb[uffer] ll lne[xt] loc[kmarks] lr[ewind] lv[imgrep] marks mksp[ell] n[ext] noa nu[mber] ownsyntax ped[it] prev[ious] ps[earch] ptn[ext] py3 pyf[ile] q[uit] redi[r] ret[ab] rub[y] sIc sIr sbN[ext] sbn[ext] scg scriptv[ersion] setl[ocal] sge sh[ell] sil[ent] sla[st] sn[ext] sp[lit] spellr[rare] src srp stj[ump] sunme syn ta[g] tabf[ind] tabo[nly] tch[dir] tf[irst] tln tmapc[lear] try una[bbreviate] uns[ilent] vert[ical] vimgrepa[dd] wa[ll] syn match vimCommand contained "\<z[-+^.=]\=\>" syn keyword vimStdPlugin contained Arguments Asm Break Cfilter Clear Continue DiffOrig Evaluate Finish Gdb Lfilter Man N[ext] Over P[rint] Program Run S Source Step Stop Termdebug TermdebugCommand TOhtml Winbar XMLent XMLns