⟦375a33021⟧

TextFile

@setfilename ../info/objects
@node Types of Lisp Object, Numbers, Introduction, Top
@chapter Types of Lisp Object

  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 possible 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.
Types can overlap, and objects may belong to two or more types.
Consequently, we can ask whether an object belongs to a particular type,
but not for ``the'' type of an object.

  A small set of fundamental object types are built into Emacs.  These
are called @dfn{primitive types}.  All other types are constructed from
these types.  The primitive types are @dfn{integer}, @dfn{cons},
@dfn{symbol}, @dfn{string}, @dfn{vector}, @dfn{subr} and several special
types, such as @dfn{buffer}, that are related to editing.  (@xref{Editing
Types}.)

  While an object may be a member of more than one type, every object is
a member of exactly one primitive type.  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.

  Note that while many other languages employ type declarations to
specify an object's type, Lisp objects are ``self-typing''.  The
primitive type of the object is implicit in the object itself.  For
example, if an object is a vector, nothing will be able to treat it as a
number because Lisp knows it is a vector, not a number.

  There are special terms for dealing with classes of types.  A
@dfn{supertype} is a union of @dfn{subtypes}.  For example, strings and
vectors are both considered arrays, so the string and vector types are
both subtypes of the array supertype.
@cindex user-defined types

  This chapter describes the purpose, print representation, and read
syntax of each of the standard types in GNU Emacs Lisp.  Details on how
to use these types can be found in later chapters.

@menu
* Print Representation and Read Syntax::
* Comments::                    Comments and their formatting conventions.
* 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, Comments, Types of Lisp Object, Types of Lisp Object
@comment  node-name,  next,  previous,  up
@section Print Representation and Read Syntax

@cindex Lisp printer
@cindex Lisp reader
  The @dfn{print representation} of an object is the format of the
output generated by the Lisp printer (the function @code{print}) for
that object.  The @dfn{read syntax} of an object is the format of the
input accepted by the Lisp reader (the function @code{read}) for that
object.  Very often, the print representation and the read syntax are the
same.

  It is important to distinguish between the textual representation of a
object (that you, the human, reads) and the object which results from
calling @code{read} on that text.

  Note that reading an object does not cause evaluation.  Reading
returns a Lisp object, which may or may not be evaluated later.
Evaluation is a separate process (@pxref{Evaluation}).  Generally, when
you evaluate an expression interactively, the Lisp interpreter first
reads the textual representation of it and then evaluates the Lisp
object returned.

@xref{Input Functions}, for a description of @code{read}, which is the
most basic function for reading objects.

  All types have a print representation.  Some types have no read
syntax, since it may not make sense to enter objects of these types
directly in a Lisp program.  Objects of these types are always printed
in @dfn{hash notation}: the characters @samp{#<} followed by a
descriptive string (typically the type name followed by the name of the
object), and closed with a matching @samp{>}.  Hash notation cannot be
read; and, the Lisp reader signals the error @code{invalid-read-syntax}
whenever a @samp{#} is encountered.  For example, the buffer type does
not have a read syntax.@refill
@cindex invalid-read-syntax error

@example
(current-buffer)
     @result{} #<buffer objects.texinfo>
@end example

@node Comments, Programming Types, Print Representation and Read Syntax, Types of Lisp Object
@comment  node-name,  next,  previous,  up
@section Comments

@cindex comments
@cindex @samp{;} comment
  The Lisp reader skips comments.  A @dfn{comment} starts with a
semicolon (@samp{;}) and continues to the end of line.

You are encouraged to format comments according to several useful conventions:

@table @samp

@item ;
Comments that start with a single semicolon, @samp{;}, should be all
aligned to the same column on the right, or to the right of such a
column if that is not possible.  Such comments usually apply only to
code written on the same line.  In Emacs, in the Lisp modes, the @kbd{M-;}
(@code{indent-for-comment}) command automatically inserts such a @samp{;}
in the right place, or aligns such a comment if it is already inserted.

(The following examples are taken from the Emacs sources.)

@group
@example
(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
@end example
@end group

@item ;;
Comments that start with a two semicolons, @samp{;;}, should be aligned
to the same level of indentation as the code.  Such comments are used to
describe the section that follows or the state of the program at that
point.  For example,

@group
@example
  (prog1 (setq auto-fill-hook
               @dots{}
               @dots{}
    ;; update mode-line
    (set-buffer-modified-p (buffer-modified-p))))
@end example
@end group

@item ;;;
Comments that start with a three semicolons, @samp{;;;}, should be 
aligned to the left margin.  Such comments are not used within function
definitions, but are used to make more general comments.
For example,

@group
@example
;;; This Lisp code is run in Emacs when it is to operate as
;;; a server for other processes.
@end example
@end group

@item ;;;;
Comments that start with a four semicolons, @samp{;;;;}, should be 
aligned to the left margin and are used to indicate section headings.
For example,

@group
@example
;;;; The kill ring
@end example
@end group
@end table

@noindent
In the Lisp modes in Emacs, various indentation commands follow these
conventions, such as @kbd{M-;} (@code{indent-for-comment}) and @key{TAB}
(@code{lisp-indent-line}).  They automatically indent comments the right
way, according the the number of semicolons.

  Any character may be included in a comment, but it is advisable to
precede any unpaired special characters, such as @samp{(} and @samp{)},
with a @samp{\} to hide their normal meaning from Lisp editing commands.

@node Programming Types, Editing Types, Comments, Types of Lisp Object
@section Programming Types

@cindex programming types
  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 provided in many Lisp implementations, in one form or
another.  The latter are unique to Emacs Lisp.

@menu
* Number Type::	        Primarily integers.
* Character Type::	The representation of letters, numbers and
                        control characters .
* Sequence Type::	A supertype of lists and arrays.
* List Type::	        What gave Lisp its name (not to mention reputation).
* Array Type::	        A supertype of strings and vectors.
* String Type::	        An (efficient) array of characters.
* Vector Type::	        One-dimensional arrays.
* Symbol Type::	        A multi-use object that refers to a function,
                        variable, property list, or itself.
* Lisp Function Type::	A piece of executable code.
* Lisp Macro Type::	A different kind of executable code from a function.
* Primitive Function Type::	A function written in C, callable from Lisp.
* Autoload Type::	A type used for automatically loading seldom
                        used functions.
@end menu

@node Number Type, Character Type, Programming Types, Programming Types
@subsection Number Type

@cindex numbers
@cindex integers

  Integers are the only kind of number in GNU Emacs Lisp, version 18.
The range of values for integers is @minus{}8388608 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)} is @minus{}8388608, on 24-bit
implementations.@refill

@cindex floating point
@cindex reals
Version 19 supports floating point numbers.

  The read syntax for numbers is a sequence of (base ten) digits with an
optional sign.  The print representation produced by the Lisp interpreter
never has a leading @samp{+}.

@example
-1               ; @r{The integer -1.}
1                ; @r{The integer 1.}
+1               ; @r{Also the integer 1.}
16777217         ; @r{Also the integer 1! (on a 24-bit implementation)}
@end example

  @xref{Numbers}, for more information.

@node Character Type, Sequence Type, Number Type, Programming Types
@subsection Character Type

@cindex ASCII characters

  A @dfn{character} object in Emacs Lisp is nothing more than an
integer.  In other words, characters are represented internally with
their eight-bit @sc{ASCII} values.  For example, the character `A' is
represented internally as the @w{integer 65}.  If an arbitrary integer
is used as a character, only the lower eight bits are significant.

  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}).

@cindex read syntax for characters
@cindex print syntax for characters
@cindex syntax, read, for characters
@cindex syntax, print, for characters

  Characters have a variety of read syntax formats, such as @samp{?A}
and @samp{?\101}.  Every different read syntax for characters starts
with a leading question mark.

  The usual read syntax for alphanumeric characters is a question mark
followed by the character; for example, @samp{?A} for the character
@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
character @kbd{a}.  For example, 

@group
@example
?Q
     @result{} 81

?q
     @result{} 113
@end example
@end group

@cindex whitespace 
@cindex backspace 
@cindex @samp{\b}
@cindex tab 
@cindex @samp{\t}
@cindex vertical tab 
@cindex @samp{\v}
@cindex formfeed 
@cindex @samp{\f}
@cindex newline 
@cindex @samp{\n}
@cindex return 
@cindex @samp{\r}
@cindex escape 
@cindex @samp{\e}
  The characters backspace, tab, vertical tab, formfeed, newline, return,
and escape may be represented as @samp{?\b}, @samp{?\t}, @samp{?\n},
@samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e}, respectively.  Those
values are 8, 9, 10, 11, 12, 13, and 27 in decimal.  Thus,@refill

@example
?\b                             ; @r{backspace, @key{BS}, @kbd{C-h}}
     @result{} 8
?\t                             ; @r{tab, @key{TAB}, @kbd{C-i}}
     @result{} 9
?\n                             ; @r{newline, @key{LFD}, @kbd{C-j}}
     @result{} 10
?\v                             ; @r{vertical tab, @kbd{C-k}}
     @result{} 11
?\f                             ; @r{formfeed character, @kbd{C-l}}
     @result{} 12
?\r                             ; @r{carriage return, @key{RET}, @kbd{C-m}}
     @result{} 13
?\e                             ; @r{escape character, @key{ESC}, @kbd{C-[}}
     @result{} 27
?\\                             ; @r{backslash character, @key{\}}
     @result{} 92
@end example

@cindex control characters
  Control characters may be represented using yet another read syntax.
This consists of a question mark followed by a backslash, hat, and
the corresponding non-control character, in either upper or lowercase.
For example, either @samp{?\^I} or @samp{?\^i} may be used as the read
syntax for the character @kbd{C-I}, the character with the print syntax
of @code{9}.  

  The @samp{^} may be replaced by @samp{C-}; for example, @samp{?\^I} may
be replaced by @samp{?\C-I} and @samp{?\^i} may be replaced by
@samp{?\C-i}.  For example,

@group
@example
?\^I
     @result{} 9
?\C-I
     @result{} 9
@end example
@end group

  When you represent control characters in files or strings, use of the
@samp{^} syntax is preferred; but when you refer to keyboard input, the
@samp{C-} syntax is preferred.

  A @dfn{meta character} is a character that has its eighth bit set.
The read syntax for these characters is question mark, backslash,
@samp{M-}, and the corresponding seven-bit character; for example,
@samp{?\M-A} for @kbd{M-A}, the character with the print representation
193.  The seven-bit character can be specified by any of the @samp{\}
escapes mentioned above or below.  Not only can @kbd{M-A} be specified
as @samp{?\M-A}, but also as @samp{?\M-\101} or as @code{?\301}.

  Similarly, the character whose decimal print representation is 130
can use any one of the following for its read syntax: @code{?\202},
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
For example, 

@group
@example
?\C-\M-b                        ?\M-\C-b
     @result{} 130               @result{} 130
?\^\M-b                         ?\M-\002
     @result{} 130               @result{} 130
@end example
@end group

@cindex @samp{?} in characters
@cindex question mark in characters
@cindex @samp{\} in characters
@cindex backslash in characters
@cindex octal characters
  Finally, the most general read syntax consists of a question mark
followed by a backslash and the @sc{ASCII} value of the character in octal
(up to three octal digits); for example, @samp{?\101} for the character
@kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for
the character @kbd{C-b}.  Although this syntax can represent any
character, it is preferred when the precise octal value is more
important than the @sc{ASCII} representation.  (The backslash character is
also known as an @dfn{escape character}, not to be confused with
@key{ESC}.) @refill

@example
?\012
     @result{} 10
?\n
     @result{} 10
?\C-j
     @result{} 10

?A
     @result{} 65
?\101
     @result{} 65

?\M-A                           
     @result{} 193                   
?\M-\101
     @result{} 193
?\301
     @result{} 193
@end example

  Any character without a special escape meaning may be preceded by a
backslash.  Thus @samp{?A} is equivalent to @samp{?\A}.  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.  Furthermore, it is better and more reliable to use one of
the easily readable formats rather than directly enter an invisible
control character, such as a tab; that's what the other formats are for,
after all.

@node Sequence Type, List Type, Character Type, Programming Types
@subsection Types of Sequences

  Lists and arrays are two types of @dfn{sequence}.  That is, an
object of type list or of type array is also considered a sequence.
The sequence type is therefore sometimes called a supertype of the two
subtypes.

  In addition, there are two kinds of array: strings and vectors.

  All these types share a common property: they consist of ordered
collections of elements.  Sequences are interesting because some Lisp
functions accept any sequence object as an argument, without
distinguishing between the three subtypes.

  Sequences are always created anew upon reading; in other words, it is
impossible to read the same sequence twice, in the sense of @code{eq}
(@pxref{Equality Predicates}).  There is one exception: the empty list
@code{()} is always read as the same object, @code{nil}.

  @xref{Sequences Arrays Vectors}, for functions that work on sequences.

@node List Type, Array Type, Sequence Type, Programming Types
@subsection List Type

@cindex address register
@cindex decrement register
  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 @sc{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{@sc{car}} referred
to the contents of the address register, and @samp{@sc{cdr}} referred to
the contents of the decrement register.  By comparison, @samp{cons} is
named for the function @code{cons} which ``constructs'' cells of a kind
that came to be called cons cells.)

  When a list as a whole is evaluated, the elements may or may not be
evaluated.  When a list, or any object, is merely read, nothing is
evaluated.  (That is, reading and evaluation are different steps.)

  @xref{Lists}, for functions that work on lists.

@cindex parenthesis
  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.  

   Upon reading, any object at all inside the parentheses is made into
an element of the list.  That is, a cons cell is made for each element.
Its @sc{car} points to the element, and its @sc{cdr} points to a cons
cell, the @sc{car} of which points to the next element in the list.  The
@sc{cdr} of the last cons cell is set to point to @code{nil}.

@cindex box diagrams, for lists
@cindex diagrams, boxed, for lists
  A list can be illustrated using diagrams in which the cons cells are
shown as pairs of boxes.  The following represents the three element
list @code{(rose violet buttercup)}:

@group
@example
    ___ ___      ___ ___      ___ ___ 
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |      
     |            |            |
      --> rose     --> violet   --> buttercup
@end example
@end group

  In the diagram, each box represents a slot that can refer to any Lisp
object.  Each pair of boxes represents a cons cell.  Each arrow is a
reference to an atom or to another cons cell.  The first box, the
@sc{car} of the first cons cell, refers to or ``contains'' @samp{rose}.
The second box, the @sc{cdr} of the first cons cell is a reference to
the next pair of boxes, the second cons cell.  The @sc{car} of the
second cons cell refers to @samp{violet} and the @sc{cdr} refers to the
third cons cell.  The @sc{cdr} of the third (and last) cons cell refers
to @code{nil}.

Here is another diagram of the exact same list,
@code{(rose violet buttercup)}, sketched in a different manner.

@group
@example
 ---------------         ----------------         -------------------
|car    |cdr    |       |car     |cdr    |       |car        |cdr    |
|       |   o---------->|        |   o---------->|           |  nil  |
| rose  |       |       | violet |       |       | buttercup |       |
 ---------------         ----------------         -------------------
@end example
@end group

@cindex @samp{(@dots{})} in lists
@cindex nil in lists
  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.  

@example
(A 2 "A")            ; @r{A list of three elements.}
()                   ; @r{A list of no elements (the empty list).}
nil                  ; @r{A list of no elements (the empty list).}
("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
(A ())               ; @r{A list of two elements: A and the empty list.}
((A B C))            ; @r{A list of one element (which is a list of 3).}
@end example

  The functions @code{symbolp}, @code{listp} and @code{atom} test
whether their argument is a symbol, list or atom, respectively.  As the
example shows, all three tests return true when applied to @code{nil}.
(@xref{Type Predicates}, for more information on such predicates.)  The
function @code{eq} tests whether its two arguments are the same object
internally in the computer.  As the example shows, this is indeed the
case.

@example
(symbolp nil)
     @result{} t
(listp nil)
     @result{} t
(atom nil)
     @result{} t
(eq () nil)
     @result{} t
@end example

@menu
* Dotted Pair Notation::	An alternative syntax for lists.
* Association List Type::	A specially constructed list.
@end menu

@node Dotted Pair Notation, Association List Type, List Type, List Type
@comment  node-name,  next,  previous,  up
@subsubsection Dotted Pair Notation

@cindex dotted pair notation
@cindex @samp{.} in lists
  @dfn{Dotted pair notation} is an alternative syntax for lists.  It
explicitly represents lists as cons cells.  In this syntax,
@code{(@var{a} .@: @var{b})} is the cons cell whose @sc{car} is the
object @var{a}, and whose @sc{cdr} is the object @var{b}.  Dotted pair
notation is therefore more general than the syntax given before.  In the
dotted pair notation, the list @samp{(1 2 3)} is written as @samp{(1 .
(2 . (3 .  nil)))}; the two notations are equivalent; but the former is
usually more convenient.  When printing a list, the dotted pair notation
is only used if the @sc{cdr} of a cell is not a list.

  `Box notation' can also be used to illustrate what dotted pairs look
like.  (The Lisp reader cannot read such an illustration; unlike either
the regular or dotted pair notation, which can be understood both by
you, a human, and by the computer, the box illustrations can only be
understood by you.)

  For example, @code{(rose . violet)} is diagrammed as follows:

@group
@example
    ________ ________
   |________|________|
     |          |   
     |          |
      --> rose   --> violet
@end example
@end group

@noindent  
The three element list @code{(rose violet . buttercup)} looks like this:

@group
@example
    ___ ___      ________ _________
   |___|___|--> |________|_________|
     |            |           |
     |            |           |
      --> rose     --> violet  --> buttercup
@end example
@end group

  These diagrams make it evident that @w{@code{(rose .@: violet .@:
buttercup)}} must have an invalid syntax since it would require that a
cons cell have three parts rather than two.

  The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
and looks like this:

@group
@example
    ___ ___      ___ ___ 
   |___|___|--> |___|___|--> nil
     |            | 
     |            |
      --> rose     --> violet
@end example
@end group

  Similarly, the three element list @code{(rose violet buttercup)}
is equivalent to @code{(rose . violet . (buttercup)))}
and looks like this:

@group
@example
    ___ ___      ___ ___      ___ ___ 
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |      
     |            |            |
      --> rose     --> violet   --> buttercup
@end example
@end group

@noindent
This last list is perhaps best illustrated by a different style of
diagram, one that emphasizes the notion that the cons cells `contain'
the information to which they refer:

@group
@example
     ---------------------------------------------
    |car   |cdr                                   |
    |      |                                      |
    |      |   --------------------------------   |
    |      |  |car     |cdr                    |  |
    | rose |  |        |                       |  |
    |      |  | violet |   -----------------   |  |
    |      |  |        |  |car        |cdr  |  |  |
    |      |  |        |  |           |     |  |  |
    |      |  |        |  | buttercup | nil |  |  |
    |      |  |        |  |           |     |  |  |
    |      |  |        |   -----------------   |  |
    |      |  |        |                       |  |
    |      |   --------------------------------   |
    |      |                                      |
     ---------------------------------------------

(rose violet buttercup) @equiv{} (rose . (violet . (buttercup)))
@end example
@end group

@node Association List Type,  , Dotted Pair Notation, List Type
@comment  node-name,  next,  previous,  up
@subsubsection Association List Type

  An @dfn{association list} or @dfn{alist} is a specially constructed
list of cons cells.  In each cons cell, the @sc{car} is treated as a
@dfn{key}, and the @sc{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.  

Elements of an alist may be written using either dotted pair notation or
regular notation, but in any single application, you must use one
notation consistently.  In Emacs, dotted pair notation is most often
used for alists.

For example,

@example
(setq alist-of-colors '((rose . red) (lilly . white)  (buttercup . yellow)))
@end example

@noindent
sets the variable @code{alist-of-colors} to an alist of three elements.  In the
first element, @code{rose} is the key and @code{red} is the value.

@xref{Association Lists}, for a further explanation of alists and for
functions that work on alists.

@node Array Type, String Type, List Type, Programming Types
@subsection Array Type

  An @dfn{array} object is composed of an arbitrary number of other Lisp
objects.  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.  Elements at the end of a
list take longer to access that elements at the beginning of a list.

  Emacs defines two types of array, both of which are one-dimensional: a
string and a vector.  A string is an array of characters and a vector is
an array of arbitrary objects.  (In other programming languages, the
term ``array'' has a more general meaning than it does in Emacs Lisp.)
Each type of array has its own read syntax (@pxref{String Type}, and
@pxref{Vector Type}).

@itemize @bullet
@item
Arrays may have any length, up to the size of the largest integer; but
once created, an array has a fixed size.

@item
Arrays are indexed such that the first element of an array has an index
of zero, the second element as an index of 1, and so on.  This is called
@dfn{zero-origin} indexing.  For example, an array of four elements is
indexed by 0, 1, 2, @w{and 3}.

@item
The elements of any array may be referenced or changed with the
functions @code{aref} and @code{aset}, respectively (@pxref{Arrays}).
@end itemize

  The array type is a subtype of sequences and a supertype of
strings and vectors.

@node String Type, Vector Type, Array Type, Programming Types
@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.  Examples of strings
include the names of Lisp symbols, messages for the user, and substrings
extracted from buffers.

@cindex @samp{"} in strings
@cindex double-quote in strings
@cindex @samp{\} in strings
@cindex backslash in strings
  The read syntax for strings is a double-quote, an arbitrary number
of characters, and another double quote, @code{"like this"}.  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).  This means that you enter a
double-quote in a string by preceding it with a backlslash, and you
enter a character @kbd{A}, @kbd{C-a}, or a @kbd{M-C-A} the same way:
@code{"like this: \", \A, \C-a, \M-\C-a"}.  (@xref{Character Type},
for a description of the read syntax for characters.)

  Unlike the C programming language, newlines are allowed in Emacs Lisp
string literals.  But an escaped newline---one that is preceded by
@samp{\}---does not become part of the string; i.e., the Lisp reader
ignores an escaped newline in a string literal.
@cindex newline in strings

@example
"It is useful to include newlines in
documentation strings, but the newline is \
ignored if escaped."
     @result{} "It is useful to include newlines in
documentation strings, but the newline is ignored if escaped."
@end example

  The print representation of strings is a double-quote, the characters
in it, and another double-quote with the exception that any backslash or
double-quote characters in the string are printed with a leading
backslash @code{"like this \" embedded quote"}.  

  @xref{Strings and Characters}, for functions that work with strings.

@node Vector Type, Symbol Type, String Type, Programming Types
@subsection Vector Type

  A @dfn{vector} object is a one-dimensional array of elements each of
which can be of any type.  It takes a constant amount of time to access
any element of a vector.  On the other hand, in a list, the access time
of an element is proportional to the distance of the element from the
beginning of the list.

  The print representation and read syntax of vectors are the same: a
left square bracket, elements, and a right square bracket.  Like
numbers and strings, vectors return themselves when evaluated.

@example
[1 "two" (three)]      ; @r{A vector of three elements.}
     @result{} [1 "two" (three)]
@end example

  @xref{Vectors}, for functions that work with vectors.

@node Symbol Type, Lisp Function Type, Vector 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, usually only one of these uses is intended.

  To support these uses, symbols have four attributes or @dfn{cells}: 

@itemize @bullet
@item
a print name cell 

@item
a function cell

@item
a value cell 

@item
a property list cell.
@end itemize

  You may imagine a symbol as being a chest of four drawers.  The
function definition is put in one drawer, the value in another, and so
on.  Each drawer, or cell, is a reference to some other Lisp object What
is put in the drawer holding the value can be changed without affecting
the contents of the drawer holding the function definition, and
vice-versa.  Note that the print name is @emph{not} the symbol; the
print name has a drawer of its own.  The print name is a way of
mentioning the symbol; the symbol is the whole chest of drawers.

  In any symbol, either the function cell or the value cell or both of
them may be empty or @dfn{void}.  (The term @dfn{void} is used to
indicate that a cell has no valid data in it, as in the error message,
@samp{The symbol's value is void}.  This should not be confused with the
symbol whose name is @code{void}.  Note also that the data in a cell may
be @code{nil}, which is not void either.)

  The four functions, @code{symbol-name}, @code{symbol-value},
@code{symbol-plist}, and @code{symbol-function}, return the contents of
the four cells.

  An example is the symbol @code{buffer-file-name}, which has the print
name @samp{buffer-file-name} and data in the value, function, and
property list cells.

@example
(symbol-name 'buffer-file-name)
     @result{} "buffer-file-name"
(symbol-value 'buffer-file-name)
     @result{} "/gnu/elisp/objects.texinfo"
(symbol-plist 'buffer-file-name)
     @result{} (variable-documentation 29529)
(symbol-function 'buffer-file-name)
     @result{} #<subr buffer-file-name>
@end example

@noindent
The value cell of the symbol contains the name of this file.  The
propertly list cell contains the list @code{(variable-documentation
29529)} which tells the Emacs help and documentation functions where to
find documentation about @code{buffer-file-name} in the @file{DOC} file.
(29529 is the offset from the beginning of the @file{DOC} file where the
documentation for the function begins.) The function cell contains the
code for returning the name of the file.  Since @code{buffer-file-name}
is a primitive function, its code has no read syntax and prints in hash
notation.  (@xref{Primitive Function Type}.  (A function definition
written in Lisp will have the Lisp (or the byte-code) in this cell.)

@unnumberedsubsubsec The Print Name Cell

  The @dfn{print name} is the most obvious characteristic of a symbol,
and is described in this section.  The other cells of symbols are
described in greater detail in @ref{Symbols}.

  You often use the print name of a symbol to refer to it; the print
name is what the printer prints when handed a symbol.  The print name is
what distinguishes one symbol from another when the Lisp reader reads
them.  The print name cell is always a string object.

@cindex @samp{\} in symbols
@cindex backslash in symbols
  You use a symbol in a program by typing its print name (without the
double-quotes that delimit strings).  The rules for reading the print
name of a symbol are 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 a symbol's name.  Other
characters may be included in a symbol's name by escaping them with a
backslash.  In contrast to its use in strings, however, a backslash in
the print name of a symbol does no more than quote the single character
that follows the backslash, without conversion.  For example, in a
string, @samp{\t} represents a @key{TAB}; in the print name of a symbol,
however, @samp{\t} merely quotes the letter @kbd{t}.  To have a symbol
with a tab character in its name, you must actually type an (escaped)
tab.  But you would hardly ever do such a thing.@refill

@quotation
@cindex Common Lisp symbols
  @b{Common Lisp Note:} In Common Lisp, lower case letters are always
``folded'' to upper case, unless they are explicitly escaped.  This is a
marked contrast to Emacs Lisp, in which uppercase and lowercase letters
are distinct.
@end quotation

  Here are several examples of symbol names.  Note that the @samp{+} in
the last example is read as a symbol name instead of a number, because
it is not followed only by digits.

@example
foo                 ; @r{A symbol named @samp{foo}.}
FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
char-to-string      ; @r{A symbol named @samp{char-to-string}.}
1+                  ; @r{A symbol named @samp{1+}}
                    ;     @r{(not @samp{+1}, which is an integer).}
\+1                 ; @r{A symbol named @samp{+1} (not a very readable name).}
\(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
@c the @'s in this next line use up three characters, hence the
@c apparent misalignment of the comment.
+-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
                    ;     @r{These characters need not be escaped.}
@end example

@node Lisp Function Type, Lisp Macro Type, Symbol Type, Programming Types
@subsection Lisp Function Type

@cindex lambda symbol
  Just as functions in other programming languages are executable, a
@dfn{Lisp function} object is a piece of executable code.  However,
Lisp functions may also be considered data, unlike the functions in
many other languages; this is because a Lisp function object is a list
whose first element is the symbol @code{lambda} (@pxref{Lambda
Expressions}); or, in some cases, a Lisp function object is a
@dfn{subr} written in the C programming language (@pxref{Primitive
Function Type}).

@cindex anonymous functions
  A @dfn{named function} is a symbol with something in its function
cell.  You define a named function with the special form @code{defun}.
For example,

@group
@example
(defun foo (n)
  (print n))
     @result{} foo

(symbol-function 'foo)
     @result{} (lambda (n) (print n))    ; @r{An interpreted function.}
@end example
@end group

  An @dfn{anonymous Lisp function}, on the other hand, may be created
by building a list that begins with @code{lambda}.  

  Each of the following forms returns a value of 3.  The @code{funcall}
function calls its first argument, passing the remaining arguments to
it.  In the first example, the function that @code{funcall} calls is
@code{+}.  In the second example, the function object is the list
starting with @code{lambda}.  (In the second example, the list starting
with @code{lambda} accomplishes exactly the same as @code{+} does in the
first example; however, you may write the anonymous function as
complexly as you like.)  In the third example, the anonymous function is
quoted with @code{function} instead of with @code{quote} (for which
@samp{'} is the short form).

@group
@example
(funcall '+ 1 2)
     @result{} 3

(funcall '(lambda (arg1 arg2) (+ arg1 arg2)) 1 2)
     @result{} 3

(funcall (function (lambda (arg1 arg2) (+ arg1 arg2))) 1 2)
     @result{} 3
@end example
@end group

  Anonymous functions are often used in circumstances where the program
itself writes the function.  In this case, the exact definition of the
list starting with @code{lambda} is not known until the anonymous
function is called.

  Incidently, if you know ahead of time that a list is going to be an
anonymous function, and you need to apply the @code{quote} function to
it, it is best to quote it with the special form @code{function}
rather than with @code{quote}.  This is because the @code{function}
special form tells the byte compiler to compile the list as a
function.  The @code{function} special form is equivalent to
@code{quote} for interpreted code.  (@xref{Anonymous Functions}.)

  @xref{Functions}, for explanations of @code{lambda}, @code{defun}, and
functions that work with functions.

@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} and the remainder
is the same as a Lisp function object, including the @code{lambda} symbol.

  Lisp macro objects are usually defined 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 an explanation
of how to write a macro.

@node Primitive Function Type, Autoload Type, Lisp Macro Type, Programming Types
@subsection Primitive Function Type

@cindex subroutine
  A @dfn{primitive function} is a function callable from Lisp but
written in the C programming language.  Primitive functions are also
called @dfn{subrs} (subroutines) or @dfn{built-in functions}.  Most
primitive functions evaluate all their arguments when they are called.
A primitive function that does not evaluate all its arguments is called
a @dfn{special form} (@pxref{Special Forms}).@refill

  To the caller of a function, it does not matter if the function is
primitive.  However, it does matter if you are trying to substitute a
function written in Lisp for a primitive of the same name.  The reason
is that the primitive function may be called directly from C code.  So
long as the redefined function is called from Lisp, the new definition
will be used; but a call from C code may still use the old definition.

  The term @dfn{function} is used to refer to all Emacs functions,
whether written in Lisp or C.  @xref{Lisp Function Type}, for information
about the functions written in Lisp.@refill

@cindex hash notation
  Primitive functions have no read syntax and print in hash notation
with the name of the subroutine.

@example
(symbol-function 'car)          ; @r{Access the function cell of the symbol.}
     @result{} #<subr car>
(subrp (symbol-function 'car))  ; @r{Is this a subroutine?}
     @result{} t                     ; @r{Yes.}
@end example

@node Autoload Type,  , Primitive Function Type, Programming 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 file has been loaded, the
symbol should have a new function cell that is not an autoload object.
The contents of this cell are evaluated as if they had been there
originally.  This means that from the point of view of a user, the
function call works as expected, using the function definition in the
loaded file.

  @xref{Autoload}, for a longer explanation.

@node Editing Types, Type Predicates, Programming Types, Types of Lisp Object
@section Editing Types

@cindex editing types
  The types in the previous section are common to many Lisp-like
languages.  But Emacs Lisp is more than an ordinary Lisp: many
additional data types and functions are provided for dealing with
editing in addition to 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, 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{Windows}).  But
a buffer need not have an associated file or window.@refill

  Buffers can be thought of as simple string, albeit often very long,
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: 

@itemize @bullet
@item
a local syntax table (@pxref{Syntax Tables});

@item
a local keymap (@pxref{Keymaps}); and,

@item
a local variable binding list (@pxref{Variables}).  
@end itemize

@noindent
Each of these overrides its global counterpart.  By paying attention to
the @dfn{buffer-local} object instead of its global counterpart, editing
commands are able to provide a different behavior in each buffer.

  Buffers have no read syntax.  They print in hash notation with the
buffer name. 

@example
(current-buffer)
     @result{} #<buffer objects.texinfo>
@end example

  @xref{Buffers}, for details about buffer objects and buffer-related functions and variables.

@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 usually displays the current buffer, but this is not
necessarily the case.  In particular, when Emacs (rather than a human)
works on a buffer, that buffer is the current buffer, but it does not
have to be visible to the user.  The @code{set-buffer} function is
used to transfer Emacs's attention without changing the displayed
buffer.  (@xref{Changing Buffers}.)

  Windows have no read syntax.  They print in hash notation, giving the
window number and buffer name.  (The window numbers are only to help
humans debug using the windows' printed representation.)

@example
(selected-window)
     @result{} #<window 1 on objects.texinfo>
@end example

  @xref{Windows}, for a description of the functions that work on windows.

@node Window Configuration Type, Marker Type, Window Type, Editing Types
@subsection Window Configuration Type

@cindex screen layout
  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.  They print as
@samp{#<window-configuration>}.  @xref{Window Configurations}, for a
description of several functions related to window configurations.

@node Marker Type, Process Type, Window Configuration Type, Editing Types
@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 automatically as 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
current character position and the name of the buffer.  

@example
(point-marker)
     @result{} #<marker at 10779 in objects.texinfo>
@end example

@xref{Markers}, for information on how to test, create, copy, and move
markers.

@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, such a shells, GDB,
telnet, and compilers, may be used to extend the processing capability
of Emacs far beyond the limitations of Emacs Lisp.

A process takes input from Emacs and the output is returned to Emacs for
further manipulation.  Both text and signals can be communicated between
Emacs and a subprocess.

  Processes have no read syntax.  They print in hash notation, giving
the name of the process.  

@example
(process-list)
     @result{} (#<process shell>)
@end example

@xref{Processes}, for information about functions that create, delete,
return information about, send input or signals to, and receive output
from processes.

@node Stream Type, Keymap Type, Process Type, Editing Types
@subsection Stream Type

  A @dfn{stream} object is used as a source or sink for characters.  A
stream is a Lisp object that can either supply characters or accept them
as output.  Many different objects can be used this way: markers,
buffers, strings, and functions.  Most often, input streams (character
sources) obtain characters from the keyboard, a buffer, or a file; and
output streams (character sinks) send characters to a buffer, such as a
@file{*Help*} buffer, or to the echo area.

  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{Minibuffers}).

  Streams have no special print or read syntax; and print as whatever
object they are.

  @xref{Streams}, for a description of various functions related to
streams, including various parsing and printing functions.

@node Keymap Type, Syntax Table Type, Stream Type, Editing 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 information about creating keymaps, handling prefix
keys, local as well as global keymaps, and changing key bindings.

@node Syntax Table Type,  , Keymap Type, Editing 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, but 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.,
for @w{position 43}.@refill

  Syntax tables are only used for scanning text in buffers, not for
reading Lisp expressions.  The table which the Lisp interpreter uses to
read expressions is built into the Emacs source 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 details about syntax classes and how to make
and modify syntax tables.

@node Type Predicates, Equality Predicates, Editing Types, Types of Lisp Object
@section Type Predicates

@cindex predicates
@cindex type checking

@cindex wrong-type-argument error
  The Emacs Lisp interpreter itself does not perform type checking on
the actual arguments passed to functions when they are called.  It could
not do 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 belongs to a type that that produces a desired result when
passed to the function.

All built-in functions do check the types of their actual arguments
when appropriate and signal a @code{wrong-type-argument} error if an
argument is of the wrong type.

For example, 

@group
@example
(+ 2 'a)
     @result{} Wrong type argument: integer-or-marker-p, a
@end example
@end group

  Many functions, called @dfn{type predicates}, are provided to test
whether an object is a member of a given type.  (Following a convention
of long standing, the print names of most Emacs Lisp predicates end in
@samp{p}.)

Here is a table pre-defined type predicates, in alphabetical order, and
where they are described further.

@table @code
@item atom
@pxref{List-related Predicates}

@item arrayp
@pxref{Arrays}

@item bufferp
@pxref{Buffers}

@item char-or-string-p
@pxref{Predicates for Strings}

@item consp
@pxref{List-related Predicates}

@item integer-or-marker-p
@pxref{Predicates on Markers}

@item integerp
@pxref{Predicates on Numbers}

@item keymapp
@pxref{Creating Keymaps}

@item listp
@pxref{List-related Predicates}

@item markerp
@pxref{Predicates on Markers}

@item natnump
@pxref{Predicates on Numbers}

@item nlistp
@pxref{List-related Predicates}

@item processp
@pxref{Processes}

@item sequencep
@pxref{Sequence Functions}

@item stringp
@pxref{Predicates for Strings}

@item subrp
@pxref{Function Cells}

@item symbolp
@pxref{Symbols}

@item syntax-table-p
@pxref{Syntax Tables}

@item user-variable-p
@pxref{Global Variables}

@item vectorp
@pxref{Vectors}

@item windowp
@pxref{Window Basics}

@end table

@node Equality Predicates,  , Type Predicates, Types of Lisp Object
@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
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.  Other objects
(e.g., lists, vectors, strings) with the same elements may or may not be
@code{eq} to each other.@refill

  (The @code{make-symbol} function returns an uninterned symbol that is
not interned in the standard @code{obarray}; such symbols should not be
tested against interned symbols until they are interned; @pxref{Creating
and Interning Symbols}.)

@example
(eq 'foo 'foo)
     @result{} t

(eq 456 456)
     @result{} t

(eq "asdf" "asdf")
     @result{} nil

(eq '(1 (2 (3))) '(1 (2 (3))))
     @result{} nil

(eq [(1 2) 3] [(1 2) 3])
     @result{} nil

(eq (point-marker) (point-marker))
     @result{} 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")
     @result{} t

(equal "asdf" "ASDF")
     @result{} nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     @result{} t
@end example
@end defun

The test for equality is implemented recursively, and circular lists may
therefore cause infinite recursion (leading to an error).
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦375a33021⟧ TextFile

Derivation

TextFile
