procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

* doc/misc/cl.texi: Further general copyedits.

Browse source 
Eg, no longer distinguish between "the optimizing compiler" and "the
non-optimizing compiler" like they were different entities.
This commit is contained in:
Glenn Morris 2012-11-02 21:19:40 -04:00
parent 7fbf8f7bd9
commit c65b407b40
2 changed files with 83 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/misc/ChangeLog
View file

@ -1,3 +1,7 @@
2012-11-03 Glenn Morris <rgm@gnu.org>
* cl.texi: Further general copyedits.
2012-11-02 Glenn Morris <rgm@gnu.org>
* cl.texi (Naming Conventions, Type Predicates, Macros)

155
doc/misc/cl.texi
View file

@ -836,7 +836,7 @@ constructs.
* Conditionals:: @code{cl-case}, @code{cl-typecase}.
* Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
* Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
* Loop Facility:: The Common Lisp @code{cl-loop} macro.
* Loop Facility:: The Common Lisp @code{loop} macro.
* Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
@end menu
@ -1524,7 +1524,7 @@ Common Lisp @dfn{blocks} provide a non-local exit mechanism very
similar to @code{catch} and @code{throw}, with lexical scoping.
This package actually implements @code{cl-block}
in terms of @code{catch}; however, the lexical scoping allows the
optimizing byte-compiler to omit the costly @code{catch} step if the
byte-compiler to omit the costly @code{catch} step if the
body of the block does not actually @code{cl-return-from} the block.
@defmac cl-block name forms@dots{}
@ -1561,7 +1561,7 @@ just as in Common Lisp.
Because they are implemented in terms of Emacs Lisp's @code{catch}
and @code{throw}, blocks have the same overhead as actual
@code{catch} constructs (roughly two function calls). However,
the optimizing byte compiler will optimize away the @code{catch}
the byte compiler will optimize away the @code{catch}
if the block does
not in fact contain any @code{cl-return} or @code{cl-return-from} calls
that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
@ -1726,18 +1726,18 @@ iterating over vectors or lists.
@section Loop Facility
@noindent
A common complaint with Lisp's traditional looping constructs is
that they are either too simple and limited, such as Common Lisp's
@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
obscure, like Common Lisp's @code{do} loop.
A common complaint with Lisp's traditional looping constructs was
that they were either too simple and limited, such as @code{dotimes}
or @code{while}, or too unreadable and obscure, like Common Lisp's
@code{do} loop.
To remedy this, recent versions of Common Lisp have added a new
construct called the ``Loop Facility'' or ``@code{loop} macro'',
with an easy-to-use but very powerful and expressive syntax.
To remedy this, Common Lisp added a construct called the ``Loop
Facility'' or ``@code{loop} macro'', with an easy-to-use but very
powerful and expressive syntax.
@menu
* Loop Basics:: @code{cl-loop} macro, basic clause structure.
* Loop Examples:: Working examples of @code{cl-loop} macro.
* Loop Basics:: The @code{cl-loop} macro, basic clause structure.
* Loop Examples:: Working examples of the @code{cl-loop} macro.
* For Clauses:: Clauses introduced by @code{for} or @code{as}.
* Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
* Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
@ -1770,9 +1770,9 @@ Common Lisp specifies a certain general order of clauses in a
loop:
@example
(cl-loop @var{name-clause}
@var{var-clauses}@dots{}
@var{action-clauses}@dots{})
(loop @var{name-clause}
@var{var-clauses}@dots{}
@var{action-clauses}@dots{})
@end example
The @var{name-clause} optionally gives a name to the implicit
@ -1798,10 +1798,10 @@ also use regular Lisp @code{cl-return} or @code{cl-return-from} to
break out of the loop.)
@end defmac
The following sections give some examples of the Loop Macro in
The following sections give some examples of the loop macro in
action, and describe the particular loop clauses in great detail.
Consult the second edition of Steele for additional discussion
and examples of the @code{loop} macro.
and examples.
@node Loop Examples
@subsection Loop Examples
@ -2165,8 +2165,9 @@ that was just set by the previous clause; in the second loop,
based on the value of @code{x} left over from the previous time
through the loop.
Another feature of the @code{cl-loop} macro is @dfn{destructuring},
similar in concept to the destructuring provided by @code{defmacro}.
Another feature of the @code{cl-loop} macro is @emph{destructuring},
similar in concept to the destructuring provided by @code{defmacro}
(@pxref{Argument Lists}).
The @var{var} part of any @code{for} clause can be given as a list
of variables instead of a single variable. The values produced
during loop execution must be lists; the values in the lists are
@ -2378,7 +2379,7 @@ by the name @code{it} in the ``then'' part. For example:
(setq funny-numbers '(6 13 -1))
@result{} (6 13 -1)
(cl-loop for x below 10
if (oddp x)
if (cl-oddp x)
collect x into odds
and if (memq x funny-numbers) return (cdr it) end
else
@ -2444,15 +2445,14 @@ loop. Many of the examples in this section illustrate the use of
@item return @var{form}
This clause causes the loop to return immediately. The following
Lisp form is evaluated to give the return value of the @code{loop}
Lisp form is evaluated to give the return value of the loop
form. The @code{finally} clauses, if any, are not executed.
Of course, @code{return} is generally used inside an @code{if} or
@code{unless}, as its use in a top-level loop clause would mean
the loop would never get to ``loop'' more than once.
The clause @samp{return @var{form}} is equivalent to
@c FIXME cl-do, cl-return?
@samp{do (return @var{form})} (or @code{return-from} if the loop
@samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop
was named). The @code{return} clause is implemented a bit more
efficiently, though.
@end table
@ -2466,7 +2466,7 @@ clause, respectively. Consult the source code in file
This package's @code{cl-loop} macro is compatible with that of Common
Lisp, except that a few features are not implemented: @code{loop-finish}
and data-type specifiers. Naturally, the @code{for} clauses which
and data-type specifiers. Naturally, the @code{for} clauses that
iterate over keymaps, overlays, intervals, frames, windows, and
buffers are Emacs-specific extensions.
@ -2519,17 +2519,17 @@ Destructuring is made available to the user by way of the
following macro:
@defmac cl-destructuring-bind arglist expr forms@dots{}
This macro expands to code which executes @var{forms}, with
This macro expands to code that executes @var{forms}, with
the variables in @var{arglist} bound to the list of values
returned by @var{expr}. The @var{arglist} can include all
the features allowed for @code{defmacro} argument lists,
the features allowed for @code{cl-defmacro} argument lists,
including destructuring. (The @code{&environment} keyword
is not allowed.) The macro expansion will signal an error
if @var{expr} returns a list of the wrong number of arguments
or with incorrect keyword arguments.
@end defmac
This package also includes the Common Lisp @code{cl-define-compiler-macro}
This package also includes the Common Lisp @code{define-compiler-macro}
facility, which allows you to define compile-time expansions and
optimizations for your functions.
@ -2592,16 +2592,19 @@ mechanism that allows you to give the compiler special hints
about the types of data that will be stored in particular variables,
and about the ways those variables and functions will be used. This
package defines versions of all the Common Lisp declaration forms:
@code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
and @code{cl-the}.
@code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
and @code{the}.
Most of the Common Lisp declarations are not currently useful in
Emacs Lisp, as the byte-code system provides little opportunity
to benefit from type information, and @code{special} declarations
are redundant in a fully dynamically-scoped Lisp. A few
declarations are meaningful when the optimizing byte
compiler is being used, however. Under the earlier non-optimizing
compiler, these declarations will effectively be ignored.
Most of the Common Lisp declarations are not currently useful in Emacs
Lisp. For example, the byte-code system provides little
opportunity to benefit from type information.
@ignore
and @code{special} declarations are redundant in a fully
dynamically-scoped Lisp.
@end ignore
A few declarations are meaningful when byte compiler optimizations
are enabled, as they are by the default. Otherwise these
declarations will effectively be ignored.
@defun cl-proclaim decl-spec
This function records a ``global'' declaration specified by
@ -2612,7 +2615,7 @@ is evaluated and thus should normally be quoted.
@defmac cl-declaim decl-specs@dots{}
This macro is like @code{cl-proclaim}, except that it takes any number
of @var{decl-spec} arguments, and the arguments are unevaluated and
unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when
unquoted. The @code{cl-declaim} macro also puts @code{(cl-eval-when
(compile load eval) @dots{})} around the declarations so that they will
be registered at compile-time as well as at run-time. (This is vital,
since normally the declarations are meant to influence the way the
@ -2635,9 +2638,9 @@ In this package, @code{cl-locally} is no different from @code{progn}.
@defmac cl-the type form
Type information provided by @code{cl-the} is ignored in this package;
in other words, @code{(cl-the @var{type} @var{form})} is equivalent
to @var{form}. Future versions of the optimizing byte-compiler may
make use of this information.
in other words, @code{(cl-the @var{type} @var{form})} is equivalent to
@var{form}. Future byte-compiler optimizations may make use of this
information.
For example, @code{mapcar} can map over both lists and arrays. It is
hard for the compiler to expand @code{mapcar} into an in-line loop
@ -2658,35 +2661,31 @@ such as @code{type} and @code{ftype}, are silently ignored.
@table @code
@item special
@c FIXME ?
Since all variables in Emacs Lisp are ``special'' (in the Common
Lisp sense), @code{special} declarations are only advisory. They
simply tell the optimizing byte compiler that the specified
simply tell the byte compiler that the specified
variables are intentionally being referred to without being
bound in the body of the function. The compiler normally emits
warnings for such references, since they could be typographical
errors for references to local variables.
The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
optimizing compiler, or to nothing at all in older compilers (which
do not warn for non-local references).
equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
In top-level contexts, it is generally better to write
@code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
since @code{defvar} makes your intentions clearer. But the older
byte compilers can not handle @code{defvar}s appearing inside of
functions, while @code{(cl-declare (special @var{var}))} takes care
to work correctly with all compilers.
since @code{defvar} makes your intentions clearer.
@item inline
The @code{inline} @var{decl-spec} lists one or more functions
whose bodies should be expanded ``in-line'' into calling functions
whenever the compiler is able to arrange for it. For example,
the Common Lisp function @code{cadr} is declared @code{inline}
by this package so that the form @code{(cadr @var{x})} will
expand directly into @code{(car (cdr @var{x}))} when it is called
in user functions, for a savings of one (relatively expensive)
function call.
the function @code{cl-acons} is declared @code{inline}
by this package so that the form @code{(cl-acons @var{key} @var{value}
@var{alist})} will
expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
when it is called in user functions, so as to save function calls.
The following declarations are all equivalent. Note that the
@code{defsubst} form is a convenient way to define a function
@ -2705,7 +2704,7 @@ request that a function you have defined should be inlined,
but it is impolite to use it to request inlining of an external
function.
In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
before a particular call to a function to cause just that call to
be inlined; the current byte compilers provide no way to implement
this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
@ -2718,8 +2717,7 @@ declaration.
@item optimize
This declaration controls how much optimization is performed by
the compiler. Naturally, it is ignored by the earlier non-optimizing
compilers.
the compiler.
The word @code{optimize} is followed by any number of lists like
@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
@ -2728,8 +2726,7 @@ and @code{safety}. The value of a quality should be an integer from
0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
The default level for both qualities is 1.
In this package, with the optimizing compiler, the
@code{speed} quality is tied to the @code{byte-optimize}
In this package, the @code{speed} quality is tied to the @code{byte-optimize}
flag, which is set to @code{nil} for @code{(speed 0)} and to
@code{t} for higher settings; and the @code{safety} quality is
tied to the @code{byte-compile-delete-errors} flag, which is
@ -2748,22 +2745,22 @@ just because of an error in a fully-optimized Lisp program.
The @code{optimize} declaration is normally used in a top-level
@code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
it to be used with @code{cl-declare} to set the level of optimization
it to be used with @code{declare} to set the level of optimization
locally for a given form, but this will not work correctly with the
current version of the optimizing compiler. (The @code{cl-declare}
current byte-compiler. (The @code{cl-declare}
will set the new optimization level, but that level will not
automatically be unset after the enclosing form is done.)
@item warn
This declaration controls what sorts of warnings are generated
by the byte compiler. Again, only the optimizing compiler
generates warnings. The word @code{warn} is followed by any
by the byte compiler. The word @code{warn} is followed by any
number of ``warning qualities'', similar in form to optimization
qualities. The currently supported warning types are
@code{redefine}, @code{callargs}, @code{unresolved}, and
@code{free-vars}; in the current system, a value of 0 will
disable these warnings and any higher value will enable them.
See the documentation for the optimizing byte compiler for details.
See the documentation of the variable @code{byte-compile-warnings}
for more details.
@end table
@node Symbols
@ -2878,6 +2875,8 @@ their names will not conflict with ``real'' variables in the user's
code.
@end defun
@c FIXME texinfo renders this as as cl-gensym-counter in info.
@c It looks fine in the index, and in the pdf version.
@defvar cl--gensym-counter
This variable holds the counter used to generate @code{cl-gensym} names.
It is incremented after each use by @code{cl-gensym}. In Common Lisp
@ -2908,13 +2907,13 @@ provided.
@noindent
This section defines a few simple Common Lisp operations on numbers
which were left out of Emacs Lisp.
that were left out of Emacs Lisp.
@menu
* Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, etc.
* Numerical Functions:: @code{abs}, @code{cl-floor}, etc.
* Numerical Functions:: @code{cl-floor}, @code{cl-ceiling}, etc.
* Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
* Implementation Parameters:: @code{cl-most-positive-float}.
* Implementation Parameters:: @code{cl-most-positive-float}, etc.
@end menu
@node Predicates on Numbers
@ -3041,6 +3040,7 @@ of @code{cl-truncate}.
This package also provides an implementation of the Common Lisp
random number generator. It uses its own additive-congruential
algorithm, which is much more likely to give statistically clean
@c FIXME? Still true?
random numbers than the simple generators supplied by many
operating systems.
@ -3048,13 +3048,15 @@ operating systems.
This function returns a random nonnegative number less than
@var{number}, and of the same type (either integer or floating-point).
The @var{state} argument should be a @code{random-state} object
which holds the state of the random number generator. The
that holds the state of the random number generator. The
function modifies this state object as a side effect. If
@var{state} is omitted, it defaults to the variable
@code{cl--random-state}, which contains a pre-initialized
@code{random-state} object.
@end defun
@c FIXME texinfo renders this as cl-random-state in info.
@c It looks fine in the index, and in the pdf version.
@defvar cl--random-state
This variable contains the system ``default'' @code{random-state}
object, used for calls to @code{cl-random} that do not specify an
@ -3099,10 +3101,10 @@ This predicate returns @code{t} if @var{object} is a
@section Implementation Parameters
@noindent
This package defines several useful constants having to with numbers.
This package defines several useful constants having to do with
floating-point numbers.
The following parameters have to do with floating-point numbers.
This package determines their values by exercising the computer's
It determines their values by exercising the computer's
floating-point arithmetic in various ways. Because this operation
might be slow, the code for initializing them is kept in a separate
function that must be called before the parameters can be used.
@ -3110,12 +3112,13 @@ function that must be called before the parameters can be used.
@defun cl-float-limits
This function makes sure that the Common Lisp floating-point parameters
like @code{cl-most-positive-float} have been initialized. Until it is
called, these parameters will be @code{nil}. If this version of Emacs
does not support floats, the parameters will remain @code{nil}. If the
parameters have already been initialized, the function returns
called, these parameters will be @code{nil}.
@c If this version of Emacs does not support floats, the parameters will
@c remain @code{nil}.
If the parameters have already been initialized, the function returns
immediately.
The algorithm makes assumptions that will be valid for most modern
The algorithm makes assumptions that will be valid for almost all
machines, but will fail if the machine's arithmetic is extremely
unusual, e.g., decimal.
@end defun
@ -3135,7 +3138,7 @@ is approximately @code{1.79e+308}.
@end defvar
@defvar cl-most-negative-float
This constant equals the most-negative value a Lisp float can hold.
This constant equals the most negative value a Lisp float can hold.
(It is assumed to be equal to @code{(- cl-most-positive-float)}.)
@end defvar
@ -4482,7 +4485,7 @@ Lisp macros emit
code which 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
optimizing compiler removes @code{cl-block}s which are not actually
byte-compiler removes @code{cl-block}s which are not actually
referenced by @code{cl-return} or @code{cl-return-from} inside the block.
@node Common Lisp Compatibility