## USR_50

    *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|  Create a plugin
     Previous chapter: |usr_45|  Select your language (local)
    Table of contents: |usr_toc|

    *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|  Create a plugin

    Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:

Generated by vim2html on 12.12.2023