@node Conditions
@section Conditions

@subsection C Reference
@cppindex ECL_HANDLER_CASE
@cppindex ECL_RESTART_CASE

@deffn Macro ECL_HANDLER_CASE
C macro for @clhs{m_hand_1.htm,handler-case}
@subsubheading Synopsis
@example
@verbatim
ECL_HANDLER_CASE_BEGIN(env,names) {

} ECL_HANDLER_CASE(n,condition) { {

} ECL_HANDLER_CASE_END;
@end verbatim
@end example

@subsubheading Description
@code{ECL_HANDLER_CASE_BEGIN} runs a block of C code with a set of error handlers bound to the names given by the list @var{names}. The subsequent @code{ECL_HANDLER_CASE} statements specify what to do when the @var{n}-th type of conditions is found, where @var{n} is an integer denoting the position of the name in the list @var{names}.

When a condition is signaled, ECL scans the list of signal handlers, looking for matches based on @code{typep}. If the match with the highest precedence belongs to the list @var{names}, ECL will perform a non-local transfer of control to the appropriate @code{ECL_HANDLER_CASE}, passing it a @var{condition} object as unique argument.

The following example shows how to establish a handler for @code{ERROR} conditions. Note how the first value to @code{ECL_HANDLER_CASE} matches the position of the condition name in the list:

@example
@verbatim
cl_object error = ecl_make_symbol("ERROR","CL");
ECL_HANDLER_CASE_BEGIN(the_env, ecl_list1(error)) {
   /* This form is evaluated with bound handlers */
   output = cl_eval(1, form);
} ECL_HANDLER_CASE(1, condition) {
   /* This code is executed when an error happens */
   /* We just return the error that took place */
   output = condition;
} ECL_HANDLER_CASE_END;
@end verbatim
@end example

@end deffn


@deffn Macro ECL_RESTART_CASE
C macro for @clhs{m_rst_ca.htm,restart-case}
@subsubheading Synopsis
@example
@verbatim
ECL_RESTART_CASE_BEGIN(env,names) {

} ECL_RESTART_CASE(n,args) { {

} ECL_RESTART_CASE_END;
@end verbatim
@end example

@subsubheading Description
@code{ECL_RESTART_CASE_BEGIN} runs a block of C code with a set of restarts bound to the names given by the list @var{names}. The subsequent @code{ECL_RESTART_CASE} statements specify what to do when the @var{n}-th restart is invoked, where @var{n} is an integer denoting the position of the name in the list @var{names}.

When the restart is invoked, it can receive any number of arguments, which are grouped in a list and stored in a new variable created with the name @var{args}.

The following example shows how to establish an @var{ABORT} and a @var{USE-VALUE} restart. Note how the first value to @var{ECL_RESTART_CASE} matches the position of the restart name in the list:

@example
@verbatim
cl_object abort = ecl_make_symbol("ABORT","CL");
cl_object use_value = ecl_make_symbol("USE-VALUE","CL");
ECL_RESTART_CASE_BEGIN(the_env, cl_list(2, abort, use_value)) {
   /* This form is evaluated with bound restarts */
   output = cl_eval(1, form);
} ECL_RESTART_CASE(1, args) {
   /* This code is executed when the 1st restart (ABORT) is invoked */
   output = ECL_NIL;
} ECL_RESTART_CASE(2, args) {
   /* This code is executed when the 2nd restart (USE-VALUE) is invoked */
   output = ECL_CAR(args);
} ECL_RESTART_CASE_END;
@end verbatim
@end example
@end deffn

@subsubsection ANSI dictionary
Common Lisp and C equivalence

@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_abortc.htm,abort} @tab cl_object cl_abort(cl_narg narg, ...)
@item @clhs{f_break.htm,break} @tab [Only in Common Lisp]
@item @clhs{f_cell_e.htm,cell-error-name} @tab [Only in Common Lisp]
@item @clhs{f_cerror.htm,cerror} @tab cl_object cl_cerror(cl_narg narg, cl_object continue_format_control, cl_object datum, ...)
@item @clhs{f_comp_1.htm,compute-restarts} @tab cl_object cl_compute_restarts(cl_narg narg, ...)
@item @clhs{f_abortc.htm,continue} @tab cl_object cl_continue(cl_narg narg, ...)
@item @clhs{f_error.htm,error} @tab cl_object cl_error(cl_narg narg, cl_object datum, ...)
@item @clhs{f_find_r.htm,find-restart} @tab cl_object cl_find_restart(cl_narg narg, cl_object identifier, ...)
@item @clhs{m_hand_1.htm,handler-case} @tab ECL_HANDLER_CASE macro
@item @clhs{f_invali.htm,invalid-method-error} @tab cl_object cl_invalid_method_error (cl_narg narg, cl_object method, cl_object format, ...)
@item @clhs{f_invoke.htm,invoke-debugger} @tab [Only in Common Lisp]
@item @clhs{f_invo_1.htm,invoke-restart} @tab cl_object cl_invoke_restart(cl_narg narg, cl_object restart, ...)
@item @clhs{f_invo_2.htm,invoke-restart-interactively} @tab cl_object cl_invoke_restart_interactively(cl_object restart)
@item @clhs{f_mk_cnd.htm,make-condition} @tab cl_make_condition(cl_narg narg, cl_object type, ...)
@item @clhs{f_meth_1.htm,method-combination-error} @tab cl_object cl_method_combination_error(cl_narg narg, cl_object format, ...)
@item @clhs{f_abortc.htm,muffle-warning} @tab cl_object cl_muffle_warning(cl_narg narg, ...)
@item @clhs{f_rst_na.htm,restart-name} @tab [Only in Common Lisp]
@item @clhs{f_rst_ca.htm,restart-case} @tab ECL_RESTART_CASE macro
@item @clhs{f_signal.htm,signal} @tab [Only in Common Lisp]
@item @clhs{f_smp_cn.htm,simple-condition-format-control} @tab [Only in Common Lisp]
@item @clhs{f_smp_cn.htm,simple-condition-format-arguments} @tab [Only in Common Lisp]
@item @clhs{f_abortc.htm,store-value} @tab cl_object cl_store_value(cl_narg narg, ...)
@item @clhs{f_abortc.htm,use-value} @tab cl_object cl_use_value(cl_narg narg, ...)
@item @clhs{f_warn.htm,warn} @tab [Only in Common Lisp]
@end multitable