1 % Copyright (C) 2008, 2009, 2010 Bert Burgemeister
3 % Permission is granted to copy, distribute and/or modify this
4 % document under the terms of the GNU Free Documentation License,
5 % Version 1.2 or any later version published by the Free Software
6 % Foundation; with no Invariant Sections, no Front-Cover Texts and
7 % no Back-Cover Texts. For details see file COPYING.
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Conditions and Errors
}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 For standardized condition types cf.\ Figure
\ref{data-types
} on
15 page
\pageref{data-types
}.
18 \IT{(
\MC*
{DEFINE-CONDITION
} \VAR{foo
} (
\OPn{\VAR{parent-type
}}\DF{\kwd{condition
}})
21 \orGOO{\Goos{\kwd{:reader
} \VAR{reader
}}\\
22 \Goos{\kwd{:writer
} \xorGOO{%
24 (
\kwd{setf
} \VAR{writer
})
}{\
}}}\\
25 \Goos{\kwd{:accessor
} \VAR{accessor
}} \\
26 \kwd{:allocation
} \xorGOO{\kwd{:instance
}\\
27 \kwd{:class
}}{\
}}\DF{\kwd{:instance
}}\\
28 \Goos{\kwd{:initarg
} \kwd{:
}\VAR{initarg-name
}}\\
29 \kwd{:initform
} \VAR{ form
}\\
30 \kwd{:type
} \VAR{ type
}\\
31 \kwd{:documentation
} \VAR{ slot-doc
}%
33 \orGOO{(
\kwd{:default-initargs
} \Goos{\VAR{name
} \VAR{value
}})\\
34 (
{\kwd{:documentation
} \VAR{ condition-doc
}})\\
35 (
\kwd{:
report } \xorGOO{\VAR{string
}\\
36 \VAR{report-function
}}{\
}})
}{\
}})
}
38 Define, as a subtype of
\VAR{parent-type
}s, condition type
39 \retval{\VAR{foo
}}. In a new condition, a
\VAR{slot
}'s value defaults
40 to
\VAR{form
} unless set via
\kwd{:
}\VAR{initarg-name
}; it is readable
41 via (
\VAR{reader
} \VAR{i
}) or (
\VAR{accessor
} \VAR{i
}), and
42 writeable via (
\VAR{writer
} \VAR{i
} \VAR{value
}) or (
\kwd{setf
}
43 (
\VAR{accessor
} \VAR{i
})
\VAR{value
}). With
44 \kwd{:allocation :class
},
\VAR{slot
} is shared by all conditions of
45 type
\VAR{foo
}. A condition is reported by
\VAR{string
} or by
46 \VAR{report-function
} of arguments condition and stream.
49 \IT{(
\FU*
{MAKE-CONDITION
} \VAR{type
} \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}})
}
51 Return new
\retval{condition of
\VAR{type
}}.
61 \VAR{type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
62 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
65 Unless handled, signal as
\kwd{condition
},
\kwd{warning
} or
\kwd{error
},
66 respectively,
\VAR{condition
} or a new condition of
\VAR{type
} or,
67 with
\FU{format
} \VAR{control
} and
\VAR{arg
}s (see p.\
\pageref{section:Format
}),
68 \kwd{simple-condition
},
\kwd{simple-warning
}, or
\kwd{simple-error
}, respectively.
69 From
\FU{SIGNAL
} and
\FU{WARN
}, return
\retval{\NIL}.
72 \IT{(
\FU*
{CERROR
} \VAR{continue-control
}
74 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
75 \VAR{type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
76 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
79 Unless handled, signal as correctable
\kwd{error
} \VAR{condition
} or
80 a new condition of
\VAR{type
} or, with
\FU{format
} \VAR{control
} and
81 \VAR{arg
}s (see p.\
\pageref{section:Format
}),
82 \kwd{simple-error
}. In the debugger, use
\FU{format
} arguments
83 \VAR{continue-control
} and
\VAR{continue-arg
}s to tag the continue
84 option. Return
\retval{\NIL}.
87 \IT{(
\MC*
{IGNORE-ERRORS
} \PROGN{\VAR{form
}})
}
89 Return
\retval{values of
\VAR{form
}s
} or, in case of
\kwd{error
}s,
90 \retval{\NIL} and the
\retvalii{condition
}.
93 \IT{(
\FU*
{INVOKE-DEBUGGER
} \VAR{condition
})
}
95 Invoke debugger with
\VAR{condition
}.
98 \IT{(
\MC*
{ASSERT
} \VAR{test
} \OP{(
\OPn{\VAR{place
}})
101 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
102 \VAR{type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
103 \VAR{control
}\text{ } \OPn{\VAR{arg
}}}{\
}}}})
}
105 If
\VAR{test
}, which may depend on
\VAR{place
}s, returns
\NIL,
106 signal as correctable
\kwd{error
} \VAR{condition
} or a new condition
107 of
\VAR{type
} or, with
\FU{format
} \VAR{control
} and
\VAR{arg
}s (see
108 p.\
\pageref{section:Format
}),
\kwd{error
}. When using the
109 debugger's continue option,
\VAR{place
}s can be altered before
110 re-evaluation of
\VAR{test
}. Return
\retval{\NIL}.
113 \IT{(
\MC*
{HANDLER-CASE
} \VAR{test
}
114 \OPn{(
\VAR{type
} (
\Op{\VAR{var
}})
115 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
} \PROGN{\VAR{condition-form
}})
}
116 \Op{(
\kwd{:no-error
} (
\OPn{\VAR{ord-$
\lambda$
}})
\OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
117 \PROGN{\VAR{form
}})
})
}
119 If, on evaluation of
\VAR{test
}, a condition of
\VAR{type
} is
120 signalled, evaluate matching
\VAR{condition-form
}s
121 with
\VAR{var
} bound to the condition, and return
\retval{their
122 values
}. Without a condition, bind
\VAR{ord-$
\lambda$
}s to values
123 of
\VAR{test
} and return
\retval{values of
\VAR{form
}s
} or, without
124 a
\kwd{:no-error
} clause, return
\retval{values of
\VAR{test
}}. See
125 p.\
\pageref{section:Functions
} for (
\OPn{\VAR{ord-$
\lambda$
}}).
128 \IT{(
\MC*
{HANDLER-BIND
} (
\OPn{(
\VAR{condition-type
}
129 \VAR{handler-function
})
})
\PROGN{\VAR{form
}})
}
131 Return
\retval{values of
\VAR{form
}s
} after evaluating them with
132 \VAR{condition-type
}s dynamically bound to their respective
133 \VAR{handler-function
}s of argument condition.
136 \IT{(
\MC*
{WITH-SIMPLE-RESTART
} (
\xorGOO{\VAR{restart
}\\
137 \NIL}{\
}} \VAR{control
}
138 \OPn{\VAR{arg
}})
\PROGN{\VAR{form
}})
}
140 Return
\retval{values of
\VAR{form
}s
} unless
\VAR{restart
} is called
141 during their evaluation. In this case, describe restart using
142 \FU{format
} \VAR{control
} and
\VAR{arg
}s (see
143 p.\
\pageref{section:Format
}) and return
\retval{\NIL}
147 \IT{(
\MC*
{RESTART-CASE
} \VAR{form
} \OPn{(
\VAR{foo
}
148 (
\OPn{\VAR{ord-$
\lambda$
}})
149 \orGOO{\kwd{:interactive
} \VAR{ arg-function
}\\
150 \kwd{:
report } \xorGOO{%
151 \VAR{report-function
}\\
152 \VAR{string
}\DF{\LIT{"
}\VAR{foo
}\LIT{"
}}}{.
}\\
153 \kwd{:test
} \VAR{ test-function
}\DF{\T}}{\
}}
154 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
155 \PROGN{\VAR{restart-form
}})
})
}
157 Evaluate
\VAR{form
} with dynamically established restarts
\VAR{foo
}. Return
158 \retval{values of
\VAR{form
}} or, if by (
\FU{invoke-restart
}
159 \VAR{foo
} \OPn{\VAR{arg
}}) one restart
\VAR{foo
} is called, use
160 \VAR{string
} or
\VAR{report-function
} (of a stream) to print a
161 description of restart
\VAR{foo
} and
162 return the
\retval{values of its
\VAR{restart-form
}s
}.
163 \VAR{arg-function
} supplies appropriate
\VAR{arg
}s if
\VAR{foo
} is
164 called by
\FU{invoke-restart-interactively
}. If (
\VAR{test-function
} \VAR{condition
})
165 returns
\T,
\VAR{foo
} is made visible under
\VAR{condition
}.
166 For (
\OPn{\VAR{ord-$
\lambda$
}}) see p.\
\pageref{section:Functions
}.
169 \IT{(
\MC*
{RESTART-BIND
} (
\OPn{(
\xorGOO{\NEV{\VAR{restart
}}\\
171 \VAR{restart-function
} \orGOO{\kwd{:interactive-function
}
173 \kwd{:
report-function
} \VAR{ function
}\\
174 \kwd{:test-function
} \VAR{ function
}}{\
}})
})
\PROGN{\VAR{form
}})
}
176 Return
\retval{values of
\VAR{form
}s
} evaluated with
\VAR{restart
}s
177 dynamically bound to
\VAR{restart-function
}s.
180 \IT{\arrGOO{(
\FU*
{INVOKE-RESTART
} \VAR{ restart
} \OPn{\VAR{ arg
}})\\
181 (
\FU*
{INVOKE-RESTART-INTERACTIVELY
} \VAR{ restart
})
}{.
}}
183 Call function associated with
\VAR{restart
} with arguments given or
184 prompted for, respectively. If
\VAR{restart
} function returns,
185 return
\retval{its values
}.
188 \IT{(
\xorGOO{\FU*
{COMPUTE-RESTARTS
}\\
189 \FU*
{FIND-RESTART
} \VAR{ name
}}{\
}} \Op{\VAR{condition
}})
}
191 Return list of
\retval{all restarts
}, or innermost
\retval{restart
}
192 \VAR{name
}, respectively, out of those either associated
193 with
\VAR{condition
} or un-associated at all; or, without
194 \VAR{condition
}, out of all restarts. Return
\retval{\NIL} if search
198 \IT{(
\FU*
{RESTART-NAME
} \VAR{restart
})
}
200 \retval{Name of
\VAR{restart
}}.
203 \IT{(
\xorGOO{\FU*
{ABORT
}\\
204 \FU*
{MUFFLE-WARNING
}\\
206 \FU*
{STORE-VALUE
} \VAR{ value
}\\
207 \FU*
{USE-VALUE
} \VAR{ value
}}{\
}} \Op{\VAR{condition
}\DF{\NIL}})
}
209 Transfer control to innermost applicable restart with same name
210 (i.e.
\kwd{abort
},
\ldots,
\kwd{continue
} \ldots) out of those either associated
211 with
\VAR{condition
} or un-associated at all; or, without
212 \VAR{condition
}, out of all restarts. If no restart is found,
213 signal
\kwd{control-error
} for
\FU{abort
} and
\FU{muffle-warning
},
214 or return
\retval{\NIL} for the rest.
217 \IT{(
\MC*
{WITH-CONDITION-RESTARTS
} \VAR{condition
}
218 \VAR{restarts
} \PROGN{\VAR{form
}})
}
220 Evaluate
\VAR{form
}s with
\VAR{restarts
}
221 dynamically associated with
\VAR{condition
}. Return
\retval{values
225 \IT{\arrGOO{(
\FU*
{ARITHMETIC-ERROR-OPERATION
} \VAR{ condition
})\\
226 (
\FU*
{ARITHMETIC-ERROR-OPERANDS
} \VAR{ condition
})
}{.
}}
228 \retval{List of function
} or
\retval{of its operands
} respectively,
229 used in the operation which caused
\VAR{condition
}.
232 \IT{(
\FU*
{CELL-ERROR-NAME
} \VAR{condition
})
}
234 \retval{Name of cell
} which caused
\VAR{condition
}.
237 \IT{(
\FU*
{UNBOUND-SLOT-INSTANCE
} \VAR{condition
})
}
239 \retval{Instance
} with unbound slot which caused
\VAR{condition
}.
242 \IT{(
\FU*
{PRINT-NOT-READABLE-OBJECT
} \VAR{condition
})
}
244 The
\retval{object
} not readably printable under
\VAR{condition
}.
248 (
\FU*
{PACKAGE-ERROR-PACKAGE
} \VAR{condition
})\\
249 (
\FU*
{FILE-ERROR-PATHNAME
} \VAR{condition
})\\
250 (
\FU*
{STREAM-ERROR-STREAM
} \VAR{condition
})
}{.
}}
252 \retval{Package
},
\retval{path
}, or
\retval{stream
}, respectively,
253 which caused the
\VAR{condition
} of indicated type.
256 \IT{\arrGOO{(
\FU*
{TYPE-ERROR-DATUM
} \VAR{ condition
})\\
257 (
\FU*
{TYPE-ERROR-EXPECTED-TYPE
} \VAR{ condition
})
}{.
}}
259 \retval{Object
} which caused
\VAR{condition
} of type
\kwd{type-error
}, or its
260 \retval{expected type
}, respectively.
263 \IT{\arrGOO{(
\FU*
{SIMPLE-CONDITION-FORMAT-CONTROL
} \VAR{ condition
})\\
264 (
\FU*
{SIMPLE-CONDITION-FORMAT-ARGUMENTS
} \VAR{ condition
})
}{.
}}
266 Return
\retval{\FU{format
} control
} or list of
\retval{\FU{format
}
267 arguments
}, respectively, of
\VAR{condition
}.
270 \IT{\V{\A break-on-signals
\A}\DF{\NIL}}
271 {\index{*BREAK-ON-SIGNALS*@
\A BREAK-ON-SIGNALS
\A}
272 Condition type debugger is to be invoked on.
275 \IT{\V{\A debugger-hook
\A}\DF{\NIL}}
276 {\index{*DEBUGGER-HOOK*@
\A DEBUGGER-HOOK
\A}
277 Function of condition and
278 function itself. Called before debugger.
286 %%% TeX-master: "clqr"