comparison man/cl.texi @ 60927:bae786986f2e

* calc.texi, cl.texi, gnus.texi, idlwave.texi, reftex.texi: Replace `legal' with `valid'.

60926:89202ce14f61

@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

@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) ())

@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}

60927:bae786986f2e

@settitle Common Lisp Extensions

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

Copyright (C) 1993, 2002, 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.1 or
any later version published by the Free Software Foundation; with no

@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) ())

@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}