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
} \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 writable via (
\VAR{writer
} \VAR{value
} \VAR{i
}) 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 page
\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 page
\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 page
\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{foo
}
115 \OPn{(
\VAR{type
} (
\Op{\VAR{var
}})
116 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
117 \PROGN{\VAR{condition-form
}})
}
119 \Op{(
\kwd{:no-error
} (
\OPn{\VAR{ord-$
\lambda$
}})
120 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
121 \PROGN{\VAR{form
}})
})
}
123 If, on evaluation of
\VAR{foo
}, a condition of
\VAR{type
} is
124 signalled, evaluate matching
\VAR{condition-form
}s with
\VAR{var
}
125 bound to the condition, and return
\retval{their values
}. Without
126 a condition, bind
\VAR{ord-$
\lambda$
}s to values of
\VAR{foo
} and
127 return
\retval{values of
\VAR{form
}s
} or, without a
128 \kwd{:no-error
} clause, return
\retval{values of
\VAR{foo
}}. See
129 page
\pageref{section:Functions
} for (
\OPn{\VAR{ord-$
\lambda$
}}).
132 \IT{(
\MC*
{HANDLER-BIND
} (
\OPn{(
\VAR{condition-type
}
133 \VAR{handler-function
})
})
\PROGN{\VAR{form
}})
}
135 Return
\retval{values of
\VAR{form
}s
} after evaluating them with
136 \VAR{condition-type
}s dynamically bound to their respective
137 \VAR{handler-function
}s of argument condition.
140 \IT{(
\MC*
{WITH-SIMPLE-RESTART
} (
\xorGOO{\VAR{restart
}\\
141 \NIL}{\
}} \VAR{control
}
142 \OPn{\VAR{arg
}})
\PROGN{\VAR{form
}})
}
144 Return
\retval{values of
\VAR{form
}s
} unless
\VAR{restart
} is called
145 during their evaluation. In this case, describe restart using
146 \FU{format
} \VAR{control
} and
\VAR{arg
}s (see
147 page
\pageref{section:Format
}) and return
\retval{\NIL}
151 \IT{(
\MC*
{RESTART-CASE
} \VAR{form
}
153 (
\OPn{\VAR{ord-$
\lambda$
}})
154 \orGOO{\kwd{:interactive
} \VAR{ arg-function
}\\
155 \kwd{:
report } \xorGOO{%
156 \VAR{report-function
}\\
157 \VAR{string
}\DF{\LIT{"
}\VAR{foo
}\LIT{"
}}}{.
}\\
158 \kwd{:test
} \VAR{ test-function
}\DF{\T}}{\
}}
159 \OPn{(
\kwd{declare
} \OPn{\NEV{\VAR{decl
}}})
}
160 \PROGN{\VAR{restart-form
}})
})
}
162 Return
\retval{values of
\VAR{form
}} or, if during evaluation of
163 \VAR{form
} one of the dynamically established
\VAR{restart
}s is
164 called, the
\retval{values of its
\VAR{restart-form
}s
}. A
165 \VAR{restart
} is visible under
\VAR{condition
} if (
\kwd{funcall
}
166 \kwd{\#'
}\VAR{test-function
} \VAR{condition
}) returns
\T. If
167 presented in the debugger,
\VAR{restart
}s are described by
168 \VAR{string
} or by
\kwd{\#'
}\VAR{report-function
} (of a stream).
169 A
\VAR{restart
} can be called by (
\kwd{invoke-restart
}
170 \VAR{restart
} \OPn{\VAR{arg
}}), where
\VAR{arg
}s match
171 \OPn{\VAR{ord-$
\lambda$
}}, or by
172 (
\kwd{invoke-restart-interactively
} \VAR{restart
}) where a list of
173 the respective
\VAR{arg
}s is supplied by
174 \kwd{\#'
}\VAR{arg-function
}. See page
\pageref{section:Functions
}
175 for
\OPn{\VAR{ord-$
\lambda$
}}.
178 \IT{(
\MC*
{RESTART-BIND
} (
\OPn{(
\xorGOO{\NEV{\VAR{restart
}}\\
180 \VAR{restart-function
} \orGOO{\kwd{:interactive-function
}
182 \kwd{:
report-function
} \VAR{ function
}\\
183 \kwd{:test-function
} \VAR{ function
}}{\
}})
})
\PROGN{\VAR{form
}})
}
185 Return
\retval{values of
\VAR{form
}s
} evaluated with
186 \VAR{restart
}s dynamically bound to
\VAR{restart-function
}s.
189 \IT{\arrGOO{(
\FU*
{INVOKE-RESTART
} \VAR{ restart
} \OPn{\VAR{ arg
}})\\
190 (
\FU*
{INVOKE-RESTART-INTERACTIVELY
} \VAR{ restart
})
}{.
}}
192 Call function associated with
\VAR{restart
} with arguments given or
193 prompted for, respectively. If
\VAR{restart
} function returns,
194 return
\retval{its values
}.
197 \IT{(
\xorGOO{\FU*
{COMPUTE-RESTARTS
}\\
198 \FU*
{FIND-RESTART
} \VAR{ name
}}{\
}} \Op{\VAR{condition
}})
}
200 Return list of
\retval{all restarts
}, or innermost
\retval{restart
}
201 \VAR{name
}, respectively, out of those either associated
202 with
\VAR{condition
} or un-associated at all; or, without
203 \VAR{condition
}, out of all restarts. Return
\retval{\NIL} if search
207 \IT{(
\FU*
{RESTART-NAME
} \VAR{restart
})
}
209 \retval{Name of
\VAR{restart
}}.
212 \IT{(
\xorGOO{\FU*
{ABORT
}\\
213 \FU*
{MUFFLE-WARNING
}\\
215 \FU*
{STORE-VALUE
} \VAR{ value
}\\
216 \FU*
{USE-VALUE
} \VAR{ value
}}{\
}} \Op{\VAR{condition
}\DF{\NIL}})
}
218 Transfer control to innermost applicable restart with same name
219 (i.e.
\kwd{abort
},
\ldots,
\kwd{continue
} \ldots) out of those either associated
220 with
\VAR{condition
} or un-associated at all; or, without
221 \VAR{condition
}, out of all restarts. If no restart is found,
222 signal
\kwd{control-error
} for
\FU{abort
} and
\FU{muffle-warning
},
223 or return
\retval{\NIL} for the rest.
226 \IT{(
\MC*
{WITH-CONDITION-RESTARTS
} \VAR{condition
}
227 \VAR{restarts
} \PROGN{\VAR{form
}})
}
229 Evaluate
\VAR{form
}s with
\VAR{restarts
}
230 dynamically associated with
\VAR{condition
}. Return
\retval{values
234 \IT{\arrGOO{(
\FU*
{ARITHMETIC-ERROR-OPERATION
} \VAR{ condition
})\\
235 (
\FU*
{ARITHMETIC-ERROR-OPERANDS
} \VAR{ condition
})
}{.
}}
237 \retval{List of function
} or
\retval{of its operands
} respectively,
238 used in the operation which caused
\VAR{condition
}.
241 \IT{(
\FU*
{CELL-ERROR-NAME
} \VAR{condition
})
}
243 \retval{Name of cell
} which caused
\VAR{condition
}.
246 \IT{(
\FU*
{UNBOUND-SLOT-INSTANCE
} \VAR{condition
})
}
248 \retval{Instance
} with unbound slot which caused
\VAR{condition
}.
251 \IT{(
\FU*
{PRINT-NOT-READABLE-OBJECT
} \VAR{condition
})
}
253 The
\retval{object
} not readably printable under
\VAR{condition
}.
257 (
\FU*
{PACKAGE-ERROR-PACKAGE
} \VAR{condition
})\\
258 (
\FU*
{FILE-ERROR-PATHNAME
} \VAR{condition
})\\
259 (
\FU*
{STREAM-ERROR-STREAM
} \VAR{condition
})
}{.
}}
261 \retval{Package
},
\retval{path
}, or
\retval{stream
}, respectively,
262 which caused the
\VAR{condition
} of indicated type.
265 \IT{\arrGOO{(
\FU*
{TYPE-ERROR-DATUM
} \VAR{ condition
})\\
266 (
\FU*
{TYPE-ERROR-EXPECTED-TYPE
} \VAR{ condition
})
}{.
}}
268 \retval{Object
} which caused
\VAR{condition
} of type
\kwd{type-error
}, or its
269 \retval{expected type
}, respectively.
272 \IT{\arrGOO{(
\FU*
{SIMPLE-CONDITION-FORMAT-CONTROL
} \VAR{ condition
})\\
273 (
\FU*
{SIMPLE-CONDITION-FORMAT-ARGUMENTS
} \VAR{ condition
})
}{.
}}
275 Return
\retval{\FU{format
} control
} or list of
\retval{\FU{format
}
276 arguments
}, respectively, of
\VAR{condition
}.
279 \IT{\V{\A break-on-signals
\A}\DF{\NIL}}
280 {\index{*BREAK-ON-SIGNALS*@
\A BREAK-ON-SIGNALS
\A}
281 Condition type debugger is to be invoked on.
284 \IT{\V{\A debugger-hook
\A}\DF{\NIL}}
285 {\index{*DEBUGGER-HOOK*@
\A DEBUGGER-HOOK
\A}
286 Function of condition and
287 function itself. Called before debugger.
295 %%% TeX-master: "clqr"