comparison man/cl.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@settitle Common Lisp Extensions

@copying
This file documents the GNU Emacs Common Lisp emulation package.

Copyright (C) 1993, 2002 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@node Top, Overview, (dir), (dir)
@chapter Common Lisp Extensions

@noindent
This document describes a set of Emacs Lisp facilities borrowed from
Common Lisp.  All the facilities are described here in detail.  While
this document does not assume any prior knowledge of Common Lisp, it

* Function Index::
* Variable Index::
@end menu

@node Overview, Program Structure, Top, Top
@ifinfo
@chapter Overview
@end ifinfo
@iftex
@section Overview
@end iftex

@noindent
Common Lisp is a huge language, and Common Lisp systems tend to be
massive and extremely complex.  Emacs Lisp, by contrast, is rather
minimalist in the choice of Lisp features it offers the programmer.

@end itemize

The package described here was written by Dave Gillespie,
@file{daveg@@synaptics.com}.  It is a total rewrite of the original
1986 @file{cl.el} package by Cesar Quiroz.  Most features of the
the Quiroz package have been retained; any incompatibilities are
noted in the descriptions below.  Care has been taken in this
version to ensure that each function is defined efficiently,
concisely, and with minimal impact on the rest of the Emacs
environment.

The type symbol @code{null} represents the symbol @code{nil}.
Thus @code{(typep @var{object} 'null)} is equivalent to
@code{(null @var{object})}.

@item
The type symbol @code{real} is a synonym for @code{number}, and
@code{fixnum} is a synonym for @code{integer}.

@item
The type symbols @code{character} and @code{string-char} match

@var{place} and @var{form} pairs, the assignments are done sequentially
just as with @code{setq}.  @code{setf} returns the value of the last
@var{form}.

The following Lisp forms will work as generalized variables, and
so may legally appear in the @var{place} argument of @code{setf}:

@itemize @bullet
@item
A symbol naming a variable.  In other words, @code{(setf x y)} is
exactly equivalent to @code{(setq x y)}, and @code{setq} itself is

sequences of code when they are @code{setf}'d (@code{(narrow-to-region
x (point-max))} in this case).

@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
where @var{subplace} is itself a legal generalized variable whose
current value is a string, and where the value stored is also a
string.  The new string is spliced into the specified part of the
destination string.  For example:

@example

     @result{} (0 1 2 3 4 5 6 7 8 9)
@end example

The @code{by} value is always positive, even for downward-counting
loops.  Some sort of @code{from} value is required for downward
loops; @samp{for x downto 5} is not a legal loop clause all by
itself.

@item for @var{var} in @var{list} by @var{function}
This clause iterates @var{var} over all the elements of @var{list},
in turn.  If you specify the @code{by} term, then @var{function}

are also recognized but are equivalent to @code{symbols} in Emacs Lisp.

Due to a minor implementation restriction, it will not work to have
more than one @code{for} clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given @code{loop}.  Fortunately,
it would rarely if ever be useful to do so.  It @emph{is} legal to mix
one of these types of clauses with other clauses like @code{for ... to}
or @code{while}.

@item for @var{var} being the hash-keys of @var{hash-table}
This clause iterates over the entries in @var{hash-table}.  For each

unnamed temporary variable.  Also, @code{into} accumulations do
not automatically imply a return value.  The loop must use some
explicit mechanism, such as @code{finally return}, to return
the accumulated result.

It is legal for several accumulation clauses of the same type to
accumulate into the same place.  From Steele:

@example
(loop for name in '(fred sue alice joe june)
      for kids in '((bob ken) () () (kris sunshine) ())

(declaim (inline foo bar))
(eval-when (compile load eval) (proclaim '(inline foo bar)))
(defsubst foo (...) ...)       ; instead of defun
@end example

@strong{Note:}  This declaration remains in effect after the
containing source file is done.  It is correct to use it to
request that a function you have defined should be inlined,
but it is impolite to use it to request inlining of an external
function.

@example
(get sym prop)  @equiv{}  (getf (symbol-plist sym) prop)
@end example

It is legal to use @code{getf} as a @code{setf} place, in which case
its @var{place} argument must itself be a legal @code{setf} place.
The @var{default} argument, if any, is ignored in this context.
The effect is to change (via @code{setcar}) the value cell in the
list that corresponds to @var{property}, or to cons a new property-value
pair onto the list if the property is not yet present.

date and time.  As an extension to Common Lisp, @var{state} may also
be an integer in which case the new object is seeded from that
integer; each different integer seed will result in a completely
different sequence of random numbers.

It is legal to print a @code{random-state} object to a buffer or
file and later read it back with @code{read}.  If a program wishes
to use a sequence of pseudo-random numbers which can be reproduced
later for debugging, it can call @code{(make-random-state t)} to
get a new sequence, then print this sequence to a file.  When the
program is later rerun, it can read the original run's random-state

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
defaults from the slot descriptor.  It is legal to include arguments
which 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.

You can specify any number of full-format @code{:constructor}

remaining differences between Emacs Lisp and Common Lisp make it
difficult to port large Common Lisp applications to Emacs.  For
one, some of the features in this package are not fully compliant
with ANSI or Steele; @pxref{Common Lisp Compatibility}.  But there
are also quite a few features that this package does not provide
at all.  Here are some major omissions that you will want watch out
for when bringing Common Lisp code into Emacs.

@itemize @bullet
@item
Case-insensitivity.  Symbols in Common Lisp are case-insensitive

@printindex vr

@setchapternewpage odd
@contents
@bye

88155:d7ddb3e565de

@settitle Common Lisp Extensions

@copying
This file documents the GNU Emacs Common Lisp emulation package.

Copyright (C) 1993, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@node Top, Overview, (dir), (dir)
@chapter Introduction

@noindent
This document describes a set of Emacs Lisp facilities borrowed from
Common Lisp.  All the facilities are described here in detail.  While
this document does not assume any prior knowledge of Common Lisp, it

* Function Index::
* Variable Index::
@end menu

@node Overview, Program Structure, Top, Top
@ifnottex
@chapter Overview
@end ifnottex

@noindent
Common Lisp is a huge language, and Common Lisp systems tend to be
massive and extremely complex.  Emacs Lisp, by contrast, is rather
minimalist in the choice of Lisp features it offers the programmer.

@end itemize

The package described here was written by Dave Gillespie,
@file{daveg@@synaptics.com}.  It is a total rewrite of the original
1986 @file{cl.el} package by Cesar Quiroz.  Most features of the
Quiroz package have been retained; any incompatibilities are
noted in the descriptions below.  Care has been taken in this
version to ensure that each function is defined efficiently,
concisely, and with minimal impact on the rest of the Emacs
environment.

The type symbol @code{null} represents the symbol @code{nil}.
Thus @code{(typep @var{object} 'null)} is equivalent to
@code{(null @var{object})}.

@item
The type symbol @code{atom} represents all objects that are not cons
cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
@code{(atom @var{object})}.

@item
The type symbol @code{real} is a synonym for @code{number}, and
@code{fixnum} is a synonym for @code{integer}.

@item
The type symbols @code{character} and @code{string-char} match

@var{place} and @var{form} pairs, the assignments are done sequentially
just as with @code{setq}.  @code{setf} returns the value of the last
@var{form}.

The following Lisp forms will work as generalized variables, and
so may appear in the @var{place} argument of @code{setf}:

@itemize @bullet
@item
A symbol naming a variable.  In other words, @code{(setf x y)} is
exactly equivalent to @code{(setq x y)}, and @code{setq} itself is

sequences of code when they are @code{setf}'d (@code{(narrow-to-region
x (point-max))} in this case).

@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
where @var{subplace} is itself a valid generalized variable whose
current value is a string, and where the value stored is also a
string.  The new string is spliced into the specified part of the
destination string.  For example:

@example

     @result{} (0 1 2 3 4 5 6 7 8 9)
@end example

The @code{by} value is always positive, even for downward-counting
loops.  Some sort of @code{from} value is required for downward
loops; @samp{for x downto 5} is not a valid loop clause all by
itself.

@item for @var{var} in @var{list} by @var{function}
This clause iterates @var{var} over all the elements of @var{list},
in turn.  If you specify the @code{by} term, then @var{function}

are also recognized but are equivalent to @code{symbols} in Emacs Lisp.

Due to a minor implementation restriction, it will not work to have
more than one @code{for} clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given @code{loop}.  Fortunately,
it would rarely if ever be useful to do so.  It @emph{is} valid to mix
one of these types of clauses with other clauses like @code{for ... to}
or @code{while}.

@item for @var{var} being the hash-keys of @var{hash-table}
This clause iterates over the entries in @var{hash-table}.  For each

unnamed temporary variable.  Also, @code{into} accumulations do
not automatically imply a return value.  The loop must use some
explicit mechanism, such as @code{finally return}, to return
the accumulated result.

It is valid for several accumulation clauses of the same type to
accumulate into the same place.  From Steele:

@example
(loop for name in '(fred sue alice joe june)
      for kids in '((bob ken) () () (kris sunshine) ())

(declaim (inline foo bar))
(eval-when (compile load eval) (proclaim '(inline foo bar)))
(defsubst foo (...) ...)       ; instead of defun
@end example

@strong{Please note:}  this declaration remains in effect after the
containing source file is done.  It is correct to use it to
request that a function you have defined should be inlined,
but it is impolite to use it to request inlining of an external
function.

@example
(get sym prop)  @equiv{}  (getf (symbol-plist sym) prop)
@end example

It is valid to use @code{getf} as a @code{setf} place, in which case
its @var{place} argument must itself be a valid @code{setf} place.
The @var{default} argument, if any, is ignored in this context.
The effect is to change (via @code{setcar}) the value cell in the
list that corresponds to @var{property}, or to cons a new property-value
pair onto the list if the property is not yet present.

date and time.  As an extension to Common Lisp, @var{state} may also
be an integer in which case the new object is seeded from that
integer; each different integer seed will result in a completely
different sequence of random numbers.

It is valid to print a @code{random-state} object to a buffer or
file and later read it back with @code{read}.  If a program wishes
to use a sequence of pseudo-random numbers which can be reproduced
later for debugging, it can call @code{(make-random-state t)} to
get a new sequence, then print this sequence to a file.  When the
program is later rerun, it can read the original run's random-state

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
defaults from the slot descriptor.  It is valid to include arguments
which 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.

You can specify any number of full-format @code{:constructor}

remaining differences between Emacs Lisp and Common Lisp make it
difficult to port large Common Lisp applications to Emacs.  For
one, some of the features in this package are not fully compliant
with ANSI or Steele; @pxref{Common Lisp Compatibility}.  But there
are also quite a few features that this package does not provide
at all.  Here are some major omissions that you will want to watch out
for when bringing Common Lisp code into Emacs.

@itemize @bullet
@item
Case-insensitivity.  Symbols in Common Lisp are case-insensitive

@printindex vr

@setchapternewpage odd
@contents
@bye

@ignore
   arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
@end ignore