Update runtime files

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