<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter>
<title>Conditions</title>
<section xml:id="ansi.conditions.c-dict">
<title>C Reference</title>
  <refentry xml:id="ECL_HANDLER_CASE">
    <refnamediv>
      <refname><function>ECL_HANDLER_CASE</function></refname>
      <refpurpose>C macro for <ulink url="&clhs;m_hand_1.htm"><symbol>handler-case</symbol></ulink></refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis><code><function>ECL_HANDLER_CASE_BEGIN</function>(env,names) {</code></synopsis>
      <synopsis><code>} <function>ECL_HANDLER_CASE(n,condition) {</function> {</code></synopsis>
      <synopsis><code>} <function>ECL_HANDLER_CASE_END</function>;</code></synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><function>ECL_HANDLER_CASE_BEGIN</function> runs a block of C code with a set of error handlers bound to the names given by the list <replaceable>names</replaceable>. The subsequent <function>ECL_HANDLER_CASE</function> statements specify what to do when the <replaceable>n</replaceable>-th type of conditions is found, where <replaceable>n</replaceable> is an integer denoting the position of the name in the list <replaceable>names</replaceable>.</para>

      <para>When a condition is signaled, &ECL; scans the list of signal handlers, looking for matches based on <symbol>typep</symbol>. If the match with the highest precedence belongs to the list <replaceable>names</replaceable>, &ECL; will perform a non-local transfer of control to the appropriate <function>ECL_HANDLER_CASE</function>, passing it a <replaceable>condition</replaceable> object as unique argument.</para>

      <para>The following example shows how to establish a handler for <symbol>ERROR</symbol> conditions. Note how the first value to <function>ECL_HANDLER_CASE</function> matches the position of the restart name in the list:</para>
      <programlisting>
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;
      </programlisting>
    </refsect1>
  </refentry>

  <refentry xml:id="ECL_RESTART_CASE">
    <refnamediv>
      <refname><function>ECL_RESTART_CASE</function></refname>
      <refpurpose>C macro for <ulink url="&clhs;m_rst_ca.htm"><symbol>restart-case</symbol></ulink></refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <synopsis><code><function>ECL_RESTART_CASE_BEGIN</function>(env,names) {</code></synopsis>
      <synopsis><code>} <function>ECL_RESTART_CASE(n,args) {</function> {</code></synopsis>
      <synopsis><code>} <function>ECL_RESTART_CASE_END</function>;</code></synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>

      <para><function>ECL_RESTART_CASE_BEGIN</function> runs a block of C code with a set of restarts bound to the names given by the list <replaceable>names</replaceable>. The subsequent <function>ECL_RESTART_CASE</function> statements specify what to do when the <replaceable>n</replaceable>-th restart is invoked, where <replaceable>n</replaceable> is an integer denoting the position of the name in the list <replaceable>names</replaceable>.</para>

      <para>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 <replaceable>args</replaceable>.</para>

      <para>The following example shows how to establish an <symbol>ABORT</symbol> and a <symbol>USE-VALUE</symbol> restart. Note how the first value to <function>ECL_RESTART_CASE</function> matches the position of the restart name in the list:</para>
      <programlisting>
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 = Cnil;
} ECL_RESTART_CASE(2, args) {
   /* This code is executed when the 2nd restart (ABORT) is invoked */
   output = ECL_CAR(args);
} ECL_RESTART_CASE_END;
      </programlisting>
    </refsect1>
  </refentry>

  <refentry>
    <refnamediv>
      <refname>Conditions C dictionary</refname>
      <refpurpose>&ANSI-C-Dict;</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
<simplelist columns="2" type="horiz">
<member>Lisp symbol</member>
<member>C function</member>

<member><ulink url="&clhs;f_abortc.htm"><symbol>abort</symbol></ulink></member>
<member><code>cl_object cl_abort(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_break.htm"><symbol>break</symbol></ulink></member>
<member><code>cl_object cl_break()</code></member>

<member><ulink url="&clhs;f_cell_e.htm"><symbol>cell-error-name</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;f_cerror.htm"><symbol>cerror</symbol></ulink></member>
<member><code>cl_object cl_cerror(cl_narg narg, cl_object continue_format_control, cl_object datum, ...)</code></member>

<member><ulink url="&clhs;f_comp_1.htm"><symbol>compute-restarts</symbol></ulink></member>
<member><code>cl_object cl_compute_restarts(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_abortc.htm"><symbol>continue</symbol></ulink></member>
<member><code>cl_object cl_continue(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_error.htm"><symbol>error</symbol></ulink></member>
<member><code>cl_object cl_error(cl_narg narg, cl_object datum, ...)</code></member>

<member><ulink url="&clhs;f_find_r.htm"><symbol>find-restart</symbol></ulink></member>
<member><code>cl_object cl_find_restart(cl_narg narg, cl_object identifier, ...)</code></member>

<member><ulink url="&clhs;m_hand_1.htm"><symbol>handler-case</symbol></ulink></member>
<member><link linkend="ECL_HANDLER_CASE"><function>ECL_HANDLER_CASE</function></link> macro</member>

<member><ulink url="&clhs;f_invali.htm"><symbol>invalid-method-error</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;f_invoke.htm"><symbol>invoke-debugger</symbol></ulink></member>
<member><code>cl_object cl_invoke_debugger(cl_object condition)</code></member>

<member><ulink url="&clhs;f_invo_1.htm"><symbol>invoke-restart</symbol></ulink></member>
<member><code>cl_object cl_invoke_restart(cl_narg narg, cl_object restart, ...)</code></member>

<member><ulink url="&clhs;f_invo_2.htm"><symbol>invoke-restart-interactively</symbol></ulink></member>
<member><code>cl_object cl_invoke_restart_interactively(cl_object restart)</code></member>

<member><ulink url="&clhs;f_mk_cnd.htm"><symbol>make-condition</symbol></ulink></member>
<member><code>cl_object cl_make_condition(cl_narg narg, cl_object type)</code></member>

<member><ulink url="&clhs;f_meth_1.htm"><symbol>method-combination-error</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;f_abortc.htm"><symbol>muffle-warning</symbol></ulink></member>
<member><code>cl_object cl_muffle_warning(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_rst_na.htm"><symbol>restart-name</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;m_rst_ca.htm"><symbol>restart-case</symbol></ulink></member>
<member><link linkend="ECL_RESTART_CASE"><function>ECL_RESTART_CASE</function></link> macro</member>

<member><ulink url="&clhs;f_signal.htm"><symbol>signal</symbol></ulink></member>
<member><code>cl_object cl_signal(cl_narg narg, cl_object datum, ...)</code></member>

<member><ulink url="&clhs;f_smp_cn.htm"><symbol>simple-condition-format-control</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;f_smp_cn.htm"><symbol>simple-condition-format-arguments</symbol></ulink></member>
<member><code>&OCL;</code></member>

<member><ulink url="&clhs;f_abortc.htm"><symbol>store-value</symbol></ulink></member>
<member><code>cl_object cl_store_value(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_abortc.htm"><symbol>use-value</symbol></ulink></member>
<member><code>cl_object cl_use_value(cl_narg narg, ...)</code></member>

<member><ulink url="&clhs;f_warn.htm"><symbol>warn</symbol></ulink></member>
<member><code>cl_object cl_warn(cl_narg narg, cl_object datum, ...)</code></member>
</simplelist>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para></para>
    </refsect1>
  </refentry>
</section>
</chapter>
</book>
