From 685b00269debcb77f533f65ba5e6421d8539229d Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 3 Nov 2012 10:56:30 -0700 Subject: [PATCH] Further edits for doc/misc/cl.texi * cl.texi: Further general copyedits. (List Functions): Remove copy-tree, standard elisp for some time. (Efficiency Concerns): Comment out examples that no longer apply. (Compiler Optimizations): Rename from "Optimizing Compiler"; reword. --- doc/misc/ChangeLog | 3 ++ doc/misc/cl.texi | 111 +++++++++++++++++++++++------------------------------ 2 files changed, 52 insertions(+), 62 deletions(-) diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 39d7ee8d1fc..6bd601bef5d 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,6 +1,9 @@ 2012-11-03 Glenn Morris * cl.texi: Further general copyedits. + (List Functions): Remove copy-tree, standard elisp for some time. + (Efficiency Concerns): Comment out examples that no longer apply. + (Compiler Optimizations): Rename from "Optimizing Compiler"; reword. 2012-11-02 Glenn Morris diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 66d25144dd6..593985edbfc 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -2867,6 +2867,7 @@ temporary variables. This function creates a new, uninterned symbol (using @code{make-symbol}) with a unique name. (The name of an uninterned symbol is relevant only if the symbol is printed.) By default, the name is generated +@c FIXME no longer true? from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, @samp{G1002}, etc. If the optional argument @var{x} is a string, that string is used as a prefix instead of @samp{G}. Uninterned symbols @@ -3207,7 +3208,7 @@ may appear in any order. The @code{:key} argument should be passed either @code{nil}, or a function of one argument. This key function is used as a filter through which the elements of the sequence are seen; for example, -@code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}: +@code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}. It searches for an element of the list whose @sc{car} equals @code{x}, rather than for an element which equals @code{x} itself. If @code{:key} is omitted or @code{nil}, the filter is effectively @@ -3225,7 +3226,7 @@ true (non-@code{nil}) to indicate a match; instead, you may use @code{:test-not} to give a function which returns @emph{false} to indicate a match. The default test function is @code{eql}. -Many functions which take @var{item} and @code{:test} or @code{:test-not} +Many functions that take @var{item} and @code{:test} or @code{:test-not} arguments also come in @code{-if} and @code{-if-not} varieties, where a @var{predicate} function is passed instead of @var{item}, and sequence elements match if the predicate returns true on them @@ -3239,7 +3240,7 @@ and sequence elements match if the predicate returns true on them to remove all zeros from sequence @code{seq}. Some operations can work on a subsequence of the argument sequence; -these function take @code{:start} and @code{:end} arguments which +these function take @code{:start} and @code{:end} arguments, which default to zero and the length of the sequence, respectively. Only elements between @var{start} (inclusive) and @var{end} (exclusive) are affected by the operation. The @var{end} argument @@ -3347,7 +3348,7 @@ the return values using @code{nconc}. @defun cl-some predicate seq &rest more-seqs This function calls @var{predicate} on each element of @var{seq} in turn; if @var{predicate} returns a non-@code{nil} value, -@code{some} returns that value, otherwise it returns @code{nil}. +@code{cl-some} returns that value, otherwise it returns @code{nil}. Given several sequence arguments, it steps through the sequences in parallel until the shortest one runs out, just as in @code{cl-mapcar}. You can rely on the left-to-right order in which @@ -3396,7 +3397,7 @@ of left-associative: @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 @end example -If @code{:key} is specified, it is a function of one argument which +If @code{:key} is specified, it is a function of one argument, which is called on each of the sequence elements in turn. If @code{:initial-value} is specified, it is effectively added to the @@ -3465,7 +3466,7 @@ of data copied is simply the shorter of the source and destination If @var{seq1} and @var{seq2} are @code{eq}, then the replacement will work correctly even if the regions indicated by the start and end arguments overlap. However, if @var{seq1} and @var{seq2} -are lists which share storage but are not @code{eq}, and the +are lists that share storage but are not @code{eq}, and the start and end arguments specify overlapping regions, the effect is undefined. @end defun @@ -3488,7 +3489,7 @@ if @var{count} was also specified). @end defun @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end} -This deletes all elements of @var{seq} which match @var{item}. +This deletes all elements of @var{seq} that match @var{item}. It is a destructive operation. Since Emacs Lisp does not support stretchable strings or vectors, this is the same as @code{cl-remove} for those sequence types. On lists, @code{cl-remove} will copy the @@ -3588,7 +3589,7 @@ elements match (according to @code{:test}, @code{:test-not}, and @code{:key}), the function returns @code{nil}. If there is a mismatch, the function returns the index (relative to @var{seq1}) of the first mismatching element. This will be the leftmost pair of -elements which do not match, or the position at which the shorter of +elements that do not match, or the position at which the shorter of the two otherwise-matching sequences runs out. If @code{:from-end} is true, then the elements are compared from right @@ -3603,7 +3604,7 @@ which compares two strings case-insensitively. @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} This function searches @var{seq2} for a subsequence that matches @var{seq1} (or part of it specified by @code{:start1} and -@code{:end1}.) Only matches which fall entirely within the region +@code{:end1}). Only matches that fall entirely within the region defined by @code{:start2} and @code{:end2} will be considered. The return value is the index of the leftmost element of the leftmost match, relative to the start of @var{seq2}, or @code{nil} @@ -3614,7 +3615,7 @@ function finds the @emph{rightmost} matching subsequence. @node Sorting Sequences @section Sorting Sequences -@defun clsort seq predicate @t{&key :key} +@defun cl-sort seq predicate @t{&key :key} This function sorts @var{seq} into increasing order as determined by using @var{predicate} to compare pairs of elements. @var{predicate} should return true (non-@code{nil}) if and only if its first argument @@ -3625,7 +3626,7 @@ numbers into decreasing rather than increasing order. This function differs from Emacs's built-in @code{sort} in that it can operate on any type of sequence, not just lists. Also, it -accepts a @code{:key} argument which is used to preprocess data +accepts a @code{:key} argument, which is used to preprocess data fed to the @var{predicate} function. For example, @example @@ -3636,7 +3637,7 @@ fed to the @var{predicate} function. For example, sorts @var{data}, a sequence of strings, into increasing alphabetical order without regard to case. A @code{:key} function of @code{car} would be useful for sorting association lists. It should only be a -simple accessor though, it's used heavily in the current +simple accessor though, since it's used heavily in the current implementation. The @code{cl-sort} function is destructive; it sorts lists by actually @@ -3692,7 +3693,7 @@ i.e., chains of cons cells. @defun cl-caddr x This function is equivalent to @code{(car (cdr (cdr @var{x})))}. -Likewise, this package defines all 28 @code{c@var{xxx}r} functions +Likewise, this package defines all 24 @code{c@var{xxx}r} functions where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. All of these functions are @code{setf}-able, and calls to them are expanded inline by the byte-compiler for maximum efficiency. @@ -3720,7 +3721,8 @@ This function returns the length of list @var{x}, exactly like @code{(length @var{x})}, except that if @var{x} is a circular list (where the @sc{cdr}-chain forms a loop rather than terminating with @code{nil}), this function returns @code{nil}. (The regular -@code{length} function would get stuck if given a circular list.) +@code{length} function would get stuck if given a circular list. +See also the @code{safe-length} function.) @end defun @defun cl-list* arg &rest others @@ -3748,18 +3750,6 @@ This function returns a copy of the list @var{list}. It copies dotted lists like @code{(1 2 . 3)} correctly. @end defun -@defun copy-tree x &optional vecp -This function returns a copy of the tree of cons cells @var{x}. -@c FIXME? cl-copy-list is not an alias of copy-sequence. -Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}), -which copies only along the @sc{cdr} direction, this function -copies (recursively) along both the @sc{car} and the @sc{cdr} -directions. If @var{x} is not a cons cell, the function simply -returns @var{x} unchanged. If the optional @var{vecp} argument -is true, this function copies vectors (recursively) as well as -cons cells. -@end defun - @defun cl-tree-equal x y @t{&key :test :test-not :key} This function compares two trees of cons cells. If @var{x} and @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are @@ -3822,7 +3812,7 @@ This is a destructive version of @code{cl-sublis}. @section Lists as Sets @noindent -These functions perform operations on lists which represent sets +These functions perform operations on lists that represent sets of elements. @defun cl-member item list @t{&key :test :test-not :key} @@ -3835,13 +3825,14 @@ are compared by @code{eql} by default; you can use the @code{:test}, The standard Emacs lisp function @code{member} uses @code{equal} for comparisons; it is equivalent to @code{(cl-member @var{item} @var{list} -:test 'equal)}. +:test 'equal)}. With no keyword arguments, @code{cl-member} is +equivalent to @code{memq}. @end defun @findex cl-member-if @findex cl-member-if-not The @code{cl-member-if} and @code{cl-member-if-not} functions -analogously search for elements which satisfy a given predicate. +analogously search for elements that satisfy a given predicate. @defun cl-tailp sublist list This function returns @code{t} if @var{sublist} is a sublist of @@ -3860,11 +3851,11 @@ become part of the list. @end defun @defun cl-union list1 list2 @t{&key :test :test-not :key} -This function combines two lists which represent sets of items, +This function combines two lists that represent sets of items, returning a list that represents the union of those two sets. -The result list will contain all items which appear in @var{list1} +The resulting list contains all items that appear in @var{list1} or @var{list2}, and no others. If an item appears in both -@var{list1} and @var{list2} it will be copied only once. If +@var{list1} and @var{list2} it is copied only once. If an item is duplicated in @var{list1} or @var{list2}, it is undefined whether or not that duplication will survive in the result list. The order of elements in the result list is also @@ -3879,7 +3870,7 @@ it tries to reuse the storage of the argument lists if possible. @defun cl-intersection list1 list2 @t{&key :test :test-not :key} This function computes the intersection of the sets represented by @var{list1} and @var{list2}. It returns the list of items -which appear in both @var{list1} and @var{list2}. +that appear in both @var{list1} and @var{list2}. @end defun @defun cl-nintersection list1 list2 @t{&key :test :test-not :key} @@ -3929,7 +3920,7 @@ This function searches the association list @var{a-list} for an element whose @sc{car} matches (in the sense of @code{:test}, @code{:test-not}, and @code{:key}, or by comparison with @code{eql}) a given @var{item}. It returns the matching element, if any, -otherwise @code{nil}. It ignores elements of @var{a-list} which +otherwise @code{nil}. It ignores elements of @var{a-list} that are not cons cells. (This corresponds to the behavior of @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's @code{assoc} ignores @code{nil}s but considers any other non-cons @@ -3990,11 +3981,11 @@ are symbols. For example, @end example @noindent -defines a struct type called @code{person} which contains three +defines a struct type called @code{person} that contains three slots. Given a @code{person} object @var{p}, you can access those slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms: +using @code{setf} on any of these place forms, for example: @example (cl-incf (person-age birthday-boy)) @@ -4011,10 +4002,10 @@ Given a @code{person}, @code{(copy-person @var{p})} makes a new object of the same type whose slots are @code{eq} to those of @var{p}. Given any Lisp object @var{x}, @code{(person-p @var{x})} returns -true if @var{x} looks like a @code{person}, false otherwise. (Again, +true if @var{x} looks like a @code{person}, and false otherwise. (Again, in Common Lisp this predicate would be exact; in Emacs Lisp the best it can do is verify that @var{x} is a vector of the correct -length which starts with the correct tag symbol.) +length that starts with the correct tag symbol.) Accessors like @code{person-name} normally check their arguments (effectively using @code{person-p}) and signal an error if the @@ -4051,7 +4042,7 @@ In general, @var{name} is either a name symbol or a list of a name symbol followed by any number of @dfn{struct options}; each @var{slot} is either a slot symbol or a list of the form @samp{(@var{slot-name} @var{default-value} @var{slot-options}@dots{})}. The @var{default-value} -is a Lisp form which is evaluated any time an instance of the +is a Lisp form that is evaluated any time an instance of the structure type is created without specifying that slot's value. Common Lisp defines several slot options, but the only one @@ -4109,11 +4100,11 @@ The argument names should match the slot names; each slot is initialized from the corresponding argument. Slots whose names do not appear in the argument list are initialized based on the @var{default-value} in their slot descriptor. Also, @code{&optional} -and @code{&key} arguments which don't specify defaults take their +and @code{&key} arguments that don't specify defaults take their defaults from the slot descriptor. It is valid to include arguments -which don't correspond to slot names; these are useful if they are +that don't correspond to slot names; these are useful if they are referred to in the defaults for optional, keyword, or @code{&aux} -arguments which @emph{do} correspond to slots. +arguments that @emph{do} correspond to slots. You can specify any number of full-format @code{:constructor} options on a structure. The default constructor is still generated @@ -4154,7 +4145,7 @@ means not to generate a copier function. (In this implementation, all copier functions are simply synonyms for @code{copy-sequence}.) @item :predicate -The argument is an alternate name for the predicate which recognizes +The argument is an alternate name for the predicate that recognizes objects of this type. The default is @code{@var{name}-p}. @code{nil} means not to generate a predicate function. (If the @code{:type} option is used without the @code{:named} option, no predicate is @@ -4214,7 +4205,7 @@ work on astronauts just like other people. @item :print-function In full Common Lisp, this option allows you to specify a function -which is called to print an instance of the structure type. The +that is called to print an instance of the structure type. The Emacs Lisp system offers no hooks into the Lisp printer which would allow for such a feature, so this package simply ignores @code{:print-function}. @@ -4391,7 +4382,7 @@ You can find out how a macro expands by using the This function takes a single Lisp form as an argument and inserts a nicely formatted copy of it in the current buffer (which must be in Lisp mode so that indentation works properly). It also expands -all Lisp macros which appear in the form. The easiest way to use +all Lisp macros that appear in the form. The easiest way to use this function is to go to the @file{*scratch*} buffer and type, say, @example @@ -4400,7 +4391,7 @@ this function is to go to the @file{*scratch*} buffer and type, say, @noindent and type @kbd{C-x C-e} immediately after the closing parenthesis; -the expansion +an expansion similar to: @example (cl-block nil @@ -4421,7 +4412,11 @@ variable @code{G1004} was created by @code{cl-gensym}.) If the optional argument @var{full} is true, then @emph{all} macros are expanded, including @code{cl-block}, @code{cl-eval-when}, and compiler macros. Expansion is done as if @var{form} were -a top-level form in a file being compiled. For example, +a top-level form in a file being compiled. + +@c FIXME none of these examples are still applicable. +@ignore +For example, @example (cl-prettyexpand '(cl-pushnew 'x list)) @@ -4431,16 +4426,12 @@ a top-level form in a file being compiled. For example, (cl-prettyexpand '(caddr (cl-member 'a list)) t) @print{} (car (cdr (cdr (memq 'a list)))) @end example +@end ignore Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all have built-in compiler macros to optimize them in common cases. @end defun -@ifinfo -@example - -@end example -@end ifinfo @appendixsec Error Checking @noindent @@ -4450,7 +4441,7 @@ where substantial gains were possible at the expense of marginal incompatibility. The Common Lisp standard (as embodied in Steele's book) uses the -phrase ``it is an error if'' to indicate a situation which is not +phrase ``it is an error if'' to indicate a situation that is not supposed to arise in complying programs; implementations are strongly encouraged but not required to signal an error in these situations. This package sometimes omits such error checking in the interest of @@ -4472,20 +4463,16 @@ you can use @code{&allow-other-keys} to omit this check. Functions defined in this package such as @code{cl-find} and @code{cl-member} do check their keyword arguments for validity. -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec Optimizing Compiler +@appendixsec Compiler Optimizations @noindent -Use of the optimizing Emacs compiler is highly recommended; many of the Common +Changing the value of @code{byte-optimize} from the default @code{t} +is highly discouraged; many of the Common Lisp macros emit -code which can be improved by optimization. In particular, +code that can be improved by optimization. In particular, @code{cl-block}s (whether explicit or implicit in constructs like @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the -byte-compiler removes @code{cl-block}s which are not actually +byte-compiler removes @code{cl-block}s that are not actually referenced by @code{cl-return} or @code{cl-return-from} inside the block. @node Common Lisp Compatibility -- 2.11.4.GIT