Home Explore Blog CI



neovim

34th chunk of `runtime/doc/vimeval.txt`
2c3f10287f3ff2558e350cfc34b3932821d4d2eb7007b3100000000100000fa1
  Unless it is caught there, the expression evaluation is abandoned.
The ":throw" command then does not throw a new exception.
   Example: >

	:function! Foo(arg)
	:  try
	:    throw a:arg
	:  catch /foo/
	:  endtry
	:  return 1
	:endfunction
	:
	:function! Bar()
	:  echo "in Bar"
	:  return 4710
	:endfunction
	:
	:throw Foo("arrgh") + Bar()

This throws "arrgh", and "in Bar" is not displayed since Bar() is not
executed. >
	:throw Foo("foo") + Bar()
however displays "in Bar" and throws 4711.

Any other command that takes an expression as argument might also be
abandoned by an (uncaught) exception during the expression evaluation.  The
exception is then propagated to the caller of the command.
   Example: >

	:if Foo("arrgh")
	:  echo "then"
	:else
	:  echo "else"
	:endif

Here neither of "then" or "else" is displayed.

							*catch-order*
Exceptions can be caught by a try conditional with one or more |:catch|
commands, see |try-conditionals|.   The values to be caught by each ":catch"
command can be specified as a pattern argument.  The subsequent catch clause
gets executed when a matching exception is caught.
   Example: >

	:function! Foo(value)
	:  try
	:    throw a:value
	:  catch /^\d\+$/
	:    echo "Number thrown"
	:  catch /.*/
	:    echo "String thrown"
	:  endtry
	:endfunction
	:
	:call Foo(0x1267)
	:call Foo('string')

The first call to Foo() displays "Number thrown", the second "String thrown".
An exception is matched against the ":catch" commands in the order they are
specified.  Only the first match counts.  So you should place the more
specific ":catch" first.  The following order does not make sense: >

	:  catch /.*/
	:    echo "String thrown"
	:  catch /^\d\+$/
	:    echo "Number thrown"

The first ":catch" here matches always, so that the second catch clause is
never taken.

							*throw-variables*
If you catch an exception by a general pattern, you may access the exact value
in the variable |v:exception|: >

	:  catch /^\d\+$/
	:    echo "Number thrown.  Value is" v:exception

You may also be interested where an exception was thrown.  This is stored in
|v:throwpoint|.  And you can obtain the stack trace from |v:stacktrace|.
Note that "v:exception", "v:stacktrace" and "v:throwpoint" are valid for the
exception most recently caught as long it is not finished.
   Example: >

	:function! Caught()
	:  if v:exception != ""
	:    echo 'Caught "' .. v:exception .. '" in ' .. v:throwpoint
	:  else
	:    echo 'Nothing caught'
	:  endif
	:endfunction
	:
	:function! Foo()
	:  try
	:    try
	:      try
	:	 throw 4711
	:      finally
	:	 call Caught()
	:      endtry
	:    catch /.*/
	:      call Caught()
	:      throw "oops"
	:    endtry
	:  catch /.*/
	:    call Caught()
	:  finally
	:    call Caught()
	:  endtry
	:endfunction
	:
	:call Foo()

This displays >

	Nothing caught
	Caught "4711" in function Foo, line 4
	Caught "oops" in function Foo, line 10
	Nothing caught

A practical example:  The following command ":LineNumber" displays the line
number in the script or function where it has been used: >

	:function! LineNumber()
	:    return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
	:endfunction
	:command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
<
							*try-nested*
An exception that is not caught by a try conditional can be caught by
a surrounding try conditional: >

	:try
	:  try
	:    throw "foo"
	:  catch /foobar/
	:    echo "foobar"
	:  finally
	:    echo "inner finally"
	:  endtry
	:catch /foo/
	:  echo "foo"
	:endtry

The inner try conditional does not catch the exception, just its finally
clause is executed.  The exception is then caught by the outer try
conditional.  The example displays "inner finally" and then "foo".

							*throw-from-catch*
You can catch an exception and throw a new one to be caught elsewhere from the
catch clause: >

	:function! Foo()
	:  throw "foo"
	:endfunction
	:
	:function! Bar()
	:  try
	:    call Foo()
	:  catch /foo/
	:    echo "Caught foo, throw

Title: Catching Exceptions and Using v:exception, v:throwpoint, and v:stacktrace
Summary
This section explains how to catch exceptions using `:catch` commands with pattern matching and provides an example. It emphasizes the importance of catch order, from specific to general patterns. It also introduces variables like `v:exception`, `v:throwpoint`, and `v:stacktrace` for accessing the exception value, location, and stack trace. The section further illustrates how exceptions propagate through nested `try` conditionals and how to throw a new exception from a `catch` clause.