| *usr_50.txt* For Vim version 9.0. Last change: 2022 Jun 20 |
| |
| VIM USER MANUAL - by Bram Moolenaar |
| |
| Advanced Vim script writing |
| |
| |
| |50.1| Exceptions |
| |50.2| Function with variable number of arguments |
| |50.3| Restoring the view |
| |
| Next chapter: |usr_51.txt| Create a plugin |
| Previous chapter: |usr_45.txt| Select your language (local) |
| Table of contents: |usr_toc.txt| |
| |
| ============================================================================== |
| *50.1* 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 |
| message with more information. |
| |
| 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). |
| |
| Besides being able to give a nice error message, Vim will also continue |
| executing commands after the `:endtry`. Otherwise, once an uncaught error is |
| encountered, execution of the script/function/mapping 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 and execution is aborted. |
| |
| 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 an error that |
| would indicate a completely different problem, such as "E21: Cannot make |
| changes, 'modifiable' is off". Think twice before you catch any error! |
| |
| Another useful mechanism is the `finally` command: > |
| |
| var tmp = tempname() |
| try |
| exe ":.,$write " .. tmp |
| exe "!filter " .. tmp |
| :.,$delete |
| exe ":$read " .. tmp |
| finally |
| 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, if something goes wrong in between `try` and `finally` or the |
| user cancels the filtering by pressing CTRL-C, the `delete(tmp)` call is |
| always executed. This makes sure you don't leave the temporary file behind. |
| |
| The `finally` does not catch the exception, the error will still abort |
| further execution. |
| |
| More information about exception handling can be found in the reference |
| manual: |exception-handling|. |
| |
| ============================================================================== |
| *50.2* Function with 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: > |
| |
| def Show(start: string, ...items: list<string>) |
| |
| The variable "items" will be a list in the function 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. |
| |
| ============================================================================== |
| *50.3* Restoring the view |
| |
| Sometimes you want to jump around, make a change and then go back to the same |
| position and view. For example to change something in the file header. This |
| can be done with two functions: > |
| |
| var view = winsaveview() |
| # Move around, make changes |
| winrestview(view) |
| |
| ============================================================================== |
| |
| Next chapter: |usr_51.txt| Create a plugin |
| |
| Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |