From aed8ce9da277f5ecffe968b324f242c41c3b752a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 10:50:31 +0200 Subject: Adding upstream version 2:9.0.1378. Signed-off-by: Daniel Baumann --- runtime/doc/usr_50.txt | 131 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 runtime/doc/usr_50.txt (limited to 'runtime/doc/usr_50.txt') diff --git a/runtime/doc/usr_50.txt b/runtime/doc/usr_50.txt new file mode 100644 index 0000000..fc46388 --- /dev/null +++ b/runtime/doc/usr_50.txt @@ -0,0 +1,131 @@ +*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) + +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) + 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: -- cgit v1.2.3