1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014 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; with no Invariant Sections, no Front-Cover Texts and
6 % no Back-Cover Texts. For details see file COPYING.
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10 \section{Conditions and Errors
}
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 For standardized condition types cf.\ Figure
\ref{data-types
} on
14 page
\pageref{data-types
}.
17 \IT{(
\MC*
{DEFINE-CONDITION
}
18 \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
40 defaults to
\VAR{form
} unless set via
\kwd{:
}\VAR{initarg-name
};
41 it is readable via (
\VAR{reader
} \VAR{i
}) or (
\VAR{accessor
}
42 \VAR{i
}), and writable via (
\VAR{writer
} \VAR{value
} \VAR{i
}) or
43 (
\kwd{setf
} (
\VAR{accessor
} \VAR{i
})
\VAR{value
}). With
44 \kwd{:allocation :class
},
\VAR{slot
} is shared by all conditions
45 of 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
}
50 \VAR{condition-type
} \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}})
}
52 Return new
\retval{instance of
\VAR{condition-type
}}.
62 \VAR{condition-type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
63 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
66 Unless handled, signal as
\kwd{condition
},
\kwd{warning
} or
67 \kwd{error
}, respectively,
\VAR{condition
} or a new instance of
68 \VAR{condition-type
} or, with
\FU{format
} \VAR{control
} and
69 \VAR{arg
}s (see page
\pageref{section:Format
}),
70 \kwd{simple-condition
},
\kwd{simple-warning
}, or
71 \kwd{simple-error
}, respectively. From
\FU{SIGNAL
} and
\FU{WARN
},
75 \IT{(
\FU*
{CERROR
} \VAR{continue-control
}
77 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
78 \VAR{condition-type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
79 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
82 Unless handled, signal as correctable
\kwd{error
} \VAR{condition
}
83 or a new instance of
\VAR{condition-type
} or, with
\FU{format
}
84 \VAR{control
} and
\VAR{arg
}s (see page
\pageref{section:Format
}),
85 \kwd{simple-error
}. In the debugger, use
\FU{format
} arguments
86 \VAR{continue-control
} and
\VAR{continue-arg
}s to tag the continue
87 option. Return
\retval{\NIL}.
90 \IT{(
\MC*
{IGNORE-ERRORS
} \PROGN{\VAR{form
}})
}
92 Return
\retval{values of
\VAR{form
}s
} or, in case of
\kwd{error
}s,
93 \retval{\NIL} and the
\retvalii{condition
}.
96 \IT{(
\FU*
{INVOKE-DEBUGGER
} \VAR{condition
})
}
98 Invoke debugger with
\VAR{condition
}.
101 \IT{(
\MC*
{ASSERT
} \VAR{test
} \OP{(
\OPn{\VAR{place
}})
104 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
105 \VAR{condition-type
}\text{ }
106 \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
107 \VAR{control
}\text{ } \OPn{\VAR{arg
}}}{\
}}}})
}
109 If
\VAR{test
}, which may depend on
\VAR{place
}s, returns
\NIL,
110 signal as correctable
\kwd{error
} \VAR{condition
} or a new
111 instance of
\VAR{condition-type
} or, with
\FU{format
}
112 \VAR{control
} and
\VAR{arg
}s (see page
\pageref{section:Format
}),
113 \kwd{error
}. When using the debugger's continue option,
114 \VAR{place
}s can be altered before re-evaluation of
115 \VAR{test
}. Return
\retval{\NIL}.
118 \IT{(
\MC*
{HANDLER-CASE
} \VAR{foo
}
120 \OPn{(
\VAR{type
} (
\Op{\VAR{var
}})
121 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
122 \PROGN{\VAR{condition-form
}})
}
124 \Op{(
\kwd{:no-error
} (
\OPn{\VAR{ord-$
\lambda$
}})
125 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
126 \PROGN{\VAR{form
}})
})
}
128 If, on evaluation of
\VAR{foo
}, a condition of
\VAR{type
} is
129 signalled, evaluate matching
\VAR{condition-form
}s with
\VAR{var
}
130 bound to the condition, and return
\retval{their values
}. Without
131 a condition, bind
\VAR{ord-$
\lambda$
}s to values of
\VAR{foo
} and
132 return
\retval{values of
\VAR{form
}s
} or, without a
133 \kwd{:no-error
} clause, return
\retval{values of
\VAR{foo
}}. See
134 page
\pageref{section:Functions
} for (
\OPn{\VAR{ord-$
\lambda$
}}).
137 \IT{(
\MC*
{HANDLER-BIND
} (
\OPn{(
\VAR{condition-type
}
138 \VAR{handler-function
})
})
\PROGN{\VAR{form
}})
}
140 Return
\retval{values of
\VAR{form
}s
} after evaluating them with
141 \VAR{condition-type
}s dynamically bound to their respective
142 \VAR{handler-function
}s of argument condition.
145 \IT{(
\MC*
{WITH-SIMPLE-RESTART
} (
\xorGOO{\VAR{restart
}\\
146 \NIL}{\
}} \VAR{control
}
147 \OPn{\VAR{arg
}})
\PROGN{\VAR{form
}})
}
149 Return
\retval{values of
\VAR{form
}s
} unless
\VAR{restart
} is
150 called during their evaluation. In this case, describe
151 \VAR{restart
} using
\FU{format
} \VAR{control
} and
\VAR{arg
}s (see
152 page
\pageref{section:Format
}) and return
\retval{\NIL} and
156 \IT{(
\MC*
{RESTART-CASE
} \VAR{form
}
158 (
\OPn{\VAR{ord-$
\lambda$
}})
159 \orGOO{\kwd{:interactive
} \VAR{ arg-function
}\\
160 \kwd{:
report } \xorGOO{%
161 \VAR{report-function
}\\
162 \VAR{string
}\DF{\LIT{"
}\VAR{restart
}\LIT{"
}}}{.
}\\
163 \kwd{:test
} \VAR{ test-function
}\DF{\T}}{\
}}
164 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
165 \PROGN{\VAR{restart-form
}})
})
}
167 Return
\retval{values of
\VAR{form
}} or, if during evaluation of
168 \VAR{form
} one of the dynamically established
\VAR{restart
}s is
169 called, the
\retval{values of its
\VAR{restart-form
}s
}. A
170 \VAR{restart
} is visible under
\VAR{condition
} if (
\kwd{funcall
}
171 \kwd{\#'
}\VAR{test-function
} \VAR{condition
}) returns
\T. If
172 presented in the debugger,
\VAR{restart
}s are described by
173 \VAR{string
} or by
\kwd{\#'
}\VAR{report-function
} (of a stream).
174 A
\VAR{restart
} can be called by (
\kwd{invoke-restart
}
175 \VAR{restart
} \OPn{\VAR{arg
}}), where
\VAR{arg
}s match
176 \OPn{\VAR{ord-$
\lambda$
}}, or by
177 (
\kwd{invoke-restart-interactively
} \VAR{restart
}) where a list of
178 the respective
\VAR{arg
}s is supplied by
179 \kwd{\#'
}\VAR{arg-function
}. See page
\pageref{section:Functions
}
180 for
\OPn{\VAR{ord-$
\lambda$
}}.
183 \IT{(
\MC*
{RESTART-BIND
}
185 \NEV{\VAR{restart
}}\\
187 \VAR{restart-function
}
189 \kwd{:interactive-function
} \VAR{ arg-function
}\\
190 \kwd{:
report-function
} \VAR{ report-function
}\\
191 \kwd{:test-function
} \VAR{ test-function
}}{\
}})
})
194 Return
\retval{values of
\VAR{form
}s
} evaluated with dynamically
195 established
\VAR{restart
}s whose
\VAR{restart-function
}s should
196 perform a non-local transfer of control. A restart is visible
197 under
\VAR{condition
} if (
\VAR{test-function
} \VAR{condition
})
198 returns
\T. If presented in the debugger,
\VAR{restart
}s are
199 described by
\VAR{restart-function
} (of a stream). A
200 \VAR{restart
} can be called by (
\kwd{invoke-restart
} \VAR{restart
}
201 \OPn{\VAR{arg
}}), where
\VAR{arg
}s must be suitable for the
202 corresponding
\VAR{restart-function
}, or by
203 (
\kwd{invoke-restart-interactively
} \VAR{restart
}) where a list of
204 the respective
\VAR{arg
}s is supplied by
\VAR{arg-function
}.
207 \IT{\arrGOO{(
\FU*
{INVOKE-RESTART
} \VAR{ restart
} \OPn{\VAR{ arg
}})\\
208 (
\FU*
{INVOKE-RESTART-INTERACTIVELY
} \VAR{ restart
})
}{.
}}
210 Call function associated with
\VAR{restart
} with arguments given
211 or prompted for, respectively. If
\VAR{restart
} function returns,
212 return
\retval{its values
}.
217 \FU*
{COMPUTE-RESTARTS
} \VAR{ name
}}{\
}} \Op{\VAR{condition
}})
}
219 Return innermost
\retval{restart
} \VAR{name
}, or a
\retval{list of
220 all restarts
}, respectively, out of those either associated with
221 \VAR{condition
} or un-associated at all; or, without
222 \VAR{condition
}, out of all restarts. Return
\retval{\NIL} if
223 search is unsuccessful.
226 \IT{(
\FU*
{RESTART-NAME
} \VAR{restart
})
}
228 \retval{Name of
\VAR{restart
}}.
231 \IT{(
\xorGOO{\FU*
{ABORT
}\\
232 \FU*
{MUFFLE-WARNING
}\\
234 \FU*
{STORE-VALUE
} \VAR{ value
}\\
235 \FU*
{USE-VALUE
} \VAR{ value
}}{\
}} \Op{\VAR{condition
}\DF{\NIL}})
}
237 Transfer control to innermost applicable restart with same name
238 (i.e.
\kwd{abort
},
\ldots,
\kwd{continue
} \ldots) out of those either associated
239 with
\VAR{condition
} or un-associated at all; or, without
240 \VAR{condition
}, out of all restarts. If no restart is found,
241 signal
\kwd{control-error
} for
\FU{abort
} and
\FU{muffle-warning
},
242 or return
\retval{\NIL} for the rest.
245 \IT{(
\MC*
{WITH-CONDITION-RESTARTS
} \VAR{condition
}
246 \VAR{restarts
} \PROGN{\VAR{form
}})
}
248 Evaluate
\VAR{form
}s with
\VAR{restarts
}
249 dynamically associated with
\VAR{condition
}. Return
\retval{values
253 \IT{\arrGOO{(
\FU*
{ARITHMETIC-ERROR-OPERATION
} \VAR{ condition
})\\
254 (
\FU*
{ARITHMETIC-ERROR-OPERANDS
} \VAR{ condition
})
}{.
}}
256 \retval{List of function
} or
\retval{of its operands
} respectively,
257 used in the operation which caused
\VAR{condition
}.
260 \IT{(
\FU*
{CELL-ERROR-NAME
} \VAR{condition
})
}
262 \retval{Name of cell
} which caused
\VAR{condition
}.
265 \IT{(
\FU*
{UNBOUND-SLOT-INSTANCE
} \VAR{condition
})
}
267 \retval{Instance
} with unbound slot which caused
\VAR{condition
}.
270 \IT{(
\FU*
{PRINT-NOT-READABLE-OBJECT
} \VAR{condition
})
}
272 The
\retval{object
} not readably printable under
\VAR{condition
}.
276 (
\FU*
{PACKAGE-ERROR-PACKAGE
} \VAR{condition
})\\
277 (
\FU*
{FILE-ERROR-PATHNAME
} \VAR{condition
})\\
278 (
\FU*
{STREAM-ERROR-STREAM
} \VAR{condition
})
}{.
}}
280 \retval{Package
},
\retval{path
}, or
\retval{stream
}, respectively,
281 which caused the
\VAR{condition
} of indicated type.
284 \IT{\arrGOO{(
\FU*
{TYPE-ERROR-DATUM
} \VAR{ condition
})\\
285 (
\FU*
{TYPE-ERROR-EXPECTED-TYPE
} \VAR{ condition
})
}{.
}}
287 \retval{Object
} which caused
\VAR{condition
} of type
\kwd{type-error
}, or its
288 \retval{expected type
}, respectively.
291 \IT{\arrGOO{(
\FU*
{SIMPLE-CONDITION-FORMAT-CONTROL
} \VAR{ condition
})\\
292 (
\FU*
{SIMPLE-CONDITION-FORMAT-ARGUMENTS
} \VAR{ condition
})
}{.
}}
294 Return
\retval{\FU{format
} control
} or list of
\retval{\FU{format
}
295 arguments
}, respectively, of
\VAR{condition
}.
298 \IT{\V{\A break-on-signals
\A}\DF{\NIL}}
299 {\index{*BREAK-ON-SIGNALS*@
\A BREAK-ON-SIGNALS
\A}
300 Condition type debugger is to be invoked on.
303 \IT{\V{\A debugger-hook
\A}\DF{\NIL}}
304 {\index{*DEBUGGER-HOOK*@
\A DEBUGGER-HOOK
\A}
305 Function of condition and
306 function itself. Called before debugger.
314 %%% TeX-master: "clqr"