diff --git a/src/doc/new-doc/standards/data_and_control_flow.txi b/src/doc/new-doc/standards/data_and_control_flow.txi index 672dfaed1..6750917a3 100644 --- a/src/doc/new-doc/standards/data_and_control_flow.txi +++ b/src/doc/new-doc/standards/data_and_control_flow.txi @@ -184,13 +184,10 @@ Another restriction of C and C++ is that functions can only take a limited numbe @subsection C Reference -@subheading @code{ecl_bds_bind} -Bind a special variable - @defun ecl_bds_bind (cl_env_ptr @var{cl_env}, cl_object @var{var}, cl_object @var{value}); @end defun @defun ecl_bds_push (cl_env_ptr @var{cl_env}, cl_object @var{var}); -@end defun +Bind a special variable @subsubheading Description Establishes a variable binding for the symbol @var{var} in the Common Lisp environment @var{env}, assigning it @var{value}. @@ -200,15 +197,12 @@ This macro or function is the equivalent of @clhs{s_let_l.htm,LET*} and @clhs{s_ @code{ecl_bds_push} does a similar thing, but reuses the old value of the same variable. It is thus the equivalent of @code{(LET ((VAR VAR)) ...)} Every variable binding must undone when no longer needed. It is best practice to match each call to @code{ecl_bds_bind} by another call to @code{ecl_bds_unwind} in the same function. - - -@subheading @code{ecl_bds_unwind} -Undo one variable binding +@end defun @defun ecl_bds_unwind1 (cl_env_ptr @var{cl_env}); @end defun @defun ecl_bds_unwind_n (cl_env_ptr @var{cl_env}, int @var{n}); -@end defun +Undo one variable binding @subsubheading Description @code{ecl_bds_unwind1} undoes the outermost variable binding, restoring the original value of the symbol in the process. @@ -216,6 +210,7 @@ Undo one variable binding @code{ecl_bds_unwind_n} does the same, but for the @var{n} last variables. Every variable binding must undone when no longer needed. It is best practice to match each call to @code{ecl_bds_bind} by another call to @code{ecl_bds_unwind} in the same function. +@end defun @deffn Macro ecl_setq (cl_env_ptr @var{cl_env}, cl_object @var{var}, cl_object @var{value}); @@ -236,9 +231,6 @@ This function implements the equivalent of @clhs{f_symb_5.htm,symbol-value} and If the symbol is not bound, an error is signaled. @end defun -@subheading @code{ecl_va_arg} -Accepting a variable number of arguments - @deffn Macro {typedef struct @{ ... @} ecl_va_list[1];} @end deffn @@ -249,7 +241,7 @@ Accepting a variable number of arguments @end deftypefn @deftypefn Macro cl_object ecl_va_end (ecl_va_list @var{arglist}); -@end deftypefn +Accepting a variable number of arguments @subsubheading Description The macros above are used to code a function that accepts an arbitrary number of arguments. We will describe them in a practical example @@ -278,14 +270,13 @@ Once @var{varargs} has been initialized, we can retrieve these values one by one The last statement before returning the output of the function is @code{ecl_va_end}. This macro performs any required cleanup and should never be omitted. -@subheading @code{ecl_nth_value, ecl_nvalues} -Accessing output values +@end deftypefn + -@subsubheading Functions and macros @deftypefun cl_object ecl_nvalues (cl_env_ptr @var{env}); @end deftypefun @deftypefun cl_object ecl_nth_value (cl_env_ptr @var{env}, int @var{n}); -@end deftypefun +Accessing output values @subsubheading Description Common Lisp functions may return zero, one or more values. In ECL, the first two cases do not require any special manipulation, as the C function returns either @code{NIL} or the first (zeroth) value directly. However, if one wishes to access additional values from a function, one needs to use these two macros or functions @@ -315,10 +306,9 @@ The somewhat equivalent Common Lisp code: (floor 13 6)) @end verbatim -@subheading @code{ecl_return0, ecl_return1, ...} -Returning multiple values +@end deftypefun + -@subsubheading Synopsis @defun ecl_return0 (cl_env_ptr @var{cl_env}); @end defun @defun ecl_return1 (cl_env_ptr @var{cl_env}, cl_object @var{value1}); @@ -326,11 +316,13 @@ Returning multiple values @defun ecl_return2 (cl_env_ptr @var{cl_env}, cl_object @var{value1}, cl_object @var{value2}); @end defun @defun ecl_return3 (cl_env_ptr @var{cl_env}, cl_object @var{value1}, cl_object @var{value2}, cl_object @var{value3}); -@end defun +Returning multiple values @subsubheading Description Returns @var{N} values from a C/C++ function in a way that a Common Lisp function can recognize and use them. The 0-th value is returned directly, while values 1 to N are stored in the Common Lisp environment @var{cl_env}. This macro has to be used from a function which returns an object of type @code{cl_object}. +@end defun + @deffn Macro ECL_BLOCK_BEGIN @verbatim ECL_BLOCK_BEGIN(env,code) {