diff --git a/src/doc/new-doc/standards/conditions.txi b/src/doc/new-doc/standards/conditions.txi new file mode 100644 index 000000000..9041cc62d --- /dev/null +++ b/src/doc/new-doc/standards/conditions.txi @@ -0,0 +1,103 @@ +@node Conditions +@section Conditions + +@node Conditions - C Reference +@subsection C Reference + +@deffn Macro ECL_HANDLER_CASE +C macro for @clhs{m_hand_1.htm,handler-case} +@subsubheading Synopsis +@verbatim +ECL_HANDLER_CASE_BEGIN(env,names) { + +} ECL_HANDLER_CASE(n,condition) { { + +} ECL_HANDLER_CASE_END; +@end verbatim + +@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 restart name in the list: + +@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 deffn + + +@deffn Macro ECL_RESTART_CASE +C macro for @clhs{m_rst_ca.htm,restart-case} +@subsubheading Synopsis +@verbatim +ECL_RESTART_CASE_BEGIN(env,names) { + +} ECL_RESTART_CASE(n,args) { { + +} ECL_RESTART_CASE_END; +@end verbatim + +@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: + +@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 = 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; +@end verbatim +@end deffn + +@subsubsection Conditions C 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 cl_object cl_break() +@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 [Only in Common Lisp] +@item @clhs{f_invoke.htm,invoke-debugger} @tab cl_object cl_invoke_debugger(cl_object condition) +@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_object cl_make_condition(cl_narg narg, cl_object type) +@item @clhs{f_meth_1.htm,method-combination-error} @tab [Only in Common Lisp] +@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 cl_object cl_signal(cl_narg narg, cl_object datum, ...) +@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 cl_object cl_warn(cl_narg narg, cl_object datum, ...) +@end multitable diff --git a/src/doc/new-doc/standards/index.txi b/src/doc/new-doc/standards/index.txi index a257733fb..0aade879a 100644 --- a/src/doc/new-doc/standards/index.txi +++ b/src/doc/new-doc/standards/index.txi @@ -9,8 +9,8 @@ * Data and control flow:: @c * Iteration:: * Objects:: -@c * Structures:: -@c * Conditions:: +* Structures:: +* Conditions:: @c * Symbols:: @c * Packages:: * Numbers:: @@ -45,9 +45,7 @@ @include standards/objects.txi @include standards/structures.txi - -@c @node Conditions -@c @section Conditions +@include standards/conditions.txi @c @node Symbols @c @section Symbols