diff options
author | Bram Moolenaar <Bram@vim.org> | 2004-06-13 20:20:40 +0000 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2004-06-13 20:20:40 +0000 |
commit | 071d4279d6ab81b7187b48f3a0fc61e587b6db6c (patch) | |
tree | 221cbe3c40e043163c06f61c52a7ba2eb41e12ce /runtime/doc/usr_41.txt | |
parent | b4210b3bc14e2918f153a7307530fbe6eba659e1 (diff) |
updated for version 7.0001v7.0001
Diffstat (limited to 'runtime/doc/usr_41.txt')
-rw-r--r-- | runtime/doc/usr_41.txt | 1724 |
1 files changed, 1724 insertions, 0 deletions
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt new file mode 100644 index 0000000000..e0ea026df2 --- /dev/null +++ b/runtime/doc/usr_41.txt @@ -0,0 +1,1724 @@ +*usr_41.txt* For Vim version 7.0aa. Last change: 2004 May 06 + + VIM USER MANUAL - by Bram Moolenaar + + Write a Vim script + + +The Vim script language is used for the startup vimrc file, syntax files, and +many other things. This chapter explains the items that can be used in a Vim +script. There are a lot of them, thus this is a long chapter. + +|41.1| Introduction +|41.2| Variables +|41.3| Expressions +|41.4| Conditionals +|41.5| Executing an expression +|41.6| Using functions +|41.7| Defining a function +|41.8| Exceptions +|41.9| Various remarks +|41.10| Writing a plugin +|41.11| Writing a filetype plugin +|41.12| Writing a compiler plugin + + Next chapter: |usr_42.txt| Add new menus + Previous chapter: |usr_40.txt| Make new commands +Table of contents: |usr_toc.txt| + +============================================================================== +*41.1* Introduction *vim-script-intro* + +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 +specific file type. A complicated macro can be defined by a separate Vim +script file. You can think of other uses yourself. + +Let's start with a simple example: > + + :let i = 1 + :while i < 5 + : echo "count is" i + : let 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. + +The ":let" command assigns a value to a variable. The generic form is: > + + :let {variable} = {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 +condition is true. The condition used here is the expression "i < 5". This +is true when the variable i is smaller than five. + 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 another ":let i =" command. The value used is the expression "i ++ 1". This adds one to the variable i and assigns the new value to the same +variable. + The output of the example code is: + + count is 1 ~ + count is 2 ~ + count is 3 ~ + count is 4 ~ + + 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). + + +THREE KINDS OF NUMBERS + +Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts +with "0x" or "0X". For example "0x1f" is 31. An octal number starts with a +zero. "017" is 15. Careful: don't put a zero before a decimal number, it +will be interpreted as an octal number! + The ":echo" command always prints decimal numbers. Example: > + + :echo 0x7f 036 +< 127 30 ~ + +A number is made negative with a minus sign. This also works for hexadecimal +and octal numbers. A minus sign is also for subtraction. Compare this with +the previous example: > + + :echo 0x7f -036 +< 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, put a space between the minus sign +and the following number: > + + :echo 0x7f - 036 + +============================================================================== +*41.2* Variables + +A variable name consists of ASCII letters, digits and the underscore. It +cannot start with a digit. Valid variable names are: + + counter + _aap3 + very_long_variable_name_with_underscores + FuncLength + LENGTH + +Invalid names are "foo+bar" and "6var". + These variables are global. To see a list of currently defined variables +use 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 = 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|. + +There are more kinds of variables, see |internal-variables|. The most often +used ones are: + + b:name variable local to a buffer + w:name variable local to a window + g:name global variable (also in a function) + v:name variable predefined by Vim + + +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. Only zero is false. + + +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 only two types of variables that Vim +supports. The type is dynamic, it is set each time when assigning a value to +the variable with ":let". + 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 +< 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" ~ + +To avoid the need for a backslash, you can use a string in single quotes: > + + :let name = '"peter"' + :echo name +< "peter" ~ + +Inside a single-quote string all the characters are taken literally. The +drawback is that it's impossible to include a single quote. A backslash is +taken literally as well, 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: + + \t <Tab> + \n <NL>, line break + \r <CR>, <Enter> + \e <Esc> + \b <BS>, backspace + \" " + \\ \, backslash + \<Esc> <Esc> + \<C-W> CTRL-W + +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. + +============================================================================== +*41.3* Expressions + +Vim has a rich, yet simple 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 +themselves. Thus everywhere an expression is expected, you can use a number, +string or variable. Other basic items in an expression are: + + $NAME environment variable + &name option + @r register + +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 + +This makes sure the "The Start" pattern is used with the 'ignorecase' option +off. Still, it keeps the value that the user had set. + + +MATHEMATICS + +It becomes more interesting if we combine these basic items. Let's start with +mathematics on numbers: + + a + b add + a - b subtract + a * b multiply + a / b divide + a % b modulo + +The usual precedence is used. Example: > + + :echo 10 + 5 * 2 +< 20 ~ + +Grouping is done with braces. No surprises here. Example: > + + :echo (10 + 5) * 2 +< 30 ~ + +Strings can be concatenated with ".". Example: > + + :echo "foo" . "bar" +< foobar ~ + +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: + + 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 ~ + +The three parts of the constructs are always evaluated first, thus you could +see it work 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} + {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} + {statements} + :else + {statements} + :endif + +The second {statements} is only executed if the first one isn't. + Finally, there is ":elseif": + + :if {condition} + {statements} + :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 + + +LOGIC OPERATIONS + +We already used some of them in the examples. These are the most often used +ones: + + a == b equal to + a != b not equal to + a > b greater than + a >= b greater than or equal to + 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 >= 600 + : 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 +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 +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 + +Notice the use of a single-quote string for the pattern. This is useful, +because backslashes 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-==|. + + +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 + loop continues. + :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. + +============================================================================== +*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 +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 + +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 +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. +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 +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. + +============================================================================== +*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 +between braces, separated by commas. Example: > + + :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. + +A function can be called in an expression. Example: > + + :let line = getline(".") + :let repl = substitute(line, '\a', "*", "g") + :call setline(".", repl) + +The getline() function obtains a line from the current file. 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 +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: > + + :substitute/\a/*/g + +Using the functions becomes more interesting when you do more work before and +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. + +String manipulation: + char2nr() get ASCII value of a character + nr2char() get a character by its ASCII value + escape() escape characters in a string with a '\' + strtrans() translate a string to make it printable + tolower() turn a string to lowercase + toupper() turn a string to uppercase + match() position where a pattern matches in a string + matchend() position where a pattern match ends in a string + matchstr() match of a pattern in a string + stridx() first index of a short string in a long string + strridx() last index of a short string in a long string + strlen() length of a string + substitute() substitute a pattern match with a string + submatch() get a specific match in a ":substitute" + strpart() get part of a string + expand() expand special keywords + type() type of a variable + iconv() convert text from one encoding to another + +Working with text in the current buffer: + byte2line() get line number at a specific byte count + line2byte() byte count at a specific line + col() column number of the cursor or a mark + virtcol() screen column of the cursor or a mark + line() line number of the cursor or mark + wincol() window column number of the cursor + winline() window line number of the cursor + cursor() position the cursor at a line/column + getline() get a line from the buffer + setline() replace a line in the buffer + append() append {string} below line {lnum} + indent() indent of a specific line + cindent() indent according to C indenting + lispindent() indent according to Lisp indenting + nextnonblank() find next non-blank line + prevnonblank() find previous non-blank line + search() find a match for a pattern + searchpair() find the other end of a start/skip/end + +System functions and manipulation of files: + browse() put up a file requester + glob() expand wildcards + globpath() expand wildcards in a number of directories + resolve() find out where a shortcut points to + fnamemodify() modify a file name + executable() check if an executable program exists + filereadable() check if a file can be read + filewritable() check if a file can be written to + isdirectory() check if a directory exists + getcwd() get the current working directory + getfsize() get the size of a file + getftime() get last modification time of a file + localtime() get current time + strftime() convert time to a string + tempname() get the name of a temporary file + delete() delete a file + rename() rename a file + system() get the result of a shell command + hostname() name of the system + +Buffers, windows and the argument list: + argc() number of entries in the argument list + argidx() current position in the argument list + argv() get one entry from the argument list + bufexists() check if a buffer exists + buflisted() check if a buffer exists and is listed + bufloaded() check if a buffer exists and is loaded + bufname() get the name of a specific buffer + bufnr() get the buffer number of a specific buffer + winnr() get the window number for the current window + bufwinnr() get the window number of a specific buffer + winbufnr() get the buffer number of a specific window + getbufvar() get a variable value from a specific buffer + setbufvar() set a variable in a specific buffer + getwinvar() get a variable value from a specific window + setwinvar() set a variable in a specific window + +Folding: + foldclosed() check for a closed fold at a specific line + foldclosedend() like foldclosed() but return the last line + foldlevel() check for the fold level at a specific line + foldtext() generate the line displayed for a closed fold + +Syntax highlighting: + hlexists() check if a highlight group exists + hlID() get ID of a highlight group + synID() get syntax ID at a specific position + synIDattr() get a specific attribute of a syntax ID + synIDtrans() get translated syntax ID + +History: + histadd() add an item to a history + histdel() delete an item from a history + histget() get an item from a history + histnr() get highest index of a history list + +Interactive: + confirm() let the user make a choice + getchar() get a character from the user + getcharmod() get modifiers for the last typed character + input() get a line from the user + inputsecret() get a line from the user without showing it + inputdialog() get a line from the user in a dialog + inputresave save and clear typeahead + inputrestore() restore typeahead + +Vim server: + serverlist() return the list of server names + remote_send() send command characters to a Vim server + remote_expr() evaluate an expression in a Vim server + server2client() send a reply to a client of a Vim server + remote_peek() check if there is a reply from a Vim server + remote_read() read a reply from a Vim server + foreground() move the Vim window to the foreground + remote_foreground() move the Vim server window to the foreground + +Various: + mode() get current editing mode + visualmode() last visual mode used + hasmapto() check if a mapping exists + mapcheck() check if a matching mapping exists + maparg() get rhs of a mapping + exists() check if a variable, function, etc. exists + has() check if a feature is supported in Vim + cscope_connection() check if a cscope connection exists + did_filetype() check if a FileType autocommand was used + eventhandler() check if invoked by an event handler + getwinposx() X position of the GUI Vim window + getwinposy() Y position of the GUI Vim window + winheight() get height of a specific window + winwidth() get width of a specific window + libcall() call a function in an external library + libcallnr() idem, returning a number + getreg() get contents of a register + getregtype() get type of a register + setreg() set contents and type of a register + +============================================================================== +*41.7* Defining a function + +Vim enables you to define your own functions. The basic function declaration +begins as follows: > + + :function {name}({var1}, {var2}, ...) + : {body} + :endfunction +< + Note: + Function names must begin with a capital letter. + +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: + > + : if a:num1 < a:num2 + +The special prefix "a:" tells Vim that the variable is a function argument. +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 + +The variable "smaller" is a local variable. Variables used inside a function +are local unless prefixed by something like "g:", "a:", or "s:". + + Note: + To access a global variable from inside a function you must prepend + "g:" to it. Thus "g:count" inside a function is used for the global + variable "count", and "count" is another variable, local to the + function. + +You now use the ":return" statement to return the smallest number to the user. +Finally, you end the function: > + + : return smaller + :endfunction + +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 + +A user defined function is called in exactly the same way as a builtin +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. +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) + + +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 n = a:firstline + : let count = 0 + : while n <= a:lastline + : let count = count + Wordcount(getline(n)) + : let n = n + 1 + : endwhile + : echo "found " . count . " 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 + +If you call this function with: > + + :10,15call Number() + +The function will be called six times. + + +VARIABLE NUMBER OF ARGUMENTS + +Vim enables you to define functions that have a variable number of arguments. +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 "Show 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. + + +LISTING FUNCTIONS + +The ":function" command lists the names and arguments of all user-defined +functions: > + + :function +< function Show(start, ...) ~ + function GetVimIndent() ~ + function SetSyn(name) ~ + +To see what a function does, use its name as an argument for ":function": > + + :function SetSyn +< 1 if &syntax == '' ~ + 2 let &syntax = a:name ~ + 3 endif ~ + endfunction ~ + + +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 +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. + +============================================================================== +*41.8* Exceptions + +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 +generating an error message, this code catches the error and gives the user a +nice message instead. + +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 +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 + +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 +always executed. This makes sure you don't leave the temporary file behind. + +More information about exception handling can be found in the reference +manual: |exception-handling|. + +============================================================================== +*41.9* 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-DOS, Windows, OS/2 and the like, <CR><LF> is used. +This is important when using mappings that end in a <CR>. See |:source_crnl|. + + +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! + +To include a whitespace character in the value of an option, it must be +escaped by a "\" (backslash) as in the following example: > + + :set tags=my\ nice\ file + +The same example written as > + + :set tags=my nice file + +will issue an error, because it is interpreted as: > + + :set tags=my + :set nice + :set file + + +COMMENTS + +The character " (the double quote mark) 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. + +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 +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 + +With the '|' character the command is separated from the next one. And that +next command is only a comment. + +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 avoid these problems, you can set the 'list' option when editing vimrc +files. + + +PITFALLS + +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 +not visible. + +And this is the same as what happens when one uses a comment after an 'unmap' +command: > + + :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 + + +RESTORING THE VIEW + +Sometimes you want to make a change and go back to where 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: > + + map ,p ma"aYHmbgg"aP`bzt`a + +What this does: > + ma"aYHmbgg"aP`bzt`a +< ma set mark a at cursor position + "aY yank current line into register a + Hmb go to top line in window and set mark b there + gg go to first line in file + "aP put the yanked line above it + `b go back to top line in display + zt position the text in the window as before + `a go back to saved cursor position + + +PACKAGING |