001: /*
002: * TclException.java --
003: *
004: * This file defines the TclException class used by Tcl to report
005: * generic script-level errors and exceptions.
006: *
007: * Copyright (c) 1997 Sun Microsystems, Inc.
008: *
009: * See the file "license.terms" for information on usage and
010: * redistribution of this file, and for a DISCLAIMER OF ALL
011: * WARRANTIES.
012: *
013: * RCS: @(#) $Id: TclException.java,v 1.3 2005/09/11 20:56:58 mdejong Exp $
014: *
015: */
016:
017: package tcl.lang;
018:
019: /*
020: * TclException is used to interrupt the Tcl script currently being
021: * interpreted by the Tcl Interpreter. Usually, a TclException is thrown
022: * to indicate a script level error, e.g.:
023: *
024: * - A syntax error occurred in a script.
025: * - A unknown variable is referenced.
026: * - A unknown command is executed.
027: * - A command is passed incorrected.
028: *
029: * A TclException can also be thrown by Tcl control structure commands such
030: * as "return" and "continue" to change the flow of control in
031: * a Tcl script.
032: *
033: * A TclException is accompanied by two pieces of information: the error
034: * message and the completion code. The error message is a string stored in
035: * the interpreter result. After a TclException is thrown and caught, the
036: * error message can be queried by Interp.getResult().
037: *
038: * The completion code indicates why the TclException is generated. It is
039: * stored in the compCode field of this class.
040: */
041:
042: public class TclException extends Exception {
043:
044: /*
045: * Stores the completion code of a TclException.
046: */
047:
048: private int compCode;
049:
050: /*
051: * An index that indicates where an error occurs inside a Tcl
052: * string. This is used to add the offending command into the stack
053: * trace.
054: *
055: * A negative value means the location of the index is unknown.
056: *
057: * Currently this field is used only by the Jacl interpreter.
058: */
059:
060: protected int errIndex;
061:
062: /*
063: *----------------------------------------------------------------------
064: *
065: * TclException --
066: *
067: * Create an TclException with the given error message and
068: * completion code and indicate the location of the error in a
069: * script.
070: *
071: * Results:
072: * None.
073: *
074: * Side effects:
075: * The instance fields are initialized; the message is assigned to
076: * the interpreter's result if interp is non-null.
077: *
078: *----------------------------------------------------------------------
079: */
080:
081: protected TclException(Interp interp, // Current interpreter. May be null if unknown.
082: String msg, // Error message.
083: int ccode, // Completion code.
084: int idx) // Error index.
085: {
086: super (msg);
087: if (ccode == TCL.OK) {
088: throw new TclRuntimeError(
089: "The reserved completion code TCL.OK (0) cannot be used "
090: + "in TclException");
091: }
092: compCode = ccode;
093: errIndex = idx;
094:
095: if (interp != null && msg != null) {
096: interp.setResult(msg);
097: }
098: }
099:
100: /*
101: *----------------------------------------------------------------------
102: *
103: * TclException --
104: *
105: * Create a TclException with the given completion code.
106: *
107: * Results:
108: * None.
109: *
110: * Side effects:
111: * The instance fields are initialized.
112: *
113: *----------------------------------------------------------------------
114: */
115:
116: public TclException(int ccode) // Completion code.
117: {
118: super ();
119: if (ccode == TCL.OK) {
120: throw new TclRuntimeError(
121: "The reserved completion code TCL.OK (0) cannot be used");
122: }
123: compCode = ccode;
124: errIndex = -1;
125: }
126:
127: /*
128: *----------------------------------------------------------------------
129: *
130: * TclException --
131: *
132: * Create an TclException with the given error message. The
133: * completion code is set to ERROR by default.
134: *
135: * Results:
136: * None.
137: *
138: * Side effects:
139: * The instance fields are initialized; the message is assigned to
140: * the interpreter's result if interp is non-null.
141: *
142: *----------------------------------------------------------------------
143: */
144:
145: public TclException(Interp interp, // Current interpreter. May be null if unknown.
146: String msg) // Error message.
147: {
148: this (interp, msg, TCL.ERROR, -1);
149: }
150:
151: /*
152: *----------------------------------------------------------------------
153: *
154: * TclException --
155: *
156: * Create an TclException with the given error message and
157: * completion code.
158: *
159: * Results:
160: * None.
161: *
162: * Side effects:
163: * The instance fields are initialized; the message is assigned to
164: * the interpreter's result if interp is non-null.
165: *
166: *----------------------------------------------------------------------
167: */
168:
169: public TclException(Interp interp, // Current interpreter. May be null if unknown.
170: String msg, // Error message.
171: int ccode) // Completion code.
172: {
173: this (interp, msg, ccode, -1);
174: }
175:
176: /*
177: *----------------------------------------------------------------------
178: *
179: * getCompletionCode --
180: *
181: * Returns the current completion code.
182: *
183: * Results:
184: * The int value of compCode.
185: *
186: * Side effects:
187: * None.
188: *
189: *----------------------------------------------------------------------
190: */
191:
192: final public int getCompletionCode() {
193: return compCode;
194: }
195:
196: /*
197: *----------------------------------------------------------------------
198: *
199: * setCompletionCode --
200: *
201: * Sets the current completion code.
202: *
203: * Results:
204: * None.
205: *
206: * Side effects:
207: * The completion code is changed.
208: *
209: *----------------------------------------------------------------------
210: */
211:
212: public final void setCompletionCode(int ccode) // New completion code.
213: {
214: if (ccode == TCL.OK) {
215: throw new TclRuntimeError(
216: "The reserved completion code TCL.OK (0) cannot be used");
217: }
218: compCode = ccode;
219: }
220:
221: } // end TclException
|