summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_50.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_50.txt')
-rw-r--r--runtime/doc/usr_50.txt131
1 files changed, 131 insertions, 0 deletions
diff --git a/runtime/doc/usr_50.txt b/runtime/doc/usr_50.txt
new file mode 100644
index 0000000..ee377ca
--- /dev/null
+++ b/runtime/doc/usr_50.txt
@@ -0,0 +1,131 @@
+*usr_50.txt* For Vim version 9.1. 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: