doc/manual/trycatch-ref.tex

   1 \section{Extension {\tt trywith}: exceptions and finalization}
   2 Lua offers error handling primitives \verb+pcall()+ and
   3 \veb+xpcall()+. However, they are pretty low level, and their syntax
   4 is cumbersome to use and read back. This extension offers a proper
   5 syntax for the handling of such exceptions.
   6
   7 \subsection{Syntax}
   8 An error handling statement has the following form:
   9
  10 \begin{verbatim}
  11 try
  12    <protected block>
  13 catch <exception pattern #1> then
  14    <exception handling block #1>
  15 catch <exception pattern #2> then
  16    <exception handling block #2>
  17    ...
  18 catch <exception pattern #n> then
  19    <exception handling block #n>
  20 finally
  21    <finalization block>
  22 end
  23 \end{verbatim}
  24
  25 \subsection{Semantics}
  26 When such a statement is executed:
  27 \begin{itemize}
  28 \item the protected code is executed
  29 \item if its execution causes an error, the error message is matched
  30   against all exception patterns, until one matches or the last one is
  31   reached (see the \verb+match+ extension for patterns
  32   semantics). Patterns can include guard clauses. The block
  33   corresponding to the first matching pattern is executed. If no
  34   pattern matches, the error will be rethrown.
  35 \item the block following the \verb+finally+ keyword will be executed
  36   no matter what: if the protected block executes succesfully, if it
  37   raises an error, if it causes a \verb+return+, if an error occurs in
  38   an exception handling block, whether an error is caught or
  39   not... The only reason why the finalization block might not be run
  40   is because of a sudden death of the process (call to {\tt os.exit()}
  41   or core dump).
  42 \end{itemize}
  43
  44 The finally block can be omitted, or there can be no error catching
  45 case. The following examples are legal:
  46
  47 \begin{verbatim}
  48 try
  49    f = io.open ('file.txt', 'r')
  50    num_char = #f:read '*a'
  51 finally
  52    f:close()
  53 end
  54
  55 try
  56    do_stuff()
  57 catch "mismatch" then
  58    print "match statement failure"
  59 catch "[Ee]of"/_ then -- regexp pattern
  60    print "An end-of-file error seems to have happened"
  61 catch x if type(x)=='table' then
  62    print "The error is a table, not a string!"
  63 end
  64 \end{verbatim}
  65
  66  \subsection{RAII}
  67  RAII, or ``Resource Acquisition Is Initialization'', is a common
  68  programming pattern in which an object's lifetime is strictly
  69  associated with a given lexical scope. For instance, if a file is
  70  opened in a given scope, it must be closed as soon as this scope is
  71  leaved, even if it's leaved due to a {\tt return} or an error. The
  72  ``finally'' block allows this, but since it's a very common use case,
  73  there is a dedicated extension ``with/do'': you initialize some resource
  74  behind the ``with'' keyword, and it will be closed after the ``do''
  75  block is left. The only constraint is that the resources must have a
  76  {\tt:close()} method which releases them. Here is a usage example:
  77
  78 \begin{verbatim}
  79 -{ extension 'withdo' }
  80
  81 with f1, f2 = io.open 'file1.txt', io.open 'file2.txt' do
  82    local t1 = f1:read '*a'
  83    local t2 = f2:read '*a'
  84    printf("The files contain %i and %i chars respectively", t1, t2)
  85 end
  86 \end{verbatim}
  87