Update runtime files
diff --git a/runtime/doc/usr_50.txt b/runtime/doc/usr_50.txt
index 2dff27e..417bdd2 100644
--- a/runtime/doc/usr_50.txt
+++ b/runtime/doc/usr_50.txt
@@ -5,46 +5,116 @@
Advanced Vim script writing
-|50.1| Line continuation
-|50.2| Restoring the view
+|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* Line continuation
+*50.1* Exceptions
-In legacy Vim script line continuation is done by preceding a continuation
-line with a backslash: >
- let mylist = [
- \ 'one',
- \ 'two',
- \ ]
+Let's start with an example: >
-This requires the 'cpo' option to exclude the "C" flag. Normally this is done
-by putting this at the start of the script: >
- let s:save_cpo = &cpo
- set cpo&vim
+ try
+ read ~/templates/pascal.tmpl
+ catch /E484:/
+ echo "Sorry, the Pascal template file cannot be found."
+ endtry
-And restore the option at the end of the script: >
- let &cpo = s:save_cpo
- unlet s:save_cpo
+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.
-A few more details can be found here: |line-continuation|.
+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).
-In |Vim9| script the backslash can still be used, but in most places it is not
-needed: >
- var mylist = [
- 'one',
- 'two',
- ]
+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.
-Also, the 'cpo' option does not need to be changed. See
-|vim9-line-continuation| for details.
+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* Restoring the view
+*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 make a change and go back to where the cursor was.
Restoring the relative position would also be nice, so that the same line