Commit af2c1526 authored by Marius Gerbershagen's avatar Marius Gerbershagen

doc: improvements to standards section

    Apply consistent formatting, fix all ANSI dictionary sections as
    well as other errors and typos.
parent 0b0c7594
Pipeline #41753437 passed with stage
......@@ -105,7 +105,7 @@ ecl_alloc_adjustable_extended_string(cl_index l)
#endif
/*
Make_simple_base_string(s) makes a simple-base string from C string s.
ecl_make_simple_base_string(s) creates a simple-base string from C string s.
*/
cl_object
ecl_make_simple_base_string(char *s, cl_fixnum l)
......
......@@ -77,11 +77,11 @@ number of values of the function. The return value of the function is
copied in the @code{values} array as well as returned directly.
In general, if one is to play with the C kernel of ECL there is no
need to know about all these conventions. There is a preprocessor that
takes care of the details, by using a lisp representation of the
statements that output values, and of the function definitions. For
instance, the actual source code for @code{cl_last} in
@code{src/c/list.d}
need to know about all these conventions. There is a preprocessor
(@pxref{Defun preprocessor}) that takes care of the details, by using a
lisp representation of the statements that output values, and of the
function definitions. For instance, the actual source code for
@code{cl_last} in @code{src/c/list.d}
@verbatim
@(defun last (l &optional (k ecl_make_fixnum(1)))
......
......@@ -778,6 +778,7 @@ interpreted. The objects of type @code{t_bytecodes} are implicitly
constructed by a call to eval, but can also be explicitly constructed
with the @code{si_make_lambda} function.
@anchor{si_safe_eval}
@cppindex si_safe_eval
@cppindex cl_safe_eval
@cppindex cl_eval
......@@ -789,7 +790,7 @@ with the @code{si_make_lambda} function.
environment@footnote{Note that @code{env} must be a lexical
environment as used in the interpreter, @xref{The lexical environment}}
@code{env}, which can be @code{ECL_NIL}. Before evaluating it, the
expression form must be bytecompiled.
expression form is bytecompiled.
@itemize @bullet
@item @strong{DEPRECATED} @code{cl_object cl_eval (cl_object form)} -
......
......@@ -28,6 +28,7 @@ When the elements of an array are declared to have some precise type, such as a
@item character @tab unsigned char or uint32_t @tab Depends on character range
@item base-char @tab unsigned char @tab
@item fixnum @tab cl_fixnum @tab Machine word (32 or 64 bits)
@item ext:cl-index @tab cl_index @tab Machine word (32 or 64 bits)
@item (signed-byte 8) @tab int8_t @tab 8 bits
@item (unsigned-byte 8) @tab uint8_t @tab 8 bits
@item (signed-byte 16) @tab int16_t @tab 16 bits
......@@ -38,7 +39,7 @@ When the elements of an array are declared to have some precise type, such as a
@item (unsigned-byte 64) @tab uint64_t @tab 64 bits
@item single-float or short-float @tab float @tab 32-bits IEEE float
@item double-float @tab double @tab 64-bits IEEE float
@item long-float @tab long double @tab Between 96 and 128 bits.
@c @item long-float @tab long double @tab Between 96 and 128 bits. !Not implemented
@item t @tab cl_object @tab Size of a pointer.
@end multitable
......@@ -215,7 +216,6 @@ These functions query various properties of the arrays. Some of them belong to t
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .32 .68
@headitem Lisp symbol @tab C function
@item @clhs{f_mk_ar.htm,make-array} @tab cl_object cl_make_array(cl_narg narg, cl_object dimension...)
......@@ -223,7 +223,7 @@ Common Lisp and C equivalence
@item @clhs{f_adju_1.htm,adjustable-array-p} @tab cl_object cl_adjustable_array_p(cl_object array)
@item @clhs{f_aref.htm,aref} @tab cl_object cl_aref(cl_narg narg, cl_object array, ...)
@item @clhs{f_ar_dim.htm,array-dimension} @tab cl_object cl_array_dimension(cl_object array, cl_object index)
@item @clhs{f_ar_d_1.htm,array-dimensions} @tab cl_object cl_array_dimension(cl_object array)
@item @clhs{f_ar_d_1.htm,array-dimensions} @tab cl_object cl_array_dimensions(cl_object array)
@item @clhs{f_ar_ele.htm,array-element-type} @tab cl_object cl_array_element_type(cl_object array)
@item @clhs{f_ar_has.htm,array-has-fill-pointer-p} @tab cl_object cl_array_has_fill_pointer_p(cl_object array)
@item @clhs{f_ar_dis.htm,array-displacement} @tab cl_object cl_array_displacement(cl_object array)
......@@ -255,4 +255,6 @@ Common Lisp and C equivalence
@item @clhs{f_bt_and.htm,bit-orc2} @tab cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)
@item @clhs{f_bt_and.htm,bit-xor} @tab cl_object cl_bit_xor(cl_narg narg, cl_object array1, cl_object array2, ...)
@item @clhs{f_bt_and.htm,bit-not} @tab cl_object cl_bit_not(cl_narg narg, cl_object array, ...)
@item @clhs{f_bt_vec.htm,bit-vector-p} @tab cl_object cl_bit_vector_p(cl_object object)
@item @clhs{f_smp_bt.htm,simple-bit-vector-p} @tab cl_object cl_simple_bit_vector_p(cl_object object)
@end multitable
......@@ -55,8 +55,7 @@ Note that @code{#\Linefeed} is synonymous with @code{#\Newline} and thus is a me
@node Characters - Newline characters
@subsection @code{#\Newline} characters
Internally, ECL represents the @code{#\Newline} character by a single code. However, when using external formats, ECL may parse character pairs as a single @code{#\Newline}, and vice versa, use multiple characters to represent a single @code{#\Newline}.
@c TODO: add an @xref to Stream -> External formats once it's written
Internally, ECL represents the @code{#\Newline} character by a single code. However, when using external formats, ECL may parse character pairs as a single @code{#\Newline}, and vice versa, use multiple characters to represent a single @code{#\Newline}, @pxref{Streams - External formats}.
@node Characters - C Reference
......@@ -86,13 +85,14 @@ For your code to be portable and future proof, use both types to really express
@cppindex ECL_CODE_CHAR
@cppindex ECL_CHAR_CODE
@cppindex ecl_char_code
@cppindex ecl_base_char_code
Creating and extracting characters from Lisp objects
@subsubheading Functions
@deftypefun cl_object ECL_CODE_CHAR (ecl_character @var{code});
@end deftypefun
@deftypefun ecl_character ECL_CHAR_CODE (cl_object @var{o});
@end deftypefun
@deftypefun cl_object ecl_char_code (ecl_character @var{code});
@deftypefun ecl_character ecl_char_code (cl_object @var{o});
@end deftypefun
@deftypefun ecl_base_char ecl_base_char_code (cl_object @var{o});
@end deftypefun
......@@ -113,11 +113,11 @@ C predicates for Lisp characters
@end deftypefun
@deftypefun bool ecl_alpha_char_p (ecl_character @var{c});
@end deftypefun
@deftypefun bool ecl_alphanumeric_p (ecl_character @var{c});
@deftypefun bool ecl_alphanumericp (ecl_character @var{c});
@end deftypefun
@deftypefun bool ecl_graphic_char_p (ecl_character @var{c});
@end deftypefun
@deftypefun bool ecl_digit_p (ecl_character @var{c});
@deftypefun bool ecl_digitp (ecl_character @var{c});
@end deftypefun
@deftypefun bool ecl_standard_char_p (ecl_character @var{c});
@end deftypefun
......@@ -147,7 +147,7 @@ These functions check or change the case of a character. Note that in a Unicode
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Lisp symbol @tab C function
@item @clhs{f_chareq.htm,char=} @tab cl_object cl_charE(cl_narg narg, ...)
......@@ -180,4 +180,5 @@ Common Lisp and C equivalence
@item @clhs{f_code_c.htm,code-char} @tab cl_object cl_code_char(cl_object code)
@item @clhs{f_char_n.htm,char-name} @tab cl_object cl_char_name(cl_object character)
@item @clhs{f_name_c.htm,name-char} @tab cl_object cl_name_char(cl_object name)
@item @clhs{v_char_c.htm,char-code-limit} @tab ECL_CHAR_CODE_LIMIT
@end multitable
@node Conditions
@section Conditions
@menu
* Conditions - C Reference::
@end menu
@node Conditions - C Reference
@subsection C Reference
@cppindex ECL_HANDLER_CASE
@cppindex ECL_RESTART_CASE
......@@ -26,7 +21,7 @@ ECL_HANDLER_CASE_BEGIN(env,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:
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:
@verbatim
cl_object error = ecl_make_symbol("ERROR","CL");
......@@ -71,19 +66,19 @@ ECL_RESTART_CASE_BEGIN(the_env, cl_list(2, abort, use_value)) {
/* 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 (ABORT) is invoked */
/* This code is executed when the 2nd restart (USE-VALUE) is invoked */
output = ECL_CAR(args);
} ECL_RESTART_CASE_END;
@end verbatim
@end deffn
@subsubsection Conditions C dictionary
@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 cl_object cl_break()
@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, ...)
......@@ -91,19 +86,19 @@ Common Lisp and C equivalence
@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_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_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_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 cl_object cl_signal(cl_narg narg, cl_object datum, ...)
@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 cl_object cl_warn(cl_narg narg, cl_object datum, ...)
@item @clhs{f_warn.htm,warn} @tab [Only in Common Lisp]
@end multitable
@node Conses
@section Conses
@menu
* Conses - C Reference::
@end menu
@node Conses - C Reference
@subsection C Reference
@subsubsection Accessors
@cppindex ECL_CONS_CAR
@cppindex ECL_CONS_CDR
@cppindex _ecl_car
@cppindex _ecl_cdr
Accessing the elements of conses
@subsubheading Functions
@deftypefun cl_object ECL_CONS_CAR (cl_object @var{o})
@end deftypefun
@deftypefun cl_object ECL_CONS_CDR (cl_object @var{o})
@end deftypefun
@deftypefun cl_object _ecl_car (cl_object @var{o})
@end deftypefun
@deftypefun cl_object _ecl_cdr (cl_object @var{o})
@end deftypefun
@deftypefun cl_object _ecl_caar (cl_object @var{o})
@end deftypefun
@deftypefun cl_object _ecl_cadr (cl_object @var{o})
@end deftypefun
...
@subsubheading Description
These functions access the elements of objects of type cons
(@code{ECL_CONS_CAR} and @code{ECL_CONS_CDR}) or type list
(@code{_ecl_car}, @code{_ecl_cdr}, @code{_ecl_caar}, ...). They don't
check the type of their arguments.
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .30 .70
@headitem Lisp symbol @tab C function
@item @clhs{f_cons.htm,cons} @tab cl_object cl_cons(cl_object car, cl_object cdr)
......@@ -61,7 +81,7 @@ Common Lisp and C equivalence
@item @clhs{f_tree_e.htm,tree-equal} @tab cl_object cl_tree_equal(cl_narg narg, cl_object tree1, cl_object tree2, ...)
@item @clhs{f_cp_lis.htm,copy-list} @tab cl_object cl_copy_list(cl_object list)
@item @clhs{f_list_.htm,list} @tab cl_object cl_list(cl_narg narg, ...)
@item @clhs{f_list_.htm,list*} @tab cl_object cl_listA(cl_narg narg, ...)
@item @clhs{f_list_.htm,list*} @tab cl_object cl_listX(cl_narg narg, ...)
@item @clhs{f_list_l.htm,list-length} @tab cl_object cl_list_length(cl_object list)
@item @clhs{f_listp.htm,listp} @tab cl_object cl_listp(cl_object object)
@item @clhs{f_mk_lis.htm,make-list} @tab cl_object cl_make_list(cl_narg narg, cl_object size, ...)
......@@ -117,6 +137,6 @@ Common Lisp and C equivalence
@item @clhs{f_set_ex.htm,set-exclusive-or} @tab cl_object cl_set_exclusive_or(cl_narg narg, cl_object list1, cl_object list2, ...)
@item @clhs{f_sex_ex.htm,nset-exclusive-or} @tab cl_object cl_nset_exclusive_or(cl_narg narg, cl_object list1, cl_object list2, ...)
@item @clhs{f_subset.htm,subsetp} @tab cl_object cl_subsetp(cl_narg narg, cl_object list1, cl_object list2, ...)
@item @clhs{f_unionc.htm,union} @tab cl_object cl_union(cl_narg narg, cl_object list1, cl_object list2)
@item @clhs{f_unionc.htm,nunion} @tab cl_object cl_nunion(cl_narg narg, cl_object list1, cl_object list2)
@item @clhs{f_unionc.htm,union} @tab cl_object cl_union(cl_narg narg, cl_object list1, cl_object list2, ...)
@item @clhs{f_unionc.htm,nunion} @tab cl_object cl_nunion(cl_narg narg, cl_object list1, cl_object list2, ...)
@end multitable
......@@ -164,7 +164,7 @@ cl_object c = cl_cos(angle);
printf("\nThe cosine of PI is %g\n", ecl_double_float(c));
@end verbatim
The second example also involves some Mathematics, but now we are going to use the C function corresponding to @code{+}. As described in @ref{Numbers - Numbers C dictionary}, the C name for the plus operator is @code{cl_P} and has a signature @code{cl_object cl_P(cl_narg narg,...)}. Our example now reads as follows
The second example also involves some Mathematics, but now we are going to use the C function corresponding to @code{+}. As described in @ref{Numbers - ANSI dictionary}, the C name for the plus operator is @code{cl_P} and has a signature @code{cl_object cl_P(cl_narg narg,...)}. Our example now reads as follows
@verbatim
cl_object one = ecl_make_fixnum(1);
......@@ -274,7 +274,7 @@ cl_object my_plus(cl_narg narg, cl_object required1, ...)
ecl_va_start(varargs, required1, narg, 1);
while (narg > 1) {
cl_object other_value = ecl_va_arg(varargs);
required1 = ecl_plus(required1, other_value);
required1 = ecl_plus(required1, other_value);
}
ecl_va_end(varargs);
ecl_return1(env, required1);
......@@ -408,7 +408,6 @@ The utility of this construct is limited, for it only protects against nonlocal
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function or constant
@item @clhs{f_apply.htm,apply} @tab cl_object cl_apply(cl_narg narg, cl_object function, ...)
......
......@@ -24,9 +24,8 @@ As specified in ANSI @bibcite{ANSI} this function outputs the internal represent
ECL only has a particular difference: it has two different compilers, one based on bytecodes and one based on the C language. The output will thus depend on the arguments and on which compiler is active at the moment in which this function is run.
@itemize
@item If the argument is a bytecompiled function, the output will be bytecodes.
@item If the argument is a lambda form, it will be processed by the active compiler and the appropriate output (bytecodes or C) will be shown.
@item If the argument is a C-compiled form, ECL will retrieve its original lambda form and process it with the currently active compiler.
@item If the argument is a bytecompiled function or a lambda form, it will be processed by the active compiler and the appropriate output (bytecodes or C) will be shown.
@item If the argument is a C-compiled form, disassembling the function by showing its C source code is not possible, since that would require saving not only the lambda form of the function, but also the precise configuration of the compiler when the function was compiled. Hence no output will be shown.
@end itemize
@end defun
......@@ -36,7 +35,7 @@ Follow the execution of functions
(trace @var{function-name*})
@table @var
@item function-name
@{@var{symbol}|@var{symbol}[@var{option form}]*)@}
@{@var{symbol} | (@var{symbol} [ @var{option} @var{form} ]*)@}
@item symbol
A symbol which is bound to a function in the global environment. Not evaluated.
@item option
......@@ -54,7 +53,7 @@ Not that if the function is called from another function compiled in the same fi
trace returns a name list of those functions that were traced by the call to trace. If no @var{function-name} is given, @code{trace} simply returns a name list of all the currently traced functions.
Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp @emph{form} accompanying the option is evaluated in an environment where @var{sys::arglist} is contains the list of arguments to the function.
Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp @emph{form} accompanying the option is evaluated in an environment where @var{sys::args} contains the list of arguments to the function.
The following options are defined:
@table @code
......@@ -69,8 +68,49 @@ In addition to the usual printout, the result of evaluating @var{form} is printe
@end table
@end defmac
See also the following example:
@exindex @code{trace} usage
@example
> (defun abc (x)
(if (>= x 10)
x
(abc (+ x (abc (1+ x))))))
> (trace abc)
> (abc 9)
1> (ABC 9)
| 2> (ABC 10)
| <2 (ABC 10)
| 2> (ABC 19)
| <2 (ABC 19)
<1 (ABC 19)
19
> (untrace abc)
(ABC)
;; Break if the first argument of the function is greater than 10
> (trace (abc :break (>= (first si::args) 10)))
((ABC :BREAK (>= (FIRST SI::ARGS) 10)))
> (abc 9)
1> (ABC 9)
| 2> (ABC 10)
Condition of type: SIMPLE-CONDITION
tracing ABC
Available restarts:
1. (CONTINUE) Return from BREAK.
2. (RESTART-TOPLEVEL) Go back to Top-Level REPL.
Broken at ABC. In: #<process TOP-LEVEL 0x1842f80>.
>>
@end example
@node Environment - C Reference
@subsection C Reference
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
......@@ -85,12 +125,12 @@ Common Lisp and C equivalence
@item @clhs{f_apropo.htm,apropos-list} @tab cl_object cl_apropos_list(cl_narg narg, cl_object string, ...)
@item @clhs{f_descri.htm,describe} @tab cl_object cl_describe(cl_narg narg, cl_object object, ...)
@item @clhs{f_desc_1.htm,describe-object} @tab [Only in Common Lisp]
@item @clhs{f_get_in.htm,get-internal-real-time} @tab cl_object cl_get_internal_real_time()
@item @clhs{f_get__1.htm,get-internal-run-time} @tab cl_object cl_get_internal_run_time()
@item @clhs{f_get_in.htm,get-internal-real-time} @tab cl_object cl_get_internal_real_time(void)
@item @clhs{f_get__1.htm,get-internal-run-time} @tab cl_object cl_get_internal_run_time(void)
@item @clhs{f_disass.htm,disassemble} @tab [Only in Common Lisp]
@item @clhs{f_docume.htm,documentation} @tab [Only in Common Lisp]
@item @clhs{f_room.htm,room} @tab cl_object cl_room(cl_narg narg, ...)
@item @clhs{f_ed.htm,ed} @tab cl_object cl_ed(cl_narg narg, ...)
@item @clhs{f_room.htm,room} @tab [Only in Common Lisp]
@item @clhs{f_ed.htm,ed} @tab [Only in Common Lisp]
@item @clhs{f_inspec.htm,inspect} @tab cl_object cl_inspect(cl_object object)
@item @clhs{f_dribbl.htm,dribble} @tab cl_object cl_dribble(cl_narg narg, ...)
@item @clhs{f_lisp_i.htm,lisp-implementation-type} @tab cl_object cl_lisp_implementation_type(void)
......@@ -102,5 +142,5 @@ Common Lisp and C equivalence
@item @clhs{f_mach_v.htm,machine-version} @tab cl_object cl_machine_version()
@item @clhs{f_sw_tpc.htm,software-type} @tab cl_object cl_software_type()
@item @clhs{f_sw_tpc.htm,software-version} @tab cl_object cl_software_version()
@item @clhs{f_user_h.htm,user-homedir-pathname} @tab cl_object cl_user_homedir_pathname()
@item @clhs{f_user_h.htm,user-homedir-pathname} @tab cl_object cl_user_homedir_pathname(cl_narg narg, ...)
@end multitable
......@@ -53,11 +53,12 @@ not see the redefinition.
@end float
A bit more critical is the value of @code{SAFETY} because as shown in
@ref{tab:optimize-safety}, it may affect the safety checks generated by
the compiler. In particular, in some circumstances the compiler may
@ref{tab:optimize-safety}, it may affect the safety checks generated
by the compiler. In particular, in some circumstances the compiler may
assume that the arguments to a function are properly typed. For
instance, if you compile with a low value of @code{SAFETY}, and invoke
@code{RPLACA}, the consequences are unspecified.
@code{RPLACA} with an object which is not a list, the consequences are
unspecified.
@float Table, tab:optimize-safety
@caption{Behavior for different levels of @code{SAFETY}}
......@@ -86,7 +87,7 @@ instance, if you compile with a low value of @code{SAFETY}, and invoke
@tab N
@tab N
@item We believe types defined before compiling a file not change before the compiled code is loaded.
@item We believe types defined before compiling a file do not change before the compiled code is loaded.
@tab Y
@tab Y
@tab N
......@@ -127,3 +128,17 @@ using the function or macro above. This pointer can be used for a
variety of tasks, such as defining special variable bindings,
controlling interrupts, retrieving function output values, etc.
@end deftypefn
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_cmp.htm,compile} @tab [Only in Common Lisp]
@item @clhs{f_eval.htm,eval} @tab cl_object cl_eval (cl_object form) - @strong{DEPRECATED, @pxref{si_safe_eval}}
@item @clhs{f_mexp_.htm,macroexpand} @tab cl_object cl_macroexpand(cl_narg narg, cl_object form, ...)
@item @clhs{f_mexp_.htm,macroexpand-1} @tab cl_object cl_macroexpand_1(cl_narg narg, cl_object form, ...)
@item @clhs{f_procla.htm,proclaim} @tab [Only in Common Lisp]
@item @clhs{f_specia.htm,special-operator-p} @tab cl_object cl_special_operator_p(cl_object form)
@item @clhs{f_consta.htm,constantp} @tab cl_object cl_constantp (cl_narg narg, cl_object arg, ...)
@end multitable
......@@ -77,10 +77,10 @@ The matching rules in Common Lisp and ECL are simple but have some unintuitive c
@node Filenames - C Reference
@subsection C Reference
@subsubsection Filenames C dictionary
@subsubsection ANSI dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .30 .70
@headitem Lisp symbol @tab C function
@item @clhs{f_namest.htm,directory-namestring} @tab cl_object cl_directory_namestring(cl_object pathname)
......
......@@ -8,12 +8,14 @@
@node Files - Dictionary
@subsection Dictionary
@subsubsection @code{DIRECTORY}
@lspindex directory
@defun directory pathspec
This function does not have any additional arguments other than the ones described in ANSI @bibcite{ANSI}. To list files and directories, it follows the rules for matching pathnames described in @ref{Filenames - Wild pathnames and matching}. In short, you have the following practical examples:
@float Table, tab:examples-using-directory
@caption{Examples of using @code{DIRECTORY}}
@caption{Examples of using @code{directory}}
@multitable @columnfractions .25 .75
@headitem Argument @tab Meaning
@item @code{"/home/jlr/*.*"} @tab List all files in directory @code{/home/jlr/} Note that it lists only files, not directories!
......@@ -22,12 +24,26 @@ This function does not have any additional arguments other than the ones describ
@item @code{"/home/jlr/**/*.*"} @tab List all files in all directories contained in @code{/home/jlr/}, recursively. Nested directories are navigated.
@end multitable
@end float
@end defun
@defun rename-file filespec new-name &key (if-exists :error)
In addition to the arguments described in ANSI @bibcite{ANSI}, the @code{rename-file} function in ECL has an @code{:if-exists} keyword argument that specifies what happens when a file with the new name already exists. Valid values of this argument are:
@multitable @columnfractions .25 .75
@headitem Argument @tab Behaviour of the @code{rename-file} function
@item @code{:error} @tab Signal an error
@item @code{:supersede}, @code{t} @tab Overwrite the existing file
@item @code{nil} @tab Don't overwrite the existing file, don't signal an error
@end multitable
@end defun
@node Files - C Reference
@subsection C Reference
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_del_fi.htm,delete-file} @tab cl_object cl_delete_file(cl_object filespec)
......@@ -37,6 +53,6 @@ Common Lisp and C equivalence
@item @clhs{f_file_e.htm,file-error-pathname} @tab [Only in Common Lisp]
@item @clhs{f_file_w.htm,file-write-date} @tab cl_object cl_file_write_date(cl_object pathspec)
@item @clhs{f_probe_.htm,probe-file} @tab cl_object cl_probe_file(cl_object pathspec)
@item @clhs{f_rn_fil.htm,rename-file} @tab cl_object cl_rename_file(cl_object filespec, cl_object new_name)
@item @clhs{f_rn_fil.htm,rename-file} @tab cl_object cl_rename_file(cl_narg narg, cl_object filespec, cl_object new_name, ...)
@item @clhs{f_tn.htm,truename} @tab cl_object cl_truename(cl_object filespec)
@end multitable
......@@ -2,17 +2,21 @@
@section Hash tables
@menu
* Hash tables - Extensions::
* Hash tables - C Reference::
@end menu
@subheading Weakness in hash tables
@node Hash tables - Extensions
@subsection Extensions
@subsubsection Weakness in hash tables
@cindex Weak hash tables
@ftindex ECL-WEAK-HASH
Weak hash tables allow the garbage collector to reclaim some of the
entries if they are not strongly referenced elsewhere. ECL supports
four kinds of weakness in hash tables: @t{:key}, @t{:value},
@t{key-and-value} and @t{key-or-value}.
@t{:key-and-value} and @t{:key-or-value}.
To make hash table weak, programmer has to provide @t{:weakness}
keyword argument to @t{cl:make-hash-table} with the desired kind of
......@@ -29,13 +33,13 @@ Returns type of the hash table weakness. Possible return values are:
@t{:key}, @t{:value}, @t{:key-and-value}, @t{:key-or-value} or @t{NIL}.
@end deffn
@subheading Thread-safe hash tables
@subsubsection Thread-safe hash tables
@cindex Synchronized hash tables
@cindex Thread-safe hash tables
By default ECL doesn't protect hash tables from simultaneous access
for performance reasons. Read and write access may is synchronized
when @t{synchronized} keyword argument to @t{make-hash-table} is
when @t{:synchronized} keyword argument to @t{make-hash-table} is
@t{T} - @code{(make-hash-table :synchronized t)}.
@lspindex hash-table-synchronized-p
......@@ -43,7 +47,7 @@ when @t{synchronized} keyword argument to @t{make-hash-table} is
Predicate answering whenever hash table is synchronized or not.
@end deffn
@subheading Hash tables serialization
@subsubsection Hash tables serialization
@cindex Hash table serialization
@lspindex hash-table-content
......@@ -59,7 +63,7 @@ table may have some content already, but conflicting keys will be
overwritten.
@end deffn
@subheading Example
@subsubsection Example
@exindex Hash table extensions example
@lisp
CL-USER> (defparameter *ht*
......@@ -84,8 +88,10 @@ CL-USER> (ext:hash-table-content *ht*)
@node Hash tables - C Reference
@subsection C Reference
@subsubsection Hash tables C dictionary
@subsubsection ANSI dictionary
Common Lisp and C equivalence
@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_clrhas.htm,clrhash} @tab cl_object cl_clrhash(cl_object hash_table)
......@@ -93,7 +99,7 @@ Common Lisp and C equivalence
@item @clhs{f_hash_1.htm,hash-table-count} @tab cl_object cl_hash_table_count(cl_object hash_table)
@item @clhs{f_hash_t.htm,hash-table-p} @tab cl_object cl_hash_table_p(cl_object hash_table)
@item @clhs{f_hash_2.htm,hash-table-rehash-size} @tab cl_object cl_hash_table_rehash_size(cl_object hash_table)
@item @clhs{f_hash_3.htm,hash-table-rehash-threshold} @tab cl_object cl_hash_table_rehash_thresholdy(cl_object hash_table)
@item @clhs{f_hash_3.htm,hash-table-rehash-threshold} @tab cl_object cl_hash_table_rehash_threshold(cl_object hash_table)
@item @clhs{f_hash_4.htm,hash-table-size} @tab cl_object cl_hash_table_size(cl_object hash_table)
@item @clhs{f_hash_5.htm,hash-table-test} @tab cl_object cl_hash_table_test(cl_object hash_table)
@item @clhs{f_mk_has.htm,make-hash-table} @tab cl_object cl_make_hash_table(cl_narg narg, ...)
......
......@@ -26,7 +26,7 @@ ECL supports all of the Common Lisp numeric tower, which is shown in @ref{tab:nu
@item long-float @tab Either equivalent to double-float, or a 96/128 bits IEEE floating point number (long double in C/C++).
@item rational @tab An alias for (or integer ratio)
@item float @tab An alias for (or single-float double-float short-float long-float)
@item real @tab An alias for (or real integer float)
@item real @tab An alias for (or rational float)
@item complex @tab Complex number made of two real numbers of the above mentioned types.
@end multitable
@end float
......@@ -43,7 +43,7 @@ Control the signaling of the floating point exceptions
@subsubheading Synopsis
@table @var
@item condition
one of @code{t}, @code{division-by-zero}, @code{floating-point-overflow}, @code{floating-point-underflow}, @code{floating-point-invalid-operation} or @code{floating-point-inexact}
a symbol - one of @code{t}, @code{division-by-zero}, @code{floating-point-overflow}, @code{floating-point-underflow}, @code{floating-point-invalid-operation} or @code{floating-point-inexact}
@item flag
a generalized boolean
@end table
......@@ -94,7 +94,7 @@ Predicates to test if @var{x} is infinite or NaN.
* Numbers - Number constructors::
* Numbers - Number accessors::
* Numbers - Number coercion::
* Numbers - Numbers C dictionary::
* Numbers - ANSI dictionary::
@end menu
@node Numbers - Number C types
......@@ -108,8 +108,8 @@ Numeric C types understood by ECL
@item float @tab short-float, single-float
@item double @tab double-float
@item long double (*) @tab long-float @tab ECL_LONG_FLOAT @tab :long-float
@item uint8_t @tab (unsigned-byte 8)
@item int8_t @tab (signed-byte 8)
@item uint8_t @tab (unsigned-byte 8) @tab ecl_uint8_t
@item int8_t @tab (signed-byte 8) @tab ecl_int8_t
@item uint16_t @tab (unsigned-byte 16) @tab ecl_uint16_t @tab :uint16-t
@item int16_t @tab (signed-byte 16) @tab ecl_int16_t @tab :int16-t
@item uint32_t @tab (unsigned-byte 32) @tab ecl_uint32_t @tab :uint32-t
......@@ -271,19 +271,18 @@ Checked conversion from Lisp types to C numbers
@subsubheading Description
These functions and macros convert a Lisp object to the corresponding C number type. The conversion is done through a coercion process which may signal an error if the argument does not fit the expected type.
@node Numbers - Numbers C dictionary
@subsubsection Numbers C dictionary
@node Numbers - ANSI dictionary
@subsubsection ANSI dictionary
Common Lisp and C equivalence
@subsubheading Synopsis
@multitable @columnfractions .30 .70
@headitem Lisp symbol @tab C function
@item @clhs{f_eq_sle.htm,=} @tab cl_object cl_E()
@item @clhs{f_eq_sle.htm,/=} @tab cl_object cl_NE()
@item @clhs{f_eq_sle.htm,<} @tab cl_object cl_L()
@item @clhs{f_eq_sle.htm,>} @tab cl_object cl_G()
@item @clhs{f_eq_sle.htm,<=} @tab cl_object cl_LE()
@item @clhs{f_eq_sle.htm,>=} @tab cl_object cl_GE()
@item @clhs{f_eq_sle.htm,=} @tab cl_object cl_E(cl_narg narg, ...)
@item @clhs{f_eq_sle.htm,/=} @tab cl_object cl_NE(cl_narg narg, ...)
@item @clhs{f_eq_sle.htm,<} @tab cl_object cl_L(cl_narg narg, ...)
@item @clhs{f_eq_sle.htm,>} @tab cl_object cl_G(cl_narg narg, ...)
@item @clhs{f_eq_sle.htm,<=} @tab cl_object cl_LE(cl_narg narg, ...)
@item @clhs{f_eq_sle.htm,>=} @tab cl_object cl_GE(cl_narg narg, ...)
@item @clhs{f_max_m.htm,max} @tab cl_object cl_max(cl_narg narg, ...)
@item @clhs{f_max_m.htm,min} @tab cl_object cl_min(cl_narg narg, ...)
@item @clhs{f_minusp.htm,minusp} @tab cl_object cl_minusp(cl_object real)
......@@ -302,7 +301,7 @@ Common Lisp and C equivalence
@item @clhs{f_sin_c.htm,tan} @tab cl_object cl_tan(cl_object radians)
@item @clhs{f_asin_.htm,asin} @tab cl_object cl_asin(cl_object number)
@item @clhs{f_asin_.htm,acos} @tab cl_object cl_acos(cl_object number)
@item @clhs{f_asin_.htm,atan} @tab cl_object cl_atan(cl_object number)
@item @clhs{f_asin_.htm,atan} @tab cl_object cl_atan(cl_narg narg, cl_object number1, ...)
@item @clhs{c_number.htm,sinh} @tab cl_object cl_sinh(cl_object number)
@item @clhs{c_number.htm,cosh} @tab cl_object cl_cosh(cl_object number)
@item @clhs{c_number.htm,tanh} @tab cl_object cl_tanh(cl_object number)
......@@ -313,8 +312,8 @@ Common Lisp and C equivalence
@item @clhs{f_pl.htm,+} @tab cl_object cl_P(cl_narg narg, ...)
@item @clhs{f__.htm,-} @tab cl_object cl_M(cl_narg narg, cl_object number, ...)
@item @clhs{f_sl.htm,/} @tab cl_object cl_N(cl_narg narg, cl_object number, ...)
@item @clhs{f_1pl_1_.htm,1+} @tab cl_object cl_1P()
@item @clhs{f_1pl_1_.htm,1-} @tab cl_object cl_1M()
@item @clhs{f_1pl_1_.htm,1+} @tab cl_object cl_1P(cl_object number)
@item @clhs{f_1pl_1_.htm,1-} @tab cl_object cl_1M(cl_object number)
@item @clhs{f_abs.htm,abs} @tab cl_object cl_abs(cl_object number)
@item @clhs{f_evenpc.htm,evenp} @tab cl_object cl_evenp(cl_object integer)
@item @clhs{f_evenpc.htm,oddp} @tab cl_object cl_oddp(cl_object integer)
......@@ -380,7 +379,7 @@ Common Lisp and C equivalence
@item @clhs{f_dec_fl.htm,float-digits} @tab cl_object cl_float_digits(cl_object float)
@item @clhs{f_dec_fl.htm,float-precision} @tab cl_object cl_float_precision(cl_object float)
@item @clhs{f_dec_fl.htm,integer-decode-float} @tab cl_object cl_integer_decode_float(cl_object float)
@item @clhs{f_float.htm,float} @tab cl_object cl_float(cl_narg narg, cl_object number)
@item @clhs{f_float.htm,float} @tab cl_object cl_float(cl_narg narg, cl_object number, ...)
@item @clhs{f_floatp.htm,floatp} @tab cl_object cl_floatp(cl_object object)
@item @clhs{f_arithm.htm,arithmetic-error-operands} @tab [Only in Common Lisp]
@item @clhs{f_arithm.htm,arithmetic-error-operation} @tab [Only in Common Lisp]
......
@node Objects
@section Objects
@menu
* Objects - C Reference::
@end menu
@node Objects - C Reference
@subsection C Reference
@subsubsection ANSI Dictionary
......
......@@ -8,8 +8,8 @@
@bibcite{ANSI}. All functions and macros are expected to behave as
described in that document and in the HyperSpec @bibcite{HyperSpec}
which is the online version of @bibcite{ANSI}. In other words, the
Standard is the basic reference for Common Lisp and also for @ecl{}, and
this part of the manual just complements it, describing
Standard is the basic reference for Common Lisp and also for @ecl{},
and this part of the manual just complements it, describing
implementation-specific features such as:
@itemize
......
@node Packages
@section Packages
In @ref{tab:ECL-packages} we list all packages available in ECL. The nicknames are aliases for a package. Thus, @code{system:symbol} may be written as @code{sys:symbol} or @code{si:symbol}. The module field explains which library provides what package. For instance, the ASDF is obtained when loading the ASDF library with @code{(require 'asdf)}.
In @ref{tab:ECL-packages} we list all packages available in ECL. The
nicknames are aliases for a package. Thus, @code{system:symbol} may be
written as @code{sys:symbol} or @code{si:symbol}. The module field
explains which library provides what package. For instance, the ASDF
package is obtained when loading the ASDF library with @code{(require 'asdf)}.
@float Table, tab:ECL-packages
@caption{ECL packages}
......@@ -18,3 +22,35 @@ In @ref{tab:ECL-packages} we list all packages available in ECL. The nicknames a
@item @code{ASDF} @tab @code{ } @tab @code{ASDF} @tab System definition file with ECL customizations.
@end multitable
@end float
@subsection C Reference
@subsubsection ANSI Dictionary
Common Lisp and C equivalence
@multitable @columnfractions .3 .7
@headitem Lisp symbol @tab C function
@item @clhs{f_export.htm,export} @tab cl_object cl_export(cl_narg narg, cl_object symbols, ...)
@item @clhs{f_find_s.htm,find-symbol} @tab cl_object cl_find_symbol(cl_narg narg, cl_object string, ...)
@item @clhs{f_find_p.htm,find-package} @tab cl_object cl_find_package(cl_object name)
@item @clhs{f_find_a.htm,find-all-symbols} @tab cl_object cl_find_all_symbols(cl_object string)
@item @clhs{f_import.htm,import} @tab cl_object cl_import(cl_narg narg, cl_object symbols, ...)
@item @clhs{f_list_a.htm,list-all-packages} @tab cl_object cl_list_all_packages(void)
@item @clhs{f_rn_pkg.htm,rename-package} @tab cl_object cl_rename_package(cl_narg narg, cl_object package, cl_object new_name, ...)
@item @clhs{f_shadow.htm,shadow} @tab cl_object cl_shadow(cl_narg narg, cl_object symbols, ...)
@item @clhs{f_shdw_i.htm,shadowing-import} @tab cl_object cl_shadowing_import(cl_narg narg, cl_object symbols, ...)
@item @clhs{f_del_pk.htm,delete-package} @tab cl_object cl_delete_package(cl_object package)
@item @clhs{f_mk_pkg.htm,make-package} @tab cl_object cl_make_package(cl_narg narg, cl_object package_name, ...)
@item @clhs{f_unexpo.htm,unexport} @tab cl_object cl_unexport(cl_narg narg, cl_object symbols, ...)
@item @clhs{f_uninte.htm,unintern} @tab cl_object cl_unintern(cl_narg narg, cl_object symbol, ...)
@item @clhs{f_unuse_.htm,unuse-package} @tab cl_object cl_unuse_package(cl_narg narg, cl_object package, ...)
@item @clhs{f_use_pk.htm,use-package} @tab cl_object cl_use_package(cl_narg narg, cl_object package, ...)
@item @clhs{f_intern.htm,intern} @tab cl_object cl_intern(cl_narg narg, cl_object string, ...)
@item @clhs{f_pkg_na.htm,package-name} @tab cl_object cl_package_name(cl_object package)
@item @clhs{f_pkg_ni.htm,package-nicknames} @tab cl_object cl_package_nicknames(cl_object package)
@item @clhs{f_pkg_sh.htm,package-shadowing-symbols} @tab cl_object cl_package_shadowing_symbols(cl_object package)
@item @clhs{f_pkg_us.htm,package-use-list} @tab cl_object cl_package_use_list(cl_object package)
@item @clhs{f_pkg__1.htm,package-used-by-list} @tab cl_object cl_package_used_by_list(cl_object package)
@item @clhs{f_pkgp.htm,packagep} @tab cl_object cl_packagep(cl_object object)
@item @clhs{f_pkg_er.htm,package-error-package} @tab [Only in Common Lisp]
@end multitable