diff options
| -rw-r--r-- | runtime/doc/builtin.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/change.txt | 5 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 14 | ||||
| -rw-r--r-- | runtime/doc/filetype.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/insert.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/tags | 6 | ||||
| -rw-r--r-- | runtime/doc/todo.txt | 5 | ||||
| -rw-r--r-- | runtime/doc/usr_41.txt | 1559 | ||||
| -rw-r--r-- | runtime/syntax/vim.vim | 16 |
9 files changed, 798 insertions, 822 deletions
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index cf48b4d989..a6b8e3163f 100644 --- 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 diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c877ddb073..2799dc9e6d 100644 --- 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 comment leader after hitting <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 diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 3d2d203164..383920718f 100644 --- 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 closed. {not available when compiled 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" you can have a local variable with the 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 diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index d832e9b113..6842e1de55 100644 --- 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 @@ define yourself. There are a few ways to avoid this: 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 < diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 5d25847aa8..3751f279aa 100644 --- 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 before the cursor in the current 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 a new line is obtained from the 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. diff --git a/runtime/doc/tags b/runtime/doc/tags index c2db4e6bb0..b52e52644e 100644 --- a/runtime/doc/tags +++ b/runtime/doc/tags @@ -6968,6 +6968,8 @@ g:netrw_win95ftp pi_netrw.txt /*g:netrw_win95ftp* 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* diff --git a/runtime/doc/todo.txt b/runtime/doc/todo.txt index 7c99a65cde..5b227e38e2 100644 --- 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/issues/1234 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. diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 89bd542825..a9abe59be1 100644 --- 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 is the vimrc file. Vim reads it when 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 uses yourself. 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 `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 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 + 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 +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, octal or binary. A hexadecimal number starts with "0x" or "0X". For example "0x1f" is decimal 31. -An octal number starts with "0o", "0O" or a zero and another digit. "0o17" is -decimal 15. Using just a zero prefix is not supported in Vim9 script. +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! +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 always prints decimal numbers. Example: > +The `echo` command evaluates its argument and always prints decimal numbers. +Example: > - :echo 0x7f 0o36 + 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: > +octal and binary numbers: > + + echo -0x7f +< -127 ~ - :echo 0x7f -0o36 -< 97 ~ +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: > -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 +< E1004: White space required before and after '-' at "-0o36" ~ - :echo 0x7f - 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 variable names are: 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: > +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. - :let s:count = 1 - :while s:count < 5 - : source other.vim - : let s:count += 1 - :endwhile +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": > -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|. + 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: > +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 s:count + unlet g:counter -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 !: > +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! s:count + unlet! g:counter -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: > +You cannot `unlet` script-local variables in |Vim9| script. You can in legacy +script. - :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" +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 -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: > +Every time you call the function it will return the next count: > + :echo g:GetCount() +< 1 ~ +> + :echo g:GetCount() +< 2 ~ - :if !exists(s:call_count) +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. -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! +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: > +Example: > - :let name = "peter" - :echo name + var name = "Peter" + echo name < peter ~ -If you want to include a double quote inside the string, put a backslash in -front of it: > +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: > - :let name = "\"peter\"" - :echo name -< "peter" ~ + 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 in an expression are: Examples: > - :echo "The value of 'tabstop' is" &ts - :echo "Your home directory is" $HOME - :if @a > 5 + echo "The value of 'tabstop' is" &ts + echo "Your home directory is" $HOME + if @a == 'text' -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: > +The &name form can also be used to set an option value, do something and +restore the old value. Example: > - :let save_ic = &ic - :set noic - :/The Start/,$delete - :let &ic = save_ic + 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: +The `if` commands executes the following statements, until the matching +`endif`, only when a condition is met. The generic form is: - :if {condition} + if {condition} {statements} - :endif + 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: +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`. - :if {condition} +You can also use `else`. The generic form for this is: + + if {condition} {statements} - :else + else {statements} - :endif + endif -The second {statements} is only executed if the first one isn't. - Finally, there is ":elseif": +The second {statements} block is only executed if the first one isn't. - :if {condition} +Finally, there is `elseif` + + if {condition} {statements} - :elseif {condition} + elseif {condition} {statements} - :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: > +This works just like using `else` and then `if`, but without the need for an +extra `endif`. - :if &term == "xterm" - : " Do stuff for xterm - :elseif &term == "vt100" - : " Do stuff for a vt100 terminal - :else - : " Do something for other terminals - :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: > +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 + 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. +If you try to compare a string with a number you will get an error. -For strings there are two more items: +For strings there are two more useful items: - a =~ b matches with - a !~ b does not match with + str =~ pat matches with + str !~ pat does not match with -The left item "a" is used as a string. The right item "b" is used as a +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": +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 + 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 + 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. +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|. +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 + tag get_cmd -The ":execute" command can only execute colon commands. The ":normal" command +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 + normal gg=G + +This jumps to the first line with "gg" and formats all lines with the "=" +operator and the "G" movement. -This jumps to the first line and formats all lines with the "=" operator. - To make ":normal" work with an expression, combine ":execute" with it. +To make `normal` work with an expression, combine `execute` with it. Example: > - :execute "normal " .. normal_commands + execute "normal " .. count .. "j" + +This will move the cursor "count" lines down. -The variable "normal_commands" must contain the Normal mode commands. - Make sure that the argument for ":normal" is a complete command. Otherwise +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: > +if you start the delete operator, you must give the movement command also. +This works: > + + normal d$ - :execute "normal Inew text \<Esc>" +This does nothing: > -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. + 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|. +list below: |function-list|. -A function is called with the ":call" command. The parameters are passed in +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 expre |