-This is ../info/lispref.info, produced by makeinfo version 4.6 from
+This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
\1f
File: lispref.info, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
-Accessing Elements of Lists
-===========================
+11.4 Accessing Elements of Lists
+================================
- - Function: car cons-cell
+ -- Function: car cons-cell
This function returns the value pointed to by the first pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CAR of CONS-CELL.
(car '())
=> nil
- - Function: cdr cons-cell
+ -- Function: cdr cons-cell
This function returns the value pointed to by the second pointer of
the cons cell CONS-CELL. Expressed another way, this function
returns the CDR of CONS-CELL.
(cdr '())
=> nil
- - Function: car-safe object
+ -- Function: car-safe object
This function lets you take the CAR of a cons cell while avoiding
errors for other data types. It returns the CAR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
(car x)
nil))
- - Function: cdr-safe object
+ -- Function: cdr-safe object
This function lets you take the CDR of a cons cell while avoiding
errors for other data types. It returns the CDR of OBJECT if
OBJECT is a cons cell, `nil' otherwise. This is in contrast to
(cdr x)
nil))
- - Function: nth n list
+ -- Function: nth n list
This function returns the Nth element of LIST. Elements are
numbered starting with zero, so the CAR of LIST is element number
zero. If the length of LIST is N or less, the value is `nil'.
=> nil
(nth -3 '(1 2 3 4))
=> 1
-
+
(nth n x) == (car (nthcdr n x))
- - Function: nthcdr n list
+ -- Function: nthcdr n list
This function returns the Nth CDR of LIST. In other words, it
removes the first N links of LIST and returns what follows.
access particular elements in a nested list. All of these can be
rewritten in terms of the functions just described.
- - Function: caar cons-cell
- - Function: cadr cons-cell
- - Function: cdar cons-cell
- - Function: cddr cons-cell
- - Function: caaar cons-cell
- - Function: caadr cons-cell
- - Function: cadar cons-cell
- - Function: caddr cons-cell
- - Function: cdaar cons-cell
- - Function: cdadr cons-cell
- - Function: cddar cons-cell
- - Function: cdddr cons-cell
- - Function: caaaar cons-cell
- - Function: caaadr cons-cell
- - Function: caadar cons-cell
- - Function: caaddr cons-cell
- - Function: cadaar cons-cell
- - Function: cadadr cons-cell
- - Function: caddar cons-cell
- - Function: cadddr cons-cell
- - Function: cdaaar cons-cell
- - Function: cdaadr cons-cell
- - Function: cdadar cons-cell
- - Function: cdaddr cons-cell
- - Function: cddaar cons-cell
- - Function: cddadr cons-cell
- - Function: cdddar cons-cell
- - Function: cddddr cons-cell
+ -- Function: caar cons-cell
+ -- Function: cadr cons-cell
+ -- Function: cdar cons-cell
+ -- Function: cddr cons-cell
+ -- Function: caaar cons-cell
+ -- Function: caadr cons-cell
+ -- Function: cadar cons-cell
+ -- Function: caddr cons-cell
+ -- Function: cdaar cons-cell
+ -- Function: cdadr cons-cell
+ -- Function: cddar cons-cell
+ -- Function: cdddr cons-cell
+ -- Function: caaaar cons-cell
+ -- Function: caaadr cons-cell
+ -- Function: caadar cons-cell
+ -- Function: caaddr cons-cell
+ -- Function: cadaar cons-cell
+ -- Function: cadadr cons-cell
+ -- Function: caddar cons-cell
+ -- Function: cadddr cons-cell
+ -- Function: cdaaar cons-cell
+ -- Function: cdaadr cons-cell
+ -- Function: cdadar cons-cell
+ -- Function: cdaddr cons-cell
+ -- Function: cddaar cons-cell
+ -- Function: cddadr cons-cell
+ -- Function: cdddar cons-cell
+ -- Function: cddddr cons-cell
Each of these functions is equivalent to one or more applications
of `car' and/or `cdr'. For example,
That is to say, read the a's and d's from right to left and apply
a `car' or `cdr' for each a or d found, respectively.
- - Function: first list
+ -- Function: first list
This is equivalent to `(nth 0 LIST)', i.e. the first element of
LIST. (Note that this is also equivalent to `car'.)
- - Function: second list
+ -- Function: second list
This is equivalent to `(nth 1 LIST)', i.e. the second element of
LIST.
- - Function: third list
- - Function: fourth list
- - Function: fifth list
- - Function: sixth list
- - Function: seventh list
- - Function: eighth list
- - Function: ninth list
- - Function: tenth list
+ -- Function: third list
+ -- Function: fourth list
+ -- Function: fifth list
+ -- Function: sixth list
+ -- Function: seventh list
+ -- Function: eighth list
+ -- Function: ninth list
+ -- Function: tenth list
These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
respectively, i.e. the third through tenth elements of LIST.
\1f
File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
-Building Cons Cells and Lists
-=============================
+11.5 Building Cons Cells and Lists
+==================================
Many functions build lists, as lists reside at the very heart of Lisp.
`cons' is the fundamental list-building function; however, it is
interesting to note that `list' is used more times in the source code
for Emacs than `cons'.
- - Function: cons object1 object2
+ -- Function: cons object1 object2
This function is the fundamental function used to build new list
structure. It creates a new cons cell, making OBJECT1 the CAR,
and OBJECT2 the CDR. It then returns the new cons cell. The
used in this example and the function named `list' described below;
any symbol can serve both purposes.
- - Function: list &rest objects
+ -- Function: list &rest objects
This function creates a list with OBJECTS as its elements. The
resulting list is always `nil'-terminated. If no OBJECTS are
given, the empty list is returned.
(list)
=> nil
- - Function: make-list length object
+ -- Function: make-list length object
This function creates a list of length LENGTH, in which all the
elements have the identical value OBJECT. Compare `make-list'
with `make-string' (*note Creating Strings::).
(make-list 0 'pigs)
=> nil
- - Function: append &rest sequences
+ -- Function: append &rest sequences
This function returns a list containing all the elements of
SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
the last one should be a list. All arguments except the last one
=> (pine oak)
(setq more-trees (append '(maple birch) trees))
=> (maple birch pine oak)
-
+
trees
=> (pine oak)
more-trees
number in this way is with `format' (*note Formatting Strings::)
or `number-to-string' (*note String Conversion::).
- - Function: reverse list
+ -- Function: reverse list
This function creates a new list whose elements are the elements of
LIST, but in reverse order. The original argument LIST is _not_
altered.
\1f
File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
-Modifying Existing List Structure
-=================================
+11.6 Modifying Existing List Structure
+======================================
You can modify the CAR and CDR contents of a cons cell with the
primitives `setcar' and `setcdr'.
\1f
File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists
-Altering List Elements with `setcar'
-------------------------------------
+11.6.1 Altering List Elements with `setcar'
+-------------------------------------------
Changing the CAR of a cons cell is done with `setcar'. When used on a
list, `setcar' replaces one element of a list with a different element.
- - Function: setcar cons-cell object
+ -- Function: setcar cons-cell object
This function stores OBJECT as the new CAR of CONS-CELL, replacing
its previous CAR. It returns the value OBJECT. For example:
=> (a b c)
(setq x2 (cons 'z (cdr x1)))
=> (z b c)
-
+
;; Replace the CAR of a shared link.
(setcar (cdr x1) 'foo)
=> foo
=> (a foo c)
x2
=> (z foo c)
-
+
;; Replace the CAR of a link that is not shared.
(setcar x1 'baz)
=> baz
\1f
File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
-Altering the CDR of a List
---------------------------
+11.6.2 Altering the CDR of a List
+---------------------------------
The lowest-level primitive for modifying a CDR is `setcdr':
- - Function: setcdr cons-cell object
+ -- Function: setcdr cons-cell object
This function stores OBJECT as the new CDR of CONS-CELL, replacing
its previous CDR. It returns the value OBJECT.
\1f
File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
-Functions that Rearrange Lists
-------------------------------
+11.6.3 Functions that Rearrange Lists
+-------------------------------------
Here are some functions that rearrange lists "destructively" by
modifying the CDRs of their component cons cells. We call these
See `delq', in *Note Sets And Lists::, for another function that
modifies cons cells.
- - Function: nconc &rest lists
+ -- Function: nconc &rest lists
This function returns a list containing all the elements of LISTS.
Unlike `append' (*note Building Lists::), the LISTS are _not_
copied. Instead, the last CDR of each of the LISTS is changed to
(defun add-foo (x) ; We want this function to add
(nconc '(foo) x)) ; `foo' to the front of its arg.
-
+
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo)) x))
-
+
(setq xx (add-foo '(1 2))) ; It seems to work.
=> (foo 1 2)
(setq xy (add-foo '(3 4))) ; What happened?
=> (foo 1 2 3 4)
(eq xx xy)
=> t
-
+
(symbol-function 'add-foo)
=> (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
- - Function: nreverse list
+ -- Function: nreverse list
This function reverses the order of the elements of LIST. Unlike
`reverse', `nreverse' alters its argument by reversing the CDRs in
the cons cells forming the list. The cons cell that used to be
| | | |
------------- ------------
- - Function: sort list predicate
+ -- Function: sort list predicate
This function sorts LIST stably, though destructively, and returns
the sorted list. It compares elements using PREDICATE. A stable
sort is one in which elements with equal sort keys maintain their
\1f
File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
-Using Lists as Sets
-===================
+11.7 Using Lists as Sets
+========================
A list can represent an unordered mathematical set--simply consider a
value an element of a set if it appears in the list, and ignore the
XEmacs Lisp does not have them. You can write them in Lisp if you
wish.
- - Function: memq object list
+ -- Function: memq object list
This function tests to see whether OBJECT is a member of LIST. If
it is, `memq' returns a list starting with the first occurrence of
OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
(memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
=> nil
- - Function: delq object list
+ -- Function: delq object list
This function destructively removes all elements `eq' to OBJECT
from LIST. The letter `q' in `delq' says that it uses `eq' to
compare OBJECT against the elements of the list, like `memq'.
The following two functions are like `memq' and `delq' but use
`equal' rather than `eq' to compare elements. They are new in Emacs 19.
- - Function: member object list
+ -- Function: member object list
The function `member' tests to see whether OBJECT is a member of
LIST, comparing members with OBJECT using `equal'. If OBJECT is a
member, `member' returns a list starting with its first occurrence
(member "foo" '("foo" "bar"))
=> ("foo" "bar")
- - Function: delete object list
+ -- Function: delete object list
This function destructively removes all elements `equal' to OBJECT
from LIST. It is to `delq' as `member' is to `memq': it uses
`equal' to compare elements with OBJECT, like `member'; when it
\1f
File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
-Association Lists
-=================
+11.8 Association Lists
+======================
An "association list", or "alist" for short, records a mapping from
keys to values. It is a list of cons cells called "associations": the
each key can occur only once. *Note Property Lists::, for a comparison
of property lists and association lists.
- - Function: assoc key alist
+ -- Function: assoc key alist
This function returns the first association for KEY in ALIST. It
compares KEY against the alist elements using `equal' (*note
Equality Predicates::). It returns `nil' if no association in
'((2 "Austrian Pine" "Red Pine")
(3 "Pitch Pine")
(5 "White Pine")))
-
+
(cdr (assoc 3 needles-per-cluster))
=> ("Pitch Pine")
(cdr (assoc 2 needles-per-cluster))
=> ("Austrian Pine" "Red Pine")
- - Function: rassoc value alist
+ -- Function: rassoc value alist
This function returns the first association with value VALUE in
ALIST. It returns `nil' if no association in ALIST has a CDR
`equal' to VALUE.
ALIST association instead of the CAR. You can think of this as
"reverse `assoc'", finding the key for a given value.
- - Function: assq key alist
+ -- Function: assq key alist
This function is like `assoc' in that it returns the first
association for KEY in ALIST, but it makes the comparison using
`eq' instead of `equal'. `assq' returns `nil' if no association
(setq leaves
'(("simple leaves" . oak)
("compound leaves" . horsechestnut)))
-
+
(assq "simple leaves" leaves)
=> nil
(assoc "simple leaves" leaves)
=> ("simple leaves" . oak)
- - Function: rassq value alist
+ -- Function: rassq value alist
This function returns the first association with value VALUE in
ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
to VALUE.
For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-
+
(rassq 'acorns trees)
=> (oak . acorns)
(rassq 'spores trees)
the CDR of an element:
(setq colors '((rose red) (lily white) (buttercup yellow)))
-
+
(rassq 'white colors)
=> nil
(lily white) == (lily . (white))
- - Function: remassoc key alist
+ -- Function: remassoc key alist
This function deletes by side effect any associations with key KEY
in ALIST--i.e. it removes any elements from ALIST whose `car' is
`equal' to KEY. The modified ALIST is returned.
`(setq foo (remassoc key foo))' to be sure of changing the value
of `foo'.
- - Function: remassq key alist
+ -- Function: remassq key alist
This function deletes by side effect any associations with key KEY
in ALIST--i.e. it removes any elements from ALIST whose `car' is
`eq' to KEY. The modified ALIST is returned.
This function is exactly like `remassoc', but comparisons between
KEY and keys in ALIST are done using `eq' instead of `equal'.
- - Function: remrassoc value alist
+ -- Function: remrassoc value alist
This function deletes by side effect any associations with value
VALUE in ALIST--i.e. it removes any elements from ALIST whose
`cdr' is `equal' to VALUE. The modified ALIST is returned.
as "reverse `remassoc'", removing an association based on its
value instead of its key.
- - Function: remrassq value alist
+ -- Function: remrassq value alist
This function deletes by side effect any associations with value
VALUE in ALIST--i.e. it removes any elements from ALIST whose
`cdr' is `eq' to VALUE. The modified ALIST is returned.
This function is exactly like `remrassoc', but comparisons between
VALUE and values in ALIST are done using `eq' instead of `equal'.
- - Function: copy-alist alist
+ -- Function: copy-alist alist
This function returns a two-level deep copy of ALIST: it creates a
new copy of each association, so that you can alter the
associations of the new alist without changing the old one.
((2 "Austrian Pine" "Red Pine")
(3 "Pitch Pine")
(5 "White Pine"))
-
+
(setq copy (copy-alist needles-per-cluster))
=>
((2 "Austrian Pine" "Red Pine")
(3 "Pitch Pine")
(5 "White Pine"))
-
+
(eq needles-per-cluster copy)
=> nil
(equal needles-per-cluster copy)
\1f
File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
-Property Lists
-==============
+11.9 Property Lists
+===================
A "property list" (or "plist") is another way of representing a mapping
from keys to values. Instead of the list consisting of conses of a key
compared with `eq', and "lax" plists, whose keys are compared with
`equal',
- - Function: valid-plist-p plist
+ -- Function: valid-plist-p plist
Given a plist, this function returns non-`nil' if its format is
correct. If it returns `nil', `check-valid-plist' will signal an
error when given the plist; that means it's a malformed or circular
plist or has non-symbols as keywords.
- - Function: check-valid-plist plist
+ -- Function: check-valid-plist plist
Given a plist, this function signals an error if there is anything
wrong with it. This means that it's a malformed or circular plist.
\1f
File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
-Working With Normal Plists
---------------------------
+11.9.1 Working With Normal Plists
+---------------------------------
- - Function: plist-get plist property &optional default
+ -- Function: plist-get plist property &optional default
This function extracts a value from a property list. The function
returns the value corresponding to the given PROPERTY, or DEFAULT
if PROPERTY is not one of the properties on the list.
- - Function: plist-put plist property value
+ -- Function: plist-put plist property value
This function changes the value in PLIST of PROPERTY to VALUE. If
PROPERTY is already a property on the list, its value is set to
VALUE, otherwise the new PROPERTY VALUE pair is added. The new
be sure to use the new value. The PLIST is modified by side
effects.
- - Function: plist-remprop plist property
+ -- Function: plist-remprop plist property
This function removes from PLIST the property PROPERTY and its
value. The new plist is returned; use `(setq x (plist-remprop x
property))' to be sure to use the new value. The PLIST is
modified by side effects.
- - Function: plist-member plist property
+ -- Function: plist-member plist property
This function returns `t' if PROPERTY has a value specified in
PLIST.
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.
- - Function: plists-eq a b &optional nil-means-not-present
+ -- Function: plists-eq a b &optional nil-means-not-present
This function returns non-`nil' if property lists A and B are `eq'
(i.e. their values are `eq').
- - Function: plists-equal a b &optional nil-means-not-present
+ -- Function: plists-equal a b &optional nil-means-not-present
This function returns non-`nil' if property lists A and B are
`equal' (i.e. their values are `equal'; their keys are still
compared using `eq').
- - Function: canonicalize-plist plist &optional nil-means-not-present
+ -- Function: canonicalize-plist plist &optional nil-means-not-present
This function destructively removes any duplicate entries from a
plist. In such cases, the first entry applies.
\1f
File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
-Working With Lax Plists
------------------------
+11.9.2 Working With Lax Plists
+------------------------------
Recall that a "lax plist" is a property list whose keys are compared
using `equal' instead of `eq'.
- - Function: lax-plist-get lax-plist property &optional default
+ -- Function: lax-plist-get lax-plist property &optional default
This function extracts a value from a lax property list. The
function returns the value corresponding to the given PROPERTY, or
DEFAULT if PROPERTY is not one of the properties on the list.
- - Function: lax-plist-put lax-plist property value
+ -- Function: lax-plist-put lax-plist property value
This function changes the value in LAX-PLIST of PROPERTY to VALUE.
- - Function: lax-plist-remprop lax-plist property
+ -- Function: lax-plist-remprop lax-plist property
This function removes from LAX-PLIST the property PROPERTY and its
value. The new plist is returned; use `(setq x (lax-plist-remprop
x property))' to be sure to use the new value. The LAX-PLIST is
modified by side effects.
- - Function: lax-plist-member lax-plist property
+ -- Function: lax-plist-member lax-plist property
This function returns `t' if PROPERTY has a value specified in
LAX-PLIST.
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.
- - Function: lax-plists-eq a b &optional nil-means-not-present
+ -- Function: lax-plists-eq a b &optional nil-means-not-present
This function returns non-`nil' if lax property lists A and B are
`eq' (i.e. their values are `eq'; their keys are still compared
using `equal').
- - Function: lax-plists-equal a b &optional nil-means-not-present
+ -- Function: lax-plists-equal a b &optional nil-means-not-present
This function returns non-`nil' if lax property lists A and B are
`equal' (i.e. their values are `equal').
- - Function: canonicalize-lax-plist lax-plist &optional
+ -- Function: canonicalize-lax-plist lax-plist &optional
nil-means-not-present
This function destructively removes any duplicate entries from a
lax plist. In such cases, the first entry applies.
\1f
File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
-Converting Plists To/From Alists
---------------------------------
+11.9.3 Converting Plists To/From Alists
+---------------------------------------
- - Function: alist-to-plist alist
+ -- Function: alist-to-plist alist
This function converts association list ALIST into the equivalent
property-list form. The plist is returned. This converts from
The original alist is not modified.
- - Function: plist-to-alist plist
+ -- Function: plist-to-alist plist
This function converts property list PLIST into the equivalent
association-list form. The alist is returned. This converts from
from the original list to form the new list rather than allocating new
cons cells.
- - Function: destructive-alist-to-plist alist
+ -- Function: destructive-alist-to-plist alist
This function destructively converts association list ALIST into
the equivalent property-list form. The plist is returned.
- - Function: destructive-plist-to-alist plist
+ -- Function: destructive-plist-to-alist plist
This function destructively converts property list PLIST into the
equivalent association-list form. The alist is returned.
\1f
File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
-Weak Lists
-==========
+11.10 Weak Lists
+================
A "weak list" is a special sort of list whose members are not counted
as references for the purpose of garbage collection. This means that,
Weak lists are similar to weak hash tables (*note Weak Hash
Tables::).
- - Function: weak-list-p object
+ -- Function: weak-list-p object
This function returns non-`nil' if OBJECT is a weak list.
Weak lists come in one of four types:
Objects in the list disappear if they are conses and the cdr is not
referenced outside of the list.
- - Function: make-weak-list &optional type
+ -- Function: make-weak-list &optional type
This function creates a new weak list of type TYPE. TYPE is a
symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
as described above) and defaults to `simple'.
- - Function: weak-list-type weak
+ -- Function: weak-list-type weak
This function returns the type of the given weak-list object.
- - Function: weak-list-list weak
+ -- Function: weak-list-list weak
This function returns the list contained in a weak-list object.
- - Function: set-weak-list-list weak new-list
+ -- Function: set-weak-list-list weak new-list
This function changes the list contained in a weak-list object.
\1f
File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
-Sequences, Arrays, and Vectors
-******************************
+12 Sequences, Arrays, and Vectors
+*********************************
Recall that the "sequence" type is the union of four other Lisp types:
lists, vectors, bit vectors, and strings. In other words, any list is
\1f
File: lispref.info, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors
-Sequences
-=========
+12.1 Sequences
+==============
In XEmacs Lisp, a "sequence" is either a list, a vector, a bit vector,
or a string. The common property that all sequences have is 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.
=> [foo (1 2)]
(setq y (copy-sequence x))
=> [foo (1 2)]
-
+
(eq x y)
=> nil
(equal x y)
=> t
(eq (elt x 1) (elt y 1))
=> t
-
+
;; Replacing an element of one sequence.
(aset x 0 'quux)
x => [quux (1 2)]
y => [foo (1 2)]
-
+
;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x => [quux (69 2)]
y => [foo (69 2)]
-
+
;; Creating a bit vector.
(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
\1f
File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
-Arrays
-======
+12.2 Arrays
+===========
An "array" object has slots that hold a number of other Lisp objects,
called the elements of the array. Any element of an array may be
\1f
File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors
-Functions that Operate on Arrays
-================================
+12.3 Functions that Operate on Arrays
+=====================================
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.
=> 11
(elt primes 4)
=> 11
-
+
(aref "abcdefg" 1)
=> ?b
-
+
(aref #*1101 2)
=> 0
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.
=> fu
w
=> [fu bar baz]
-
+
(setq x "asdfasfd")
=> "asdfasfd"
(aset x 3 ?Z)
=> ?Z
x
=> "asdZasfd"
-
+
(setq bv #*1111)
=> #*1111
(aset bv 2 0)
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.
=> [0 0 0 0 0 0 0]
a
=> [0 0 0 0 0 0 0]
-
+
(setq s "When in the course")
=> "When in the course"
(fillarray s ?-)
=> "------------------"
-
+
(setq bv #*1101)
=> #*1101
(fillarray bv 0)
\1f
File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors
-Vectors
-=======
+12.4 Vectors
+============
Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time. A "vector" is a
\1f
File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors
-Functions That Operate on Vectors
-=================================
+12.5 Functions That Operate on Vectors
+======================================
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.
\1f
File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors
-Bit Vectors
-===========
+12.6 Bit Vectors
+================
Bit vectors are specialized vectors that can only represent arrays of
1's and 0's. Bit vectors have a very efficient representation and are
\1f
File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors
-Functions That Operate on Bit Vectors
-=====================================
+12.7 Functions That Operate on Bit Vectors
+==========================================
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 bits
+ -- Function: bit-vector &rest bits
This function creates and returns a bit vector whose elements are
the arguments BITS. Each argument must be a bit, i.e. one of the
two integers 0 or 1.
(bit-vector)
=> #*
- - Function: make-bit-vector length bit
+ -- Function: make-bit-vector length bit
This function creates and returns a bit vector consisting of
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
\1f
File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top
-Symbols
-*******
+13 Symbols
+**********
A "symbol" is an object with a unique name. This chapter describes
symbols, their components, their property lists, and how they are
created and interned. Separate chapters describe the use of symbols as
variables and as function names; see *Note Variables::, and *Note
-Functions::. For the precise read syntax for symbols, see *Note Symbol
-Type::.
+Functions and Commands::. For the precise read syntax for symbols, see
+*Note Symbol Type::.
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:
\1f
File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols
-Symbol Components
-=================
+13.1 Symbol Components
+======================
Each symbol has four components (or "cells"), each of which references
another object:
\1f
File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
-Defining Symbols
-================
+13.2 Defining Symbols
+=====================
A "definition" in Lisp is a special form that announces your intention
to use a certain symbol in a particular way. In XEmacs Lisp, you can
term "function definition", meaning the contents of the function cell,
is derived from the idea that `defun' gives the symbol its definition
as a function.) `defsubst', `define-function' and `defalias' are other
-ways of defining a function. *Note Functions::.
+ways of defining a function. *Note Functions and Commands::.
`defmacro' defines a symbol as a macro. It creates a macro object
and stores it in the function cell of the symbol. Note that a given
\1f
File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols
-Creating and Interning Symbols
-==============================
+13.3 Creating and Interning Symbols
+===================================
To understand how symbols are created in XEmacs Lisp, you must know how
Lisp reads them. Lisp must ensure that it finds the same symbol every
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
=> foo
(eq sym 'foo)
=> t
-
+
(setq sym1 (intern "foo" other-obarray))
=> foo
(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
(eq sym 'frazzle) ; And it is the same one.
=> t
- - Variable: obarray
+ -- Variable: obarray
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.
\1f
File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols
-Symbol Properties
-=================
+13.4 Symbol Properties
+======================
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
\1f
File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties
-Property Lists and Association Lists
-------------------------------------
+13.4.1 Property Lists and Association Lists
+-------------------------------------------
Association lists (*note Association Lists::) are very similar to
property lists. In contrast to association lists, the order of the
\1f
File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
-Property List Functions for Objects
------------------------------------
+13.4.2 Property List Functions for Objects
+------------------------------------------
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
+ -- Function: symbol-plist symbol
This function returns the property list of SYMBOL.
- - Function: object-plist object
+ -- 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
+ -- 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.
instead. `setplist' can only be used with symbols, not other
object types.
- - Function: get object property &optional default
+ -- Function: get object property &optional default
This function finds the value of the property named PROPERTY in
OBJECT's property list. If there is no such property, `default'
(which itself defaults to `nil') is returned.
See `put' for an example.
- - Function: put object property value
+ -- 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.
(object-plist 'fly)
=> (verb transitive noun (a buzzing little bug))
- - Function: remprop object property
+ -- 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
\1f
File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties
-Property Lists Not Associated with Objects
-------------------------------------------
+13.4.3 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
- - Macro: 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'.
\1f
File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top
-Evaluation
-**********
+14 Evaluation
+*************
The "evaluation" of expressions in XEmacs Lisp is performed by the
"Lisp interpreter"--a program that receives a Lisp object as input and
\1f
File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation
-Introduction to Evaluation
-==========================
+14.1 Introduction to Evaluation
+===============================
The Lisp interpreter, or evaluator, is the program that computes the
value of an expression that is given to it. When a function written in
function `car'.
Evaluation of a function call ultimately calls the function specified
-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::).
+in it. *Note Functions and Commands::. 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::).
The evaluation of forms takes place in a context called the
"environment", which consists of the current values and bindings of all
\1f
File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation
-Eval
-====
+14.2 Eval
+=========
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
specify limits to the evaluation process, or record recently returned
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
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.
- - Variable: max-lisp-eval-depth
+ -- Variable: max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to `eval',
`apply', and `funcall' before an error is signaled (with error
message `"Lisp nesting exceeds max-lisp-eval-depth"'). This counts
function call arguments and function body forms.
This limit, with the associated error when it is exceeded, is one
- way that Lisp avoids infinite recursion on an ill-defined function.
+ way that Lisp avoids infinite recursion on an ill-defined function.
The default value of this variable is 1000. If you set it to a
value less than 100, Lisp will reset it to 100 if the given value
`max-specpdl-size' provides another limit on nesting. *Note Local
Variables::.
- - Variable: values
+ -- Variable: values
The value of this variable is a list of the values returned by all
the expressions that were read from buffers (including the
minibuffer), evaluated, and printed. The elements are ordered
\1f
File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation
-Kinds of Forms
-==============
+14.3 Kinds of Forms
+===================
A Lisp object that is intended to be evaluated is called a "form". How
XEmacs evaluates a form depends on its data type. XEmacs has three
\1f
File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms
-Self-Evaluating Forms
----------------------
+14.3.1 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
\1f
File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
-Symbol Forms
-------------
+14.3.2 Symbol Forms
+-------------------
When a symbol is evaluated, it is treated as a variable. The result is
the variable's value, if it has one. If it has none (if its value cell
\1f
File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms
-Classification of List Forms
-----------------------------
+14.3.3 Classification of List Forms
+-----------------------------------
A form that is a nonempty list is either a function call, a macro call,
or a special form, according to its first element. These three kinds
\1f
File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
-Symbol Function Indirection
----------------------------
+14.3.4 Symbol Function Indirection
+----------------------------------
If the first element of the list is a symbol then evaluation examines
the symbol's function cell, and uses its contents instead of the
The built-in function `indirect-function' provides an easy way to
perform symbol function indirection explicitly.
- - Function: indirect-function object
+ -- Function: indirect-function object
This function returns the meaning of OBJECT as a function. If
OBJECT is a symbol, then it finds OBJECT's function definition and
starts over with that value. If OBJECT is not a symbol, then it
\1f
File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms
-Evaluation of Function Forms
-----------------------------
+14.3.5 Evaluation of Function Forms
+-----------------------------------
If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
\1f
File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms
-Lisp Macro Evaluation
----------------------
+14.3.6 Lisp Macro Evaluation
+----------------------------
If the first element of a list being evaluated is a macro object, then
the list is a "macro call". When a macro call is evaluated, the
\1f
File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms
-Special Forms
--------------
+14.3.7 Special Forms
+--------------------
A "special form" is a primitive function specially marked so that its
arguments are not all evaluated. Most special forms define control
\1f
File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms
-Autoloading
------------
+14.3.8 Autoloading
+------------------
The "autoload" feature allows you to call a function or macro whose
function definition has not yet been loaded into XEmacs. It specifies
\1f
File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation
-Quoting
-=======
+14.4 Quoting
+============
The special form `quote' returns its single argument, as written,
without evaluating it. This provides a way to include constant symbols
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)
- - Special Form: quote object
+ -- Special Form: quote object
This special form returns OBJECT, without evaluating it.
Because `quote' is used so often in programs, Lisp provides a
\1f
File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top
-Control Structures
-******************
+15 Control Structures
+*********************
A Lisp program consists of expressions or "forms" (*note Forms::). We
control the order of execution of the forms by enclosing them in
\1f
File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures
-Sequencing
-==========
+15.1 Sequencing
+===============
Evaluating forms in the order they appear is the most common way
control passes from one form to another. In some contexts, such as in a
is not used as often as it used to be. It is needed now most often
inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
- - Special Form: progn forms...
+ -- Special Form: progn forms...
This special form evaluates all of the FORMS, in textual order,
returning the result of the final form.
Two other control constructs likewise evaluate a series of forms but
return a different value:
- - Special Form: prog1 form1 forms...
+ -- Special Form: prog1 form1 forms...
This special form evaluates FORM1 and all of the FORMS, in textual
order, returning the result of FORM1.
(prog1 (car x) (setq x (cdr x)))
- - Special Form: prog2 form1 form2 forms...
+ -- Special Form: prog2 form1 form2 forms...
This special form evaluates FORM1, FORM2, and all of the following
FORMS, in textual order, returning the result of FORM2.
\1f
File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures
-Conditionals
-============
+15.2 Conditionals
+=================
Conditional control structures choose among alternatives. XEmacs Lisp
has two conditional forms: `if', which is much the same as in other
languages, and `cond', which is a generalized case statement.
- - Special Form: if condition then-form else-forms...
+ -- Special Form: if condition then-form else-forms...
`if' chooses between the THEN-FORM and the ELSE-FORMS based on the
value of CONDITION. If the evaluated CONDITION is non-`nil',
THEN-FORM is evaluated and the result returned. Otherwise, the
'very-false)
=> very-false
- - Special Form: cond clause...
+ -- Special Form: cond clause...
`cond' chooses among an arbitrary number of alternatives. Each
CLAUSE in the `cond' must be a list. The CAR of this list is the
CONDITION; the remaining elements, if any, the BODY-FORMS. Thus,
\1f
File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures
-Constructs for Combining Conditions
-===================================
+15.3 Constructs for Combining Conditions
+========================================
This section describes three constructs that are often used together
with `if' and `cond' to express complicated conditions. The constructs
`and' and `or' can also be used individually as kinds of multiple
conditional constructs.
- - Function: not condition
+ -- Function: not condition
This function tests for the falsehood of CONDITION. It returns
`t' if CONDITION is `nil', and `nil' otherwise. The function
`not' is identical to `null', and we recommend using the name
`null' if you are testing for an empty list.
- - Special Form: and conditions...
+ -- Special Form: and conditions...
The `and' special form tests whether all the CONDITIONS are true.
It works by evaluating the CONDITIONS one by one in the order
written.
==
(cond (ARG1 (cond (ARG2 ARG3))))
- - Special Form: or conditions...
+ -- Special Form: or conditions...
The `or' special form tests whether at least one of the CONDITIONS
is true. It works by evaluating all the CONDITIONS one by one in
the order written.
\1f
File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures
-Iteration
-=========
+15.4 Iteration
+==============
Iteration means executing part of a program repetitively. For example,
you might want to repeat some computation once for each element of a
list, or once for each integer from 0 to N. You can do this in XEmacs
Lisp with the special form `while':
- - Special Form: while condition forms...
+ -- Special Form: while condition forms...
`while' first evaluates CONDITION. If the result is non-`nil', it
evaluates FORMS in textual order. Then it reevaluates CONDITION,
and if the result is non-`nil', it evaluates FORMS again. This
\1f
File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures
-Nonlocal Exits
-==============
+15.5 Nonlocal Exits
+===================
A "nonlocal exit" is a transfer of control from one point in a program
to another remote point. Nonlocal exits can occur in XEmacs Lisp as a
\1f
File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits
-Explicit Nonlocal Exits: `catch' and `throw'
---------------------------------------------
+15.5.1 Explicit Nonlocal Exits: `catch' and `throw'
+---------------------------------------------------
Most control constructs affect only the flow of control within the
construct itself. The function `throw' is the exception to this rule
`return', `return-from', and `go', for example. XEmacs Lisp has
only `throw'.
- - Special Form: catch tag body...
+ -- Special Form: catch tag body...
`catch' establishes a return point for the `throw' function. The
return point is distinguished from other such return points by TAG,
which may be any Lisp object. The argument TAG is evaluated
the `catch' exits immediately; the value it returns is whatever
was specified as the second argument of `throw'.
- - Function: throw tag value
+ -- Function: throw tag value
The purpose of `throw' is to return from a return point previously
established with `catch'. The argument TAG is used to choose
among the various existing return points; it must be `eq' to the
\1f
File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits
-Examples of `catch' and `throw'
--------------------------------
+15.5.2 Examples of `catch' and `throw'
+--------------------------------------
One way to use `catch' and `throw' is to exit from a doubly nested
loop. (In most languages, this would be done with a "go to".) Here we
(catch tag
(throw 'hack 'yes)))
=> catch2
-
+
(catch 'hack
(print (catch2 'hack))
'no)
(catch tag
(throw 'hack 'yes)))
=> catch2
-
+
(catch 'hack
(print (catch2 'quux))
'no)
\1f
File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits
-Errors
-------
+15.5.3 Errors
+-------------
When XEmacs Lisp attempts to evaluate a form that, for some reason,
cannot be evaluated, it "signals" an "error".
\1f
File: lispref.info, Node: Signaling Errors, Next: Processing of Errors, Up: Errors
-How to Signal an Error
-......................
+15.5.3.1 How to Signal an Error
+...............................
Most errors are signaled "automatically" within Lisp primitives which
you call for other purposes, such as if you try to take the CAR of an
malformed-property-list
circular-list
circular-property-list
-
+
invalid-argument
wrong-type-argument
args-out-of-range
wrong-number-of-arguments
invalid-function
no-catch
-
+
invalid-state
void-function
cyclic-function-indirection
void-variable
cyclic-variable-indirection
-
+
invalid-operation
invalid-change
setting-constant
errors (e.g. running off the end of a buffer), `invalid-change' as
just mentioned, and arithmetic errors.
- - Function: error datum &rest args
+ -- Function: error datum &rest args
This function signals a non-continuable error.
DATUM should normally be an error symbol, i.e. a symbol defined
(error 'syntax-error
"Dialog descriptor must supply at least one button"
descriptor)
-
+
(error "You have committed an error.
Try something else.")
error--> You have committed an error.
Try something else.
-
+
(error "You have committed %d errors." 10)
error--> You have committed 10 errors.
will be interpreted as a format specifier, with undesirable
results. Instead, use `(error "%s" STRING)'.
- - Function: cerror datum &rest args
+ -- Function: cerror datum &rest args
This function behaves like `error', except that the error it
signals is continuable. That means that debugger commands `c' and
`r' can resume execution.
- - Function: signal error-symbol data
+ -- Function: signal error-symbol data
This function signals a continuable error named by ERROR-SYMBOL.
The argument DATA is a list of additional Lisp objects relevant to
the circumstances of the error.
(signal 'wrong-number-of-arguments '(x y))
error--> Wrong number of arguments: x, y
-
+
(signal 'no-such-error '("My unknown error condition"))
error--> Peculiar error (no-such-error "My unknown error condition")
- - Function: signal-error error-symbol data
+ -- Function: signal-error error-symbol data
This function behaves like `signal', except that the error it
signals is not continuable.
- - Macro: check-argument-type predicate argument
+ -- Macro: check-argument-type predicate argument
This macro checks that ARGUMENT satisfies PREDICATE. If that is
not the case, it signals a continuable `wrong-type-argument' error
until the returned value satisfies PREDICATE, and assigns the
\1f
File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors
-How XEmacs Processes Errors
-...........................
+15.5.3.2 How XEmacs Processes Errors
+....................................
When an error is signaled, `signal' searches for an active "handler"
for the error. A handler is a sequence of Lisp expressions designated
formatted error message to the echo area. The functions that do the
formatting are explained below.
- - Function: display-error error-object stream
+ -- Function: display-error error-object stream
This function displays ERROR-OBJECT on STREAM. ERROR-OBJECT is a
cons of error type, a symbol, and error arguments, a list. If the
error type symbol of one of its error condition superclasses has a
the actual error message. Otherwise, the error is printed as
`Error: arg1, arg2, ...'.
- - Function: error-message-string error-object
+ -- Function: error-message-string error-object
This function converts ERROR-OBJECT to an error message string,
and returns it. The message is equivalent to the one that would be
printed by `display-error', except that it is conveniently returned
\1f
File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors
-Writing Code to Handle Errors
-.............................
+15.5.3.3 Writing Code to Handle Errors
+......................................
The usual effect of signaling an error is to terminate the command that
is running and return immediately to the XEmacs editor command loop.
handler (though using `throw' when there is no suitable `catch' signals
an error that can be handled).
- - Special Form: condition-case var protected-form handlers...
+ -- Special Form: condition-case var protected-form handlers...
This special form establishes the error handlers HANDLERS around
the execution of PROTECTED-FORM. If PROTECTED-FORM executes
without error, the value it returns becomes the value of the
of handlers:
(error nil)
-
+
(arith-error (message "Division by zero"))
-
+
((arith-error file-error)
(message
"Either division by zero or failure to open a file"))
(princ (format "Arithmetic error: %s" err))
1000000)))
=> safe-divide
-
+
(safe-divide 5 0)
-| Arithmetic error: (arith-error)
=> 1000000
(setq baz 34)
=> 34
-
+
(condition-case err
(if (eq baz 35)
t
\1f
File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
-Error Symbols and Condition Names
-.................................
+15.5.3.4 Error Symbols and Condition Names
+..........................................
When you signal an error, you specify an "error symbol" to specify the
kind of error you have in mind. Each error has one and only one error
In other words, each error condition "inherits" from another error
condition, with `error' sitting at the top of the inheritance hierarchy.
- - Function: define-error error-symbol error-message &optional
+ -- Function: define-error error-symbol error-message &optional
inherits-from
This function defines a new error, denoted by ERROR-SYMBOL.
ERROR-MESSAGE is an informative message explaining the error, and
\1f
File: lispref.info, Node: Cleanups, Prev: Errors, Up: Nonlocal Exits
-Cleaning Up from Nonlocal Exits
--------------------------------
+15.5.4 Cleaning Up from Nonlocal Exits
+--------------------------------------
The `unwind-protect' construct is essential whenever you temporarily
put a data structure in an inconsistent state; it permits you to ensure
the data are consistent in the event of an error or throw.
- - Special Form: unwind-protect body cleanup-forms...
+ -- Special Form: unwind-protect body cleanup-forms...
`unwind-protect' executes the BODY with a guarantee that the
CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
how that happens. The BODY may complete normally, or execute a
(kill-buffer (current-buffer)))))
\1f
-File: lispref.info, Node: Variables, Next: Functions, Prev: Control Structures, Up: Top
+File: lispref.info, Node: Variables, Next: Functions and Commands, Prev: Control Structures, Up: Top
-Variables
-*********
+16 Variables
+************
A "variable" is a name used in a program to stand for a value. Nearly
all programming languages have variables of some sort. In the text of
\1f
File: lispref.info, Node: Global Variables, Next: Constant Variables, Up: Variables
-Global Variables
-================
+16.1 Global Variables
+=====================
The simplest way to use a variable is "globally". This means that the
variable has just one value at a time, and this value is in effect (at
\1f
File: lispref.info, Node: Constant Variables, Next: Local Variables, Prev: Global Variables, Up: Variables
-Variables That Never Change
-===========================
+16.2 Variables That Never Change
+================================
In XEmacs Lisp, some symbols always evaluate to themselves: the two
special symbols `nil' and `t', as well as "keyword symbols", that is,
\1f
File: lispref.info, Node: Local Variables, Next: Void Variables, Prev: Constant Variables, Up: Variables
-Local Variables
-===============
+16.3 Local Variables
+====================
Global variables have values that last until explicitly superseded with
new values. Sometimes it is useful to create variable values that
The special forms `let' and `let*' exist to create local bindings.
- - Special Form: let (bindings...) forms...
+ -- Special Form: let (bindings...) forms...
This special form binds variables according to BINDINGS and then
evaluates all of the FORMS in textual order. The `let'-form
returns the value of the last form in FORMS.
(list Y Z))
=> (1 2)
- - Special Form: let* (bindings...) forms...
+ -- Special Form: let* (bindings...) forms...
This special form is like `let', but it binds each variable right
after computing its local value, before computing the local value
for the next variable. Therefore, an expression in BINDINGS can
Here is a complete list of the other facilities that create local
bindings:
- * Function calls (*note Functions::).
+ * Function calls (*note Functions and Commands::).
* Macro calls (*note Macros::).
bindings, but they are localized depending on "where" you are in Emacs,
rather than localized in time.
- - Variable: max-specpdl-size
+ -- Variable: max-specpdl-size
This variable defines the limit on the total number of local
variable bindings and `unwind-protect' cleanups (*note Nonlocal
Exits::) that are allowed before signaling an error (with data
\1f
File: lispref.info, Node: Void Variables, Next: Defining Variables, Prev: Local Variables, Up: Variables
-When a Variable is "Void"
-=========================
+16.4 When a Variable is "Void"
+==============================
If you have never given a symbol any value as a global variable, we say
that that symbol's global value is "void". In other words, the
After you have given a variable a value, you can make it void once
more using `makunbound'.
- - Function: makunbound symbol
+ -- Function: makunbound symbol
This function makes the current binding of SYMBOL void.
Subsequent attempts to use this symbol's value as a variable will
signal the error `void-variable', unless or until you set it again.
error--> Symbol's value as variable is void: x
x ; The global binding is unchanged.
=> 1
-
+
(let ((x 2)) ; Locally bind it.
(let ((x 3)) ; And again.
(makunbound 'x) ; Void the innermost-local binding.
x)) ; And refer: it's void.
error--> Symbol's value as variable is void: x
-
+
(let ((x 2))
(let ((x 3))
(makunbound 'x)) ; Void inner binding, then remove it.
You can use the function `boundp' to test whether a variable is
currently void.
- - Function: boundp variable
+ -- Function: boundp variable
`boundp' returns `t' if VARIABLE (a symbol) is not void; more
precisely, if its current binding is not void. It returns `nil'
otherwise.
\1f
File: lispref.info, Node: Defining Variables, Next: Accessing Variables, Prev: Void Variables, Up: Variables
-Defining Global Variables
-=========================
+16.5 Defining Global Variables
+==============================
You may announce your intention to use a symbol as a global variable
with a "variable definition": a special form, either `defconst' or
and override the default values given in the definitions. For this
reason, user options must be defined with `defvar'.
- - Special Form: defvar symbol [value [doc-string]]
+ -- Special Form: defvar symbol [value [doc-string]]
This special form defines SYMBOL as a value and initializes it.
The definition informs a person reading your code that SYMBOL is
used as a variable that programs are likely to set or change. It
The `defvar' form returns SYMBOL, but it is normally used at top
level in a file where its value does not matter.
- - Special Form: defconst symbol [value [doc-string]]
+ -- Special Form: defconst symbol [value [doc-string]]
This special form defines SYMBOL as a value and initializes it.
It informs a person reading your code that SYMBOL has a global
value, established here, that will not normally be changed or
pi
=> 3
- - Function: user-variable-p variable
+ -- Function: user-variable-p variable
This function returns `t' if VARIABLE is a user option--a variable
intended to be set by the user for customization--and `nil'
otherwise. (Variables other than user options exist for the
\1f
File: lispref.info, Node: Accessing Variables, Next: Setting Variables, Prev: Defining Variables, Up: Variables
-Accessing Variable Values
-=========================
+16.6 Accessing Variable Values
+==============================
The usual way to reference a variable is to write the symbol which
names it (*note Symbol Forms::). This requires you to specify the
you want to do. Occasionally you need to choose at run time which
variable to reference; then you can use `symbol-value'.
- - Function: symbol-value symbol
+ -- Function: symbol-value symbol
This function returns the value of SYMBOL. This is the value in
the innermost local binding of the symbol, or its global value if
it has no local bindings.
=> 5
(setq foo 9)
=> 9
-
+
;; Here the symbol `abracadabra'
;; is the symbol whose value is examined.
(let ((abracadabra 'foo))
(symbol-value 'abracadabra))
=> foo
-
+
;; Here the value of `abracadabra',
;; which is `foo',
;; is the symbol whose value is examined.
(let ((abracadabra 'foo))
(symbol-value abracadabra))
=> 9
-
+
(symbol-value 'abracadabra)
=> 5
\1f
File: lispref.info, Node: Setting Variables, Next: Variable Scoping, Prev: Accessing Variables, Up: Variables
-How to Alter a Variable Value
-=============================
+16.7 How to Alter a Variable Value
+==================================
The usual way to change the value of a variable is with the special
form `setq'. When you need to compute the choice of variable at run
time, use the function `set'.
- - Special Form: setq [symbol form]...
+ -- Special Form: setq [symbol form]...
This special form is the most common method of changing a
variable's value. Each SYMBOL is given a new value, which is the
result of evaluating the corresponding FORM. The most-local
y (1+ x)) ; the value of `y' is computed.
=> 11
- - Function: set symbol value
+ -- Function: set symbol value
This function sets SYMBOL's value to VALUE, then returns VALUE.
Since `set' is a function, the expression written for SYMBOL is
evaluated to obtain the symbol to set.
One other function for setting a variable is designed to add an
element to a list if it is not already present in the list.
- - Function: add-to-list symbol element
+ -- Function: add-to-list symbol element
This function sets the variable SYMBOL by consing ELEMENT onto the
old value, if ELEMENT is not already a member of that value. It
returns the resulting list, whether updated or not. The value of
(setq foo '(a b))
=> (a b)
-
+
(add-to-list 'foo 'c) ;; Add `c'.
=> (c a b)
-
+
(add-to-list 'foo 'b) ;; No effect.
=> (c a b)
-
+
foo ;; `foo' was changed.
=> (c a b)
\1f
File: lispref.info, Node: Variable Scoping, Next: Buffer-Local Variables, Prev: Setting Variables, Up: Variables
-Scoping Rules for Variable Bindings
-===================================
+16.8 Scoping Rules for Variable Bindings
+========================================
A given symbol `foo' may have several local variable bindings,
established at different places in the Lisp program, as well as a global
\1f
File: lispref.info, Node: Scope, Next: Extent, Up: Variable Scoping
-Scope
------
+16.8.1 Scope
+------------
XEmacs Lisp uses "indefinite scope" for local variable bindings. This
means that any function anywhere in the program text might access a
(defun binder (x) ; `x' is bound in `binder'.
(foo 5)) ; `foo' is some other function.
-
+
(defun user () ; `x' is used in `user'.
(list x))
\1f
File: lispref.info, Node: Extent, Next: Impl of Scope, Prev: Scope, Up: Variable Scoping
-Extent
-------
+16.8.2 Extent
+-------------
"Extent" refers to the time during program execution that a variable
name is valid. In XEmacs Lisp, a variable is valid only while the form
\1f
File: lispref.info, Node: Impl of Scope, Next: Using Scoping, Prev: Extent, Up: Variable Scoping
-Implementation of Dynamic Scoping
----------------------------------
+16.8.3 Implementation of Dynamic Scoping
+----------------------------------------
A simple sample implementation (which is not how XEmacs Lisp actually
works) may help you understand dynamic binding. This technique is
\1f
File: lispref.info, Node: Using Scoping, Prev: Impl of Scope, Up: Variable Scoping
-Proper Use of Dynamic Scoping
------------------------------
+16.8.4 Proper Use of Dynamic Scoping
+------------------------------------
Binding a variable in one function and using it in another is a
powerful technique, but if used without restraint, it can make programs
\1f
File: lispref.info, Node: Buffer-Local Variables, Next: Variable Aliases, Prev: Variable Scoping, Up: Variables
-Buffer-Local Variables
-======================
+16.9 Buffer-Local Variables
+===========================
Global and local variable bindings are found in most programming
languages in one form or another. XEmacs also supports another, unusual
\1f
File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
-Introduction to Buffer-Local Variables
---------------------------------------
+16.9.1 Introduction to Buffer-Local Variables
+---------------------------------------------
A buffer-local variable has a buffer-local binding associated with a
particular buffer. The binding is in effect when that buffer is
\1f
File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
-Creating and Deleting Buffer-Local Bindings
--------------------------------------------
+16.9.2 Creating and Deleting Buffer-Local Bindings
+--------------------------------------------------
- - Command: make-local-variable variable
+ -- Command: make-local-variable variable
This function creates a buffer-local binding in the current buffer
for VARIABLE (a symbol). Other buffers are not affected. The
value returned is VARIABLE.
=> 6 ; in `b1'.
foo
=> 6
-
+
;; In buffer `b2', the value hasn't changed.
(save-excursion
(set-buffer "b2")
*Please note:* do not use `make-local-variable' for a hook
variable. Instead, use `make-local-hook'. *Note Hooks::.
- - Command: make-variable-buffer-local variable
+ -- Command: make-variable-buffer-local variable
This function marks VARIABLE (a symbol) automatically
buffer-local, so that any subsequent attempt to set it will make it
local to the current buffer at the time.
The value returned is VARIABLE.
- - Function: local-variable-p variable buffer &optional after-set
+ -- Function: local-variable-p variable buffer &optional after-set
This returns `t' if VARIABLE is buffer-local in buffer BUFFER;
else `nil'.
indicates that the variable has had `make-variable-buffer-local'
applied to it.
- - Function: buffer-local-variables &optional buffer
+ -- Function: buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables
in buffer BUFFER. It returns an association list (*note
Association Lists::) in which each association contains one
Note that storing new values into the CDRs of cons cells in this
list does _not_ change the local values of the variables.
- - Command: kill-local-variable variable
+ -- Command: kill-local-variable variable
This function deletes the buffer-local binding (if any) for
VARIABLE (a symbol) in the current buffer. As a result, the
global (default) binding of VARIABLE becomes visible in this
one buffer-local variable interactively, just as it is useful to
create buffer-local variables interactively.
- - Function: kill-all-local-variables
+ -- Function: kill-all-local-variables
This function eliminates all the buffer-local variable bindings of
the current buffer except for variables marked as "permanent". As
a result, the buffer will see the default values of most variables.
\1f
File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables
-The Default Value of a Buffer-Local Variable
---------------------------------------------
+16.9.3 The Default Value of a Buffer-Local Variable
+---------------------------------------------------
The global value of a variable with buffer-local bindings is also
called the "default" value, because it is the value that is in effect
The special forms `defvar' and `defconst' also set the default value
(if they set the variable at all), rather than any local value.
- - Function: default-value symbol
+ -- Function: default-value symbol
This function returns SYMBOL's default value. This is the value
that is seen in buffers that do not have their own values for this
variable. If SYMBOL is not buffer-local, this is equivalent to
`symbol-value' (*note Accessing Variables::).
- - Function: default-boundp symbol
+ -- Function: default-boundp symbol
The function `default-boundp' tells you whether SYMBOL's default
value is nonvoid. If `(default-boundp 'foo)' returns `nil', then
`(default-value 'foo)' would get an error.
`default-boundp' is to `default-value' as `boundp' is to
`symbol-value'.
- - Special Form: setq-default symbol value
+ -- Special Form: setq-default symbol value
This sets the default value of SYMBOL to VALUE. It does not
evaluate SYMBOL, but does evaluate VALUE. The value of the
`setq-default' form is VALUE.
=> value-in-foo
(default-value 'local)
=> new-default
-
+
;; In (the new) buffer `bar':
local
=> new-default
=> another-default
(default-value 'local)
=> another-default
-
+
;; Back in buffer `foo':
local
=> value-in-foo
(default-value 'local)
=> another-default
- - Function: set-default symbol value
+ -- Function: set-default symbol value
This function is like `setq-default', except that SYMBOL is
evaluated.
\1f
File: lispref.info, Node: Variable Aliases, Prev: Buffer-Local Variables, Up: Variables
-Variable Aliases
-================
+16.10 Variable Aliases
+======================
You can define a variable as an "alias" for another. Any time you
reference the former variable, the current value of the latter is
you want to rename a variable but still make old code work (*note
Obsoleteness::).
- - Function: defvaralias variable alias
+ -- Function: defvaralias variable alias
This function defines VARIABLE as an alias for ALIAS.
Thenceforth, any operations performed on VARIABLE will actually be
performed on ALIAS. Both VARIABLE and ALIAS should be symbols.
variable, a variable that has a buffer-local value in any buffer,
or the symbols `nil' or `t'.
- - Function: variable-alias variable &optional follow-past-lisp-magic
+ -- Function: variable-alias variable &optional follow-past-lisp-magic
If VARIABLE is aliased to another variable, this function returns
that variable. VARIABLE should be a symbol. If VARIABLE is not
aliased, this function returns `nil'.
- - Function: indirect-variable object &optional follow-past-lisp-magic
+ -- Function: indirect-variable object &optional follow-past-lisp-magic
This function returns the variable at the end of OBJECT's
variable-alias chain. If OBJECT is a symbol, follow all variable
aliases and return the final (non-aliased) symbol. If OBJECT is
variable chain of symbols.
\1f
-File: lispref.info, Node: Functions, Next: Macros, Prev: Variables, Up: Top
+File: lispref.info, Node: Functions and Commands, Next: Macros, Prev: Variables, Up: Top
-Functions
-*********
+17 Functions and Commands
+*************************
A Lisp program is composed mainly of Lisp functions. This chapter
explains what functions are, how they accept arguments, and how to
that have a special bearing on how functions work.
\1f
-File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions
+File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions and Commands
-What Is a Function?
-===================
+17.1 What Is a Function?
+========================
In a general sense, a function is a rule for carrying on a computation
given several values called "arguments". The result of the computation
specifically to mean a function written in Lisp. Special forms and
macros are not functions.
+"command"
+ A "command" is a possible definition for a key sequence--we count
+ mouse events and menu accesses as key sequences for this purpose.
+ More formally, within XEmacs lisp, a command is something that
+ `command-execute' can invoke.
+
+ Some functions are commands; a function written in Lisp is a
+ command if it contains an interactive declaration. A trivial
+ interactive declaration is a line `(interactive)' immediately
+ after the documentation string. For more complex examples, with
+ prompting and completion, see *Note Defining Commands::. Such a
+ function can be called from Lisp expressions like other functions;
+ in this case, the fact that the function is a command makes no
+ difference.
+
+ Keyboard macros (strings and vectors) are commands also, even
+ though they are not functions. A symbol is a command if its
+ function definition is a command; such symbols can be invoked with
+ `M-x'. The symbol is a function as well if the definition is a
+ function.
+
+ In the case where you want to call a command in reaction to a
+ user-generated event, you'll need to bind it to that event. For
+ how to do this, see *Note Key Binding Commands::. *Note Command
+ Overview::.
+
+"keystroke command"
+ A "keystroke command" is a command that is bound to a key sequence
+ (typically one to three keystrokes). The distinction is made here
+ merely to avoid confusion with the meaning of "command" in
+ non-Emacs editors; for Lisp programs, the distinction is normally
+ unimportant.
+
"primitive"
A "primitive" is a function callable from Lisp that is written in
C, such as `car' or `append'. These functions are also called
programmers to do the sorts of things that special forms can do.
*Note Macros::, for how to define and use macros.
-"command"
- A "command" is an object that `command-execute' can invoke; it is
- a possible definition for a key sequence. Some functions are
- commands; a function written in Lisp is a command if it contains an
- interactive declaration (*note Defining Commands::). Such a
- function can be called from Lisp expressions like other functions;
- in this case, the fact that the function is a command makes no
- difference.
-
- Keyboard macros (strings and vectors) are commands also, even
- though they are not functions. A symbol is a command if its
- function definition is a command; such symbols can be invoked with
- `M-x'. The symbol is a function as well if the definition is a
- function. *Note Command Overview::.
-
-"keystroke command"
- A "keystroke command" is a command that is bound to a key sequence
- (typically one to three keystrokes). The distinction is made here
- merely to avoid confusion with the meaning of "command" in
- non-Emacs editors; for Lisp programs, the distinction is normally
- unimportant.
-
"compiled function"
A "compiled function" is a function that has been compiled by the
byte compiler. *Note Compiled-Function Type::.
- - Function: subrp object
+ -- Function: subrp object
This function returns `t' if OBJECT is a built-in function (i.e.,
a Lisp primitive).
(subrp (symbol-function 'message))
=> t
- - Function: compiled-function-p object
+ -- Function: compiled-function-p object
This function returns `t' if OBJECT is a compiled function. For
example:
=> t
\1f
-File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions
+File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions and Commands
-Lambda Expressions
-==================
+17.2 Lambda Expressions
+=======================
A function written in Lisp is a list that looks like this:
\1f
File: lispref.info, Node: Lambda Components, Next: Simple Lambda, Up: Lambda Expressions
-Components of a Lambda Expression
----------------------------------
+17.2.1 Components of a Lambda Expression
+----------------------------------------
A function written in Lisp (a "lambda expression") is a list that looks
like this:
\1f
File: lispref.info, Node: Simple Lambda, Next: Argument List, Prev: Lambda Components, Up: Lambda Expressions
-A Simple Lambda-Expression Example
-----------------------------------
+17.2.2 A Simple Lambda-Expression Example
+-----------------------------------------
Consider for example the following function:
\1f
File: lispref.info, Node: Argument List, Next: Function Documentation, Prev: Simple Lambda, Up: Lambda Expressions
-Advanced Features of Argument Lists
------------------------------------
+17.2.3 Advanced Features of Argument Lists
+------------------------------------------
Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
three argument variables, so it must be called with three arguments: if
\1f
File: lispref.info, Node: Function Documentation, Prev: Argument List, Up: Lambda Expressions
-Documentation Strings of Functions
-----------------------------------
+17.2.4 Documentation Strings of Functions
+-----------------------------------------
A lambda expression may optionally have a "documentation string" just
after the lambda list. This string does not affect execution of the
then it serves both as the return value and as the documentation.
\1f
-File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions
+File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions and Commands
-Naming a Function
-=================
+17.3 Naming a Function
+======================
In most computer languages, every function has a name; the idea of a
function without a name is nonsensical. In Lisp, a function in the
these two uses of a symbol are independent and do not conflict.
\1f
-File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions
+File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions and Commands
-Defining Functions
-==================
+17.4 Defining Functions
+=======================
We usually give a name to a function when it is first created. This is
called "defining a function", and it is done with the `defun' special
form.
- - Special Form: defun name argument-list body-forms
+ -- Special Form: defun name argument-list body-forms
`defun' is the usual way to define new Lisp functions. It defines
the symbol NAME as a function that looks like this:
=> foo
(foo)
=> 5
-
+
(defun bar (a &optional b &rest c)
(list a b c))
=> bar
=> (1 nil nil)
(bar)
error--> Wrong number of arguments.
-
+
(defun capitalize-backwards ()
"Upcase the last letter of a word."
(interactive)
distinguish deliberate redefinition from unintentional
redefinition.
- - Function: define-function name definition
- - Function: defalias name definition
+ -- Function: define-function name definition
+ -- Function: defalias name definition
These equivalent special forms define the symbol NAME as a
function, with definition DEFINITION (which can be any valid Lisp
function).
the Lisp compiler to open-code it. *Note Inline Functions::.
\1f
-File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions
+File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions and Commands
-Calling Functions
-=================
+17.5 Calling Functions
+======================
Defining functions is only half the battle. Functions don't do
anything until you "call" them, i.e., tell them to run. Calling a
run time which function to call. To do that, use the functions
`funcall' and `apply'.
- - Function: funcall function &rest arguments
+ -- Function: funcall function &rest arguments
`funcall' calls FUNCTION with ARGUMENTS, and returns whatever
FUNCTION returns.
Compare these example with the examples of `apply'.
- - Function: apply function &rest arguments
+ -- Function: apply function &rest arguments
`apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
with one difference: the last of ARGUMENTS is a list of arguments
to give to FUNCTION, rather than a single argument. We also say
=> 10
(apply '+ '(1 2 3 4))
=> 10
-
+
(apply 'append '((a b c) nil (x y z) nil))
=> (a b c x y z)
function as the argument. Here are two different kinds of no-op
function:
- - Function: identity arg
+ -- Function: identity arg
This function returns ARG and has no side effects.
- - Command: ignore &rest args
+ -- Command: ignore &rest args
This function ignores any arguments and returns `nil'.
\1f
-File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions
+File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions and Commands
-Mapping Functions
-=================
+17.6 Mapping Functions
+======================
A "mapping function" applies a given function to each element of a list
or other collection. XEmacs Lisp has several such functions; `mapcar'
Mapping functions should never modify the sequence being mapped over.
The results are unpredictable.
- - Function: mapcar function sequence
+ -- Function: mapcar function sequence
`mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
returns a list of the results.
SEQUENCE.
For example:
-
+
(mapcar 'car '((a b) (c d) (e f)))
=> (a c e)
(mapcar '1+ [1 2 3])
=> (2 3 4)
(mapcar 'char-to-string "abc")
=> ("a" "b" "c")
-
+
;; Call each function in `my-hooks'.
(mapcar 'funcall my-hooks)
-
+
(defun mapcar* (f &rest args)
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
(apply 'mapcar* f
;; Recurse for rest of elements.
(mapcar 'cdr args)))))
-
+
(mapcar* 'cons '(a b c) '(1 2 3 4))
=> ((a . 1) (b . 2) (c . 3))
- - Function: mapconcat function sequence separator
+ -- Function: mapconcat function sequence separator
`mapconcat' applies FUNCTION to each element of SEQUENCE: the
results, which must be strings, are concatenated. Between each
pair of result strings, `mapconcat' inserts the string SEPARATOR.
'(The cat in the hat)
" ")
=> "The cat in the hat"
-
+
(mapconcat (function (lambda (x) (format "%c" (1+ x))))
"HAL-8000"
"")
=> "IBM.9111"
\1f
-File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions
+File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions and Commands
-Anonymous Functions
-===================
+17.7 Anonymous Functions
+========================
In Lisp, a function is a list that starts with `lambda', a byte-code
function compiled from such a list, or alternatively a primitive
In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function.
- - Special Form: function function-object
+ -- Special Form: function function-object
This special form returns FUNCTION-OBJECT without evaluating it.
In this, it is equivalent to `quote'. However, it serves as a
note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
realistic example using `function' and an anonymous function.
\1f
-File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions
+File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions and Commands
-Accessing Function Cell Contents
-================================
+17.8 Accessing Function Cell Contents
+=====================================
The "function definition" of a symbol is the object stored in the
function cell of the symbol. The functions described here access, test,
See also the function `indirect-function' in *Note Function
Indirection::.
- - Function: symbol-function symbol
+ -- Function: symbol-function symbol
This returns the object in the function cell of SYMBOL. If the
symbol's function cell is void, a `void-function' error is
signaled.
`fboundp'. After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.
- - Function: fboundp symbol
+ -- Function: fboundp symbol
This function returns `t' if SYMBOL has an object in its function
cell, `nil' otherwise. It does not check that the object is a
legitimate function.
- - Function: fmakunbound symbol
+ -- Function: fmakunbound symbol
This function makes SYMBOL's function cell void, so that a
subsequent attempt to access this cell will cause a `void-function'
error. (See also `makunbound', in *Note Local Variables::.)
(foo 1)
error--> Symbol's function definition is void: foo
- - Function: fset symbol object
+ -- Function: fset symbol object
This function stores OBJECT in the function cell of SYMBOL. The
result is OBJECT. Normally OBJECT should be a function or the
name of a function, but this is not checked.
=> #<subr car>
(first '(1 2 3))
=> 1
-
+
;; Make the symbol `car' the function definition of `xfirst'.
(fset 'xfirst 'car)
=> car
=> car
(symbol-function (symbol-function 'xfirst))
=> #<subr car>
-
+
;; Define a named keyboard macro.
(fset 'kill-two-lines "\^u2\^k")
=> "\^u2\^k"
redefine a function defined elsewhere.
\1f
-File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions
+File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions and Commands
-Inline Functions
-================
+17.9 Inline Functions
+=====================
You can define an "inline function" by using `defsubst' instead of
`defun'. An inline function works just like an ordinary function
file, following the definition, just like macros.
\1f
-File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions
+File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions and Commands
-Other Topics Related to Functions
-=================================
+17.10 Other Topics Related to Functions
+=======================================
Here is a table of several functions that do things related to function
calling and function definitions. They are documented elsewhere, but
See *Note Key Lookup::.
\1f
-File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top
+File: lispref.info, Node: Macros, Next: Loading, Prev: Functions and Commands, Up: Top
-Macros
-******
+18 Macros
+*********
"Macros" enable you to define new control constructs and other language
features. A macro is defined much like a function, but instead of
\1f
File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros
-A Simple Example of a Macro
-===========================
+18.1 A Simple Example of a Macro
+================================
Suppose we would like to define a Lisp construct to increment a
variable value, much like the `++' operator in C. We would like to
\1f
File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros
-Expansion of a Macro Call
-=========================
+18.2 Expansion of a Macro Call
+==============================
A macro call looks just like a function call in that it is a list which
starts with the name of the macro. The rest of the elements of the list
You can see the expansion of a given macro call by calling
`macroexpand'.
- - Function: macroexpand form &optional environment
+ -- Function: macroexpand form &optional environment
This function expands FORM, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something
which is not a macro call results. That is the value returned by
(defmacro inc (var)
(list 'setq var (list '1+ var)))
=> inc
-
+
(macroexpand '(inc r))
=> (setq r (1+ r))
-
+
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
=> inc2
-
+
(macroexpand '(inc2 r s))
=> (progn (inc r) (inc s)) ; `inc' not expanded here.
\1f
File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
-Macros and Byte Compilation
-===========================
+18.3 Macros and Byte Compilation
+================================
You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion. Why not have the macro body
\1f
File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
-Defining Macros
-===============
+18.4 Defining Macros
+====================
A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
function; expansion of the macro works by applying the function (with
Lisp macros have names, and they are usually defined with the special
form `defmacro'.
- - Special Form: defmacro name argument-list body-forms...
+ -- Special Form: defmacro name argument-list body-forms...
`defmacro' defines the symbol NAME as a macro that looks like this:
(macro lambda ARGUMENT-LIST . BODY-FORMS)
\1f
File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
-Backquote
-=========
+18.5 Backquote
+==============
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro
=> (1 2 3 4 2 3)
`(1 ,@some-list 4 ,@some-list)
=> (1 2 3 4 2 3)
-
+
(setq list '(hack foo bar))
=> (hack foo bar)
(cons 'use
\1f
File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
-Common Problems Using Macros
-============================
+18.6 Common Problems Using Macros
+=================================
The basic facts of macro expansion have counterintuitive consequences.
This section describes some important consequences that can lead to
\1f
File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
-Evaluating Macro Arguments Repeatedly
--------------------------------------
+18.6.1 Evaluating Macro Arguments Repeatedly
+--------------------------------------------
When defining a macro you must pay attention to the number of times the
arguments will be evaluated when the expansion is executed. The
(cons 'while (cons (list '<= var final)
(append body (list (list 'inc var)))))))
=> for
-
+
(for i from 1 to 3 do
(setq square (* i i))
(princ (format "\n%d %d" i square)))
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
-
+
-|1 1
-|2 4
-|3 9
\1f
File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
-Local Variables in Macro Expansions
------------------------------------
+18.6.2 Local Variables in Macro Expansions
+------------------------------------------
In the previous section, the definition of `for' was fixed as follows
to make the expansion evaluate the macro arguments the proper number of
\1f
File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
-Evaluating Macro Arguments in Expansion
----------------------------------------
+18.6.3 Evaluating Macro Arguments in Expansion
+----------------------------------------------
Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
\1f
File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
-How Many Times is the Macro Expanded?
--------------------------------------
+18.6.4 How Many Times is the Macro Expanded?
+--------------------------------------------
Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is
(defmacro empty-object ()
(list 'quote (cons nil nil)))
-
+
(defun initialize (condition)
(let ((object (empty-object)))
(if condition
\1f
File: lispref.info, Node: Customization, Up: Top
-Writing Customization Definitions
-*********************************
+19 Writing Customization Definitions
+************************************
This chapter describes how to declare user options for customization,
and also customization groups for classifying them. We use the term
\1f
File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
-Common Keywords for All Kinds of Items
-======================================
+19.1 Common Keywords for All Kinds of Items
+===========================================
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
\1f
File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
-Defining Custom Groups
-======================
+19.2 Defining Custom Groups
+===========================
Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package. If the
The way to declare new customization groups is with `defgroup'.
- - Macro: defgroup group members doc [keyword value]...
+ -- Macro: defgroup group members doc [keyword value]...
Declare GROUP as a customization group containing MEMBERS. Do not
quote the symbol GROUP. The argument DOC specifies the
documentation string for the group.
\1f
File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
-Defining Customization Variables
-================================
+19.3 Defining Customization Variables
+=====================================
Use `defcustom' to declare user-editable variables.
- - Macro: defcustom option default doc [keyword value]...
+ -- Macro: defcustom option default doc [keyword value]...
Declare OPTION as a customizable user option variable. Do not
quote OPTION. The argument DOC specifies the documentation string
for the variable.
\1f
File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
-Customization Types
-===================
+19.4 Customization Types
+========================
When you define a user option with `defcustom', you must specify its
"customization type". That is a Lisp object which describes (1) which
\1f
File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
-Simple Types
-------------
+19.4.1 Simple Types
+-------------------
This section describes all the simple customization types.
\1f
File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
-Composite Types
----------------
+19.4.2 Composite Types
+----------------------
When none of the simple types is appropriate, you can use composite
types, which build new types from other types. Here are several ways of
\1f
File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
-Splicing into Lists
--------------------
+19.4.3 Splicing into Lists
+--------------------------
The `:inline' feature lets you splice a variable number of elements
into the middle of a list or vector. You use it in a `set', `choice'
\1f
File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
-Type Keywords
--------------
+19.4.4 Type Keywords
+--------------------
You can specify keyword-argument pairs in a customization type after the
type name symbol. Here are the keywords you can use, and their
\1f
File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
-Loading
-*******
+20 Loading
+**********
Loading a file of Lisp code means bringing its contents into the Lisp
environment in the form of Lisp objects. XEmacs finds and opens the
\1f
File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
-How Programs Do Loading
-=======================
+20.1 How Programs Do Loading
+============================
XEmacs Lisp has several interfaces for loading. For example,
`autoload' creates a placeholder object for a function in a file;
if it isn't already loaded (*note Named Features::). Ultimately, all
these facilities call the `load' function to do the work.
- - Function: load filename &optional missing-ok nomessage nosuffix
+ -- Function: load filename &optional missing-ok nomessage nosuffix
This function finds and opens a file of Lisp code, evaluates all
the forms in it, and closes the file.
`load' returns `t' if the file loads successfully.
- - User Option: load-path
+ -- User Option: load-path
The value of this variable is a list of directories to search when
loading files with `load'. Each element is a string (which must be
a directory name) or `nil' (which stands for the current working
should bind `load-path' locally with `let' around the calls to
`load'.
- - Function: locate-file filename path-list &optional suffixes mode
+ -- Function: locate-file filename path-list &optional suffixes mode
This function searches for a file in the same way that `load' does,
and returns the file found (if any). (In fact, `load' uses this
function to search through `load-path'.) It searches for FILENAME
you will have to call `locate-file-clear-hashing' to get it back
on track. See that function for details.
- - Function: locate-file-clear-hashing path
+ -- Function: locate-file-clear-hashing path
This function clears the hash records for the specified list of
directories. `locate-file' uses a hashing scheme to speed lookup,
and will correctly track the following environmental changes:
the directory list. In this case, you must call
`locate-file-clear-hashing'.
- - Variable: load-in-progress
+ -- Variable: load-in-progress
This variable is non-`nil' if Emacs is in the process of loading a
file, and it is `nil' otherwise.
- - Variable: load-read-function
+ -- Variable: load-read-function
This variable specifies an alternate expression-reading function
for `load' and `eval-region' to use instead of `read'. The
function should accept one argument, just as `read' does.
Normally, the variable's value is `nil', which means those
functions should use `read'.
- - User Option: load-warn-when-source-newer
+ -- User Option: load-warn-when-source-newer
This variable specifies whether `load' should check whether the
source is newer than the binary. If this variable is true, then
when a `.elc' file is being loaded and the corresponding `.el' is
newer, a warning message will be printed. The default is `nil',
but it is bound to `t' during the initial loadup.
- - User Option: load-warn-when-source-only
+ -- User Option: load-warn-when-source-only
This variable specifies whether `load' should warn when loading a
`.el' file instead of an `.elc'. If this variable is true, then
when `load' is called with a filename without an extension, and
`load', no warning will be printed. The default is `nil', but it
is bound to `t' during the initial loadup.
- - User Option: load-ignore-elc-files
+ -- User Option: load-ignore-elc-files
This variable specifies whether `load' should ignore `.elc' files
when a suffix is not given. This is normally used only to
bootstrap the `.elc' files when building XEmacs, when you use the
projects / chise / xemacs-chise.git.1 / blobdiff