-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
that each is an ordered collection of elements. This section describes
functions that accept any kind of sequence.
- - Function: sequencep OBJECT
+ - Function: sequencep object
Returns `t' if OBJECT is a list, vector, bit vector, or string,
`nil' otherwise.
- - Function: copy-sequence SEQUENCE
+ - Function: copy-sequence sequence
Returns a copy of SEQUENCE. The copy is the same type of object
as the original sequence, and it has the same elements in the same
order.
(bit-vector 1 0 1 1 0 1 0 0)
=> #*10110100
- - Function: length SEQUENCE
+ - Function: length sequence
Returns the number of elements in SEQUENCE. If SEQUENCE is a cons
cell that is not a list (because the final CDR is not `nil'), a
`wrong-type-argument' error is signaled.
(length #*01101)
=> 5
- - Function: elt SEQUENCE INDEX
+ - Function: elt sequence index
This function returns the element of SEQUENCE indexed by INDEX.
Legitimate values of INDEX are integers ranging from 0 up to one
less than the length of SEQUENCE. If SEQUENCE is a list, then
(elt [1 2 3 4] -1)
error-->Args out of range: [1 2 3 4], -1
- This function generalizes `aref' (*note Array Functions::.) and
- `nth' (*note List Elements::.).
+ This function generalizes `aref' (*note Array Functions::) and
+ `nth' (*note List Elements::).
\1f
File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
* The elements of an array may be referenced or changed with the
functions `aref' and `aset', respectively (*note Array
- Functions::.).
+ Functions::).
In principle, if you wish to have an array of text characters, you
could use either a string or a vector. In practice, we always choose
In this section, we describe the functions that accept strings,
vectors, and bit vectors.
- - Function: arrayp OBJECT
+ - Function: arrayp object
This function returns `t' if OBJECT is an array (i.e., a string,
vector, or bit vector).
(arrayp #*101)
=> t
- - Function: aref ARRAY INDEX
+ - Function: aref array index
This function returns the INDEXth element of ARRAY. The first
element is at index zero.
See also the function `elt', in *Note Sequence Functions::.
- - Function: aset ARRAY INDEX OBJECT
+ - Function: aset array index object
This function sets the INDEXth element of ARRAY to be OBJECT. It
returns OBJECT.
If ARRAY is a string and OBJECT is not a character, a
`wrong-type-argument' error results.
- - Function: fillarray ARRAY OBJECT
+ - Function: fillarray array object
This function fills the array ARRAY with OBJECT, so that each
element of ARRAY is OBJECT. It returns ARRAY.
Here are some functions that relate to vectors:
- - Function: vectorp OBJECT
+ - Function: vectorp object
This function returns `t' if OBJECT is a vector.
(vectorp [a])
(vectorp "asdf")
=> nil
- - Function: vector &rest OBJECTS
+ - Function: vector &rest objects
This function creates and returns a vector whose elements are the
arguments, OBJECTS.
(vector)
=> []
- - Function: make-vector LENGTH OBJECT
+ - Function: make-vector length object
This function returns a new vector consisting of LENGTH elements,
each initialized to OBJECT.
(setq sleepy (make-vector 9 'Z))
=> [Z Z Z Z Z Z Z Z Z]
- - Function: vconcat &rest SEQUENCES
+ - Function: vconcat &rest sequences
This function returns a new vector containing all the elements of
the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or
strings. If no SEQUENCES are given, an empty vector is returned.
of the original integers. *Don't use this feature; we plan to
eliminate it. If you already use this feature, change your
programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::.)
- or `number-to-string' (*note String Conversion::.).
+ number in this way is with `format' (*note Formatting Strings::)
+ or `number-to-string' (*note String Conversion::).
For other concatenation functions, see `mapconcat' in *Note
Mapping Functions::, `concat' in *Note Creating Strings::, `append'
Functions::.
The `append' function provides a way to convert a vector into a list
-with the same elements (*note Building Lists::.):
+with the same elements (*note Building Lists::):
(setq avector [1 two (quote (three)) "four" [five]])
=> [1 two (quote (three)) "four" [five]]
Here are some functions that relate to bit vectors:
- - Function: bit-vector-p OBJECT
+ - Function: bit-vector-p object
This function returns `t' if OBJECT is a bit vector.
(bit-vector-p #*01)
(bit-vector-p "01")
=> nil
- - Function: bitp OBJECT
+ - Function: bitp object
This function returns `t' if OBJECT is either 0 or 1.
- - Function: bit-vector &rest OBJECTS
+ - Function: bit-vector &rest bits
This function creates and returns a bit vector whose elements are
- the arguments OBJECTS. The elements must be either of the two
- integers 0 or 1.
+ the arguments BITS. Each argument must be a bit, i.e. one of the
+ two integers 0 or 1.
(bit-vector 0 0 0 1 0 0 0 0 1 0)
=> #*0001000010
(bit-vector)
=> #*
- - Function: make-bit-vector LENGTH OBJECT
+ - Function: make-bit-vector length bit
This function creates and returns a bit vector consisting of
- LENGTH elements, each initialized to OBJECT.
+ LENGTH elements, each initialized to BIT, which must be one of the
+ two integers 0 or 1.
(setq picket-fence (make-bit-vector 9 1))
=> #*111111111
- - Function: bvconcat &rest SEQUENCES
+ - Function: bvconcat &rest sequences
This function returns a new bit vector containing all the elements
of the SEQUENCES. The arguments SEQUENCES may be lists, vectors,
or bit vectors, all of whose elements are the integers 0 or 1. If
Building Lists::.
The `append' function provides a way to convert a bit vector into a
-list with the same elements (*note Building Lists::.):
+list with the same elements (*note Building Lists::):
(setq bv #*00001110)
=> #*00001110
You can test whether an arbitrary Lisp object is a symbol with
`symbolp':
- - Function: symbolp OBJECT
+ - Function: symbolp object
This function returns `t' if OBJECT is a symbol, `nil' otherwise.
* Menu:
In normal usage, the function cell usually contains a function or
macro, as that is what the Lisp interpreter expects to see there (*note
-Evaluation::.). Keyboard macros (*note Keyboard Macros::.), keymaps
-(*note Keymaps::.) and autoload objects (*note Autoloading::.) are also
+Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps
+(*note Keymaps::) and autoload objects (*note Autoloading::) are also
sometimes stored in the function cell of symbols. We often refer to
"the function `foo'" when we really mean the function stored in the
function cell of the symbol `foo'. We make the distinction only when
necessary.
The property list cell normally should hold a correctly formatted
-property list (*note Property Lists::.), as a number of functions expect
+property list (*note Property Lists::), as a number of functions expect
to see a property list there.
The function cell or the value cell may be "void", which means that
where that documentation string begins.) The function cell contains
the function for returning the name of the file. `buffer-file-name'
names a primitive function, which has no read syntax and prints in hash
-notation (*note Primitive Function Type::.). A symbol naming a
-function written in Lisp would have a lambda expression (or a byte-code
-object) in this cell.
+notation (*note Primitive Function Type::). A symbol naming a function
+written in Lisp would have a lambda expression (or a byte-code object)
+in this cell.
\1f
File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
variable with `setq', whether you define it first or not. The real
purpose of definitions is to guide programmers and programming tools.
They inform programmers who read the code that certain symbols are
-*intended* to be used as variables, or as functions. In addition,
+_intended_ to be used as variables, or as functions. In addition,
utilities such as `etags' and `make-docfile' recognize definitions, and
add appropriate information to tag tables and the `DOC' file. *Note
Accessing Documentation::.
It is possible for two different symbols to have the same name in
different obarrays; these symbols are not `eq' or `equal'. However,
this normally happens only as part of the abbrev mechanism (*note
-Abbrevs::.).
+Abbrevs::).
Common Lisp note: In Common Lisp, a single symbol may be interned
in several obarrays.
arguments. A `wrong-type-argument' error is signaled if the name is
not a string, or if the obarray is not a vector.
- - Function: symbol-name SYMBOL
+ - Function: symbol-name symbol
This function returns the string that is SYMBOL's name. For
example:
the name of the symbol, but fails to update the obarray, so don't
do it!
- - Function: make-symbol NAME
+ - Function: make-symbol name
This function returns a newly-allocated, uninterned symbol whose
name is NAME (which must be a string). Its value and function
definition are void, and its property list is `nil'. In the
(eq sym 'foo)
=> nil
- - Function: intern NAME &optional OBARRAY
+ - Function: intern name &optional obarray
This function returns the interned symbol whose name is NAME. If
there is no such symbol in the obarray OBARRAY, `intern' creates a
new one, adds it to the obarray, and returns it. If OBARRAY is
(eq sym 'foo)
=> nil
- - Function: intern-soft NAME &optional OBARRAY
+ - Function: intern-soft name &optional obarray
This function returns the symbol in OBARRAY whose name is NAME, or
`nil' if OBARRAY has no symbol with that name. Therefore, you can
use `intern-soft' to test whether a symbol with a given name is
=> frazzle
(intern-soft "frazzle") ; That one cannot be found.
=> nil
-
(setq sym (intern "frazzle")) ; Create an interned one.
=> frazzle
-
(intern-soft "frazzle") ; That one can be found!
=> frazzle
-
(eq sym 'frazzle) ; And it is the same one.
=> t
This variable is the standard obarray for use by `intern' and
`read'.
- - Function: mapatoms FUNCTION &optional OBARRAY
+ - Function: mapatoms function &optional obarray
This function calls FUNCTION for each symbol in the obarray
OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to
the value of `obarray', the standard obarray for ordinary symbols.
See `documentation' in *Note Accessing Documentation::, for another
example using `mapatoms'.
- - Function: unintern SYMBOL &optional OBARRAY
+ - Function: unintern symbol &optional obarray
This function deletes SYMBOL from the obarray OBARRAY. If
`symbol' is not actually in the obarray, `unintern' does nothing.
If OBARRAY is `nil', the current obarray is used.
Symbol Properties
=================
- A "property list" ("plist" for short) is a list of paired elements
-stored in the property list cell of a symbol. Each of the pairs
+ A "property list" ("plist" for short) is a list of paired elements,
+often stored in the property list cell of a symbol. Each of the pairs
associates a property name (usually a symbol) with a property or value.
Property lists are generally used to record information about a
symbol, such as its documentation as a variable, the name of the file
where it was defined, or perhaps even the grammatical class of the
symbol (representing a word) in a language-understanding system.
- Many objects other than symbols can have property lists associated
-with them, and XEmacs provides a full complement of functions for
-working with property lists. *Note Property Lists::.
+ Some objects which are not symbols also have property lists
+associated with them, and XEmacs provides a full complement of
+functions for working with property lists. *Note Property Lists::.
The property names and values in a property list can be any Lisp
objects, but the names are usually symbols. They are compared using
* Plists and Alists:: Comparison of the advantages of property
lists and association lists.
-* Symbol Plists:: Functions to access symbols' property lists.
+* Object Plists:: Functions to access objects' property lists.
* Other Plists:: Accessing property lists stored elsewhere.
\1f
-File: lispref.info, Node: Plists and Alists, Next: Symbol Plists, Up: Symbol Properties
+File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties
Property Lists and Association Lists
------------------------------------
- Association lists (*note Association Lists::.) are very similar to
+ Association lists (*note Association Lists::) are very similar to
property lists. In contrast to association lists, the order of the
pairs in the property list is not significant since the property names
must be distinct.
possible with a property list.
\1f
-File: lispref.info, Node: Symbol Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
+File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
-Property List Functions for Symbols
+Property List Functions for Objects
-----------------------------------
- - Function: symbol-plist SYMBOL
+ Once upon a time, only symbols had property lists. Now, several
+other object types, including strings, extents, faces and glyphs also
+have property lists.
+
+ - Function: symbol-plist symbol
This function returns the property list of SYMBOL.
- - Function: setplist SYMBOL PLIST
+ - Function: object-plist object
+ This function returns the property list of OBJECT. If OBJECT is a
+ symbol, this is identical to `symbol-plist'.
+
+ - Function: setplist symbol plist
This function sets SYMBOL's property list to PLIST. Normally,
PLIST should be a well-formed property list, but this is not
enforced.
For symbols in special obarrays, which are not used for ordinary
purposes, it may make sense to use the property list cell in a
nonstandard fashion; in fact, the abbrev mechanism does so (*note
- Abbrevs::.).
+ Abbrevs::). But generally, its use is discouraged. Use `put'
+ instead. `setplist' can only be used with symbols, not other
+ object types.
- - Function: get SYMBOL PROPERTY
+ - Function: get object property &optional default
This function finds the value of the property named PROPERTY in
- SYMBOL's property list. If there is no such property, `nil' is
- returned. Thus, there is no distinction between a value of `nil'
- and the absence of the property.
+ OBJECT's property list. If there is no such property, `default'
+ (which itself defaults to `nil') is returned.
- The name PROPERTY is compared with the existing property names
- using `eq', so any object is a legitimate property.
+ PROPERTY is compared with the existing properties using `eq', so
+ any object is a legitimate property.
See `put' for an example.
- - Function: put SYMBOL PROPERTY VALUE
- This function puts VALUE onto SYMBOL's property list under the
+ - Function: put object property value
+ This function puts VALUE onto OBJECT's property list under the
property name PROPERTY, replacing any previous property value.
The `put' function returns VALUE.
=> (a buzzing little bug)
(get 'fly 'verb)
=> transitive
- (symbol-plist 'fly)
+ (object-plist 'fly)
=> (verb transitive noun (a buzzing little bug))
+ - Function: remprop object property
+ This function removes the entry for PROPERTY from the property
+ list of OBJECT. It returns `t' if the property was indeed found
+ and removed, or `nil' if there was no such property. (This
+ function was probably omitted from Emacs originally because, since
+ `get' did not allow a DEFAULT, it was very difficult to
+ distinguish between a missing property and a property whose value
+ was `nil'; thus, setting a property to `nil' was close enough to
+ `remprop' for most purposes.)
+
\1f
-File: lispref.info, Node: Other Plists, Prev: Symbol Plists, Up: Symbol Properties
+File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties
-Property Lists Outside Symbols
-------------------------------
+Property Lists Not Associated with Objects
+------------------------------------------
These functions are useful for manipulating property lists that are
stored in places other than symbols:
- - Function: getf PLIST PROPERTY &optional DEFAULT
+ - Function: getf plist property &optional default
This returns the value of the PROPERTY property stored in the
property list PLIST. For example,
(getf '(foo 4) 'foo)
=> 4
- - Function: putf PLIST PROPERTY VALUE
+ - Macro: putf plist property value
This stores VALUE as the value of the PROPERTY property in the
property list PLIST. It may modify PLIST destructively, or it may
construct a new list structure without altering the old. The
(setq my-plist (putf my-plist 'quux '(a)))
=> (quux (a) bar t foo 5)
- - Function: plists-eq A B
+ - Function: plists-eq a b
This function returns non-`nil' if property lists A and B are
`eq'. This means that the property lists have the same values for
all the same properties, where comparison between values is done
using `eq'.
- - Function: plists-equal A B
+ - Function: plists-equal a b
This function returns non-`nil' if property lists A and B are
`equal'.
in it. *Note Functions::. The execution of the function may itself
work by evaluating the function definition; or the function may be a
Lisp primitive implemented in C, or it may be a byte-compiled function
-(*note Byte Compilation::.).
+(*note Byte Compilation::).
The evaluation of forms takes place in a context called the
"environment", which consists of the current values and bindings of all
environment is used. *Note Variables::.
Evaluation of a form may create new environments for recursive
-evaluation by binding variables (*note Local Variables::.). These
+evaluation by binding variables (*note Local Variables::). These
environments are temporary and vanish by the time evaluation of the form
is complete. The form may also make changes that persist; these changes
are called "side effects". An example of a form that produces side
effects is `(setq foo 1)'.
The details of what evaluation means for each kind of form are
-described below (*note Forms::.).
+described below (*note Forms::).
---------- Footnotes ----------
The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
-values. Loading a file also does evaluation (*note Loading::.).
+values. Loading a file also does evaluation (*note Loading::).
- - Function: eval FORM
+ - Function: eval form
This is the basic function for performing evaluation. It evaluates
FORM in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (*note
- Forms::.).
+ Forms::).
Since `eval' is a function, the argument expression that appears
in a call to `eval' is evaluated twice: once as preparation before
The number of currently active calls to `eval' is limited to
`max-lisp-eval-depth' (see below).
- - Command: eval-region START END &optional STREAM
+ - Command: eval-region start end &optional stream
This function evaluates the forms in the current buffer in the
region defined by the positions START and END. It reads forms from
the region and calls `eval' on them until the end of the region is
`eval-region' always returns `nil'.
- - Command: eval-buffer BUFFER &optional STREAM
+ - Command: eval-buffer buffer &optional stream
This is like `eval-region' except that it operates on the whole
contents of BUFFER.
we find the real function via the symbol.
* Function Forms:: Forms that call functions.
* Macro Forms:: Forms that call macros.
-* Special Forms:: "Special forms" are idiosyncratic primitives,
+* Special Forms:: ``Special forms'' are idiosyncratic primitives,
most of them extremely important.
* Autoloading:: Functions set up to load files
containing their real definitions.
-\1f
-File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms
-
-Self-Evaluating Forms
----------------------
-
- A "self-evaluating form" is any form that is not a list or symbol.
-Self-evaluating forms evaluate to themselves: the result of evaluation
-is the same object that was evaluated. Thus, the number 25 evaluates to
-25, and the string `"foo"' evaluates to the string `"foo"'. Likewise,
-evaluation of a vector does not cause evaluation of the elements of the
-vector--it returns the same vector with its contents unchanged.
-
- '123 ; An object, shown without evaluation.
- => 123
- 123 ; Evaluated as usual--result is the same.
- => 123
- (eval '123) ; Evaluated "by hand"--result is the same.
- => 123
- (eval (eval '123)) ; Evaluating twice changes nothing.
- => 123
-
- It is common to write numbers, characters, strings, and even vectors
-in Lisp code, taking advantage of the fact that they self-evaluate.
-However, it is quite unusual to do this for types that lack a read
-syntax, because there's no way to write them textually. It is possible
-to construct Lisp expressions containing these types by means of a Lisp
-program. Here is an example:
-
- ;; Build an expression containing a buffer object.
- (setq buffer (list 'print (current-buffer)))
- => (print #<buffer eval.texi>)
- ;; Evaluate it.
- (eval buffer)
- -| #<buffer eval.texi>
- => #<buffer eval.texi>
-