diff options
Diffstat (limited to 'doc/throw.n')
| -rw-r--r-- | doc/throw.n | 50 |
1 files changed, 50 insertions, 0 deletions
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: |