diff options
| -rw-r--r-- | ChangeLog | 1 | ||||
| -rw-r--r-- | doc/throw.n | 50 | ||||
| -rw-r--r-- | doc/try.n | 104 |
3 files changed, 155 insertions, 0 deletions
@@ -2,6 +2,7 @@ TIP #329 IMPLEMENTATION + * doc/throw.n, doc/try.n: Documentation of the new commands. * library/init.tcl (throw, try): Implementation of commands documented in TIP. This implementation is in Tcl and is a stop-gap until higher-performance ones can be written. diff --git a/doc/throw.n b/doc/throw.n new file mode 100644 index 0000000..2c69df8 --- /dev/null +++ b/doc/throw.n @@ -0,0 +1,50 @@ +'\" +'\" Copyright (c) 2008 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: throw.n,v 1.1 2008/12/16 21:29:10 dkf Exp $ +'\" +.so man.macros +.TH throw n 8.6 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +throw \- Generate a machine-readable error +.SH SYNOPSIS +\fBthrow\fI type message\fR +.BE +.SH DESCRIPTION +.PP +This command causes the current evaluation to be unwound with an error. The +error created is described by the \fItype\fR and \fImessage\fR arguments: +\fItype\fR must contain a list of words describing the error in a form that is +machine-readable (and which will form the error-code part of the result +dictionary), and \fImessage\fR should contain text that is intended for +display to a human being. +.PP +The stack will be unwound until the error is trapped by a suitable \fBcatch\fR +or \fBtry\fR command. If it reaches the event loop without being trapped, it +will be reported through the \fBbgerror\fR mechanism. If it reaches the top +level of script evaluation in \fBtclsh\fR, it will be printed on the console +before, in the non-interactive case, causing an exit (the behavior in other +programs will depend on the details of how Tcl is embedded and used). +.PP +By convention, the words in the \fItype\fR argument should go from most +general to most specific. +.SH EXAMPLES +.PP +The following produces an error that is identical to that produced by +\fBexpr\fR when trying to divide a value by zero. +.PP +.CS +\fBthrow\fR {ARITH DIVZERO {divide by zero}} {divide by zero} +.CE +.SH "SEE ALSO" +catch(n), error(n), return(n), try(n) +.SH "KEYWORDS" +error, exception +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/try.n b/doc/try.n new file mode 100644 index 0000000..f6ccb7f --- /dev/null +++ b/doc/try.n @@ -0,0 +1,104 @@ +'\" +'\" Copyright (c) 2008 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: try.n,v 1.1 2008/12/16 21:29:10 dkf Exp $ +'\" +.so man.macros +.TH try n 8.6 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +try \- Trap and process errors and exceptions +.SH SYNOPSIS +\fBtry\fI body\fR ?\fIhandler...\fR? ?\fBfinally\fI script\fR? +.BE +.SH DESCRIPTION +.PP +This command executes the script \fIbody\fR and, depending on what the outcome +of that script is (normal exit, error, or some other exceptional result), runs +a handler script to deal with the case. Once that has all happened, if the +\fBfinally\fR clause is present, the \fIscript\fR it includes will be run and +the result of the handler (or the \fIbody\fR if no handler matched) is allowed +to continue to propagate. Note that the \fBfinally\fR clause is processed even +if an error occurs and irrespective of which, if any, \fIhandler\fR is used. +.PP +The \fIhandler\fR clauses are each expressed as several words, and must have +one of the following forms: +.TP +\fBon \fIcode variableList script\fR +. +This clause matches if the evaluation of \fIbody\fR completed with the +exeception code \fIcode\fR. The \fIcode\fR may be expressed as an integer or +one of the following literal words: \fBok\fR, \fBerror\fR, \fBreturn\fR, +\fBbreak\fR, or \fBcontinue\fR. Those literals correspond to the integers 0 +through 4 respectively. +.TP +\fBtrap \fIpattern variableList script\fR +. +This clause matches if the evaluation of \fIbody\fR resulted in an error and +the prefix of the \fB\-errorcode\fR from the interpreter's status dictionary +is equal to the \fIpattern\fR. The number of prefix words taken from the +\fB\-errorcode\fR is equal to the list-length of \fIpattern\fR, and inter-word +spaces are normalized in both the \fB\-errorcode\fR and \fIpattern\fR before +comparison. +.PP +The \fIvariableList\fR word in each \fIhandler\fR is always interpreted as a +list of variable names. If the first word of the list is present and +non-empty, it names a variable into which the result of the evaluation of +\fIbody\fR (from the main \fBtry\fR) will be placed; this will contain the +human-readable form of any errors. If the second word of the list is present +and non-empty, it names a variable into which the options dictionary of the +interpreter at the moment of completion of execution of \fIbody\fR. +.PP +The \fIscript\fR word of each \fIhandler\fR is also always interpreted the +same: as a Tcl script to evaluate if the clause is matched. If \fIscript\fR is +a literal +.QW \- +and the \fIhandler\fR is not the last one, the \fIscript\fR of the following +\fIhandler\fR is invoked instead (just like with the \fBswitch\fR command). +.PP +Note that \fIhandler\fR clauses are matched against in order, and that the +first matching one is always selected. At most one \fIhandler\fR clause will +selected. As a consequence, an \fBon error\fR will mask any subsequent +\fBtrap\fR in the \fBtry\fR. Also note that \fBon error\fR is equivalent to +\fBtrap {}\fR. +.PP +If an exception (i.e. any non-\fBok\fR result) occurs during the evaluation of +either the \fIhandler\fR or the \fBfinally\fR clause, the original exception's +status dictionary will be added to the new exception's status dictionary under +the \fB\-during\fR key. +.SH EXAMPLES +.PP +Ensure that a file is closed no matter what: +.PP +.CS +set f [open /some/file/name a] +\fBtry\fR { + puts $f "some message" + # ... +} \fBfinally\fR { + close $f +} +.CE +.PP +Handle different reasons for a file to not be openable for reading: +.PP +.CS +\fBtry\fR { + set f [open /some/file/name] +} \fBtrap\fR {POSIX EISDIR} {} { + puts "failed to open /some/file/name: it's a directory" +} \fBtrap\fR {POSIX ENOENT} {} { + puts "failed to open /some/file/name: it doesn't exist" +} +.CE +.SH "SEE ALSO" +catch(n), error(n), return(n), throw(n) +.SH "KEYWORDS" +cleanup, error, exception, final, resource management +'\" Local Variables: +'\" mode: nroff +'\" End: |