From f4fe2e932cc8f445e9e1bc52863e11b669e3afc9 Mon Sep 17 00:00:00 2001
From: "Frank Ch. Eigler" <fche@elastic.org>
Date: Wed, 3 Mar 2010 00:28:22 -0500
Subject: PR11004: try / catch error-handling script syntax

* parse.h (try_block): New class.  Update basic visitors.
* staptree.cxx: Implement basic visitors.
* parse.cxx (expect_kw): Fix to actually look for keywords.
  (parse_try_block): New function.
  (lexer ctor): Designate 'try' and 'catch' as keywords.
* elaborate.cxx (dead_assignment_remover, dead_statmtexpr_remover): Optimize.
  (other visitors): Implement.
* translate.cxx (c_unparser): Implement via super-handy __local__ labels.
  (emit_probe, emit_function): Make outer out: label also __local__.
* testsuite/buildok/fortyone.stp, semko/fortynine.stp,
  systemtap.base/trycatch.exp: Test it.
* NEWS, doc/langref.txt, stap.1.in: Document it.
---
 doc/langref.tex | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'doc/langref.tex')

diff --git a/doc/langref.tex b/doc/langref.tex
index 0f5b92d2..27ac1c33 100644
--- a/doc/langref.tex
+++ b/doc/langref.tex
@@ -52,7 +52,7 @@
 \newpage{}
 This document was derived from other documents contributed to the SystemTap project by employees of Red Hat, IBM and Intel.\newline
 
-Copyright \copyright\space  2007-2009 Red Hat Inc.\newline
+Copyright \copyright\space  2007-2010 Red Hat Inc.\newline
 Copyright \copyright\space  2007-2009 IBM Corp.\newline
 Copyright \copyright\space  2007 Intel Corporation.\newline
 
@@ -1869,6 +1869,28 @@ nesting loop statement, such as within a \texttt{while, for,} or \texttt{foreach
 statement. The syntax and semantics are the same as those used in C.
 
 
+\subsection{try/catch}
+\index{try}
+\index{catch}
+Use \texttt{try}/\texttt{catch} to handle most kinds of run-time errors within the script
+instead of aborting the probe handler in progress.  The semantics are similar
+to C++ in that try/catch blocks may be nested.  The error string may be captured
+by optionally naming a variable which is to receive it.
+
+\begin{vindent}
+\begin{verbatim}
+try { 
+   /* do something */
+   /* trigger error like kread(0), or divide by zero, or error("foo") */
+} catch (msg) { /* omit (msg) entirely if not interested */
+   /* println("caught error ", msg) */
+   /* handle error */
+}
+/* execution continues */
+\end{verbatim}
+\end{vindent}
+
+
 \subsection{delete}
 \index{delete}
 \texttt{delete} removes an element.
-- 
cgit