# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1301628246 25200
# Node ID d6ad4ed57dda75604b46efd868ba39516d385b96
# Parent  a12d7f53c2ab32cf436e4e8f0a2584c67e0a0ab5
Add onCleanup function to documentation.

diff -r a12d7f53c2ab -r d6ad4ed57dda doc/ChangeLog
--- a/doc/ChangeLog	Thu Mar 31 10:41:32 2011 -0700
+++ b/doc/ChangeLog	Thu Mar 31 20:24:06 2011 -0700
@@ -1,3 +1,8 @@
+2011-03-31  Rik  <octave@nomad.inbox5.com>
+
+	* interpreter/errors.txi, interpreter/octave.texi: Add onCleanup
+	function to documentation.
+
 2011-03-31  Rik  <octave@nomad.inbox5.com>
 
 	* interpreter/contrib.txi: Add recommended format for commit messages
diff -r a12d7f53c2ab -r d6ad4ed57dda doc/interpreter/errors.txi
--- a/doc/interpreter/errors.txi	Thu Mar 31 10:41:32 2011 -0700
+++ b/doc/interpreter/errors.txi	Thu Mar 31 20:24:06 2011 -0700
@@ -49,6 +49,7 @@
 @menu
 * Raising Errors::
 * Catching Errors::
+* Recovering From Errors::
 @end menu
 
 @node Raising Errors
@@ -212,6 +213,38 @@
 
 @DOCSTRING(errno_list)
 
+@node Recovering From Errors
+@subsection Recovering From Errors
+
+Octave provides several ways of recovering from errors.  There are
+@code{try}/@code{catch} blocks, 
+@code{unwind_protect}/@code{unwind_protect_cleanup} blocks, 
+and finally the @code{onCleanup} command.
+
+The @code{onCleanup} command associates an ordinary Octave variable (the
+trigger) with an arbitrary function (the action).  Whenever the Octave variable
+ceases to exist---whether due to a function return, an error, or simply because
+the variable has been removed with @code{clear}---then the assigned function
+is executed.
+
+The function can do anything necessary for cleanup such as closing open file
+handles, printing an error message, or restoring global variables to their
+initial values.  The last example is a very convenient idiom for Octave code.
+For example:
+
+@example
+@group
+function rand42
+  old_state = rand ('state');
+  restore_state = onCleanup (@@() rand ('state', old_state);
+  rand ('state', 42);
+  @dots{}
+endfunction  # rand generator state restored by onCleanup
+@end group
+@end example
+
+@DOCSTRING(onCleanup)
+
 @node Handling Warnings
 @section Handling Warnings
 
diff -r a12d7f53c2ab -r d6ad4ed57dda doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi	Thu Mar 31 10:41:32 2011 -0700
+++ b/doc/interpreter/octave.texi	Thu Mar 31 20:24:06 2011 -0700
@@ -443,6 +443,7 @@
 
 * Raising Errors::
 * Catching Errors::
+* Recovering From Errors::
 
 Handling Warnings
 
diff -r a12d7f53c2ab -r d6ad4ed57dda src/ChangeLog
--- a/src/ChangeLog	Thu Mar 31 10:41:32 2011 -0700
+++ b/src/ChangeLog	Thu Mar 31 20:24:06 2011 -0700
@@ -1,3 +1,8 @@
+2011-03-31  Rik  <octave@nomad.inbox5.com>
+
+	* DLD-FUNCTIONS/onCleanup.cc: Remove non-existent @seealso link in
+	docstring.
+
 2011-03-31  Rik  <octave@nomad.inbox5.com>
 
 	* DLD-FUNCTIONS/quadcc.cc: Add reference to original paper in docstring.
diff -r a12d7f53c2ab -r d6ad4ed57dda src/DLD-FUNCTIONS/onCleanup.cc
--- a/src/DLD-FUNCTIONS/onCleanup.cc	Thu Mar 31 10:41:32 2011 -0700
+++ b/src/DLD-FUNCTIONS/onCleanup.cc	Thu Mar 31 20:24:06 2011 -0700
@@ -257,7 +257,7 @@
 elements) or returned from a function, @var{action} will be executed after\n\
 clearing the last copy of the object.  Note that if multiple local onCleanup\n\
 variables are created, the order in which they are called is unspecified.\n\
-@seealso{unwind_protect}\n\
+For similar functionality @xref{The @code{unwind_protect} Statement}.\n\
 @end deftypefn")
 {
   octave_value retval;