+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
+ 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
+ This function changes the value in LAX-PLIST of PROPERTY to VALUE.
+
+ - 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
+ This function returns `t' if PROPERTY has a value specified in
+ LAX-PLIST.
+
+ In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
+non-`nil', then a property with a `nil' value is ignored or removed.
+This feature is a virus that has infected old Lisp implementations (and
+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
+ 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
+ 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
+ nil-means-not-present
+ This function destructively removes any duplicate entries from a
+ lax plist. In such cases, the first entry applies.
+
+ The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
+ return value may not be `eq' to the passed-in value, so make sure
+ to `setq' the value back into where it came from.
+
+\1f
+File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
+
+Converting Plists To/From Alists
+--------------------------------
+
+ - Function: alist-to-plist alist
+ This function converts association list ALIST into the equivalent
+ property-list form. The plist is returned. This converts from
+
+ ((a . 1) (b . 2) (c . 3))
+
+ into
+
+ (a 1 b 2 c 3)
+
+ The original alist is not modified.
+
+ - Function: plist-to-alist plist
+ This function converts property list PLIST into the equivalent
+ association-list form. The alist is returned. This converts from
+
+ (a 1 b 2 c 3)
+
+ into
+
+ ((a . 1) (b . 2) (c . 3))
+
+ The original plist is not modified.
+
+ The following two functions are equivalent to the preceding two
+except that they destructively modify their arguments, using cons cells
+from the original list to form the new list rather than allocating new
+cons cells.
+
+ - 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
+ 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
+==========
+
+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,
+for any object in the list, if there are no references to the object
+anywhere outside of the list (or other weak list or weak hash table),
+that object will disappear the next time a garbage collection happens.
+Weak lists can be useful for keeping track of things such as unobtrusive
+lists of another function's buffers or markers. When that function is
+done with the elements, they will automatically disappear from the list.
+
+ Weak lists are used internally, for example, to manage the list
+holding the children of an extent--an extent that is unused but has a
+parent will still be reclaimed, and will automatically be removed from
+its parent's list of children.
+
+ Weak lists are similar to weak hash tables (*note Weak Hash
+Tables::).
+
+ - Function: weak-list-p object
+ This function returns non-`nil' if OBJECT is a weak list.
+
+ Weak lists come in one of four types:
+
+`simple'
+ Objects in the list disappear if not referenced outside of the
+ list.
+
+`assoc'
+ Objects in the list disappear if they are conses and either the
+ car or the cdr of the cons is not referenced outside of the list.
+
+`key-assoc'
+ Objects in the list disappear if they are conses and the car is not
+ referenced outside of the list.
+
+`value-assoc'
+ 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
+ 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
+ This function returns the type of the given weak-list object.
+
+ - Function: weak-list-list weak
+ This function returns the list contained in a weak-list object.
+
+ - 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
+******************************
+
+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
+a sequence, any vector is a sequence, any bit vector is a sequence, and
+any string is a sequence. The common property that all sequences have
+is that each is an ordered collection of elements.
+
+ An "array" is a single primitive object that has a slot for each
+elements. All the elements are accessible in constant time, but the
+length of an existing array cannot be changed. Strings, vectors, and
+bit vectors are the three types of arrays.
+
+ A list is a sequence of elements, but it is not a single primitive
+object; it is made of cons cells, one cell per element. Finding the
+Nth element requires looking through N cons cells, so elements farther
+from the beginning of the list take longer to access. But it is
+possible to add elements to the list, or remove elements.
+
+ The following diagram shows the relationship between these types:
+
+ ___________________________________
+ | |
+ | Sequence |
+ | ______ ______________________ |
+ | | | | | |
+ | | List | | Array | |
+ | | | | ________ _______ | |
+ | |______| | | | | | | |
+ | | | Vector | | String| | |
+ | | |________| |_______| | |
+ | | __________________ | |
+ | | | | | |
+ | | | Bit Vector | | |
+ | | |__________________| | |
+ | |______________________| |
+ |___________________________________|
+
+ The elements of vectors and lists may be any Lisp objects. The
+elements of strings are all characters. The elements of bit vectors
+are the numbers 0 and 1.
+
+* Menu:
+
+* Sequence Functions:: Functions that accept any kind of sequence.
+* Arrays:: Characteristics of arrays in XEmacs Lisp.
+* Array Functions:: Functions specifically for arrays.
+* Vectors:: Special characteristics of XEmacs Lisp vectors.
+* Vector Functions:: Functions specifically for vectors.
+* Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
+* Bit Vector Functions:: Functions specifically for bit vectors.
+
+\1f
+File: lispref.info, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors
+
+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
+ Returns `t' if OBJECT is a list, vector, bit vector, or string,
+ `nil' otherwise.
+
+ - 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.
+
+ Storing a new element into the copy does not affect the original
+ SEQUENCE, and vice versa. However, the elements of the new
+ sequence are not copies; they are identical (`eq') to the elements
+ of the original. Therefore, changes made within these elements, as
+ found via the copied sequence, are also visible in the original
+ sequence.
+
+ If the sequence is a string with extents or text properties, the
+ extents and text properties in the copy are also copied, not
+ shared with the original. (This means that modifying the extents
+ or text properties of the original will not affect the copy.)
+ However, the actual values of the properties are shared. *Note
+ Extents::, *Note Text Properties::.
+
+ See also `append' in *Note Building Lists::, `concat' in *Note
+ Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
+ in *Note Bit Vectors::, for other ways to copy sequences.
+
+ (setq bar '(1 2))
+ => (1 2)
+ (setq x (vector 'foo bar))
+ => [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
+ 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 '(1 2 3))
+ => 3
+ (length ())
+ => 0
+ (length "foobar")
+ => 6
+ (length [1 2 3])
+ => 3
+ (length #*01101)
+ => 5
+
+ - 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
+ out-of-range values of INDEX return `nil'; otherwise, they trigger
+ an `args-out-of-range' error.
+
+ (elt [1 2 3 4] 2)
+ => 3
+ (elt '(1 2 3 4) 2)
+ => 3
+ (char-to-string (elt "1234" 2))
+ => "3"
+ (elt #*00010000 3)
+ => 1
+ (elt [1 2 3 4] 4)
+ error-->Args out of range: [1 2 3 4], 4
+ (elt [1 2 3 4] -1)
+ error-->Args out of range: [1 2 3 4], -1
+
+ This function generalizes `aref' (*note Array Functions::) and
+ `nth' (*note List Elements::).
+
+\1f
+File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
+
+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
+accessed in constant time. In contrast, an element of a list requires
+access time that is proportional to the position of the element in the
+list.
+
+ When you create an array, you must specify how many elements it has.
+The amount of space allocated depends on the number of elements.
+Therefore, it is impossible to change the size of an array once it is
+created; you cannot add or remove elements. However, you can replace an
+element with a different value.
+
+ XEmacs defines three types of array, all of which are
+one-dimensional: "strings", "vectors", and "bit vectors". A vector is a
+general array; its elements can be any Lisp objects. A string is a
+specialized array; its elements must be characters. A bit vector is
+another specialized array; its elements must be bits (an integer, either
+0 or 1). Each type of array has its own read syntax. *Note String
+Type::, *Note Vector Type::, and *Note Bit Vector Type::.
+
+ All kinds of array share these characteristics:
+
+ * The first element of an array has index zero, the second element
+ has index 1, and so on. This is called "zero-origin" indexing.
+ For example, an array of four elements has indices 0, 1, 2, and 3.
+
+ * The elements of an array may be referenced or changed with the
+ functions `aref' and `aset', respectively (*note Array
+ Functions::).
+
+ In principle, if you wish to have an array of text characters, you
+could use either a string or a vector. In practice, we always choose
+strings for such applications, for four reasons:
+
+ * They usually occupy one-fourth the space of a vector of the same
+ elements. (This is one-eighth the space for 64-bit machines such
+ as the DEC Alpha, and may also be different when MULE support is
+ compiled into XEmacs.)
+
+ * Strings are printed in a way that shows the contents more clearly
+ as characters.
+
+ * Strings can hold extent and text properties. *Note Extents::,
+ *Note Text Properties::.
+
+ * Many of the specialized editing and I/O facilities of XEmacs
+ accept only strings. For example, you cannot insert a vector of
+ characters into a buffer the way you can insert a string. *Note
+ Strings and Characters::.
+
+ By contrast, for an array of keyboard input characters (such as a key
+sequence), a vector may be necessary, because many keyboard input
+characters are non-printable and are represented with symbols rather
+than with characters. *Note Key Sequence Input::.
+
+ Similarly, when representing an array of bits, a bit vector has the
+following advantages over a regular vector:
+
+ * They occupy 1/32nd the space of a vector of the same elements.
+ (1/64th on 64-bit machines such as the DEC Alpha.)
+
+ * Bit vectors are printed in a way that shows the contents more
+ clearly as bits.
+
+\1f
+File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors
+
+Functions that Operate on Arrays
+================================
+
+In this section, we describe the functions that accept strings, vectors,
+and bit vectors.
+
+ - Function: arrayp object
+ This function returns `t' if OBJECT is an array (i.e., a string,
+ vector, or bit vector).
+
+ (arrayp "asdf")
+ => t
+ (arrayp [a])
+ => t
+ (arrayp #*101)
+ => t
+
+ - Function: aref array index
+ This function returns the INDEXth element of ARRAY. The first
+ element is at index zero.
+
+ (setq primes [2 3 5 7 11 13])
+ => [2 3 5 7 11 13]
+ (aref primes 4)
+ => 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
+ This function sets the INDEXth element of ARRAY to be OBJECT. It
+ returns OBJECT.
+
+ (setq w [foo bar baz])
+ => [foo bar baz]
+ (aset w 0 'fu)
+ => fu
+ w
+ => [fu bar baz]
+
+ (setq x "asdfasfd")
+ => "asdfasfd"
+ (aset x 3 ?Z)
+ => ?Z
+ x
+ => "asdZasfd"
+
+ (setq bv #*1111)
+ => #*1111
+ (aset bv 2 0)
+ => 0
+ bv
+ => #*1101
+
+ If ARRAY is a string and OBJECT is not a character, a
+ `wrong-type-argument' error results.
+
+ - Function: fillarray array object
+ This function fills the array ARRAY with OBJECT, so that each
+ element of ARRAY is OBJECT. It returns ARRAY.
+
+ (setq a [a b c d e f g])
+ => [a b c d e f g]
+ (fillarray a 0)
+ => [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)
+ => #*0000
+
+ If ARRAY is a string and OBJECT is not a character, a
+ `wrong-type-argument' error results.
+
+ The general sequence functions `copy-sequence' and `length' are
+often useful for objects known to be arrays. *Note Sequence
+Functions::.
+
+\1f
+File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors
+
+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
+general-purpose array; its elements can be any Lisp objects. (The other
+kind of array in XEmacs Lisp is the "string", whose elements must be
+characters.) Vectors in XEmacs serve as obarrays (vectors of symbols),
+although this is a shortcoming that should be fixed. They are also used
+internally as part of the representation of a byte-compiled function; if
+you print such a function, you will see a vector in it.
+
+ In XEmacs Lisp, the indices of the elements of a vector start from
+zero and count up from there.
+
+ Vectors are printed with square brackets surrounding the elements.
+Thus, a vector whose elements are the symbols `a', `b' and `a' is
+printed as `[a b a]'. You can write vectors in the same way in Lisp
+input.
+
+ A vector, like a string or a number, is considered a constant for
+evaluation: the result of evaluating it is the same vector. This does
+not evaluate or even examine the elements of the vector. *Note
+Self-Evaluating Forms::.
+
+ Here are examples of these principles:
+
+ (setq avector [1 two '(three) "four" [five]])
+ => [1 two (quote (three)) "four" [five]]
+ (eval avector)
+ => [1 two (quote (three)) "four" [five]]
+ (eq avector (eval avector))
+ => t
+
+\1f
+File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors
+
+Functions That Operate on Vectors
+=================================
+
+Here are some functions that relate to vectors:
+
+ - Function: vectorp object
+ This function returns `t' if OBJECT is a vector.
+
+ (vectorp [a])
+ => t
+ (vectorp "asdf")
+ => nil
+
+ - Function: vector &rest objects
+ This function creates and returns a vector whose elements are the
+ arguments, OBJECTS.
+
+ (vector 'foo 23 [bar baz] "rats")
+ => [foo 23 [bar baz] "rats"]
+ (vector)
+ => []
+
+ - 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
+ 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.
+
+ The value is a newly constructed vector that is not `eq' to any
+ existing vector.
+
+ (setq a (vconcat '(A B C) '(D E F)))
+ => [A B C D E F]
+ (eq a (vconcat a))
+ => nil
+ (vconcat)
+ => []
+ (vconcat [A B C] "aa" '(foo (6 7)))
+ => [A B C 97 97 foo (6 7)]
+
+ The `vconcat' function also allows integers as arguments. It
+ converts them to strings of digits, making up the decimal print
+ representation of the integer, and then uses the strings instead
+ of the original integers. *Don't use this feature; we plan to
+ eliminate it. If you already use this feature, change your
+ programs now!* The proper way to convert an integer to a decimal
+ number in this way is with `format' (*note Formatting Strings::)
+ or `number-to-string' (*note String Conversion::).
+
+ For other concatenation functions, see `mapconcat' in *Note
+ Mapping Functions::, `concat' in *Note Creating Strings::, `append'
+ in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
+ Functions::.
+
+ The `append' function provides a way to convert a vector into a list
+with the same elements (*note Building Lists::):
+
+ (setq avector [1 two (quote (three)) "four" [five]])
+ => [1 two (quote (three)) "four" [five]]
+ (append avector nil)
+ => (1 two (quote (three)) "four" [five])
+
+\1f
+File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors
+
+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
+useful for representing sets of boolean (true or false) values.
+
+ There is no limit on the size of a bit vector. You could, for
+example, create a bit vector with 100,000 elements if you really wanted
+to.
+
+ Bit vectors have a special printed representation consisting of `#*'
+followed by the bits of the vector. For example, a bit vector whose
+elements are 0, 1, 1, 0, and 1, respectively, is printed as
+
+ #*01101
+
+ Bit vectors are considered constants for evaluation, like vectors,
+strings, and numbers. *Note Self-Evaluating Forms::.
+
+\1f
+File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors
+
+Functions That Operate on Bit Vectors
+=====================================
+
+Here are some functions that relate to bit vectors:
+
+ - Function: bit-vector-p object
+ This function returns `t' if OBJECT is a bit vector.
+
+ (bit-vector-p #*01)
+ => t
+ (bit-vector-p [0 1])
+ => nil
+ (bit-vector-p "01")
+ => nil
+
+ - Function: bitp object
+ This function returns `t' if OBJECT is either 0 or 1.
+
+ - 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 0 0 0 1 0 0 0 0 1 0)
+ => #*0001000010
+ (bit-vector)
+ => #*
+
+ - 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
+ 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
+ no SEQUENCES are given, an empty bit vector is returned.
+
+ The value is a newly constructed bit vector that is not `eq' to any
+ existing bit vector.
+
+ (setq a (bvconcat '(1 1 0) '(0 0 1)))
+ => #*110001
+ (eq a (bvconcat a))
+ => nil
+ (bvconcat)
+ => #*
+ (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
+ => #*1000011100001
+
+ For other concatenation functions, see `mapconcat' in *Note
+ Mapping Functions::, `concat' in *Note Creating Strings::,
+ `vconcat' in *Note Vector Functions::, and `append' in *Note
+ Building Lists::.
+
+ The `append' function provides a way to convert a bit vector into a
+list with the same elements (*note Building Lists::):
+
+ (setq bv #*00001110)
+ => #*00001110
+ (append bv nil)
+ => (0 0 0 0 1 1 1 0)
+
+\1f
+File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top
+
+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::.
+
+ You can test whether an arbitrary Lisp object is a symbol with
+`symbolp':
+
+ - Function: symbolp object
+ This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+
+* Menu:
+
+* Symbol Components:: Symbols have names, values, function definitions
+ and property lists.
+* Definitions:: A definition says how a symbol will be used.
+* Creating Symbols:: How symbols are kept unique.
+* Symbol Properties:: Each symbol has a property list
+ for recording miscellaneous information.
+
+\1f
+File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols
+
+Symbol Components
+=================
+
+Each symbol has four components (or "cells"), each of which references
+another object:
+
+Print name
+ The "print name cell" holds a string that names the symbol for
+ reading and printing. See `symbol-name' in *Note Creating
+ Symbols::.
+
+Value
+ The "value cell" holds the current value of the symbol as a
+ variable. When a symbol is used as a form, the value of the form
+ is the contents of the symbol's value cell. See `symbol-value' in
+ *Note Accessing Variables::.
+
+Function
+ The "function cell" holds the function definition of the symbol.
+ When a symbol is used as a function, its function definition is
+ used in its place. This cell is also used to make a symbol stand
+ for a keymap or a keyboard macro, for editor command execution.
+ Because each symbol has separate value and function cells,
+ variables and function names do not conflict. See
+ `symbol-function' in *Note Function Cells::.
+
+Property list
+ The "property list cell" holds the property list of the symbol.
+ See `symbol-plist' in *Note Symbol Properties::.
+
+ The print name cell always holds a string, and cannot be changed.
+The other three cells can be set individually to any specified Lisp
+object.
+
+ The print name cell holds the string that is the name of the symbol.
+Since symbols are represented textually by their names, it is important
+not to have two symbols with the same name. The Lisp reader ensures
+this: every time it reads a symbol, it looks for an existing symbol with
+the specified name before it creates a new one. (In XEmacs Lisp, this
+lookup uses a hashing algorithm and an obarray; see *Note Creating
+Symbols::.)
+
+ In normal usage, the function cell usually contains a function or
+macro, as that is what the Lisp interpreter expects to see there (*note
+Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps
+(*note Keymaps::) and autoload objects (*note Autoloading::) are also
+sometimes stored in the function cell of symbols. We often refer to
+"the function `foo'" when we really mean the function stored in the
+function cell of the symbol `foo'. We make the distinction only when
+necessary.
+
+ The property list cell normally should hold a correctly formatted
+property list (*note Property Lists::), as a number of functions expect
+to see a property list there.
+
+ The function cell or the value cell may be "void", which means that
+the cell does not reference any object. (This is not the same thing as
+holding the symbol `void', nor the same as holding the symbol `nil'.)
+Examining a cell that is void results in an error, such as `Symbol's
+value as variable is void'.
+
+ The four functions `symbol-name', `symbol-value', `symbol-plist',
+and `symbol-function' return the contents of the four cells of a
+symbol. Here as an example we show the contents of the four cells of
+the symbol `buffer-file-name':
+
+ (symbol-name 'buffer-file-name)
+ => "buffer-file-name"
+ (symbol-value 'buffer-file-name)
+ => "/gnu/elisp/symbols.texi"
+ (symbol-plist 'buffer-file-name)
+ => (variable-documentation 29529)
+ (symbol-function 'buffer-file-name)
+ => #<subr buffer-file-name>
+
+Because this symbol is the variable which holds the name of the file
+being visited in the current buffer, the value cell contents we see are
+the name of the source file of this chapter of the XEmacs Lisp Reference
+Manual. The property list cell contains the list
+`(variable-documentation 29529)' which tells the documentation
+functions where to find the documentation string for the variable
+`buffer-file-name' in the `DOC' file. (29529 is the offset from the
+beginning of the `DOC' file to where that documentation string begins.)
+The function cell contains the function for returning the name of the
+file. `buffer-file-name' names a primitive function, which has no read
+syntax and prints in hash notation (*note Primitive Function Type::). A
+symbol naming a function written in Lisp would have a lambda expression
+(or a byte-code object) in this cell.
+
+\1f
+File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
+
+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
+define a symbol as a variable, or define it as a function (or macro),
+or both independently.
+
+ A definition construct typically specifies a value or meaning for the
+symbol for one kind of use, plus documentation for its meaning when used
+in this way. Thus, when you define a symbol as a variable, you can
+supply an initial value for the variable, plus documentation for the
+variable.
+
+ `defvar' and `defconst' are special forms that define a symbol as a
+global variable. They are documented in detail in *Note Defining
+Variables::.
+
+ `defun' defines a symbol as a function, creating a lambda expression
+and storing it in the function cell of the symbol. This lambda
+expression thus becomes the function definition of the symbol. (The
+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::.
+
+ `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
+symbol can be a macro or a function, but not both at once, because both
+macro and function definitions are kept in the function cell, and that
+cell can hold only one Lisp object at any given time. *Note Macros::.
+
+ In XEmacs Lisp, a definition is not required in order to use a symbol
+as a variable or function. Thus, you can make a symbol a global
+variable with `setq', whether you define it first or not. The real
+purpose of definitions is to guide programmers and programming tools.
+They inform programmers who read the code that certain symbols are
+_intended_ to be used as variables, or as functions. In addition,
+utilities such as `etags' and `make-docfile' recognize definitions, and
+add appropriate information to tag tables and the `DOC' file. *Note
+Accessing Documentation::.
+
+\1f
+File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols
+
+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
+time it reads the same set of characters. Failure to do so would cause
+complete confusion.
+
+ When the Lisp reader encounters a symbol, it reads all the characters
+of the name. Then it "hashes" those characters to find an index in a
+table called an "obarray". Hashing is an efficient method of looking
+something up. For example, instead of searching a telephone book cover
+to cover when looking up Jan Jones, you start with the J's and go from
+there. That is a simple version of hashing. Each element of the
+obarray is a "bucket" which holds all the symbols with a given hash
+code; to look for a given name, it is sufficient to look through all
+the symbols in the bucket for that name's hash code.
+
+ If a symbol with the desired name is found, the reader uses that
+symbol. If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray. Finding or adding
+a symbol with a certain name is called "interning" it, and the symbol
+is then called an "interned symbol".
+
+ Interning ensures that each obarray has just one symbol with any
+particular name. Other like-named symbols may exist, but not in the
+same obarray. Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
+
+ No obarray contains all symbols; in fact, some symbols are not in any
+obarray. They are called "uninterned symbols". An uninterned symbol
+has the same four cells as other symbols; however, the only way to gain
+access to it is by finding it in some other object or as the value of a
+variable.
+
+ In XEmacs Lisp, an obarray is actually a vector. Each element of the
+vector is a bucket; its value is either an interned symbol whose name
+hashes to that bucket, or 0 if the bucket is empty. Each interned
+symbol has an internal link (invisible to the user) to the next symbol
+in the bucket. Because these links are invisible, there is no way to
+find all the symbols in an obarray except using `mapatoms' (below).
+The order of symbols in a bucket is not significant.
+
+ In an empty obarray, every element is 0, and you can create an
+obarray with `(make-vector LENGTH 0)'. *This is the only valid way to
+create an obarray.* Prime numbers as lengths tend to result in good
+hashing; lengths one less than a power of two are also good.
+
+ *Do not try to put symbols in an obarray yourself.* This does not
+work--only `intern' can enter a symbol in an obarray properly. *Do not
+try to intern one symbol in two obarrays.* This would garble both
+obarrays, because a symbol has just one slot to hold the following
+symbol in the obarray bucket. The results would be unpredictable.
+
+ It is possible for two different symbols to have the same name in
+different obarrays; these symbols are not `eq' or `equal'. However,
+this normally happens only as part of the abbrev mechanism (*note
+Abbrevs::).
+
+ Common Lisp note: In Common Lisp, a single symbol may be interned
+ in several obarrays.
+
+ Most of the functions below take a name and sometimes an obarray as
+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
+ This function returns the string that is SYMBOL's name. For
+ example:
+
+ (symbol-name 'foo)
+ => "foo"
+
+ Changing the string by substituting characters, etc, does change
+ the name of the symbol, but fails to update the obarray, so don't
+ do it!
+
+ - 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
+ example below, the value of `sym' is not `eq' to `foo' because it
+ is a distinct uninterned symbol whose name is also `foo'.
+
+ (setq sym (make-symbol "foo"))
+ => foo
+ (eq sym 'foo)
+ => nil
+
+ - 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
+ omitted, the value of the global variable `obarray' is used.
+
+ (setq sym (intern "foo"))
+ => foo
+ (eq sym 'foo)
+ => t
+
+ (setq sym1 (intern "foo" other-obarray))
+ => foo
+ (eq sym 'foo)
+ => nil
+
+ - 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
+ already interned. If OBARRAY is omitted, the value of the global
+ variable `obarray' is used.
+
+ (intern-soft "frazzle") ; No such symbol exists.
+ => nil
+ (make-symbol "frazzle") ; Create an uninterned one.
+ => frazzle
+ (intern-soft "frazzle") ; That one cannot be found.
+ => nil
+ (setq sym (intern "frazzle")) ; Create an interned one.
+ => frazzle
+ (intern-soft "frazzle") ; That one can be found!
+ => frazzle
+ (eq sym 'frazzle) ; And it is the same one.
+ => t
+
+ - Variable: obarray
+ This variable is the standard obarray for use by `intern' and
+ `read'.
+
+ - 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.
+
+ (setq count 0)
+ => 0
+ (defun count-syms (s)
+ (setq count (1+ count)))
+ => count-syms
+ (mapatoms 'count-syms)
+ => nil
+ count
+ => 1871
+
+ See `documentation' in *Note Accessing Documentation::, for another
+ example using `mapatoms'.
+
+ - 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.
+
+ If you provide a string instead of a symbol as SYMBOL, it stands
+ for a symbol name. Then `unintern' deletes the symbol (if any) in
+ the obarray which has that name. If there is no such symbol,
+ `unintern' does nothing.
+
+ If `unintern' does delete a symbol, it returns `t'. Otherwise it
+ returns `nil'.
+
+\1f
+File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols
+
+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
+associates a property name (usually a symbol) with a property or value.
+Property lists are generally used to record information about a
+symbol, such as its documentation as a variable, the name of the file
+where it was defined, or perhaps even the grammatical class of the
+symbol (representing a word) in a language-understanding system.
+
+ Some objects which are not symbols also have property lists
+associated with them, and XEmacs provides a full complement of
+functions for working with property lists. *Note Property Lists::.
+
+ The property names and values in a property list can be any Lisp
+objects, but the names are usually symbols. They are compared using
+`eq'. Here is an example of a property list, found on the symbol
+`progn' when the compiler is loaded:
+
+ (lisp-indent-function 0 byte-compile byte-compile-progn)
+
+Here `lisp-indent-function' and `byte-compile' are property names, and
+the other two elements are the corresponding values.
+
+* Menu:
+
+* Plists and Alists:: Comparison of the advantages of property
+ lists and association lists.
+* Object Plists:: Functions to access objects' property lists.
+* Other Plists:: Accessing property lists stored elsewhere.
+
+\1f
+File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties
+
+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
+pairs in the property list is not significant since the property names
+must be distinct.
+
+ Property lists are better than association lists for attaching
+information to various Lisp function names or variables. If all the
+associations are recorded in one association list, the program will need
+to search that entire list each time a function or variable is to be
+operated on. By contrast, if the information is recorded in the
+property lists of the function names or variables themselves, each
+search will scan only the length of one property list, which is usually
+short. This is why the documentation for a variable is recorded in a
+property named `variable-documentation'. The byte compiler likewise
+uses properties to record those functions needing special treatment.
+
+ However, association lists have their own advantages. Depending on
+your application, it may be faster to add an association to the front of
+an association list than to update a property. All properties for a
+symbol are stored in the same property list, so there is a possibility
+of a conflict between different uses of a property name. (For this
+reason, it is a good idea to choose property names that are probably
+unique, such as by including the name of the library in the property
+name.) An association list may be used like a stack where associations
+are pushed on the front of the list and later discarded; this is not
+possible with a property list.
+
+\1f
+File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
+
+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
+ This function returns the property list of SYMBOL.
+
+ - Function: object-plist object
+ This function returns the property list of OBJECT. If OBJECT is a
+ symbol, this is identical to `symbol-plist'.
+
+ - Function: setplist symbol plist
+ This function sets SYMBOL's property list to PLIST. Normally,
+ PLIST should be a well-formed property list, but this is not
+ enforced.
+
+ (setplist 'foo '(a 1 b (2 3) c nil))
+ => (a 1 b (2 3) c nil)
+ (symbol-plist 'foo)
+ => (a 1 b (2 3) c nil)
+
+ For symbols in special obarrays, which are not used for ordinary
+ purposes, it may make sense to use the property list cell in a
+ nonstandard fashion; in fact, the abbrev mechanism does so (*note
+ Abbrevs::). But generally, its use is discouraged. Use `put'
+ instead. `setplist' can only be used with symbols, not other
+ object types.
+
+ - 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.
+
+ PROPERTY is compared with the existing properties using `eq', so
+ any object is a legitimate property.
+
+ See `put' for an example.
+
+ - 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.
+
+ (put 'fly 'verb 'transitive)
+ =>'transitive
+ (put 'fly 'noun '(a buzzing little bug))
+ => (a buzzing little bug)
+ (get 'fly 'verb)
+ => transitive
+ (object-plist 'fly)
+ => (verb transitive noun (a buzzing little bug))
+
+ - Function: remprop object property
+ This function removes the entry for PROPERTY from the property
+ list of OBJECT. It returns `t' if the property was indeed found
+ and removed, or `nil' if there was no such property. (This
+ function was probably omitted from Emacs originally because, since
+ `get' did not allow a DEFAULT, it was very difficult to
+ distinguish between a missing property and a property whose value
+ was `nil'; thus, setting a property to `nil' was close enough to
+ `remprop' for most purposes.)
+
+\1f
+File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties
+
+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
+ 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
+ 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
+ function returns the modified property list, so you can store that
+ back in the place where you got PLIST. For example,
+
+ (setq my-plist '(bar t foo 4))
+ => (bar t foo 4)
+ (setq my-plist (putf my-plist 'foo 69))
+ => (bar t foo 69)
+ (setq my-plist (putf my-plist 'quux '(a)))
+ => (quux (a) bar t foo 5)
+
+ - 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
+ This function returns non-`nil' if property lists A and B are
+ `equal'.
+
+ Both of the above functions do order-insensitive comparisons.
+
+ (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
+ => t
+ (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ => nil
+ (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ => t
+
+\1f
+File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top
+
+Evaluation
+**********
+
+The "evaluation" of expressions in XEmacs Lisp is performed by the
+"Lisp interpreter"--a program that receives a Lisp object as input and
+computes its "value as an expression". How it does this depends on the
+data type of the object, according to rules described in this chapter.
+The interpreter runs automatically to evaluate portions of your
+program, but can also be called explicitly via the Lisp primitive
+function `eval'.
+
+* Menu:
+
+* Intro Eval:: Evaluation in the scheme of things.
+* Eval:: How to invoke the Lisp interpreter explicitly.
+* Forms:: How various sorts of objects are evaluated.
+* Quoting:: Avoiding evaluation (to put constants in the program).
+
+\1f
+File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation
+
+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
+Lisp is called, the evaluator computes the value of the function by
+evaluating the expressions in the function body. Thus, running any
+Lisp program really means running the Lisp interpreter.
+
+ How the evaluator handles an object depends primarily on the data
+type of the object.
+
+ A Lisp object that is intended for evaluation is called an
+"expression" or a "form". The fact that expressions are data objects
+and not merely text is one of the fundamental differences between
+Lisp-like languages and typical programming languages. Any object can
+be evaluated, but in practice only numbers, symbols, lists and strings
+are evaluated very often.
+
+ It is very common to read a Lisp expression and then evaluate the
+expression, but reading and evaluation are separate activities, and
+either can be performed alone. Reading per se does not evaluate
+anything; it converts the printed representation of a Lisp object to the
+object itself. It is up to the caller of `read' whether this object is
+a form to be evaluated, or serves some entirely different purpose.
+*Note Input Functions::.
+
+ Do not confuse evaluation with command key interpretation. The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses `call-interactively' to invoke the command. The execution of the
+command itself involves evaluation if the command is written in Lisp,
+but that is not a part of command key interpretation itself. *Note
+Command Loop::.
+
+ Evaluation is a recursive process. That is, evaluation of a form may
+call `eval' to evaluate parts of the form. For example, evaluation of
+a function call first evaluates each argument of the function call, and
+then evaluates each form in the function body. Consider evaluation of
+the form `(car x)': the subform `x' must first be evaluated
+recursively, so that its value can be passed as an argument to the
+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::).
+
+ The evaluation of forms takes place in a context called the
+"environment", which consists of the current values and bindings of all
+Lisp variables.(1) Whenever the form refers to a variable without
+creating a new binding for it, the value of the binding in the current
+environment is used. *Note Variables::.
+
+ Evaluation of a form may create new environments for recursive
+evaluation by binding variables (*note Local Variables::). These
+environments are temporary and vanish by the time evaluation of the form
+is complete. The form may also make changes that persist; these changes
+are called "side effects". An example of a form that produces side
+effects is `(setq foo 1)'.
+
+ The details of what evaluation means for each kind of form are
+described below (*note Forms::).
+
+ ---------- Footnotes ----------
+
+ (1) This definition of "environment" is specifically not intended to
+include all the data that can affect the result of a program.
+
+\1f
+File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation
+
+Eval
+====
+
+Most often, forms are evaluated automatically, by virtue of their
+occurrence in a program being run. On rare occasions, you may need to
+write code that evaluates a form that is computed at run time, such as
+after reading a form from text being edited or getting one from a
+property list. On these occasions, use the `eval' function.
+
+ *Please note:* it is generally cleaner and more flexible to call
+functions that are stored in data structures, rather than to evaluate
+expressions stored in data structures. Using functions provides the
+ability to pass information to them as arguments.
+
+ The functions and variables described in this section evaluate forms,
+specify limits to the evaluation process, or record recently returned
+values. Loading a file also does evaluation (*note Loading::).
+
+ - Function: eval form
+ This is the basic function for performing evaluation. It evaluates
+ FORM in the current environment and returns the result. How the
+ evaluation proceeds depends on the type of the object (*note
+ Forms::).
+
+ Since `eval' is a function, the argument expression that appears
+ in a call to `eval' is evaluated twice: once as preparation before
+ `eval' is called, and again by the `eval' function itself. Here
+ is an example:
+
+ (setq foo 'bar)
+ => bar
+ (setq bar 'baz)
+ => baz
+ ;; `eval' receives argument `bar', which is the value of `foo'
+ (eval foo)
+ => baz
+ (eval 'foo)
+ => bar
+
+ The number of currently active calls to `eval' is limited to
+ `max-lisp-eval-depth' (see below).
+
+ - 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
+ reached, or until an error is signaled and not handled.
+
+ If STREAM is supplied, `standard-output' is bound to it during the
+ evaluation.
+
+ You can use the variable `load-read-function' to specify a function
+ for `eval-region' to use instead of `read' for reading
+ expressions. *Note How Programs Do Loading::.
+
+ `eval-region' always returns `nil'.
+
+ - 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
+ 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
+ internal uses of those functions, such as for calling the functions
+ mentioned in Lisp expressions, and recursive evaluation of
+ 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.
+
+ 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
+ is reached.
+
+ `max-specpdl-size' provides another limit on nesting. *Note Local
+ Variables::.
+
+ - 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
+ most recent first.
+
+ (setq x 1)
+ => 1
+ (list 'A (1+ 2) auto-save-default)
+ => (A 3 t)
+ values
+ => ((A 3 t) 1 ...)
+
+ This variable is useful for referring back to values of forms
+ recently evaluated. It is generally a bad idea to print the value
+ of `values' itself, since this may be very long. Instead, examine
+ particular elements, like this:
+
+ ;; Refer to the most recent evaluation result.
+ (nth 0 values)
+ => (A 3 t)
+ ;; That put a new element on,
+ ;; so all elements move back one.
+ (nth 1 values)
+ => (A 3 t)
+ ;; This gets the element that was next-to-most-recent
+ ;; before this example.
+ (nth 3 values)
+ => 1
+
+\1f
+File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation
+
+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
+different kinds of form that are evaluated differently: symbols, lists,
+and "all other types". This section describes all three kinds,
+starting with "all other types" which are self-evaluating forms.
+
+* Menu:
+
+* Self-Evaluating Forms:: Forms that evaluate to themselves.
+* Symbol Forms:: Symbols evaluate as variables.
+* Classifying Lists:: How to distinguish various sorts of list forms.
+* Function Indirection:: When a symbol appears as the car of a list,
+ we find the real function via the symbol.
+* Function Forms:: Forms that call functions.
+* Macro Forms:: Forms that call macros.
+* Special Forms:: ``Special forms'' are idiosyncratic primitives,
+ most of them extremely important.
+* Autoloading:: Functions set up to load files
+ containing their real definitions.
+
+\1f
+File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms
+
+Self-Evaluating Forms
+---------------------
+
+A "self-evaluating form" is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated. Thus, the number 25 evaluates to
+25, and the string `"foo"' evaluates to the string `"foo"'. Likewise,
+evaluation of a vector does not cause evaluation of the elements of the
+vector--it returns the same vector with its contents unchanged.
+
+ '123 ; An object, shown without evaluation.
+ => 123
+ 123 ; Evaluated as usual--result is the same.
+ => 123
+ (eval '123) ; Evaluated "by hand"--result is the same.
+ => 123
+ (eval (eval '123)) ; Evaluating twice changes nothing.
+ => 123
+
+ It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually. It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program. Here is an example:
+
+ ;; Build an expression containing a buffer object.
+ (setq buffer (list 'print (current-buffer)))
+ => (print #<buffer eval.texi>)
+ ;; Evaluate it.
+ (eval buffer)
+ -| #<buffer eval.texi>
+ => #<buffer eval.texi>
+
+\1f
+File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
+
+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
+is void), an error is signaled. For more information on the use of
+variables, see *Note Variables::.
+
+ In the following example, we set the value of a symbol with `setq'.
+Then we evaluate the symbol, and get back the value that `setq' stored.
+
+ (setq a 123)
+ => 123
+ (eval 'a)
+ => 123
+ a
+ => 123
+
+ The symbols `nil' and `t' are treated specially, so that the value
+of `nil' is always `nil', and the value of `t' is always `t'; you
+cannot set or bind them to any other values. Thus, these two symbols
+act like self-evaluating forms, even though `eval' treats them like any
+other symbol.
+
+\1f
+File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms
+
+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
+of forms are evaluated in different ways, described below. The
+remaining list elements constitute the "arguments" for the function,
+macro, or special form.
+
+ The first step in evaluating a nonempty list is to examine its first
+element. This element alone determines what kind of form the list is
+and how the rest of the list is to be processed. The first element is
+_not_ evaluated, as it would be in some Lisp dialects such as Scheme.
+
+\1f
+File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
+
+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
+original symbol. If the contents are another symbol, this process,
+called "symbol function indirection", is repeated until it obtains a
+non-symbol. *Note Function Names::, for more information about using a
+symbol as a name for a function stored in the function cell of the
+symbol.
+
+ One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol. Or a
+symbol may have a void function cell, in which case the subroutine
+`symbol-function' signals a `void-function' error. But if neither of
+these things happens, we eventually obtain a non-symbol, which ought to
+be a function or other suitable object.
+
+ More precisely, we should now have a Lisp function (a lambda
+expression), a byte-code function, a primitive function, a Lisp macro, a
+special form, or an autoload object. Each of these types is a case
+described in one of the following sections. If the object is not one of
+these types, the error `invalid-function' is signaled.
+
+ The following example illustrates the symbol indirection process. We
+use `fset' to set the function cell of a symbol and `symbol-function'
+to get the function cell contents (*note Function Cells::).
+Specifically, we store the symbol `car' into the function cell of
+`first', and the symbol `first' into the function cell of `erste'.
+
+ ;; Build this function cell linkage:
+ ;; ------------- ----- ------- -------
+ ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
+ ;; ------------- ----- ------- -------
+
+ (symbol-function 'car)
+ => #<subr car>
+ (fset 'first 'car)
+ => car
+ (fset 'erste 'first)
+ => first
+ (erste '(1 2 3)) ; Call the function referenced by `erste'.
+ => 1
+
+ By contrast, the following example calls a function without any
+symbol function indirection, because the first element is an anonymous
+Lisp function, not a symbol.
+
+ ((lambda (arg) (erste arg))
+ '(1 2 3))
+ => 1
+
+Executing the function itself evaluates its body; this does involve
+symbol function indirection when calling `erste'.
+
+ The built-in function `indirect-function' provides an easy way to
+perform symbol function indirection explicitly.
+
+ - 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
+ returns OBJECT itself.
+
+ Here is how you could define `indirect-function' in Lisp:
+
+ (defun indirect-function (function)
+ (if (symbolp function)
+ (indirect-function (symbol-function function))
+ function))
+
+\1f
+File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms
+
+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
+a "function call". For example, here is a call to the function `+':
+
+ (+ 1 x)
+
+ The first step in evaluating a function call is to evaluate the
+remaining elements of the list from left to right. The results are the
+actual argument values, one value for each list element. The next step
+is to call the function with this list of arguments, effectively using
+the function `apply' (*note Calling Functions::). If the function is
+written in Lisp, the arguments are used to bind the argument variables
+of the function (*note Lambda Expressions::); then the forms in the
+function body are evaluated in order, and the value of the last body
+form becomes the value of the function call.
+
+\1f
+File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms
+
+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
+elements of the rest of the list are _not_ initially evaluated.
+Instead, these elements themselves are used as the arguments of the
+macro. The macro definition computes a replacement form, called the
+"expansion" of the macro, to be evaluated in place of the original
+form. The expansion may be any sort of form: a self-evaluating
+constant, a symbol, or a list. If the expansion is itself a macro call,
+this process of expansion repeats until some other sort of form results.
+
+ Ordinary evaluation of a macro call finishes by evaluating the
+expansion. However, the macro expansion is not necessarily evaluated
+right away, or at all, because other programs also expand macro calls,
+and they may or may not evaluate the expansions.
+
+ Normally, the argument expressions are not evaluated as part of
+computing the macro expansion, but instead appear as part of the
+expansion, so they are computed when the expansion is computed.
+
+ For example, given a macro defined as follows:
+
+ (defmacro cadr (x)
+ (list 'car (list 'cdr x)))
+
+an expression such as `(cadr (assq 'handler list))' is a macro call,
+and its expansion is:
+
+ (car (cdr (assq 'handler list)))
+
+Note that the argument `(assq 'handler list)' appears in the expansion.
+
+ *Note Macros::, for a complete description of XEmacs Lisp macros.
+
+\1f
+File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms
+
+Special Forms
+-------------
+
+A "special form" is a primitive function specially marked so that its
+arguments are not all evaluated. Most special forms define control
+structures or perform variable bindings--things which functions cannot
+do.
+
+ Each special form has its own rules for which arguments are evaluated
+and which are used without evaluation. Whether a particular argument is
+evaluated may depend on the results of evaluating other arguments.
+
+ Here is a list, in alphabetical order, of all of the special forms in
+XEmacs Lisp with a reference to where each is described.
+
+`and'
+ *note Combining Conditions::
+
+`catch'
+ *note Catch and Throw::
+
+`cond'
+ *note Conditionals::
+
+`condition-case'
+ *note Handling Errors::
+
+`defconst'
+ *note Defining Variables::
+
+`defmacro'
+ *note Defining Macros::
+
+`defun'
+ *note Defining Functions::
+
+`defvar'
+ *note Defining Variables::
+
+`function'
+ *note Anonymous Functions::
+
+`if'
+ *note Conditionals::
+
+`interactive'
+ *note Interactive Call::
+
+`let'
+`let*'
+ *note Local Variables::
+
+`or'
+ *note Combining Conditions::
+
+`prog1'
+`prog2'
+`progn'
+ *note Sequencing::
+
+`quote'
+ *note Quoting::
+
+`save-current-buffer'
+ *note Excursions::
+
+`save-excursion'
+ *note Excursions::
+
+`save-restriction'
+ *note Narrowing::
+
+`save-selected-window'
+ *note Excursions::
+
+`save-window-excursion'
+ *note Window Configurations::
+
+`setq'
+ *note Setting Variables::
+
+`setq-default'
+ *note Creating Buffer-Local::
+
+`unwind-protect'
+ *note Nonlocal Exits::
+
+`while'
+ *note Iteration::
+
+`with-output-to-temp-buffer'
+ *note Temporary Displays::
+
+ Common Lisp note: here are some comparisons of special forms in
+ XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are
+ special forms in both XEmacs Lisp and Common Lisp. `defun' is a
+ special form in XEmacs Lisp, but a macro in Common Lisp.
+ `save-excursion' is a special form in XEmacs Lisp, but doesn't
+ exist in Common Lisp. `throw' is a special form in Common Lisp
+ (because it must be able to throw multiple values), but it is a
+ function in XEmacs Lisp (which doesn't have multiple values).
+
+\1f
+File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms
+
+Autoloading
+-----------
+
+The "autoload" feature allows you to call a function or macro whose
+function definition has not yet been loaded into XEmacs. It specifies
+which file contains the definition. When an autoload object appears as
+a symbol's function definition, calling that symbol as a function
+automatically loads the specified file; then it calls the real
+definition loaded from that file. *Note Autoload::.
+
+\1f
+File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation
+
+Quoting
+=======
+
+The special form `quote' returns its single argument, as written,
+without evaluating it. This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program. (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
+
+ - Special Form: quote object
+ This special form returns OBJECT, without evaluating it.
+
+ Because `quote' is used so often in programs, Lisp provides a
+convenient read syntax for it. An apostrophe character (`'') followed
+by a Lisp object (in read syntax) expands to a list whose first element
+is `quote', and whose second element is the object. Thus, the read
+syntax `'x' is an abbreviation for `(quote x)'.
+
+ Here are some examples of expressions that use `quote':
+
+ (quote (+ 1 2))
+ => (+ 1 2)
+ (quote foo)
+ => foo
+ 'foo
+ => foo
+ ''foo
+ => (quote foo)
+ '(quote foo)
+ => (quote foo)
+ ['foo]
+ => [(quote foo)]
+
+ Other quoting constructs include `function' (*note Anonymous
+Functions::), which causes an anonymous lambda expression written in
+Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
+only part of a list, while computing and substituting other parts.
+
+\1f
+File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top
+
+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
+"control structures". Control structures are special forms which
+control when, whether, or how many times to execute the forms they
+contain.
+
+ The simplest order of execution is sequential execution: first form
+A, then form B, and so on. This is what happens when you write several
+forms in succession in the body of a function, or at top level in a
+file of Lisp code--the forms are executed in the order written. We
+call this "textual order". For example, if a function body consists of
+two forms A and B, evaluation of the function evaluates first A and
+then B, and the function's value is the value of B.
+
+ Explicit control structures make possible an order of execution other
+than sequential.
+
+ XEmacs Lisp provides several kinds of control structure, including
+other varieties of sequencing, conditionals, iteration, and (controlled)
+jumps--all discussed below. The built-in control structures are
+special forms since their subforms are not necessarily evaluated or not
+evaluated sequentially. You can use macros to define your own control
+structure constructs (*note Macros::).
+
+* Menu:
+
+* Sequencing:: Evaluation in textual order.
+* Conditionals:: `if', `cond'.
+* Combining Conditions:: `and', `or', `not'.
+* Iteration:: `while' loops.
+* Nonlocal Exits:: Jumping out of a sequence.
+
+\1f
+File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures
+
+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
+function body, this happens automatically. Elsewhere you must use a
+control structure construct to do this: `progn', the simplest control
+construct of Lisp.
+
+ A `progn' special form looks like this:
+
+ (progn A B C ...)
+
+and it says to execute the forms A, B, C and so on, in that order.
+These forms are called the body of the `progn' form. The value of the
+last form in the body becomes the value of the entire `progn'.
+
+ In the early days of Lisp, `progn' was the only way to execute two
+or more forms in succession and use the value of the last of them. But
+programmers found they often needed to use a `progn' in the body of a
+function, where (at that time) only one form was allowed. So the body
+of a function was made into an "implicit `progn'": several forms are
+allowed just as in the body of an actual `progn'. Many other control
+structures likewise contain an implicit `progn'. As a result, `progn'
+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...
+ This special form evaluates all of the FORMS, in textual order,
+ returning the result of the final form.
+
+ (progn (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The third form"
+
+ Two other control constructs likewise evaluate a series of forms but
+return a different value:
+
+ - Special Form: prog1 form1 forms...
+ This special form evaluates FORM1 and all of the FORMS, in textual
+ order, returning the result of FORM1.
+
+ (prog1 (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The first form"
+
+ Here is a way to remove the first element from a list in the
+ variable `x', then return the value of that former element:
+
+ (prog1 (car x) (setq x (cdr x)))
+
+ - 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.
+
+ (prog2 (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The second form"
+
+\1f
+File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures
+
+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...
+ `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
+ ELSE-FORMS are evaluated in textual order, and the value of the
+ last one is returned. (The ELSE part of `if' is an example of an
+ implicit `progn'. *Note Sequencing::.)
+
+ If CONDITION has the value `nil', and no ELSE-FORMS are given,
+ `if' returns `nil'.
+
+ `if' is a special form because the branch that is not selected is
+ never evaluated--it is ignored. Thus, in the example below,
+ `true' is not printed because `print' is never called.
+
+ (if nil
+ (print 'true)
+ 'very-false)
+ => very-false
+
+ - 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,
+ a clause looks like this:
+
+ (CONDITION BODY-FORMS...)
+
+ `cond' tries the clauses in textual order, by evaluating the
+ CONDITION of each clause. If the value of CONDITION is non-`nil',
+ the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
+ the value of the last of BODY-FORMS becomes the value of the
+ `cond'. The remaining clauses are ignored.
+
+ If the value of CONDITION is `nil', the clause "fails", so the
+ `cond' moves on to the following clause, trying its CONDITION.
+
+ If every CONDITION evaluates to `nil', so that every clause fails,
+ `cond' returns `nil'.
+
+ A clause may also look like this:
+
+ (CONDITION)
+
+ Then, if CONDITION is non-`nil' when tested, the value of
+ CONDITION becomes the value of the `cond' form.
+
+ The following example has four clauses, which test for the cases
+ where the value of `x' is a number, string, buffer and symbol,
+ respectively:
+
+ (cond ((numberp x) x)
+ ((stringp x) x)
+ ((bufferp x)
+ (setq temporary-hack x) ; multiple body-forms
+ (buffer-name x)) ; in one clause
+ ((symbolp x) (symbol-value x)))
+
+ Often we want to execute the last clause whenever none of the
+ previous clauses was successful. To do this, we use `t' as the
+ CONDITION of the last clause, like this: `(t BODY-FORMS)'. The
+ form `t' evaluates to `t', which is never `nil', so this clause
+ never fails, provided the `cond' gets to it at all.
+
+ For example,
+
+ (cond ((eq a 'hack) 'foo)
+ (t "default"))
+ => "default"
+
+ This expression is a `cond' which returns `foo' if the value of
+ `a' is 1, and returns the string `"default"' otherwise.
+
+ Any conditional construct can be expressed with `cond' or with `if'.
+Therefore, the choice between them is a matter of style. For example:
+
+ (if A B C)
+ ==
+ (cond (A B) (t C))
+
+\1f
+File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures
+
+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
+ 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...
+ The `and' special form tests whether all the CONDITIONS are true.
+ It works by evaluating the CONDITIONS one by one in the order
+ written.
+
+ If any of the CONDITIONS evaluates to `nil', then the result of
+ the `and' must be `nil' regardless of the remaining CONDITIONS; so
+ `and' returns right away, ignoring the remaining CONDITIONS.
+
+ If all the CONDITIONS turn out non-`nil', then the value of the
+ last of them becomes the value of the `and' form.
+
+ Here is an example. The first condition returns the integer 1,
+ which is not `nil'. Similarly, the second condition returns the
+ integer 2, which is not `nil'. The third condition is `nil', so
+ the remaining condition is never evaluated.
+
+ (and (print 1) (print 2) nil (print 3))
+ -| 1
+ -| 2
+ => nil
+
+ Here is a more realistic example of using `and':
+
+ (if (and (consp foo) (eq (car foo) 'x))
+ (message "foo is a list starting with x"))
+
+ Note that `(car foo)' is not executed if `(consp foo)' returns
+ `nil', thus avoiding an error.
+
+ `and' can be expressed in terms of either `if' or `cond'. For
+ example:
+
+ (and ARG1 ARG2 ARG3)
+ ==
+ (if ARG1 (if ARG2 ARG3))
+ ==
+ (cond (ARG1 (cond (ARG2 ARG3))))
+
+ - 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.
+
+ If any of the CONDITIONS evaluates to a non-`nil' value, then the
+ result of the `or' must be non-`nil'; so `or' returns right away,
+ ignoring the remaining CONDITIONS. The value it returns is the
+ non-`nil' value of the condition just evaluated.
+
+ If all the CONDITIONS turn out `nil', then the `or' expression
+ returns `nil'.
+
+ For example, this expression tests whether `x' is either 0 or
+ `nil':
+
+ (or (eq x nil) (eq x 0))
+
+ Like the `and' construct, `or' can be written in terms of `cond'.
+ For example:
+
+ (or ARG1 ARG2 ARG3)
+ ==
+ (cond (ARG1)
+ (ARG2)
+ (ARG3))
+
+ You could almost write `or' in terms of `if', but not quite:
+
+ (if ARG1 ARG1
+ (if ARG2 ARG2
+ ARG3))
+
+ This is not completely equivalent because it can evaluate ARG1 or
+ ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
+ any argument more than once.
+
+\1f
+File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures
+
+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...
+ `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
+ process repeats until CONDITION evaluates to `nil'.
+
+ There is no limit on the number of iterations that may occur. The
+ loop will continue until either CONDITION evaluates to `nil' or
+ until an error or `throw' jumps out of it (*note Nonlocal Exits::).
+
+ The value of a `while' form is always `nil'.
+
+ (setq num 0)
+ => 0
+ (while (< num 4)
+ (princ (format "Iteration %d." num))
+ (setq num (1+ num)))
+ -| Iteration 0.
+ -| Iteration 1.
+ -| Iteration 2.
+ -| Iteration 3.
+ => nil
+
+ If you would like to execute something on each iteration before the
+ end-test, put it together with the end-test in a `progn' as the
+ first argument of `while', as shown here:
+
+ (while (progn
+ (forward-line 1)
+ (not (looking-at "^$"))))
+
+ This moves forward one line and continues moving by lines until it
+ reaches an empty. It is unusual in that the `while' has no body,
+ just the end test (which also does the real work of moving point).
+
+\1f
+File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures
+
+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
+result of errors; you can also use them under explicit control.
+Nonlocal exits unbind all variable bindings made by the constructs being
+exited.
+
+* Menu:
+
+* Catch and Throw:: Nonlocal exits for the program's own purposes.
+* Examples of Catch:: Showing how such nonlocal exits can be written.
+* Errors:: How errors are signaled and handled.
+* Cleanups:: Arranging to run a cleanup form if an error happens.
+
+\1f
+File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits
+
+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
+of normal program execution: it performs a nonlocal exit on request.
+(There are other exceptions, but they are for error handling only.)
+`throw' is used inside a `catch', and jumps back to that `catch'. For
+example:
+
+ (catch 'foo
+ (progn
+ ...
+ (throw 'foo t)
+ ...))
+
+The `throw' transfers control straight back to the corresponding
+`catch', which returns immediately. The code following the `throw' is
+not executed. The second argument of `throw' is used as the return
+value of the `catch'.
+
+ The `throw' and the `catch' are matched through the first argument:
+`throw' searches for a `catch' whose first argument is `eq' to the one
+specified. Thus, in the above example, the `throw' specifies `foo',
+and the `catch' specifies the same symbol, so that `catch' is
+applicable. If there is more than one applicable `catch', the
+innermost one takes precedence.
+
+ Executing `throw' exits all Lisp constructs up to the matching
+`catch', including function calls. When binding constructs such as
+`let' or function calls are exited in this way, the bindings are
+unbound, just as they are when these constructs exit normally (*note
+Local Variables::). Likewise, `throw' restores the buffer and position
+saved by `save-excursion' (*note Excursions::), and the narrowing
+status saved by `save-restriction' and the window selection saved by
+`save-window-excursion' (*note Window Configurations::). It also runs
+any cleanups established with the `unwind-protect' special form when it
+exits that form (*note Cleanups::).
+
+ The `throw' need not appear lexically within the `catch' that it
+jumps to. It can equally well be called from another function called
+within the `catch'. As long as the `throw' takes place chronologically
+after entry to the `catch', and chronologically before exit from it, it
+has access to that `catch'. This is why `throw' can be used in
+commands such as `exit-recursive-edit' that throw back to the editor
+command loop (*note Recursive Editing::).
+
+ Common Lisp note: Most other versions of Lisp, including Common
+ Lisp, have several ways of transferring control nonsequentially:
+ `return', `return-from', and `go', for example. XEmacs Lisp has
+ only `throw'.
+
+ - 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
+ normally before the return point is established.
+
+ With the return point in effect, `catch' evaluates the forms of the
+ BODY in textual order. If the forms execute normally, without
+ error or nonlocal exit, the value of the last body form is
+ returned from the `catch'.
+
+ If a `throw' is done within BODY specifying the same value TAG,
+ the `catch' exits immediately; the value it returns is whatever
+ was specified as the second argument of `throw'.
+
+ - 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
+ value specified in the `catch'. If multiple return points match
+ TAG, the innermost one is used.
+
+ The argument VALUE is used as the value to return from that
+ `catch'.
+
+ If no return point is in effect with tag TAG, then a `no-catch'
+ error is signaled with data `(TAG VALUE)'.
+
+\1f
+File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits
+
+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
+compute `(foo I J)' for I and J varying from 0 to 9:
+
+ (defun search-foo ()
+ (catch 'loop
+ (let ((i 0))
+ (while (< i 10)
+ (let ((j 0))
+ (while (< j 10)
+ (if (foo i j)
+ (throw 'loop (list i j)))
+ (setq j (1+ j))))
+ (setq i (1+ i))))))
+
+If `foo' ever returns non-`nil', we stop immediately and return a list
+of I and J. If `foo' always returns `nil', the `catch' returns
+normally, and the value is `nil', since that is the result of the
+`while'.
+
+ Here are two tricky examples, slightly different, showing two return
+points at once. First, two return points with the same tag, `hack':
+
+ (defun catch2 (tag)
+ (catch tag
+ (throw 'hack 'yes)))
+ => catch2
+
+ (catch 'hack
+ (print (catch2 'hack))
+ 'no)
+ -| yes
+ => no
+
+Since both return points have tags that match the `throw', it goes to
+the inner one, the one established in `catch2'. Therefore, `catch2'
+returns normally with value `yes', and this value is printed. Finally
+the second body form in the outer `catch', which is `'no', is evaluated
+and returned from the outer `catch'.
+
+ Now let's change the argument given to `catch2':
+
+ (defun catch2 (tag)
+ (catch tag
+ (throw 'hack 'yes)))
+ => catch2
+
+ (catch 'hack
+ (print (catch2 'quux))
+ 'no)
+ => yes
+
+We still have two return points, but this time only the outer one has
+the tag `hack'; the inner one has the tag `quux' instead. Therefore,
+`throw' makes the outer `catch' return the value `yes'. The function
+`print' is never called, and the body-form `'no' is never evaluated.
+
+\1f
+File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits
+
+Errors
+------
+
+When XEmacs Lisp attempts to evaluate a form that, for some reason,
+cannot be evaluated, it "signals" an "error".
+
+ When an error is signaled, XEmacs's default reaction is to print an
+error message and terminate execution of the current command. This is
+the right thing to do in most cases, such as if you type `C-f' at the
+end of the buffer.
+
+ In complicated programs, simple termination may not be what you want.
+For example, the program may have made temporary changes in data
+structures, or created temporary buffers that should be deleted before
+the program is finished. In such cases, you would use `unwind-protect'
+to establish "cleanup expressions" to be evaluated in case of error.
+(*Note Cleanups::.) Occasionally, you may wish the program to continue
+execution despite an error in a subroutine. In these cases, you would
+use `condition-case' to establish "error handlers" to recover control
+in case of error.
+
+ Resist the temptation to use error handling to transfer control from
+one part of the program to another; use `catch' and `throw' instead.
+*Note Catch and Throw::.
+
+* Menu:
projects / chise / xemacs-chise.git.1 / blobdiff