liberte@m.cs.uiuc.edu (Daniel LaLiberte) (12/02/88)
Here is the new chapter on Types of Lisp Objects.
Please check it out for accuracy and completeness.
dan
===
@node Types of Lisp Objects
@chapter Types of Lisp Objects
A Lisp @dfn{object} is data used and manipulated by Lisp programs. Data
objects such as the number @samp{@code{1}} and the list @samp{@code{(this
is a list)}} are said to have a type.
A @dfn{type} may be defined as a set of Lisp objects. Objects of the
same type have a similar structure and may often be used in the same
contexts. An object may be a member of more than one type
simultaneously, so it doesn't make sense to ask what the type of an
object is; rather, we might ask whether an object belongs to a particular
type.
While an object may be a member of more than one type, every object is a
member of @emph{exactly} one primitive type. A @dfn{primitive type} is
specially recognized by Emacs and is not ``divisible'' into any other
type. The primitive type of an
object is stored along with the object's data and Lisp functions are
provided to check whether an object is a member of each primitive type.
Examples of primitive types are number, list, and string.
Some types have properties in common with each other and it is useful
to talk about a collection of other types, called a @dfn{supertype}.
Members of a supertype are called @dfn{subtypes}.
For example, strings and vectors have the common property
of being arrays, so the string and vector types are both subtypes of
the array supertype.
A special case use of a type is called a @dfn{derived} type.
There are several derived types recognized by Emacs.
For example, a Lisp function is simply a list where
the first element is @code{lambda}.
In addition to the standard derived types recognized by Emacs, you may,
of course, derive your own types. To do so you may want to provide
supporting functions to create objects of your type and to check whether
an object is a member of your type.
This chapter describes the purpose of each of the standard types in
GNU Emacs Lisp along with their print representation and read syntax.
@node Print Representation and Read Syntax, Number Type, ,
@section Print Representation and Read Syntax
The @dfn{print representation} of an object is the format of the output
generated by the Lisp printer. All types have a print representation.
The @dfn{read syntax} of an object, if it has one, is the format of input
accepted by the Lisp reader. Anything which may be printed may also be
read except for the @dfn{unreadable} types.
However, not every read syntax has a corresponding print syntax (see
Characters and Lists).
Some types do not have a read syntax defined for them. Normally
this is because it would not be particularly useful to have one. These
objects are represented in @dfn{hash notation}, which is the characters
@samp{#<} followed by a descriptive string (typically the type name
and the name of the object), and closed with @samp{>}.
The Lisp reader will signal an @code{invalid-read-syntax} error if it
encounters the character @samp{#}. The buffer type is an example of a
type with no read syntax.
@example
(current-buffer)
=> #<buffer objects.texinfo>
@end example
The Lisp reader skips comments. A comment starts with a semicolon
(@samp{;}) and continues to the end of line. Any characters may be
included in the comment but it is advisable to preceed special
characters such as unbalanced @samp{(} and @samp{)} with @samp{\} to
hide their normal meaning from Lisp editing commands. Many examples
in this manual include comments.
@node Number Type, Character Type, Print Representation and Read Syntax,
@section Number Type
There is only one kind of number in GNU Emacs Lisp version 18, an
integer. The range of values for a small integer is -8388608 to 8388607
(24 bits) on many machines, although it is 25 or 26 bits on some. It is
important to note that in GNU Emacs Lisp, arithmetic functions do not
check for overflow. Thus @code{(1+ 8388607) == -8388608} (on 24 bit
implementations).
The Lisp reader accepts numbers as a sequence of digits with an optional
sign.
@example
-1 ;The integer -1.
1 ;The integer 1.
+1 ;Also the integer 1.
16777217 ;Also the integer 1! (on a 24 bit implementation)
@end example
@node Character Type, Sequence Type, Number Type,
@section Character Type
Characters in GNU Emacs Lisp are represented internally with their ASCII
values. For example, the character @key{A} is represented internally as the
integer 65. If an arbitrary integer is used as a character, only the
lower 8 bits are significant, but this behavior is not guaranteed (or is it??).
It is unusual for a programmer to work with individual characters. It is
far more common to work with @emph{strings}, which are composed of characters.
There are a variety of read syntax formats for characters.
The normal syntax for reading individual characters is a question mark
followed by the character (e.g., @samp{?A} for the character
@kbd{A}).
For control characters, one valid representation is the sequence:
question mark, backslash, caret, and the corresponding non-control
character (e.g., @samp{?\^I} for the character @kbd{C-i}). Similarly,
the syntax @samp{?\C-i} is valid for @kbd{C-i}.
The @samp{\C-i} syntax will work with either upper or lower case @kbd{I}
(the result is the same), but the @samp{C} must be upper case.
For any character, another possible format is a question mark, then a
backslash followed by the ASCII value of the character in octal (e.g.,
@samp{?\001} for @kbd{C-a}). This syntax is preferred when the precise
octal value is more important than the ASCII representation.
@dfn{Meta} characters are defined as the set of ASCII characters
which have their eighth bit set. These characters may be written as
@samp{?\M-A} (the character @kbd{M-A}, the @samp{A} is upper case), or
@samp{?\M-a} (the character @kbd{M-a}, the @samp{a} is lower case).
Backspace, newline, formfeed, tab, and return can be
abbreviated: @kbd{?\b ?\n ?\f ?\t ?\r} (lower case only).
The characters @samp{()\|;'`"#.,} @b{must} be preceded by a backslash
to work reliably in all contexts. The space character,
tab, newline, formfeed and any explicit control characters must also be
preceeded by backslash; but rather than entering these invisible characters
explicitly, it is better to use one of the other formats.
Here is a summary of all the possible escape sequences. (The backslash
character is also known as an @dfn{escape}, not to be confused with
@key{ESC}.)
@table @code
@item \001
An octal integer: read as the ASCII equivalent (ASCII 1, @kbd{C-a})
@item \^a
"^" and a character: read as that control character (ASCII 1, @kbd{C-a})
@item \C-a
"C-" and a character: read as that control character (ASCII 1, @kbd{C-a})
@item \M-a
"M-" and a character: read as that meta character (ASCII 301, @kbd{M-a})
@item \b
a backspace (ASCII 8, @key{BS}, @kbd{C-h})
@item \n
a newline (ASCII 10, @key{LFD}, @kbd{C-j})
@item \r
a carriage return (ASCII 13, @key{RET}, @kbd{C-m})
@item \t
a tab character (ASCII 9, @key{TAB}, @kbd{C-i})
@item \f
a formfeed character (ASCII 12, @kbd{C-l})
@end table
Characters always print as decimal integers. Thus, the following list
of characters which are specified with a variety of read formats is
printed as a list of numbers.
@example
'(?A ?\000 ?\t ?\n ?\f ?\r ?\( ?\) ?\\ ?\| ?\011 ?\^I ?\C-i ?\M-i)
=> (65 0 9 10 12 13 40 41 92 124 9 9 9 201)
@end example
@node String Type, Vector Type, , Array Type
@subsection String Type
A @dfn{string} is an array of characters.
Strings are used for many purposes, as can be expected in a text editor.
Some examples of strings are the names of Lisp symbols, messages for
the user, and substrings extracted from buffers.
Strings share all the
attributes of vectors except that their elements are restricted to being
characters (i.e. integers between 0 and 255); strings, however, are not
vectors.
A string may be entered in a program as a list of characters between
double quotes. The Lisp reader will read those characters in the same
way as for the character type (without the preceding question mark).
@xref{Character Type} for the details about character syntax. In
particular, @samp{"\\"} reads as a string consisting of one backslash
character and, @samp{"\""} reads as the string consisting of one double
quote character.
It is useful to include actual newline characters in strings as shown
in the following example. If you wish to inhibit the inclusion of
a new line, preceed it with backslash.
@example
"This is the first half of line 1; \
this is the second half of line 1.
This is all of line 2."
=> "This is the first half of line 1; this is the second half of line 1.
This is all of line 2."
@end example
For control characters in strings, the Lisp printer will print out the
string with the actual control characters embedded in it. However,
control characters will be displayed on the screen according to how
Emacs is set up to display them (@pxref{ctl-arrow}). The other two
characters requiring special syntax (backslash and double-quote) print
out with a leading backslash:
@node List Type, Array Type, Sequence Type,
@section List Type
A @dfn{list} is a series of zero or more cons cells, linked together. A
@dfn{cons cell} (also called a @dfn{pair}) is a Lisp object comprised of
two pointers known as the @dfn{car} and the @dfn{cdr}, each of which, in
turn, can point to any Lisp object. Normal use of cons cells is that the
@code{cdr} point to another cons cell or the empty list.
A list without any elements in it is called the @dfn{empty list}; it is
identical to the symbol @code{nil}. In other words, @code{nil} is
both a symbol and a list.
@example
(symbolp nil) => t
(listp nil) => t
@end example
To enter a list in a program, begin with an open parenthesis @samp{(},
follow it with the list of elements of the list, and end with a close
parenthesis @samp{)}. Any objects (symbols, numbers, vectors, strings, or
other lists) that are read between such a pair of parentheses become
the elements of the list. The use of the escape character (@samp{\})
nullifies this special meaning of open/close parenthesis, but it is
advisable to avoid this use. (Also, unbalanced parentheses in strings and
comments can confuse some of the Lisp editing commands.)
@example
(A 2 "A") ; A list of three elements
() ; A list of no elements (the empty list)
nil ; A list of no elements (the empty list)
("A ()") ; A list of one element: the string "A ()"
(A ()) ; A list of two elements: A and the empty list
((A B C)) ; A list of one element (which is a list of 3)
@end example
The character period @samp{.} is significant in lists. Following
a period should be one object which becomes the @code{cdr} of the
final cons cell in the list. Therefore, these unusual lists are not
terminated with @code{nil}. A cons cell is also called a @dfn{dotted pair}
since it may be read as the car dotted with the cdr.
@example
(A . B) ; A list of one element and a non-@code{nil} cdr
(A B . C) ; A list of two elements and a non-@code{nil} cdr
(A . B . C) ; Invalid syntax
(A . (B)) ; A list which is equivalent to (A B)
(A . (B . (C))) ; A list which is equivalent to (A B C)
@end example
Lists print in the same way as they are read, except that the period
syntax is not used if the cdr is a cons cell.
@node Vector Type, , String Type, Array Type
@subsection Vector Type
A @dfn{vector} is a one-dimensional array of elements of any type.
Unlike a list, any element of a vector may be accessed in equal time.
The print representation and read syntax of vectors are identical: the
elements of a vector are preceded by a left square bracket @samp{[} and
followed by a right square bracket @samp{]}. It should be noted that
two vectors created with the same elements will not be the same vector.
Indeed, there is no way in which to @dfn{read} the same vector twice.
@example
(setq v1 (vector 1 2 'foo))
=> [1 2 foo] ;Create a vector of three elements.
(setq v2 (vector 1 2 'foo))
=> [1 2 foo] ;Create another vector of three elements.
(eq v1 v2)
=> nil ;They are not the same vector.
[1 2 3]
=> [1 2 3]
(eq [a b c] [a b c]) ;NB: the elements are not evaluated.
=> nil ;They are not the same vector.
(equal [a b c] [a b c])
=> t ;But they have the same structure.
@end example
@node Array Type, Symbol Type, List Type,
@section Array Type
An @dfn{array} is a Lisp object composed of other Lisp objects any of which
may be accessed in equal time. The term @dfn{array} has a more general
meaning in other contexts, but in GNU Emacs Lisp, there are only two types of
arrays, both one-dimensional. A string is an array of characters and a
vector is an array of any type.
All arrays have a fixed length and are indexed @dfn{zero-origin}. For
example, an array of four elements allows indices 0, 1, 2, and 3. The
elements of any array may be referenced or changed with the functions
@code{aref} and @code{aset}.
Arrays are a subtype of sequences and there is a collection of more general
functions which operate on sequences.
@node Sequence Type, List Type, Character Type,
@section Sequence Type
The @dfn{sequence} type is a supertype of three other Lisp types:
lists, vectors, and strings. That is to say, lists, vectors, and strings
are all sequences. Common between all sequences is that each is composed of
an ordered collection of elements.
Some Lisp functions can accept any kind of sequence as an
argument; only the ordered elements of the sequence are significant.
@node Symbol Type, Primitive Function Type, Array Type,
@section Symbol Type
A @dfn{symbol} in GNU Emacs Lisp is an object that serves several
purposes. A symbol may be used in programs to refer to a global
variable value, a function, a property list, or the symbol itself. In a
given context, only one of these uses is intended.
To support these uses, symbols have four attributes or @dfn{cells}: a
print name cell, a value cell, a function cell, and a property list
cell. Each of these is a reference to some other Lisp object, and all
but the print name may be void. The term @dfn{void} will be used to
indicate that a cell has no valid data in it, e.g., @samp{The symbol's
value is void}. This should not be confused with the symbol
@code{void}. Note that the data in a cell may be @code{nil} which is
not void either. An example is the symbol @code{buffer-file-name} which
has the print name "buffer-file-name" and data in the value, function,
and property list cells.
The print name cell is described here. The other cells of symbols are
described in the chapter on Symbols (@pxref{Symbols}).
The print name is the most obvious thing about a symbol: it is what the
printer prints when handed a symbol, and it is what distinguishes symbols
from one another when the Lisp reader reads them. The print name cell
references a string which is the print name, hence the name can consist of
any string of characters whatsoever. You may use a symbol in a program by
typing its print name (without double quotes).
The rules for reading a symbol are similar to those for reading a
string: all alphanumeric characters are read as part of the symbol's
name. Other characters may be included in a symbol's name by escaping
them with a backslash. Unlike the use in strings, the meaning of
backslash is limited to quoting the single character that follows with
no special interpretation. Hence to have a symbol with a tab character
(@key{TAB}) in its name, @samp{\t} will not work; rather you must
actually type a tab. Putting unusual characters in a symbol's name is a
very poor idea.
________________________________
CN: In Common Lisp, lower case letters are always ``folded'' to
upper case, unless they are explicitly ``escaped''. This is not
the case in GNU Emacs Lisp.
____________________
Each line below shows the printed representation of a single symbol.
@example
foo ; A symbol named "foo"
FOO ; A symbol named "FOO", different from foo
char-to-string ; A symbol named "char-to-string"
1+ ; A symbol named "1+"
+1 ; An integer, not a symbol
-1 ; An integer, not a symbol
\+1 ; A symbol named "+1" (a poor name to choose)
\(*\ 1\ 2\) ; A symbol named "(* 1 2)" (a worse name)
+-*/_~!@@$%^&=:<>@{@} ; The characters that don't need to be escaped.
; (except + and - if they preceed digits)
@end example
@node Primitive Function Type, Buffer Type, Symbol Type,
@section Primitive Function Type
A @dfn{primitive function} is a function callable from Lisp that is written
in C. Primitives are also called @dfn{subrs} (subroutines), @dfn{built-in
functions}, or @dfn{compiled functions}. They print in hash notation with
the symbol name of the function.
@xref{Lisp Function Type} for the related Lisp function.
@example
(symbol-function 'car) @r{; Access the function cell of the symbol.}
=> #<subr car> @r{; A compiled function}
(subrp (symbol-function 'car)) @r{; Is this a subr?}
=> t
@end example
@node Buffer Type, Marker Type, Primitive Function Type,
@section Buffer Type
A @dfn{buffer} is an object containing characters. Buffers are used to
hold the contents of files when they are visited and buffers may be
displayed in windows. But a buffer need not have an associated file or
window. While several buffers may exist at one time, only one buffer
is designated the @dfn{current buffer}. Most editing commands act on the
contents of the current buffer.
Buffers can be treated rather like simple strings, but they are, in
fact, complex objects which allow for inexpensive modification. A large
set of functions is available to insert, delete, copy, or otherwise
manipulate the characters in the buffer.
Several other data structures may be associated with buffers: a buffer may
have a local syntax table, a local keymap, and a local variable binding
list. Each of these overrides its global counterpart. The effect is that
editing commands may have a different behavior in each buffer.
Buffers have no read syntax. They print in hash
notation with the buffer name.
@example
(current-buffer)
=> #<buffer objects.texinfo>
@end example
@node Marker Type, Window Type, Buffer Type,
@section Marker Type
A @dfn{marker} is an object which denotes a
position in a specific buffer. They have two cells, one for the
buffer, and one for the position in that buffer.
The position value is changed as text is inserted or deleted
so that the marker always points to the same place in the text.
Makers have no read syntax. They print in hash notation giving the
character position and the name of the buffer.
@example
(point-marker)
=> #<marker at 10779 in objects.texinfo>
@end example
@node Window Type, Window Configuration Type, Marker Type,
@section Window Type
A @dfn{window} is an object that describes the portion of the terminal
screen that Emacs uses to display a buffer. Every window has an
associated buffer, but not all buffers must be displayed in a window. Windows
cannot be read in. They print out in hash notation giving the window
number and buffer name.
@example
(selected-window)
=> #<window 1 on objects.texinfo>
@end example
@node Window Configuration Type, Process Type, Window Type,
@section Window Configuration Type
A @dfn{window configuration} stores information about the positions and
sizes of windows at some particular time so that the configuration may be
recreated later. Window configurations have no read syntax and always
print as @samp{#<window-configuration>}.
@xref{Window Configurations} for the details.
@node Process Type, Derived Types, Window Configuration Type,
@section Process Type
A @dfn{process} is a complex data structure which references the subprocess
that Emacs has spawned off to perform some task. Text and signals can be
communicated between Emacs and the subprocess. Processes have no read
syntax. They print out in hash notation giving the name of the process.
@example
(process-list)
=> (#<process shell>)
@end example
@node Stream Type, , , Process Type
@section Stream Type
A @dfn{stream} is a type of object that Emacs can use as a source (input) or
sink (output) for characters. Many different objects fulfill this
requirement: markers, buffers, strings, functions, and function names.
The object @code{nil} is used as a stream to mean that the value of the
variable @code{standard-input} or @code{standard-output} should be used.
Similarly, the object @code{t} is used as a stream to represent input
or output in the @dfn{minibuffer}. @xref{Streams} for the details.
@node Derived Types, Predicates, Process Type,
@section Derived Types
GNU Emacs Lisp uses several other derived types which are special
case uses of
types described previously.
@node Association List Type, Lisp Function Type, , Derived Types
@subsection Association List Type
An @dfn{association list} is a list of pairs (cons cells), where the @code{car}
of each pair is the key, and the @code{cdr} is the associated value.
Association lists are often used to record information that one might
otherwise keep on a stack since new pairs may be simply added to the
front of the list.
@xref{Association Lists} for the details.
@node Lisp Function Type, Lisp Macro Type, Association List Type, Derived Types
@subsection Lisp Function Type
Lisp functions are the principal means by which Emacs may be
extended. A Lisp @dfn{function} is a list where the first element is the
symbol @code{lambda}.
Lisp function objects are normally created with @code{defun}. But lists
that begin with @code{lambda} may be read in and used as functions.
@xref{Functions} for the details.
@example
(defun foo (n) (print n))
=> foo
(symbol-function 'foo)
=> (lambda (n) (print n)) ;An interpreted function.
@end example
@node Lisp Macro Type, Autoload Type, Lisp Function Type, Derived Types
@subsection Lisp Macro Type
Lisp macros appear to be similar to Lisp functions but they are
evaluated quite differently.
A Lisp @dfn{macro} is a list where the first
element is the symbol @code{macro}.
Lisp macro objects are normally created with
@code{defmacro}. But lists that begin with
@code{macro} may be read in and used as
macros. @xref{Macros} for the details.
@node Autoload Type, Byte Code Type, Lisp Macro Type, Derived Types
@subsection Autoload Type
The purpose of using @code{autoload} objects is to avoid loading a file of
definitions unless they are needed.
An @dfn{autoload} object is a list
where the first element is the symbol @code{autoload}. An autoload
object is normally created with the @code{autoload} function.
@xref{autoload} for the details.
@node Byte Code Type, Syntax Table Type, Autoload Type, Derived Types
@subsection Byte Code Type
@dfn{Byte code} is generated from Lisp function and
macro objects. It is a list where the first element is the symbol
@code{byte-code}. Evaluation of byte code is much faster than evaluation
of non byte code. @xref{Byte Compilation} for the details.
@node Syntax Table Type, Keymap Type, Byte Code Type, Derived Types
@subsection Syntax Table Type
A @dfn{syntax table} is a vector of 256 integers. The elements define how the
corresponding characters will be interpreted when they appear in a buffer.
For example, in C mode, the character @samp{+} is punctuation, while in Lisp
mode it can be a character in a symbol name.
Syntax tables are only used for editing text in buffers, not for reading Lisp
expressions. The table which Lisp uses to read expressions is built into
the C code and cannot be changed.
@xref{Syntax Tables} for the details.
@node Keymap Type, , Syntax Table Type, Derived Types
@subsection Keymap Type
A @dfn{keymap} is a map from keys typed by the user to functions which they
call. There are two kinds of keymaps: @dfn{full keymaps}, which are
implemented as vectors of 128 elements, and @dfn{sparse keymaps}, which are
implemented as association lists with a preceding @code{keymap} symbol.
@xref{Keymaps} for the details.
@node Predicates, , Derived Types,
@section Predicates
A @dfn{predicate} tests to see if some relation is met by its
arguments. It returns a truth value which, in Lisp, is @code{nil} for
false, and anything else for true. Most predicates return either the
value @code{t} or their argument for a true value. Any non-@code{nil}
value is interpreted as a true value.
@node Type Predicates, Equality Predicates, , Predicates
@subsection Type Predicates
The GNU Emacs Lisp interpreter does not perform any type checking on the
actual arguments of function calls. It is up to each function to test
whether each actual argument is a member of the correct type.
All primitive functions do test the type of the actual arguments.
Many functions are provided to test whether an object is a member of a
type. Here is a table of all of them and where they are described.
@table @code
@item integerp
@pxref{integerp}
@item natnump
@pxref{natnump}
@item markerp
@pxref{markerp}
@item integer-or-marker-p
@pxref{integer-or-marker-p}
@item sequencep
@pxref{sequencep}
@item stringp
@pxref{stringp}
@item char-or-string-p
@pxref{char-or-string-p}
@item arrayp
@pxref{arrayp}
@item vectorp
@pxref{vectorp}
@item consp
@pxref{consp}
@item listp
@pxref{listp}
@item nlistp
@pxref{nlistp}
@item bufferp
@pxref{bufferp}
@item windowp
@pxref{windowp}
@item processp
@pxref{processp}
@item symbolp
@pxref{symbolp}
@item user-variable-p
@pxref{user-variable-p}
@item subrp
@pxref{subrp}
@item featurep
@pxref{featurep}
@item keymapp
@pxref{keymapp}
@item syntax-table-p
@pxref{syntax-table-p}
@end table
@node Equality Predicates, , Type Predicates, Predicates
@subsection Equality Predicates
There are two functions to test equality between any two objects. These
are described here. There are also functions to test equality between
objects of specific types. For descriptions of these functions, see the
appropriate chapter on the type.
@defun eq object1 object2
This function returns @code{t} if the two objects are the same object,
@code{nil} otherwise. Symbols with the same print name are always
@code{eq} (what about uninterned symbols??). Numbers with the same value
are @code{eq}. Other objects (e.g., lists, vectors, strings) with the same
elements may or may not be.
Also, if two objects are @code{eq} to each other,
a change in one will be reflected in the same change in the other.
@end defun
@example
(eq 'foo 'foo)
=> t
(eq 456 456)
=> t
(eq "asdf" "asdf")
=> nil
(eq '(1 (2 (3))) '(1 (2 (3))))
=> nil
(eq [(1 2) 3] [(1 2) 3])
=> nil
(eq (point-marker) (point-marker))
=> nil
@end example
@defun equal object1 object2
This function returns @code{t} if the two objects are structurally ``the
same'', @code{nil} otherwise. Objects (in particular, primitive objects)
which are @code{eq} are also @code{equal}. Lists, vectors, markers, and
strings are @code{equal} if the corresponding elements are @code{equal}.
(what about other primitive types: buffers, window, etc?)
@example
(equal "asdf" "asdf")
=> t
(equal "asdf" "ASDF")
=> nil
(equal '(1 (2 (3))) '(1 (2 (3))))
=> t
(equal [(1 2) 3] [(1 2) 3])
=> t
(equal (point-marker) (point-marker))
=> t
@end example
@end defunliberte@M.CS.UIUC.EDU (Daniel LaLiberte) (12/04/88)
I am planning to replace cross reference to functions with cross references to the sections those functions are in. This is painful for me to do, aside from the tedium, because I believe there should be cross referencing to functions. However, that requires changes to TeX (fixed size tables are the *wrong* way to do things) and the info programs. Someone could change the info programs, but we have to live with TeX as it is for now. The manual is about 400 pages. That will grow a bit before it is finished. dan
liberte@M.CS.UIUC.EDU (Daniel LaLiberte) (02/06/89)
After much reorganization from the last round of reviews, here
is the latest version of the Objects chapter. Please comment.
(ignore the @nodes for now)
Dan LaLiberte
uiucdcs!liberte
liberte@cs.uiuc.edu
liberte%a.cs.uiuc.edu@uiucvmd.bitnet
====================================
@node Types of Lisp Objects
@chapter Types of Lisp Objects
A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
programs. For our purposes, a @dfn{type} is a set of objects.
Every object belongs to at least one type. Objects of the same type
have a similar structure and may usually be used in the same contexts.
Since an object may be in more than one type simultaneously, we ask whether
an object belongs to a particular type, not what type the object belongs to.
While an object may be a member of more than one type, every object is a
member of exactly one primitive type. A @dfn{primitive type} is a type
built into Emacs' source code, as opposed to being defined in Lisp. The
primitive type of an object is stored along with the object's data. A
Lisp function is provided for each primitive type to check whether an
object is a member of that type.
@cindex types, primitive
Note that while C or Pascal compilers employ type declarations to reason
about the types of objects, Lisp objects are ``self-typing'', meaning
that the primitive type of the object is implicit in the object itself.
This is typically implemented using some sort of tagging scheme. There
are no type declarations in Emacs Lisp.
Some other terminology deals with classes of types. A @dfn{supertype}
is a collection of other @dfn{subtypes} that have some common property.
For example, strings and vectors have the common property
of being arrays, so the string and vector types are both subtypes of
the array supertype.
There are several special-case uses of primitive types that constitute
new types. For example, a Lisp function type is just a list whose first
element is the symbol @code{lambda}.
In addition to the standard types provided by Emacs, you may create
your own types out of any existing types. To do so, you may provide
supporting functions to create objects of your type and to check whether
an object belongs to your type.
@cindex types, user-defined
@b{Common Lisp Note:} Emacs Lisp does not provide @code{defstruct} to
define structured types; however, see @file{cl.el}.
@cindex Common Lisp
@cindex structured types
This chapter describes the purpose, print representation, and read
syntax of each of the standard types in GNU Emacs Lisp. Further details
on specific types can be found in later chapters.
@menu
* Print Representation and Read Syntax::
* Programming Types:: Types found in all Lisp systems.
* Editing Types:: Types specific to Emacs.
* Type Predicates:: Tests related to types.
* Equality Predicates:: Tests of equality between any two objects.
@end menu
@node Print Representation and Read Syntax, Programming Types, , Types of Lisp Objects
@section Print Representation and Read Syntax
The @dfn{print representation} of an object is the format of the
output generated by the Lisp printer for that object. The @dfn{read
syntax} of an object is the format of the input accepted by the Lisp
reader for that object. Very often, the print representation and the
read syntax are the same.
All types have a print representation. Not every type has a read
syntax, since it may not be useful to be able to enter objects of
some types directly in a Lisp program. These types are always printed
in @dfn{hash notation}: the characters @samp{#<} followed by a
@cindex hash notation
descriptive string (typically the type name followed by the name of the
object), and closed with a matching @samp{>}.
Hash notation can never be read because the Lisp reader signals the error
@code{invalid-read-syntax} whenever a @samp{#} is encountered.
@findex invalid-read-syntax
As you can see from the example, the buffer type is one that does not
have a read syntax.
@example
(current-buffer)
@arrow #<buffer objects.texinfo>
@end example
The Lisp reader skips comments. A @dfn{comment} starts with a semicolon
(@samp{;}) and continues to the end of line. Any characters may be
included in the comment, but it is advisable to precede special
characters, such as @samp{(} and @samp{)}, with a @samp{\} to
hide their normal meaning from Lisp editing commands.
@node Programming Types, Editing Types, Print Representation and Read Syntax, Types of Lisp Objects
@section Programming Types
The types in Emacs Lisp can be divided into two general categories:
those having to do with Lisp programming, and those having to do with
editing. The former are obviously provided in many Lisp implementations,
in some form or another. The latter are unique to Emacs Lisp.
@node Number Type, Character Type, , Programming Types
@subsection Number Type
Integers are the only kind of number in GNU Emacs Lisp, version 18. The
range of values for integers is @minus8388608 to 8388607 (24 bits; i.e.,
@ifinfo -2**24 @end ifinfo
@tex $-2^{24}$ @end tex
to
@ifinfo 2**24 - 1@end ifinfo
@tex $2^{24}-1$@end tex
) on most machines, although it is 25 or 26 bits on some. It is
important to note that the Emacs Lisp arithmetic functions do not check
for overflow. Thus @code{(1+ 8388607)@equiv -8388608}, on 24-bit
implementations.
The read syntax for numbers is a sequence of (base ten) digits with an
optional sign. The print representation never has a leading @samp{+}.
@xref{Numbers} for more information.
@example
-1 ; The integer -1.
1 ; The integer 1.
+1 ; Also the integer 1.
16777217 ; Also the integer 1! (on a 24-bit implementation)
@end example
@node Character Type, Sequence Type, Number Type,
@subsection Character Type
A @dfn{character} is an eight-bit integer. If an arbitrary integer is
used as a character, only the lower eight bits are significant.
Characters in Emacs Lisp are represented internally with their ASCII
values. For example, the character @key{A} is represented internally as
the @w{integer 65}.
It is unusual for a programmer to work with individual characters. It
is far more common to work with @emph{strings},
which are sequences composed of characters (@pxref{String Type}).
Characters have a variety of read syntax formats. The print
representation of characters is always a (decimal) number, regardless of
the read syntax in which it was specified. Each read syntax starts with
a leading question mark. The usual syntax for alphanumeric characters
is a question mark followed by the character; e.g., @samp{?A} for the
character @kbd{A}.
Another syntax is question mark, backslash and an ASCII value in octal
(up to three octal digits); e.g., @samp{?\001} for the character
@kbd{C-a}. Although this syntax can represent any character, it is
preferred when the precise octal value is more important than the ASCII
representation. (The backslash character is also known as an
@dfn{escape character}, not to be confused with @key{ESC}.)
Yet another syntax, this one for control characters, is question mark,
backslash, hat, and the corresponding non-control character, in either
upper or lowercase; e.g., @samp{?\^I} for the character @kbd{C-i}.
(Recall that @kbd{C-i} and @kbd{C-I} are the same character, namely, the
@w{value 9}.) The @samp{^} may be replaced by @samp{C-}; e.g.,
@samp{?\C-I}.
@dfn{Meta characters} are those characters which have their eighth bit
set. The syntax for these characters is question mark, backslash,
@samp{M-}, and the corresponding seven-bit character; e.g., @samp{?\M-A}
for @kbd{M-A}, the @w{value 193}. The seven-bit character can be
specified with one of the @samp{\} escapes mentioned above or below; e.g.,
@samp{?\M-\001} is the character @kbd{M-C-A}, the @w{value 129}.
The characters backspace, tab, vertical tab, formfeed, newline,
return, and escape can be abbreviated @samp{?\b}, @samp{?\t},
@samp{?\v}, @samp{?\f}, @samp{?\n}, @samp{?\r}, @samp{?\e},
respectively. Those values are 8, 10, 12, 9, and 13, in decimal.
Any character without a special escape meaning may be preceded by a backslash.
But any of the characters @samp{()\|;'`"#.,} @emph{must} be preceded by a
backslash to work reliably in all contexts. The space character, tab,
newline, formfeed and literal control characters must also be preceded
by a backslash. Rather than entering invisible control characters
directly, though, it is better to use one of the other formats; that's what
they are there for, after all.
Here are examples of the read syntax formats for characters.
@table @code
@item ?A
A character: read as the character (ASCII 65, @kbd{A}).
@item ?\001
An octal integer: read as the ASCII equivalent (ASCII 1, @kbd{C-A}).
@item ?\^A
@samp{^} and a character: read as that control character (ASCII 1,
@kbd{C-A}).
@item ?\C-A
@samp{C-} and a character: read as that control character (ASCII 1,
@kbd{C-A}).
@item ?\M-A
@samp{M-} and a character: read as that meta character (ASCII 193,
@kbd{M-A}).
@item ?\b
a backspace (ASCII 8, @key{BS}, @kbd{C-h}).
@item ?\t
a tab character (ASCII 9, @key{TAB}, @kbd{C-i}).
@item ?\n
a newline (ASCII 10, @key{LFD}, @kbd{C-j}).
@item ?\v
a vertical tab (ASCII 11, @kbd{C-k}).
@item ?\f
a formfeed character (ASCII 12, @kbd{C-l}).
@item ?\r
a carriage return (ASCII 13, @key{RET}, @kbd{C-m}).
@item ?\e
an escape character (ASCII 27, @key{ESC}).
@item ?\\
a backslash character (ASCII 92, @key{\}).
@end table
@node Sequence Type, List Type, Character Type, Programming Types
@subsection Sequence Type
The @dfn{sequence} type is a supertype of three other Lisp types:
lists, vectors, and strings. That is, an object of type list, vector,
or string also belongs to the type sequence. The common property of
these types is that objects of these types consist of ordered collections of
elements. The thing that makes sequences interesting is that some Lisp
functions accept any sequence object as an argument, not distinguishing
between the three subtypes.
Sequences are always created anew upon reading; it is impossible to read
the same sequence twice, in the sense of @code{eq} (@pxref{eq}).
There is one exception: @code{nil} is always read as the same object.
@xref{Sequences} for the details.
@menu
* List Type:: What gave Lisp its name (not to mention reputation).
* String Type:: An (efficient) array of characters.
* Vector Type:: One-dimensional arrays.
@end menu
@node List Type, Vector Type, , Sequence Type
@subsubsection List Type
A @dfn{list} object is a series of cons cells, linked together. A
@dfn{cons cell} is an object comprised of two pointers named the
@dfn{car} and the @dfn{cdr}, each of which can point to any Lisp object.
In most circumstances, though, the @code{cdr} points to either another
cons cell or the empty list. (Unfortunately, the names @samp{car} and
@samp{cdr} have only historical meaning now. The original Lisp
implementation on an @w{IBM 704} computer referred to an ``address
register'' and ``decrement register''. Hence, @samp{car} was
@cindex address register
@cindex decrement register
the contents of the address register, and @samp{cdr} the contents of the
decrement register. By comparison, @samp{cons} stands for
``construct''.)
The read syntax and print representation for lists are identical, and
consist of a left parenthesis, an arbitrary number of elements, and a
right parenthesis. Any object at all inside the parentheses is made
into an element of the list (upon reading). That is, a cons cell is made
for each element. Its @code{car} points to the element, and its
@code{cdr} points to the next element in the list. The @code{cdr} of the
last element is set to point to @code{nil}. Also, each element is evaluated;
it is actually the result of the evaluation that is put into the list.
A list with no elements in it is the @dfn{empty list}; it is
identical to the symbol @code{nil}. In other words, @code{nil} is both
a symbol and a list. In the example, @code{listp} and @code{symbolp}
test if their argument is a list or symbol, respectively. @xref{Type
Predicates} for more information on such predicates.
@example
(A 2 "A") ; A list of three elements.
() ; A list of no elements (the empty list).
nil ; A list of no elements (the empty list).
("A ()") ; A list of one element: the string "A ()".
(A ()) ; A list of two elements: A and the empty list.
((A B C)) ; A list of one element (which is a list of 3).
(symbolp nil)
@arrow t
(listp nil)
@arrow t
(eq () nil)
@arrow t
@end example
An alternative syntax for lists makes the representation of lists as
cons cells explicit. @samp{(@var{a} . @var{b})} is the cons cell whose
@code{car} is the object @var{a}, and whose @code{cdr} is the object
@var{b}. The so-called @dfn{dotted pair notation} is
therefore more general than the syntax given before. A list @samp{(1 2
3)} is equivalently written as @samp{(1 . (2 . (3 . nil)))}; the former
is just more convenient. When printing a list, the dotted pair notation is
only used if the @code{cdr} of a cell is not a list.
@xref{Lists} for the details.
@example
(A . B) ; A list of one element and a non-@code{nil} cdr
(A B . C) ; A list of two elements and a non-@code{nil} cdr
(A . B . C) ; Invalid syntax
(A . (B)) ; Equivalent to (A B)
(A . (B . (C))) ; Equivalent to (A B C)
@end example
@node Association List Type, Autoload Type, ,Derived Types
@subsubsection Association List Type
An @dfn{association list} is a specially constructed list of cons
cells (or pairs). In each cons cell, the @code{car} is treated as a
@dfn{key}, and the @code{cdr} is treated as an associated @dfn{value}.
Association lists are often used to record information that one might
otherwise keep on a stack, since new pairs may be simply added to the
front of the list.
@xref{Association Lists} for the details.
@node Array Type, Vector Type, , Sequence Type
@subsubsection Array Type
An @dfn{array} object is composed of an arbitrary number of other Lisp
objects, any of which may be accessed in equal time. (Lists do not have
this equal access time property). The term ``array'' has a more general
meaning in other programming languages, but Emacs Lisp defines only two
types of arrays, both one-dimensional: A string is an array of
characters and a vector is an array of arbitrary objects.
All arrays have a fixed length and are indexed @dfn{zero-origin};
i.e., the first element of an array is at index zero. For example, an
array of four elements is indexed by 0, 1, 2, @w{and 3}. The elements
of any array may be referenced or changed with the functions @code{aref}
(@pxref{aref}) and @code{aset} (@pxref{aset}), respectively.
To sum up, the array type is a subtype of sequences and a supertype of
strings and vectors.
@node String Type, , Vector Type, Sequence Type
@subsubsection String Type
A @dfn{string} is an array of characters.
Strings are used for many purposes, as can be expected in a text editor.
Examples of strings include the names of Lisp symbols, messages for
the user, and substrings extracted from buffers.
The read syntax for strings is a double quote, an arbitrary number of
characters, and another double quote. The Lisp reader will accept the
same formats for reading the characters of a string as it does for
reading single characters (without the question mark that begins a
character literal, of course). @xref{Character
Type} for more details about characters. In particular, to enter a
double quote in a string, preceed it with a backslash.
Unlike some other languages, newlines are allowed in Emacs Lisp string
literals. But if the newline is escaped, it does not become part of the
string; i.e., the reader ignores an escaped newline in a string literal.
@cindex newline, in string literal
@example
"It is useful to include newlines in
documentation strings, but the newline is \
ignored if escaped."
=> "It is useful to include newlines in
documentation strings, but the newline is ignored if escaped."
@end example
The print representation of strings is simply the characters in it,
with the following exceptions: The display of control characters depends
on the value of the built-in variable @code{ctl-arrow}
(@pxref{ctl-arrow}); and the backslash and double quote characters
themselves are printed with a leading backslash.
@xref{Strings} for the details.
@node Vector Type, String Type, Array Type, Sequence Type
@subsubsection Vector Type
A @dfn{vector} object is a one-dimensional array of elements each of
which can be of any type. Unlike with lists, it takes the same amount of
time to access any element of a vector.
The print representation and read syntax of vectors are the same: a
left square bracket, the list of elements, and a right square bracket.
@example
[1 "two" (three)] ; A vector of three elements
=> [1 "two" (three)]
@end example
@node Symbol Type, Lisp Function Type, Array Type, Programming Types
@subsection Symbol Type
A @dfn{symbol} in GNU Emacs Lisp is an object that serves several
purposes. A symbol may be used in programs to refer to a global
variable value, a function, a property list, or the symbol itself. In a
given context, only one of these uses is intended.
To support these uses, symbols have four attributes or @dfn{cells}: a
print name cell, a value cell, a function cell, and a property list
cell. Each of these is a reference to some other Lisp object, and all
but the print name may be void. The term @dfn{void} will be used to
indicate that a cell has no valid data in it, e.g., @samp{The symbol's
value is void}. This should not be confused with the symbol
@code{void}. Note that the data in a cell may be @code{nil}, which is
not void either.
An example is the symbol @code{buffer-file-name} which
has the print name "buffer-file-name" and data in the value, function,
and property list cells.
The print name cell is described here. The other cells of symbols are
described in the chapter on Symbols (@pxref{Symbols}).
The print name is the most obvious thing about a symbol: it is what
the printer prints when handed a symbol, and it is what distinguishes
one symbol from another when the Lisp reader reads them. The print
name cell is always a string object.
You use a symbol in a program by typing its print name (without the
double quotes that delimit strings, of course). The rules for reading a
symbol are therefore similar to those for reading a string. Any of the
characters @samp{A-Z}, @samp{a-z}, @samp{0-9}, and
@samp{-+*/_~!@@$%^&=:<>@{@}} are read as part of the symbol's name.
Other characters may be included in a symbol's name by escaping them
with a backslash. Unlike in strings, the backslash simply quotes the
single character that follows. For example, to have a symbol with a tab
character in its name, @samp{\t} will not work; instead, you must
actually type an (escaped) tab.
@b{Common Lisp Note:} lower case letters are always ``folded'' to upper
@cindex Common Lisp, symbols in
case, unless they are explicitly escaped. In Emacs Lisp, uppercase and
lowercase letters are distinct.
Here are some examples of symbol names. In the last example, note that
since the @samp{+} was not followed by only digits, it is read as a
symbol name, instead of a number.
@example
foo ; A symbol named "foo".
FOO ; A symbol named "FOO", different from "foo".
char-to-string ; A symbol named "char-to-string".
1+ ; A symbol named "1+" (``+1'' is an integer).
\+1 ; A symbol named "+1" (not a very readable name).
\(*\ 1\ 2\) ; A symbol named "(* 1 2)" (a worse name).
@c the @'s in this next line use up three characters, hence the
@c apparent misalignment of the comment.
+-*/_~!@@$%^&=:<>@{@} ; A symbol named "+-*/_~!@@$%^&=:<>@{@}".
; These characters do not require escape.
@end example
@node Lisp Function Type, Lisp Macro Type, Symbol Type, Programming Types
@subsection Lisp Function Type
A @dfn{Lisp function} object is a piece of executable code, just as in
other programming languages. Lisp functions may also be considered as
data, though, unlike many other languages: a Lisp function object is a
list whose first element is the symbol @code{lambda}.
Lisp function objects are usually created with the built-in function
@code{defun}. Any list that begins with @code{lambda}, however, is a
function as far as Emacs Lisp is concerned.
@xref{Functions} for the details.
@example
(defun foo (n) (print n))
@arrow foo
(symbol-function 'foo)
@arrow (lambda (n) (print n)) ; An interpreted function.
@end example
@node Lisp Macro Type, Primitive Function Type, Lisp Function Type, Programming Types
@subsection Lisp Macro Type
A @dfn{Lisp macro} object is a piece of executable code, like a
function, but with different parameter-passing semantics. A Lisp macro
is a list whose first element is the symbol @code{macro}.
Lisp macro objects are usually created with the built-in function
@code{defmacro}. Any list that begins with @code{macro}, however, is a
macro as far as Emacs is concerned.
@xref{Macros} for the details.
@node Byte Code Type, Syntax Table Type, Autoload Type, Derived Types
@subsection Byte Code Type
A @dfn{byte code} object is a list whose first element is the symbol
@code{byte-code}. Byte code is generated by the function
@code{byte-compile} from Lisp function and Lisp
macro objects. Evaluation of byte code is usually much faster than
evaluation of the Lisp objects it is generated from.
@xref{Byte Compilation} for the details.
@node Primitive Function Type, , Lisp Macro Type, Programming Types
@subsection Primitive Function Type
A @dfn{primitive function} is a function callable from Lisp but
written in C. Primitive functions are also called @dfn{subrs}
(subroutines) or @dfn{built-in functions}. Most primitive functions
evaluate all their arguments when they are called (@pxref{Primitive
Function Calls}). A primitive function that does not evaluate all its
arguments is called a @dfn{special form} instead (@pxref{Special
Forms}).
In most cases, it does not matter that a function is primitive. (It
does matter if you are trying to substitute a Lisp function for a
primitive of the same name. For an example, @pxref{Minor Modes}.) So
the term "function" is used to mean any Lisp functions and those
primitive functions that are not special forms. @xref{Lisp Function
Type} for the related Lisp function type.
Primitive functions have no read syntax and print in hash notation with
the name of the subr.
@example
(symbol-function 'car) ; Access the function cell of the symbol.
@arrow #<subr car>
(subrp (symbol-function 'car)) ; Is this a subr?
@arrow t ; Yes.
@end example
@node Autoload Type, Byte Code Type, Association Lisp Type, Derived Types
@subsection Autoload Type
An @dfn{autoload} object is a list whose first element is the symbol
@code{autoload}. An autoload object is usually created with the function
@code{autoload} which stores the object in the function cell of a symbol.
An autoload object references a file to load when the symbol
is used as a function. After the load, the symbol should have a
new function cell that is not an autoload object.
@xref{autoload} for the details.
@node Editing Types, Predicates, Programming Types, Types of Lisp Objects
@section Editing Types
The types in the previous section are common to many Lisp-like
languages. But Emacs Lisp is more than Lisp since many additional data
types and functions are provided that deal with editing,
rather than Lisp programming per se.
@menu
* Buffer Type:: The basic object of editing.
* Window Type:: What makes buffers visible.
* Window Configuration Type:: Save what the screen looks like.
* Marker Type:: A position in a buffer.
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Syntax Table Type:: What a character means.
@end menu
@node Buffer Type, Window Type, , Editing Types
@subsection Buffer Type
A @dfn{buffer} object contains an indefinite number of characters. A
buffer is most commonly used to hold the contents of a disk
file (@pxref{Files}). Most buffers are also meant to be seen by the
user, and therefore displayed, at some time, in a window (@pxref{Window
Type}). But a buffer need not have an associated file or window.
Buffers can be thought of as simple, albeit often very long,
strings, but they are, in fact, more complex. For example, text can be
inserted into a buffer very quickly, while ``inserting'' text into a
string is accomplished with concatenation and the result is an entirely new
string object.
Each buffer has a designated position within the buffer, called the
@dfn{point} (@pxref{Positions}). Although many buffers may exist
simultaneously, only one buffer is the @dfn{current buffer}. Most
editing commands act on the contents of the current buffer in the
neighborhood of its point. Many other functions manipulate or test the
characters in a buffer and, indeed, quite a bit of this manual is
devoted to describing such functions.
Several other data structures are associated with buffers: a local
syntax table (@pxref{Syntax Tables}; a local keymap (@pxref{Keymaps});
and a local variable binding list (@pxref{Variables}). Each of these
overrides its global counterpart. Editing commands can use these to
provide a different behavior in each buffer, by paying attention to the
so-called @dfn{buffer-local} object instead of the global counterpart.
Buffers have no read syntax. They print in hash notation with the
buffer name. @xref{Buffers} for the details on buffer objects and related
functions.
@example
(current-buffer)
@arrow #<buffer objects.texinfo>
@end example
@node Window Type, Window Configuration Type, Buffer Type, Editing Types
@subsection Window Type
A @dfn{window} object describes the portion of the terminal
screen that Emacs uses to display a buffer. Every window has an
associated buffer, but a buffer might not be displayed in any
window. On the other hand, a buffer may be displayed in more than
one window.
While many windows may exist simultaneously, only one window is the
@dfn{selected window}. This is the window where the cursor is (usually)
displayed when command input is requested. The selected window
often displays the current buffer, but this is not necessarily the
case (@pxref{set-buffer}).
Windows have no read syntax. They print in hash notation, giving the
window number and buffer name. @xref{Windows} for the details.
@example
(selected-window)
@arrow #<window 1 on objects.texinfo>
@end example
@node Window Configuration Type, Marker Type, Window Type, Editing Types
@subsection Window Configuration Type
A @dfn{window configuration} object stores information about the
positions and sizes of windows at the time the window configuration is
created, so that the screen layout may be recreated later.
Window configurations have no read syntax and always print as
@samp{#<window-configuration>}. @xref{Window Configurations} for the
details.
@node Marker Type, Window Type, Buffer Type,
@subsection Marker Type
A @dfn{marker} object denotes a position in a specific buffer.
Markers therefore have two cells: one for the buffer, and one for the
position. The position value is changed, if necessary, as text is
inserted into or deleted from the buffer. This is to ensure that
the marker always points between the same two characters in the buffer
(unless the insertion or deletion is at the marker position).
Markers have no read syntax. They print in hash notation, giving the
character position and the name of the buffer. @xref{Markers} for the
details.
@example
(point-marker)
@arrow #<marker at 10779 in objects.texinfo>
@end example
@node Process Type, Stream Type, Marker Type, Editing Types
@subsection Process Type
A @dfn{process} object references a subprocess that runs independently
of the Emacs process. External subprocesses may be used to extend the
processing capability of Emacs far beyond the limitations of
Emacs Lisp.
Processes take input from Emacs and the output is returned to Emacs for
further manipulation. Both text and signals can be communicated between
Emacs and the subprocess.
Processes have no read syntax. They print in hash notation, giving
the name of the process. @xref{Processes} for the details.
@example
(process-list)
@arrow (#<process shell>)
@end example
@node Stream Type, Derived Types, Process Type, Editing Types
@subsection Stream Type
A @dfn{stream} object is used as a source or sink for characters.
Many different objects meet this description: markers, buffers, strings,
and functions. A character source is an @dfn{input stream} (from Emacs'
point of view). A character sink is a @dfn{output stream}. For example,
a marker can be thought of as a source if characters are read from the
marker's buffer, starting at the marker's position. A function is a
source if it returns characters; a sink if it accepts characters.
The object @code{nil}, in addition to its other meanings, stands for
the stream referenced by the variables @code{standard-input} and
@code{standard-output}. Also, the object @code{t} stands for
input or output in the minibuffer (@pxref{The Minibuffer}).
Streams have no read syntax, and print as whatever object they are.
@xref{Streams} for the details.
@node Keymap Type, Syntax Table Type , Byte Code Type, Derived Types
@subsection Keymap Type
A @dfn{keymap} object maps keys typed by the user to functions. Emacs
defines two kinds of keymaps: @dfn{full keymaps}, which are vectors of
128 elements, and @dfn{sparse keymaps}, which are association lists with
a preceding @code{keymap} symbol.
@xref{Keymaps} for the details.
@node Syntax Table Type, , Keymap Type, Derived Types
@subsection Syntax Table Type
A @dfn{syntax table} object is a vector of 256 integers. Each element
of the vector defines how the corresponding character is interpreted
when it appears in a buffer. For example, in C mode (@pxref{Major
Modes}), the @samp{+} character is punctuation, while in Lisp mode it is
a valid character in a symbol. These different interpretations are
effected by changing the syntax table entry for @samp{+}, i.e.,
@w{position 43}.
Syntax tables are only used for text in buffers, not for reading Lisp
expressions. The table which the Lisp interpreter uses to read
expressions is built into the C code and cannot be changed. For example, you
cannot change the list delimiters to be @samp{@{} and @samp{@}} instead of
@samp{(} and @samp{)}.
@xref{Syntax Tables} for the details.
@node Type Predicates, Equality Predicates, , Predicates
@section Type Predicates
The Emacs Lisp interpreter itself does not perform any type checking
on the actual arguments of function calls. It could not be otherwise,
since objects in Lisp are not declared to be of a certain type, as
they are in other programming languages. It is therefore up to
each individual function to test whether each actual argument is a
member of the correct type. All built-in functions do check the type
of their actual arguments and signal a @code{wrong-type-argument} error
if an argument is of the wrong type.
Many functions are provided to test whether an object is a member of a
given type. Here is a table of all of them, in alphabetical order, and
where they are described further.
@table @code
@item arrayp
@pxref{arrayp}
@item bufferp
@pxref{bufferp}
@item char-or-string-p
@pxref{char-or-string-p}
@item consp
@pxref{consp}
@item featurep
@pxref{featurep}
@item integer-or-marker-p
@pxref{integer-or-marker-p}
@item integerp
@pxref{integerp}
@item keymapp
@pxref{keymapp}
@item listp
@pxref{listp}
@item markerp
@pxref{markerp}
@item natnump
@pxref{natnump}
@item nlistp
@pxref{nlistp}
@item processp
@pxref{processp}
@item sequencep
@pxref{sequencep}
@item stringp
@pxref{stringp}
@item subrp
@pxref{subrp}
@item symbolp
@pxref{symbolp}
@item syntax-table-p
@pxref{syntax-table-p}
@item user-variable-p
@pxref{user-variable-p}
@item vectorp
@pxref{vectorp}
@item windowp
@pxref{windowp}
@end table
@node Equality Predicates, , Type Predicates, Predicates
@section Equality Predicates
@cindex equality
Two functions test equality between any two objects. These are
described here. Other functions test equality between objects of
specific types, e.g., strings. See the appropriate chapter on the type
for these predicates.
@defun eq object1 object2
This function returns @code{t} if @var{object1} and @var{object2} are
the same object, @code{nil} otherwise. The ``same object'' means, in
this case, that a change in one will be reflected by the same change in
the other.
@code{eq} will be true if @var{object1} and @var{object2} are numbers
with the same value, or symbols with the same print name.
(@code{make-symbol} @findex make-symbol causes an exception to this;
@pxref{Creating and Interning Symbols}.) Other objects (e.g., lists,
vectors, strings) with the same elements may or may not be @code{eq} to
each other.
@example
(eq 'foo 'foo)
@arrow t
(eq 456 456)
@arrow t
(eq "asdf" "asdf")
@arrow nil
(eq '(1 (2 (3))) '(1 (2 (3))))
@arrow nil
(eq [(1 2) 3] [(1 2) 3])
@arrow nil
(eq (point-marker) (point-marker))
@arrow nil
@end example
@end defun
@defun equal object1 object2
This function returns @code{t} if @var{object1} and @var{object2} have
equal components, @code{nil} otherwise. Whereas @code{eq} tests if two
objects are the same, @code{equal} looks inside the objects, if
necessary, to see if their elements are the same. So, if two objects are
@code{eq}, they are @code{equal}, but the converse is not always true.
@example
(equal "asdf" "asdf")
@arrow t
(equal "asdf" "ASDF")
@arrow nil
(equal '(1 (2 (3))) '(1 (2 (3))))
@arrow t
@end example
@end defun