1 % Copyright (C) 2008, 2009, 2010, 2011, 2012 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
}
19 \VAR{foo
} (
\OPn{\VAR{parent-type
}}\DF{\kwd{condition
}})
22 \orGOO{\Goos{\kwd{:reader
} \VAR{reader
}}\\
23 \Goos{\kwd{:writer
} \xorGOO{%
25 (
\kwd{setf
} \VAR{writer
})
}{\
}}}\\
26 \Goos{\kwd{:accessor
} \VAR{accessor
}} \\
27 \kwd{:allocation
} \xorGOO{\kwd{:instance
}\\
28 \kwd{:class
}}{\
}}\DF{\kwd{:instance
}}\\
29 \Goos{\kwd{:initarg
} \kwd{:
}\VAR{initarg-name
}}\\
30 \kwd{:initform
} \VAR{ form
}\\
31 \kwd{:type
} \VAR{ type
}\\
32 \kwd{:documentation
} \VAR{ slot-doc
}%
34 \orGOO{(
\kwd{:default-initargs
} \Goos{\VAR{name
} \VAR{value
}})\\
35 (
{\kwd{:documentation
} \VAR{ condition-doc
}})\\
36 (
\kwd{:
report } \xorGOO{\VAR{string
}\\
37 \VAR{report-function
}}{\
}})
}{\
}})
}
39 Define, as a subtype of
\VAR{parent-type
}s, condition type
40 \retval{\VAR{foo
}}. In a new condition, a
\VAR{slot
}'s value
41 defaults to
\VAR{form
} unless set via
\kwd{:
}\VAR{initarg-name
};
42 it is readable via (
\VAR{reader
} \VAR{i
}) or (
\VAR{accessor
}
43 \VAR{i
}), and writable via (
\VAR{writer
} \VAR{value
} \VAR{i
}) or
44 (
\kwd{setf
} (
\VAR{accessor
} \VAR{i
})
\VAR{value
}). With
45 \kwd{:allocation :class
},
\VAR{slot
} is shared by all conditions
46 of type
\VAR{foo
}. A condition is reported by
\VAR{string
} or by
47 \VAR{report-function
} of arguments condition and stream.
50 \IT{(
\FU*
{MAKE-CONDITION
}
51 \VAR{condition-type
} \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}})
}
53 Return new
\retval{instance of
\VAR{condition-type
}}.
63 \VAR{condition-type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
64 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
67 Unless handled, signal as
\kwd{condition
},
\kwd{warning
} or
68 \kwd{error
}, respectively,
\VAR{condition
} or a new instance of
69 \VAR{condition-type
} or, with
\FU{format
} \VAR{control
} and
70 \VAR{arg
}s (see page
\pageref{section:Format
}),
71 \kwd{simple-condition
},
\kwd{simple-warning
}, or
72 \kwd{simple-error
}, respectively. From
\FU{SIGNAL
} and
\FU{WARN
},
76 \IT{(
\FU*
{CERROR
} \VAR{continue-control
}
78 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
79 \VAR{condition-type
}\text{ } \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
80 \VAR{control
}\text{ } \OPn{\VAR{arg
}}%
83 Unless handled, signal as correctable
\kwd{error
} \VAR{condition
}
84 or a new instance of
\VAR{condition-type
} or, with
\FU{format
}
85 \VAR{control
} and
\VAR{arg
}s (see page
\pageref{section:Format
}),
86 \kwd{simple-error
}. In the debugger, use
\FU{format
} arguments
87 \VAR{continue-control
} and
\VAR{continue-arg
}s to tag the continue
88 option. Return
\retval{\NIL}.
91 \IT{(
\MC*
{IGNORE-ERRORS
} \PROGN{\VAR{form
}})
}
93 Return
\retval{values of
\VAR{form
}s
} or, in case of
\kwd{error
}s,
94 \retval{\NIL} and the
\retvalii{condition
}.
97 \IT{(
\FU*
{INVOKE-DEBUGGER
} \VAR{condition
})
}
99 Invoke debugger with
\VAR{condition
}.
102 \IT{(
\MC*
{ASSERT
} \VAR{test
} \OP{(
\OPn{\VAR{place
}})
105 \VAR{condition
}\text{ } \OPn{\VAR{continue-arg
}}\\
106 \VAR{condition-type
}\text{ }
107 \Goos{\kwd{:
}\VAR{initarg-name
} \VAR{value
}}\\
108 \VAR{control
}\text{ } \OPn{\VAR{arg
}}}{\
}}}})
}
110 If
\VAR{test
}, which may depend on
\VAR{place
}s, returns
\NIL,
111 signal as correctable
\kwd{error
} \VAR{condition
} or a new
112 instance of
\VAR{condition-type
} or, with
\FU{format
}
113 \VAR{control
} and
\VAR{arg
}s (see page
\pageref{section:Format
}),
114 \kwd{error
}. When using the debugger's continue option,
115 \VAR{place
}s can be altered before re-evaluation of
116 \VAR{test
}. Return
\retval{\NIL}.
119 \IT{(
\MC*
{HANDLER-CASE
} \VAR{foo
}
121 \OPn{(
\VAR{type
} (
\Op{\VAR{var
}})
122 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
123 \PROGN{\VAR{condition-form
}})
}
125 \Op{(
\kwd{:no-error
} (
\OPn{\VAR{ord-$
\lambda$
}})
126 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
127 \PROGN{\VAR{form
}})
})
}
129 If, on evaluation of
\VAR{foo
}, a condition of
\VAR{type
} is
130 signalled, evaluate matching
\VAR{condition-form
}s with
\VAR{var
}
131 bound to the condition, and return
\retval{their values
}. Without
132 a condition, bind
\VAR{ord-$
\lambda$
}s to values of
\VAR{foo
} and
133 return
\retval{values of
\VAR{form
}s
} or, without a
134 \kwd{:no-error
} clause, return
\retval{values of
\VAR{foo
}}. See
135 page
\pageref{section:Functions
} for (
\OPn{\VAR{ord-$
\lambda$
}}).
138 \IT{(
\MC*
{HANDLER-BIND
} (
\OPn{(
\VAR{condition-type
}
139 \VAR{handler-function
})
})
\PROGN{\VAR{form
}})
}
141 Return
\retval{values of
\VAR{form
}s
} after evaluating them with
142 \VAR{condition-type
}s dynamically bound to their respective
143 \VAR{handler-function
}s of argument condition.
146 \IT{(
\MC*
{WITH-SIMPLE-RESTART
} (
\xorGOO{\VAR{restart
}\\
147 \NIL}{\
}} \VAR{control
}
148 \OPn{\VAR{arg
}})
\PROGN{\VAR{form
}})
}
150 Return
\retval{values of
\VAR{form
}s
} unless
\VAR{restart
} is
151 called during their evaluation. In this case, describe
152 \VAR{restart
} using
\FU{format
} \VAR{control
} and
\VAR{arg
}s (see
153 page
\pageref{section:Format
}) and return
\retval{\NIL} and
157 \IT{(
\MC*
{RESTART-CASE
} \VAR{form
}
159 (
\OPn{\VAR{ord-$
\lambda$
}})
160 \orGOO{\kwd{:interactive
} \VAR{ arg-function
}\\
161 \kwd{:
report } \xorGOO{%
162 \VAR{report-function
}\\
163 \VAR{string
}\DF{\LIT{"
}\VAR{foo
}\LIT{"
}}}{.
}\\
164 \kwd{:test
} \VAR{ test-function
}\DF{\T}}{\
}}
165 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
166 \PROGN{\VAR{restart-form
}})
})
}
168 Return
\retval{values of
\VAR{form
}} or, if during evaluation of
169 \VAR{form
} one of the dynamically established
\VAR{restart
}s is
170 called, the
\retval{values of its
\VAR{restart-form
}s
}. A
171 \VAR{restart
} is visible under
\VAR{condition
} if (
\kwd{funcall
}
172 \kwd{\#'
}\VAR{test-function
} \VAR{condition
}) returns
\T. If
173 presented in the debugger,
\VAR{restart
}s are described by
174 \VAR{string
} or by
\kwd{\#'
}\VAR{report-function
} (of a stream).
175 A
\VAR{restart
} can be called by (
\kwd{invoke-restart
}
176 \VAR{restart
} \OPn{\VAR{arg
}}), where
\VAR{arg
}s match
177 \OPn{\VAR{ord-$
\lambda$
}}, or by
178 (
\kwd{invoke-restart-interactively
} \VAR{restart
}) where a list of
179 the respective
\VAR{arg
}s is supplied by
180 \kwd{\#'
}\VAR{arg-function
}. See page
\pageref{section:Functions
}
181 for
\OPn{\VAR{ord-$
\lambda$
}}.
184 \IT{(
\MC*
{RESTART-BIND
} (
\OPn{(
\xorGOO{\NEV{\VAR{restart
}}\\
186 \VAR{restart-function
} \orGOO{\kwd{:interactive-function
}
188 \kwd{:
report-function
} \VAR{ function
}\\
189 \kwd{:test-function
} \VAR{ function
}}{\
}})
})
\PROGN{\VAR{form
}})
}
191 Return
\retval{values of
\VAR{form
}s
} evaluated with
192 \VAR{restart
}s dynamically bound to
\VAR{restart-function
}s.
195 \IT{\arrGOO{(
\FU*
{INVOKE-RESTART
} \VAR{ restart
} \OPn{\VAR{ arg
}})\\
196 (
\FU*
{INVOKE-RESTART-INTERACTIVELY
} \VAR{ restart
})
}{.
}}
198 Call function associated with
\VAR{restart
} with arguments given
199 or prompted for, respectively. If
\VAR{restart
} function returns,
200 return
\retval{its values
}.
205 \FU*
{COMPUTE-RESTARTS
} \VAR{ name
}}{\
}} \Op{\VAR{condition
}})
}
207 Return innermost
\retval{restart
} \VAR{name
}, or a
\retval{list of
208 all restarts
}, respectively, out of those either associated with
209 \VAR{condition
} or un-associated at all; or, without
210 \VAR{condition
}, out of all restarts. Return
\retval{\NIL} if
211 search is unsuccessful.
214 \IT{(
\FU*
{RESTART-NAME
} \VAR{restart
})
}
216 \retval{Name of
\VAR{restart
}}.
219 \IT{(
\xorGOO{\FU*
{ABORT
}\\
220 \FU*
{MUFFLE-WARNING
}\\
222 \FU*
{STORE-VALUE
} \VAR{ value
}\\
223 \FU*
{USE-VALUE
} \VAR{ value
}}{\
}} \Op{\VAR{condition
}\DF{\NIL}})
}
225 Transfer control to innermost applicable restart with same name
226 (i.e.
\kwd{abort
},
\ldots,
\kwd{continue
} \ldots) out of those either associated
227 with
\VAR{condition
} or un-associated at all; or, without
228 \VAR{condition
}, out of all restarts. If no restart is found,
229 signal
\kwd{control-error
} for
\FU{abort
} and
\FU{muffle-warning
},
230 or return
\retval{\NIL} for the rest.
233 \IT{(
\MC*
{WITH-CONDITION-RESTARTS
} \VAR{condition
}
234 \VAR{restarts
} \PROGN{\VAR{form
}})
}
236 Evaluate
\VAR{form
}s with
\VAR{restarts
}
237 dynamically associated with
\VAR{condition
}. Return
\retval{values
241 \IT{\arrGOO{(
\FU*
{ARITHMETIC-ERROR-OPERATION
} \VAR{ condition
})\\
242 (
\FU*
{ARITHMETIC-ERROR-OPERANDS
} \VAR{ condition
})
}{.
}}
244 \retval{List of function
} or
\retval{of its operands
} respectively,
245 used in the operation which caused
\VAR{condition
}.
248 \IT{(
\FU*
{CELL-ERROR-NAME
} \VAR{condition
})
}
250 \retval{Name of cell
} which caused
\VAR{condition
}.
253 \IT{(
\FU*
{UNBOUND-SLOT-INSTANCE
} \VAR{condition
})
}
255 \retval{Instance
} with unbound slot which caused
\VAR{condition
}.
258 \IT{(
\FU*
{PRINT-NOT-READABLE-OBJECT
} \VAR{condition
})
}
260 The
\retval{object
} not readably printable under
\VAR{condition
}.
264 (
\FU*
{PACKAGE-ERROR-PACKAGE
} \VAR{condition
})\\
265 (
\FU*
{FILE-ERROR-PATHNAME
} \VAR{condition
})\\
266 (
\FU*
{STREAM-ERROR-STREAM
} \VAR{condition
})
}{.
}}
268 \retval{Package
},
\retval{path
}, or
\retval{stream
}, respectively,
269 which caused the
\VAR{condition
} of indicated type.
272 \IT{\arrGOO{(
\FU*
{TYPE-ERROR-DATUM
} \VAR{ condition
})\\
273 (
\FU*
{TYPE-ERROR-EXPECTED-TYPE
} \VAR{ condition
})
}{.
}}
275 \retval{Object
} which caused
\VAR{condition
} of type
\kwd{type-error
}, or its
276 \retval{expected type
}, respectively.
279 \IT{\arrGOO{(
\FU*
{SIMPLE-CONDITION-FORMAT-CONTROL
} \VAR{ condition
})\\
280 (
\FU*
{SIMPLE-CONDITION-FORMAT-ARGUMENTS
} \VAR{ condition
})
}{.
}}
282 Return
\retval{\FU{format
} control
} or list of
\retval{\FU{format
}
283 arguments
}, respectively, of
\VAR{condition
}.
286 \IT{\V{\A break-on-signals
\A}\DF{\NIL}}
287 {\index{*BREAK-ON-SIGNALS*@
\A BREAK-ON-SIGNALS
\A}
288 Condition type debugger is to be invoked on.
291 \IT{\V{\A debugger-hook
\A}\DF{\NIL}}
292 {\index{*DEBUGGER-HOOK*@
\A DEBUGGER-HOOK
\A}
293 Function of condition and
294 function itself. Called before debugger.
302 %%% TeX-master: "clqr"