From 24e3407010d9f17bd996ac43ea450fae2e4f49d8 Mon Sep 17 00:00:00 2001 From: Tomek Kurcz Date: Wed, 6 Sep 2017 13:37:56 +0200 Subject: [PATCH] texinfo: Add C/C++ and CL indexes --- src/doc/new-doc/extensions/memory.txi | 4 +++ src/doc/new-doc/extensions/signals.txi | 2 ++ src/doc/new-doc/standards/arrays.txi | 19 ++++++++++-- src/doc/new-doc/standards/characters.txi | 31 ++++++++++++++++--- src/doc/new-doc/standards/conditions.txi | 2 ++ .../standards/data_and_control_flow.txi | 25 ++++++++++++++- src/doc/new-doc/standards/environment.txi | 6 ++-- src/doc/new-doc/standards/streams.txi | 3 ++ src/doc/new-doc/standards/strings.txi | 13 ++++++-- src/doc/new-doc/standards/symbols.txi | 2 ++ .../new-doc/standards/types_and_classes.txi | 2 ++ src/doc/new-doc/user-guide/embedding.txi | 12 +++++++ 12 files changed, 108 insertions(+), 13 deletions(-) diff --git a/src/doc/new-doc/extensions/memory.txi b/src/doc/new-doc/extensions/memory.txi index 661f046c0..0dba2d044 100644 --- a/src/doc/new-doc/extensions/memory.txi +++ b/src/doc/new-doc/extensions/memory.txi @@ -44,6 +44,10 @@ Beginning with version 9.2.1, ECL operates a tighter control of the resources it The customizable limits are listed in @ref{tab:mem-limits}, but they need a careful description. +@lspindex ext:heap-size +@lspindex ext:c-stack +@lspindex ext:binding-stack +@lspindex ext:lisp-stack @itemize @item @code{ext:heap-size} limits the total amount of memory which is available for lisp objects. This is the memory used when you create conses, arrays, structures, etc. diff --git a/src/doc/new-doc/extensions/signals.txi b/src/doc/new-doc/extensions/signals.txi index dd9c437c9..980df082b 100644 --- a/src/doc/new-doc/extensions/signals.txi +++ b/src/doc/new-doc/extensions/signals.txi @@ -90,6 +90,8 @@ The other option is to let ECL handle signals itself. This would be safer when t @node Signals and Interrupts - Signals Reference @subsection Signals Reference +@lspindex ext:with-interrupts +@lspindex ext:without-interrupts @defmac ext:with-interrupts &body body Execute code with interrupts optionally enabled. diff --git a/src/doc/new-doc/standards/arrays.txi b/src/doc/new-doc/standards/arrays.txi index 501ac24b9..0fac0e315 100644 --- a/src/doc/new-doc/standards/arrays.txi +++ b/src/doc/new-doc/standards/arrays.txi @@ -1,5 +1,6 @@ @node Arrays @section Arrays +@cindex Arrays @node Arrays - Array limits @subsection Array limits @@ -44,7 +45,10 @@ Let us remark that some of these specialized types might not exist in your platf C types, limits and enumerations @subsubheading Constants and types - +@cppindex ECL_ARRAY_RANK_LIMIT +@cppindex ECL_ARRAY_DIMENSION_LIMIT +@cppindex ECL_ARRAY_TOTAL_LIMIT +@cppindex cl_elttype @defvr Constant ECL_ARRAY_RANK_LIMIT @end defvr @defvr Constant ECL_ARRAY_DIMENSION_LIMIT @@ -75,7 +79,8 @@ ECL uses also internally a set of constants to describe the different specialize To and from element types @subsubheading Functions - +@cppindex ecl_aet_to_symbol +@cppindex ecl_symbol_to_aet @deftypefun cl_object ecl_aet_to_symbol (cl_elttype @var{param}) @end deftypefun @deftypefun cl_elttype ecl_symbol_to_aet (cl_object @var{type}) @@ -90,6 +95,9 @@ The functions may signal an error if any of the arguments is an invalid C or Lis Creating array and vectors @subsubheading Functions +@cppindex ecl_alloc_simple_vector +@cppindex si_make_vector +@cppindex si_make_array @deftypefun cl_object ecl_alloc_simple_vector( cl_elttype element_type, cl_index length); @end deftypefun @deftypefun cl_object si_make_vector( cl_object element_type, cl_object length, cl_object adjustablep, cl_object fill_pointerp, cl_object displaced_to, cl_object displacement); @@ -149,6 +157,10 @@ cl_object a = si_make_array(dims, type, Cnil, /* adjustable */ @end verbatim @subsubsection Accessors +@cppindex ecl_aref +@cppindex ecl_aset +@cppindex ecl_aref1 +@cppindex ecl_aset1 Reading and writing array elements @subsubheading Functions @@ -172,6 +184,9 @@ The first argument to @code{ecl_aref} or @code{ecl_aset} is an array of any numb All functions above check that the index does not exceed the array bounds, that the values match the array element type and that the argument is an array (or a vector). If these conditions are not met, a type error is signaled. @subsubsection Array properties +@cppindex ecl_array_elttype +@cppindex ecl_array_rank +@cppindex ecl_array_dimension Array size, fill pointer, etc. @subsubheading Synopsis diff --git a/src/doc/new-doc/standards/characters.txi b/src/doc/new-doc/standards/characters.txi index 16aaa3d7e..d2b6e5e58 100644 --- a/src/doc/new-doc/standards/characters.txi +++ b/src/doc/new-doc/standards/characters.txi @@ -12,7 +12,8 @@ When using C characters we are actually relying on the char type of the C langua When no option is specified ECL builds with support for a larger character set, the Unicode 6.0 standard. This uses 24 bit large character codes, also known as @dfn{codepoints}, with a large database of character properties which include their nature (alphanumeric, numeric, etc), their case, their collation properties, whether they are standalone or composing characters, etc. @subsubsection Character types -If compiled without Unicode support, ECL all characters are implemented using 8-bit codes and the type @code{extended-char} is empty. If compiled with Unicode support, characters are implemented using 24 bits and the @code{extended-char} type covers characters above code 255. +@lspindex extended-char +If ECL is compiled without Unicode support, all characters are implemented using 8-bit codes and the type @code{extended-char} is empty. If compiled with Unicode support, characters are implemented using 24 bits and the @code{extended-char} type covers characters above code 255. @multitable @columnfractions .33 .33 .33 @headitem Type @tab With Unicode @tab Without Unicode @item standard-char @tab #\Newline,32-126 @tab #\Newline,32-126 @@ -21,6 +22,7 @@ If compiled without Unicode support, ECL all characters are implemented using 8- @end multitable @subsubsection Character names +@lspindex standard-char All characters have a name. For non-printing characters between 0 and 32, and for 127 we use the ordinary ASCII names. Characters above 127 are printed and read using hexadecimal Unicode notation, with a U followed by 24 bit hexadecimal number, as in @code{U0126}. @float Table, tab:example-char-names @@ -55,6 +57,8 @@ Internally, ECL represents the @code{#\Newline} character by a single code. Howe @subsection C Reference @subsubsection C types +@cppindex ecl_base_char +@cppindex ecl_character C character types @subsubheading Type names @multitable {aaaaaaaaaaaaa} {aaaaaaaaa} @@ -62,15 +66,20 @@ C character types @item ecl_base_char @tab base-char @end multitable @subsubheading Description + ECL defines two C types to hold its characters: @code{ecl_base_char} and @code{ecl_character}. - When ECL is built without Unicode, they both coincide and typically match @code{unsigned char}, to cover the 256 codes that are needed. - - When ECL is built with Unicode, the two types are no longer equivalent, with @code{ecl_character} being larger. +@itemize +@item When ECL is built without Unicode, they both coincide and typically match @code{unsigned char}, to cover the 256 codes that are needed. +@item When ECL is built with Unicode, the two types are no longer equivalent, with @code{ecl_character} being larger. +@end itemize For your code to be portable and future proof, use both types to really express what you intend to do. @subsubsection Constructors +@cppindex ECL_CODE_CHAR +@cppindex ECL_CHAR_CODE +@cppindex ecl_char_code Creating and extracting characters from Lisp objects @subsubheading Functions @deftypefun cl_object ECL_CODE_CHAR (ecl_character @var{code}); @@ -85,8 +94,15 @@ Creating and extracting characters from Lisp objects These functions and macros convert back and forth from C character types to Lisp. The macros @code{ECL_CHAR_CODE} and @code{ECL_CODE_CHAR} perform this coercion without checking the arguments. The functions @code{ecl_char_code} and @code{ecl_base_char_code}, on the other hand, verify that the argument has the right type and signal an error otherwise. @subsubsection Predicates +@cppindex ecl_base_char_p +@cppindex ecl_alpha_char_p +@cppindex ecl_alphanumeric_p +@cppindex ecl_graphic_char_p +@cppindex ecl_digit_p +@cppindex ecl_standard_char_p C predicates for Lisp characters @subsubheading Functions + @deftypefun bool ecl_base_char_p (ecl_character @var{c}); @end deftypefun @deftypefun bool ecl_alpha_char_p (ecl_character @var{c}); @@ -103,6 +119,11 @@ C predicates for Lisp characters These functions are equivalent to their Lisp equivalents but return C booleans. @subsubsection Character case +@cppindex ecl_upper_case_p +@cppindex ecl_lower_case_p +@cppindex ecl_both_case_p +@cppindex ecl_char_downcase +@cppindex ecl_char_upcase C functions related to the character case @subsubheading Functions @deftypefun bool ecl_upper_case_p (ecl_character @var{c}); @@ -116,7 +137,7 @@ C functions related to the character case @deftypefun ecl_character ecl_char_upcase (ecl_character @var{c}); @end deftypefun @subsubheading Description -These functions check or change the case of a character. Note that in an Unicode context, the output of these functions might not be accurate (for instance when the uppercase character has two or more codepoints). +These functions check or change the case of a character. Note that in a Unicode context, the output of these functions might not be accurate (for instance when the uppercase character has two or more codepoints). @subsubsection ANSI Dictionary Common Lisp and C equivalence diff --git a/src/doc/new-doc/standards/conditions.txi b/src/doc/new-doc/standards/conditions.txi index 9041cc62d..98f5fd157 100644 --- a/src/doc/new-doc/standards/conditions.txi +++ b/src/doc/new-doc/standards/conditions.txi @@ -3,6 +3,8 @@ @node Conditions - C Reference @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} 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 6750917a3..dad07b8e2 100644 --- a/src/doc/new-doc/standards/data_and_control_flow.txi +++ b/src/doc/new-doc/standards/data_and_control_flow.txi @@ -183,7 +183,8 @@ Another restriction of C and C++ is that functions can only take a limited numbe @subsection C Reference - +@cppindex ecl_bds_bind +@cppindex ecl_bds_push @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}); @@ -199,6 +200,8 @@ This macro or function is the equivalent of @clhs{s_let_l.htm,LET*} and @clhs{s_ 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 +@cppindex ecl_bds_unwind1 +@cppindex ecl_bds_unwind_n @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}); @@ -213,6 +216,7 @@ Every variable binding must undone when no longer needed. It is best practice to @end defun +@cppindex ecl_setq @deffn Macro ecl_setq (cl_env_ptr @var{cl_env}, cl_object @var{var}, cl_object @var{value}); C equivalent of setq @@ -222,6 +226,8 @@ Assigns @var{value} to the special variable denoted by the symbol @var{var}, in This function implements a variable assignment, not a variable binding. It is thus the equivalent of @clhs{s_setq.htm,setq}. @end deffn + +@cppindex ecl_symbol_value @defun ecl_symbol_value (cl_env_ptr @var{cl_env}, cl_object @var{var}); @subsubheading Description Retrieves the value of the special variable or constant denoted by the symbol @var{var}, in the Common Lisp environment @var{cl_env}. @@ -231,6 +237,11 @@ 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 + +@cppindex ecl_va_list +@cppindex ecl_va_start +@cppindex ecl_va_arg +@cppindex ecl_va_end @deffn Macro {typedef struct @{ ... @} ecl_va_list[1];} @end deffn @@ -273,6 +284,8 @@ The last statement before returning the output of the function is @code{ecl_va_e @end deftypefn +@cppindex ecl_nvalues +@cppindex ecl_nth_value @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}); @@ -309,6 +322,10 @@ The somewhat equivalent Common Lisp code: @end deftypefun +@cppindex ecl_return0 +@cppindex ecl_return1 +@cppindex ecl_return2 +@cppindex ecl_return3 @defun ecl_return0 (cl_env_ptr @var{cl_env}); @end defun @defun ecl_return1 (cl_env_ptr @var{cl_env}, cl_object @var{value1}); @@ -323,6 +340,8 @@ Returns @var{N} values from a C/C++ function in a way that a Common Lisp functio @end defun + +@cppindex ECL_BLOCK_BEGIN @deffn Macro ECL_BLOCK_BEGIN @verbatim ECL_BLOCK_BEGIN(env,code) { @@ -338,6 +357,8 @@ ECL_BLOCK_BEGIN(env,code) { The C/C++ program has to ensure that the code in @code{ECL_BLOCK_END} gets executed, avoiding a direct exit of the block via @code{goto} or a C/C++ return. @end deffn + +@cppindex ECL_CATCH_BEGIN @deffn Macro ECL_CATCH_BEGIN @verbatim ECL_CATCH_BEGIN(env,tag) { @@ -353,6 +374,8 @@ ECL_CATCH_BEGIN(env,tag) { The C/C++ program has to ensure that the code in @code{ECL_CATCH_END} gets executed, avoiding a direct exit of the catch block via goto or a C/C++ return. @end deffn + +@cppindex ECL_UNWIND_PROTECT_BEGIN @deffn Macro ECL_UNWIND_PROTECT_BEGIN C macro for unwind-protect diff --git a/src/doc/new-doc/standards/environment.txi b/src/doc/new-doc/standards/environment.txi index b7933f340..07b103d30 100644 --- a/src/doc/new-doc/standards/environment.txi +++ b/src/doc/new-doc/standards/environment.txi @@ -3,6 +3,8 @@ @node Environment - Dictionary @subsection Dictionary +@lspindex disassemble +@lspindex trace @defun disassemble function-designator* Display the assembly code of a function @@ -23,7 +25,7 @@ ECL only has a particular difference: it has two different compilers, one based @end itemize @end defun -@deffn Macro trace function-name* +@defmac trace function-name* Follow the execution of functions @subsubheading Synopsis (trace @var{function-name*}) @@ -60,7 +62,7 @@ If specified, and @var{form} evaluates to true, then the debugger is invoked at @item :print, :print-after In addition to the usual printout, the result of evaluating @var{form} is printed at the start of the function or at the end of the function, depending on the option. Multiple print options cause multiple values to be output, in the order in which they were introduced. @end table -@end deffn +@end defmac @node Environment - C Reference @subsection C Reference diff --git a/src/doc/new-doc/standards/streams.txi b/src/doc/new-doc/standards/streams.txi index 400116ca9..ef18e221c 100644 --- a/src/doc/new-doc/standards/streams.txi +++ b/src/doc/new-doc/standards/streams.txi @@ -10,6 +10,9 @@ ECL implements all stream types described in ANSI @bibcite{ANSI}. Additionally, @node Streams - Element types @subsubsection Element types +@lspindex write-char +@lspindex write-sequence +@lspindex read-char ECL distinguishes between two kinds of streams: character streams and byte streams. @dfn{Character streams} only accept and produce characters, written or read one by one, with @code{write-char} or @code{read-char}, or in chunks, with @code{write-sequence} or any of the Lisp printer functions. Character operations are conditioned by the external format, as described in @ref{Streams - External formats}. ANSI Common Lisp also supports binary streams. Here input and output is performed in chunks of bits. Binary streams are created with the function open passing as argument a subtype of integer and the implementation is free to round up that integer type to the closest size it supports. In particular ECL rounds up the size to a multiple of a byte. For example, the form @code{(open "foo.bin" :direction :output :element-type '(unsigned-byte 13))}, will open the file @code{foo.bin} for writing, using 16-bit words as the element type. diff --git a/src/doc/new-doc/standards/strings.txi b/src/doc/new-doc/standards/strings.txi index 79c94713a..ffea53894 100644 --- a/src/doc/new-doc/standards/strings.txi +++ b/src/doc/new-doc/standards/strings.txi @@ -21,17 +21,22 @@ It is important to remember that strings with unicode characters can only be pri @node Strings - C reference @subsection C reference @subsubsection Base string constructors +@cppindex ecl_alloc_adjustable_base_string +@cppindex ecl_alloc_adjustable_simple_string +@cppindex ecl_make_simple_base_string +@cppindex ecl_make_constant_base_string + Building strings of C data @subsubheading Functions @deftypefun cl_object ecl_alloc_adjustable_base_string (cl_index @var{length}); @end deftypefun -@deftypefun cl_object ecl_alloc_adjustable_simple_string( cl_index @var{length}); +@deftypefun cl_object ecl_alloc_adjustable_simple_string (cl_index @var{length}); @end deftypefun -@deftypefun cl_object ecl_make_simple_base_string( ecl_base_char* @var{data}, cl_index @var{length}); +@deftypefun cl_object ecl_make_simple_base_string (ecl_base_char* @var{data}, cl_index @var{length}); @end deftypefun -@deftypefun cl_object ecl_make_constant_base_string( ecl_base_char* @var{data}, cl_index @var{length}); +@deftypefun cl_object ecl_make_constant_base_string (ecl_base_char* @var{data}, cl_index @var{length}); @end deftypefun @subsubheading Description @@ -44,6 +49,8 @@ These are different ways to create a base string, which is a string that holds a The other constructors create strings but use some preexisting data. @code{ecl_make_simple_base_string} creates a string copying the data that the user supplies, and using freshly allocated memory. @code{ecl_make_constant_base_string} on the other hand, does not allocate memory, but simply uses the supplied pointer as buffer for the string. This last function should be used with care, ensuring that the supplied buffer is not deallocated. @subsubsection String accessors +@cppindex ecl_char +@cppindex ecl_char_set Reading and writing characters into a string @subsubheading Functions diff --git a/src/doc/new-doc/standards/symbols.txi b/src/doc/new-doc/standards/symbols.txi index ef036e0ac..26893aaa2 100644 --- a/src/doc/new-doc/standards/symbols.txi +++ b/src/doc/new-doc/standards/symbols.txi @@ -4,6 +4,8 @@ There are no implementation-specific limits on the size or content of symbol names. It is however not allowed to write on the strings which have been passed to @code{#'make-symbol} or returned from @code{#'symbol-name}. @subsection C Reference +@cppindex ecl_make_keyword +@cppindex ecl_make_symbol @deftypefun cl_object ecl_make_keyword (char * @var{name}); Find a lisp keyword diff --git a/src/doc/new-doc/standards/types_and_classes.txi b/src/doc/new-doc/standards/types_and_classes.txi index 4cff0defc..c9daec640 100644 --- a/src/doc/new-doc/standards/types_and_classes.txi +++ b/src/doc/new-doc/standards/types_and_classes.txi @@ -1,5 +1,7 @@ @node Types and classes @section Types and classes +@lspindex single-float +@lspindex double-float ECL defines the following additional built-in classes in the @code{CL} package: diff --git a/src/doc/new-doc/user-guide/embedding.txi b/src/doc/new-doc/user-guide/embedding.txi index 463a5bb71..20e1dcc55 100644 --- a/src/doc/new-doc/user-guide/embedding.txi +++ b/src/doc/new-doc/user-guide/embedding.txi @@ -7,6 +7,7 @@ @node Embedding ECL - Embedding Reference @subsection Embedding Reference +@cppindex CL_CATCH_ALL @defmac CL_CATCH_ALL Create a protected region. @@ -49,6 +50,8 @@ As explained in @code{CL_UNWIND_PROTECT},it is normally advisable to set up an u @end defmac + +@cppindex CL_UNWIND_PROTECT @defmac CL_UNWIND_PROTECT Create a protected region. @@ -89,6 +92,7 @@ Besides this, normal mechanisms for exit, such as ext:quit, and uncaught excepti @end defmac +@cppindex cl_boot @deftypefun int cl_boot (int @var{argc}, char **@var{argv}); Setup the lisp environment. @table @var @@ -104,6 +108,7 @@ This function must be called before any other function from the ECL library, inc @end deftypefun +@cppindex cl_shutdown @deftypefun int cl_shutdown (void); Close the lisp environment. @@ -154,6 +159,8 @@ The second set is related to the sizes of different stacks. Currently ECL uses f @end float @end deftypefun + +@cppindex ecl_get_option @deftypefun cl_fixnum ecl_get_option (int @var{option}); Read the value of a boot option. @table @var @@ -166,6 +173,7 @@ This functions reads the value of different options that have to be customized @ @end deftypefun +@cppindex ecl_clear_interrupts @defmac ecl_clear_interrupts(); Clear all pending signals and exceptions. @@ -176,6 +184,8 @@ This macro clears all pending interrupts. @code{ecl_disable_interrupts} and @code{ecl_enable_interrupts}. @end defmac + +@cppindex ecl_disable_interrupts @defmac ecl_disable_interrupts(); Postpone handling of signals and exceptions. @@ -186,6 +196,8 @@ This macro sets a thread-local flag indicating that all received signals should @code{ecl_enable_interrupts} and @code{ecl_clear_interrupts}. @end defmac + +@cppindex ecl_enable_interrupts @defmac ecl_enable_interrupts(); Activate handling of signals and exceptions.