vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_50.txt (4554B)


      1 *usr_50.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			 Advanced Vim script writing
      8 
      9 
     10 |50.1|	Exceptions
     11 |50.2|	Function with variable number of arguments
     12 |50.3|	Restoring the view
     13 
     14      Next chapter: |usr_51.txt|  Create a plugin
     15  Previous chapter: |usr_45.txt|  Select your language (local)
     16 Table of contents: |usr_toc.txt|
     17 
     18 ==============================================================================
     19 *50.1*	Exceptions
     20 
     21 Let's start with an example: >
     22 
     23 	try
     24 	   read ~/templates/pascal.tmpl
     25 	catch /E484:/
     26 	   echo "Sorry, the Pascal template file cannot be found."
     27 	endtry
     28 
     29 The `read` command will fail if the file does not exist.  Instead of
     30 generating an error message, this code catches the error and gives the user a
     31 message with more information.
     32 
     33 For the commands in between `try` and `endtry` errors are turned into
     34 exceptions.  An exception is a string.  In the case of an error the string
     35 contains the error message.  And every error message has a number.  In this
     36 case, the error we catch contains "E484:".  This number is guaranteed to stay
     37 the same (the text may change, e.g., it may be translated).
     38 
     39 Besides being able to give a nice error message, Vim will also continue
     40 executing commands after the `:endtry`.  Otherwise, once an uncaught error is
     41 encountered, execution of the script/function/mapping will be aborted.
     42 
     43 When the `read` command causes another error, the pattern "E484:" will not
     44 match in it.  Thus this exception will not be caught and result in the usual
     45 error message and execution is aborted.
     46 
     47 You might be tempted to do this: >
     48 
     49 	try
     50 	   read ~/templates/pascal.tmpl
     51 	catch
     52 	   echo "Sorry, the Pascal template file cannot be found."
     53 	endtry
     54 
     55 This means all errors are caught.  But then you will not see an error that
     56 would indicate a completely different problem, such as "E21: Cannot make
     57 changes, 'modifiable' is off".  Think twice before you catch any error!
     58 
     59 Another useful mechanism is the `finally` command: >
     60 
     61 	var tmp = tempname()
     62 	try
     63 	   exe ":.,$write " .. tmp
     64 	   exe "!filter " .. tmp
     65 	   :.,$delete
     66 	   exe ":$read " .. tmp
     67 	finally
     68 	   delete(tmp)
     69 	endtry
     70 
     71 This filters the lines from the cursor until the end of the file through the
     72 "filter" command, which takes a file name argument.  No matter if the
     73 filtering works, if something goes wrong in between `try` and `finally` or the
     74 user cancels the filtering by pressing CTRL-C, the `delete(tmp)` call is
     75 always executed.  This makes sure you don't leave the temporary file behind.
     76 
     77 The `finally` does not catch the exception, the error will still abort
     78 further execution.
     79 
     80 More information about exception handling can be found in the reference
     81 manual: |exception-handling|.
     82 
     83 ==============================================================================
     84 *50.2*	Function with variable number of arguments
     85 
     86 Vim enables you to define functions that have a variable number of arguments.
     87 The following command, for instance, defines a function that must have 1
     88 argument (start) and can have up to 20 additional arguments: >
     89 
     90 	def Show(start: string, ...items: list<string>)
     91 
     92 The variable "items" will be a list in the function containing the extra
     93 arguments.  You can use it like any list, for example: >
     94 
     95 	def Show(start: string, ...items: list<string>)
     96 	  echohl Title
     97 	  echo "start is " .. start
     98 	  echohl None
     99 	  for index in range(len(items))
    100 	    echon $"  Arg {index} is {items[index]}"
    101 	  endfor
    102 	  echo
    103 	enddef
    104 
    105 You can call it like this: >
    106 
    107 	Show('Title', 'one', 'two', 'three')
    108 <	start is Title  Arg 0 is one  Arg 1 is two  Arg 2 is three ~
    109 
    110 This uses the `echohl` command to specify the highlighting used for the
    111 following `echo` command.  `echohl None` stops it again.  The `echon` command
    112 works like `echo`, but doesn't output a line break.
    113 
    114 If you call it with one argument the "items" list will be empty.
    115 `range(len(items))` returns a list with the indexes, what `for` loops over,
    116 we'll explain that further down.
    117 
    118 ==============================================================================
    119 *50.3*	Restoring the view
    120 
    121 Sometimes you want to jump around, make a change and then go back to the same
    122 position and view.  For example to change something in the file header.  This
    123 can be done with two functions: >
    124 
    125 	var view = winsaveview()
    126 	# Move around, make changes
    127 	winrestview(view)
    128 
    129 ==============================================================================
    130 
    131 Next chapter: |usr_51.txt|  Create a plugin
    132 
    133 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: