Path: utzoo!utgpu!watmath!uunet!bu-cs!bloom-beacon!tut.cis.ohio-state.edu!m.cs.uiuc.edu!liberte
From: liberte@m.cs.uiuc.edu (Daniel LaLiberte)
Newsgroups: gnu.emacs.lisp.manual
Subject: objects.texinfo
Message-ID: <8812021034.AA29099@m.cs.uiuc.edu>
Date: 2 Dec 88 10:34:00 GMT
Sender: daemon@tut.cis.ohio-state.edu
Distribution: gnu
Organization: GNUs Not Usenet
Lines: 742

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)
     => #
@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.}
     => #               @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)
=> #
@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)
     => #
@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)
     => #
@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{#}.
@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)
     => (#)
@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 defun