[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r110761: More edits for cl.texi
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r110761: More edits for cl.texi |
Date: |
Thu, 01 Nov 2012 00:16:32 -0700 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110761
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Thu 2012-11-01 00:16:32 -0700
message:
More edits for cl.texi
* doc/misc/cl.texi: More copyedits, plus:
(Time of Evaluation, Iteration): Add xref to Emacs Lisp manual.
(Macro Bindings, Blocks and Exits): Acknowledge existence of lexical-binding.
(Iteration): Mainly defer to doc of standard dolist, dotimes.
modified:
doc/misc/ChangeLog
doc/misc/cl.texi
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-11-01 01:44:50 +0000
+++ b/doc/misc/ChangeLog 2012-11-01 07:16:32 +0000
@@ -1,6 +1,10 @@
2012-11-01 Glenn Morris <address@hidden>
* cl.texi: General copyedits for style, line-breaks, etc.
+ (Time of Evaluation, Iteration): Add xref to Emacs Lisp manual.
+ (Macro Bindings, Blocks and Exits):
+ Acknowledge existence of lexical-binding.
+ (Iteration): Mainly defer to doc of standard dolist, dotimes.
2012-10-31 Glenn Morris <address@hidden>
=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi 2012-11-01 01:44:50 +0000
+++ b/doc/misc/cl.texi 2012-11-01 07:16:32 +0000
@@ -300,6 +300,7 @@
This is analogous to the @code{defsubst} form;
@code{cl-defsubst} uses a different method (compiler macros) which
works in all versions of Emacs, and also generates somewhat more
address@hidden Really?
efficient inline expansions. In particular, @code{cl-defsubst}
arranges for the processing of keyword arguments, default values,
etc., to be done at compile-time whenever possible.
@@ -309,7 +310,8 @@
This is identical to the regular @code{defmacro} form,
except that @var{arglist} is allowed to be a full Common Lisp
argument list. The @code{&environment} keyword is supported as
-described in Steele. The @code{&whole} keyword is supported only
+described in Steele's book @cite{Common Lisp, the Language}.
+The @code{&whole} keyword is supported only
within destructured lists (see below); top-level @code{&whole}
cannot be implemented with the current Emacs Lisp interpreter.
The macro expander body is enclosed in an implicit block called
@@ -462,7 +464,7 @@
destructuring is only allowed with @code{defmacro}; this package
allows it with @code{cl-defun} and other argument lists as well.
In destructuring, any argument variable (@var{var} in the above
-diagram) can be replaced by a list of variables, or more generally,
+example) can be replaced by a list of variables, or more generally,
a recursive argument list. The corresponding argument value must
be a list whose elements match this recursive argument list.
For example:
@@ -584,12 +586,12 @@
@end defmac
Emacs includes two special forms related to @code{cl-eval-when}.
address@hidden During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
One of these, @code{eval-when-compile}, is not quite equivalent to
any @code{cl-eval-when} construct and is described below.
The other form, @code{(eval-and-compile @dots{})}, is exactly
-equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and
-so is not itself defined by this package.
+equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
@defmac eval-when-compile address@hidden
The @var{forms} are evaluated at compile-time; at execution time,
@@ -703,6 +705,7 @@
@item
The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
defined by this package rather than @code{floatp}, so it will work
address@hidden FIXME are any such platforms still relevant?
correctly even in Emacs versions without floating-point support.
@item
@@ -781,8 +784,8 @@
not implement @code{unsigned-byte} by default.
@end defmac
-The @code{cl-typecase} and @code{cl-check-type} macros also use type
-names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
+The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
+(@pxref{Assertions}) macros also use type names. The @code{cl-map},
@code{cl-concatenate}, and @code{cl-merge} functions take type-name
arguments to specify the type of sequence to return. @xref{Sequences}.
@@ -1324,7 +1327,7 @@
The @code{cl-labels} form is like @code{cl-flet}, except that
the function bindings can be recursive. The scoping is lexical,
but you can only capture functions in closures if
address@hidden is address@hidden
address@hidden is @code{t}.
@xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
@ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
@@ -1356,12 +1359,8 @@
and macro-expander forms). The macro is defined accordingly for
use within the body of the @code{cl-macrolet}.
address@hidden FIXME this should be modified to say ``even when lexical-binding
address@hidden is code{nil}'', but is that true? The doc of cl-macrolet just
address@hidden refers us to cl-flet, which refers to cl-labels, which says that
it
address@hidden behaves differently according to whether l-b is true or not.
-Because of the nature of macros, @code{cl-macrolet} is lexically
-scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
+Because of the nature of macros, @code{cl-macrolet} is always lexically
+scoped. The @code{cl-macrolet} binding will
affect only calls that appear physically within the body
@var{forms}, possibly after expansion of other macros in the
body.
@@ -1388,12 +1387,15 @@
Likewise, a @code{let} or @code{let*} binding a symbol macro is
treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
address@hidden FIXME does it work like this in Emacs with lexical-binding = t?
Common Lisp, where the rules of lexical scoping cause a @code{let}
-binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
address@hidden FIXME obsolete.
-only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
-macro.
+binding to shadow a @code{symbol-macrolet} binding. In this package,
+such shadowing does not occur, even when @code{lexical-binding} is
address@hidden See http://debbugs.gnu.org/12119
address@hidden (This behavior predates the addition of lexical binding to
+Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
+At present in this package, only @code{lexical-let} and
address@hidden will shadow a symbol macro. @xref{Obsolete
+Lexical Binding}.
There is no analogue of @code{defmacro} for symbol macros; all symbol
macros are local. A typical use of @code{cl-symbol-macrolet} is in the
@@ -1401,7 +1403,7 @@
@example
(cl-defmacro my-dolist ((x list) &rest body)
- (let ((var (gensym)))
+ (let ((var (cl-gensym)))
(list 'cl-loop 'for var 'on list 'do
(cl-list* 'cl-symbol-macrolet
(list (list x (list 'car var)))
@@ -1516,8 +1518,8 @@
@noindent
Common Lisp @dfn{blocks} provide a non-local exit mechanism very
-similar to @code{catch} and @code{throw}, but lexically rather than
-dynamically scoped. This package actually implements @code{cl-block}
+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
body of the block does not actually @code{cl-return-from} the block.
@@ -1532,11 +1534,12 @@
The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
the @code{catch}/@code{throw} mechanism. The main differences are
that block @var{name}s are unevaluated symbols, rather than forms
-(such as quoted symbols) which evaluate to a tag at run-time; and
-also that blocks are lexically scoped whereas @code{catch}/@code{throw}
-are dynamically scoped. This means that functions called from the
-body of a @code{catch} can also @code{throw} to the @code{catch},
-but the @code{cl-return-from} referring to a block name must appear
+(such as quoted symbols) that evaluate to a tag at run-time; and
+also that blocks are always lexically scoped.
+In a dynamically scoped @code{catch}, functions called from the
address@hidden body can also @code{throw} to the @code{catch}. This
+is not an option for @code{cl-block}, where
+the @code{cl-return-from} referring to a block name must appear
physically within the @var{forms} that make up the body of the block.
They may not appear within other called functions, although they may
appear within macro expansions or @code{lambda}s in the body. Block
@@ -1546,20 +1549,20 @@
the function or expander bodies with implicit blocks with the
same name as the function or macro. This does not occur in Emacs
Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
-forms which do create the implicit block.
+forms, which do create the implicit block.
The Common Lisp looping constructs defined by this package,
such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
just as in Common Lisp.
-Because they are implemented in terms of Emacs Lisp @code{catch}
+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}
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}
-functions which don't use @code{cl-return} don't pay the overhead to
+functions that don't use @code{cl-return} don't pay the overhead to
support it.
@end defmac
@@ -1581,8 +1584,8 @@
@noindent
The macros described here provide more sophisticated, high-level
-looping constructs to complement Emacs Lisp's basic @code{while}
-loop.
+looping constructs to complement Emacs Lisp's basic loop forms
+(@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
@defmac cl-loop address@hidden
This package supports both the simple, old-style meaning of
@@ -1646,7 +1649,7 @@
in place of @samp{(@var{var})}, again following the analogy with
@code{let}.
-This example (from Steele) illustrates a loop which applies the
+This example (from Steele) illustrates a loop that applies the
function @code{f} to successive pairs of values from the lists
@code{foo} and @code{bar}; it is equivalent to the call
@code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
@@ -1683,23 +1686,19 @@
@end defmac
@defmac cl-dolist (var list [result]) address@hidden
-This is a more specialized loop which iterates across the elements
-of a list. @var{list} should evaluate to a list; the body @var{forms}
-are executed with @var{var} bound to each element of the list in
-turn. Finally, the @var{result} form (or @code{nil}) is evaluated
-with @var{var} bound to @code{nil} to produce the result returned by
-the loop. Unlike with Emacs's built in @code{dolist}, the loop is
-surrounded by an implicit @code{nil} block.
+This is exactly like the standard Emacs Lisp macro @code{dolist},
+but surrounds the loop with an implicit @code{nil} block.
@end defmac
@defmac cl-dotimes (var count [result]) address@hidden
-This is a more specialized loop which iterates a specified number
-of times. The body is executed with @var{var} bound to the integers
+This is exactly like the standard Emacs Lisp macro @code{dotimes},
+but surrounds the loop with an implicit @code{nil} block.
+The body is executed with @var{var} bound to the integers
from zero (inclusive) to @var{count} (exclusive), in turn. Then
address@hidden FIXME lispref does not state this part explicitly, could move
this there.
the @code{result} form is evaluated with @var{var} bound to the total
number of iterations that were done (i.e., @code{(max 0 @var{count})})
-to get the return value for the loop form. Unlike with Emacs's built in
address@hidden, the loop is surrounded by an implicit @code{nil} block.
+to get the return value for the loop form.
@end defmac
@defmac cl-do-symbols (var [obarray [result]]) address@hidden
@@ -1798,8 +1797,8 @@
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's @dfn{Common Lisp, the Language},
-for additional discussion and examples of the @code{loop} macro.
+Consult the second edition of Steele for additional discussion
+and examples of the @code{loop} macro.
@node Loop Examples
@subsection Loop Examples
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r110761: More edits for cl.texi,
Glenn Morris <=