variable, and the type is known by the compiler but not represented in
the data. Such type declarations do not exist in Emacs Lisp. A Lisp
variable can have any type of value, and it remembers whatever value
-you store in it, type and all.
+you store in it, type and all. (Actually, a small number of Emacs
+Lisp variables can only take on values of a certain type.
+@xref{Variables with Restricted Values}.)
This chapter describes the purpose, printed representation, and read
syntax of each of the standard types in GNU Emacs Lisp. Details on how
The @dfn{printed representation} of an object is the format of the
output generated by the Lisp printer (the function @code{prin1}) 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. @xref{Read and Print}.
-
- Most objects have more than one possible read syntax. Some types of
-object have no read syntax, since it may not make sense to enter objects
-of these types directly in a Lisp program. Except for these cases, the
-printed representation of an object is also a read syntax for it.
-
- In other languages, an expression is text; it has no other form. In
-Lisp, an expression is primarily a Lisp object and only secondarily the
-text that is the object's read syntax. Often there is no need to
-emphasize this distinction, but you must keep it in the back of your
-mind, or you will occasionally be very confused.
+that object. Every data type has a unique printed representation.
+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. This
+is not necessarily unique; many kinds of object have more than one
+syntax. @xref{Read and Print}.
@cindex hash notation
- Every type has a printed representation. Some types have no read
-syntax---for example, the buffer type has none. Objects of these types
-are 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 at all, so the Lisp reader signals the error
-@code{invalid-read-syntax} whenever it encounters @samp{#<}.
-@kindex invalid-read-syntax
+ In most cases, an object's printed representation is also a read
+syntax for the object. However, some types have no read syntax, since
+it does not make sense to enter objects of these types as constants in
+a Lisp program. These objects are 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{>}. For example:
@example
(current-buffer)
@result{} #<buffer objects.texi>
@end example
+@noindent
+Hash notation cannot be read at all, so the Lisp reader signals the
+error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
+@kindex invalid-read-syntax
+
+ In other languages, an expression is text; it has no other form. In
+Lisp, an expression is primarily a Lisp object and only secondarily the
+text that is the object's read syntax. Often there is no need to
+emphasize this distinction, but you must keep it in the back of your
+mind, or you will occasionally be very confused.
+
When you evaluate an expression interactively, the Lisp interpreter
first reads the textual representation of it, producing a Lisp object,
and then evaluates that object (@pxref{Evaluation}). However,
@subsection Floating Point Type
Floating point numbers are the computer equivalent of scientific
-notation. The precise number of significant figures and the range of
-possible exponents is machine-specific; Emacs always uses the C data
-type @code{double} to store the value.
+notation; you can think of a floating point number as a fraction
+together with a power of ten. The precise number of significant
+figures and the range of possible exponents is machine-specific; Emacs
+uses the C data type @code{double} to store the value, and internally
+this records a power of 2 rather than a power of 10.
The printed representation for floating point numbers requires either
a decimal point (with at least one digit following), an exponent, or
@node Character Type
@subsection Character Type
-@cindex @sc{ascii} character codes
+@cindex @acronym{ASCII} character codes
A @dfn{character} in Emacs Lisp is nothing more than an integer. In
other words, characters are represented by their character codes. For
common to work with @emph{strings}, which are sequences composed of
characters. @xref{String Type}.
- Characters in strings, buffers, and files are currently limited to the
-range of 0 to 524287---nineteen bits. But not all values in that range
-are valid character codes. Codes 0 through 127 are @sc{ascii} codes; the
-rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}). Characters that represent
-keyboard input have a much wider range, to encode modifier keys such as
+ Characters in strings, buffers, and files are currently limited to
+the range of 0 to 524287---nineteen bits. But not all values in that
+range are valid character codes. Codes 0 through 127 are
+@acronym{ASCII} codes; the rest are non-@acronym{ASCII}
+(@pxref{Non-ASCII Characters}). Characters that represent keyboard
+input have a much wider range, to encode modifier keys such as
Control, Meta and Shift.
@cindex read syntax for characters
@end example
In strings and buffers, the only control characters allowed are those
-that exist in @sc{ascii}; but for keyboard input purposes, you can turn
+that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}. The character
-codes for these non-@sc{ascii} control characters include the
+codes for these non-@acronym{ASCII} control characters include the
@tex
@math{2^{26}}
@end tex
2**26
@end ifnottex
bit as well as the code for the corresponding non-control
-character. Ordinary terminals have no way of generating non-@sc{ascii}
+character. Ordinary terminals have no way of generating non-@acronym{ASCII}
control characters, but you can generate them straightforwardly using X
and other window systems.
@ifnottex
2**7
@end ifnottex
-bit attached to an @sc{ascii} character indicates a meta character; thus, the
-meta characters that can fit in a string have codes in the range from
-128 to 255, and are the meta versions of the ordinary @sc{ascii}
-characters. (In Emacs versions 18 and older, this convention was used
-for characters outside of strings as well.)
+bit attached to an @acronym{ASCII} character indicates a meta
+character; thus, the meta characters that can fit in a string have
+codes in the range from 128 to 255, and are the meta versions of the
+ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older,
+this convention was used for characters outside of strings as well.)
The read syntax for meta characters uses @samp{\M-}. For example,
@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
The case of a graphic character is indicated by its character code;
-for example, @sc{ascii} distinguishes between the characters @samp{a}
-and @samp{A}. But @sc{ascii} has no way to represent whether a control
+for example, @acronym{ASCII} distinguishes between the characters @samp{a}
+and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
character is upper case or lower case. Emacs uses the
@tex
@math{2^{25}}
@cindex hyper characters
@cindex super characters
@cindex alt characters
- The X Window System defines three other @anchor{modifier bits}
-modifier bits that can be set
+ The X Window System defines three other
+@anchor{modifier bits}modifier bits that can be set
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
represents the space character.)
@tex
-Numerically, the
-bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
+Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
+for super and @math{2^{24}} for hyper.
@end tex
@ifnottex
Numerically, the
mark followed by a backslash and the octal character code (up to three
octal digits); thus, @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 @sc{ascii}
+character @kbd{C-b}. Although this syntax can represent any @acronym{ASCII}
character, it is preferred only when the precise octal value is more
-important than the @sc{ascii} representation.
+important than the @acronym{ASCII} representation.
@example
@group
@node Symbol Type
@subsection Symbol Type
- A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
-name serves as the printed representation of the symbol. In ordinary
-use, the name is unique---no two symbols have the same name.
+ A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
+symbol name serves as the printed representation of the symbol. In
+ordinary Lisp use, with one single obarray (@pxref{Creating Symbols},
+a symbol's name is unique---no two symbols have the same name.
A symbol can serve as a variable, as a function name, or to hold a
property list. Or it may serve only to be distinct from all other Lisp
Here are several examples of symbol names. Note that the @samp{+} in
the fifth example is escaped to prevent it from being read as a number.
-This is not necessary in the seventh example because the rest of the name
+This is not necessary in the fourth example because the rest of the name
makes it invalid as a number.
@example
A @dfn{list} is a series of cons cells, linked together so that the
@sc{cdr} slot of each cons cell holds either the next cons cell or the
-empty list. @xref{Lists}, for functions that work on lists. Because
-most cons cells are used as part of lists, the phrase @dfn{list
-structure} has come to refer to any structure made out of cons cells.
-
- The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
-original Lisp implementation ran on an @w{IBM 704} computer which
-divided words into two parts, called the ``address'' part and the
-``decrement''; @sc{car} was an instruction to extract the contents of
-the address part of a register, and @sc{cdr} an instruction to extract
-the contents of the decrement. By contrast, ``cons cells'' are named
-for the function @code{cons} that creates them, which in turn was named
-for its purpose, the construction of cells.
+empty list. The empty list is actually the symbol @code{nil}.
+@xref{Lists}, for functions that work on lists. Because most cons
+cells are used as part of lists, the phrase @dfn{list structure} has
+come to refer to any structure made out of cons cells.
@cindex atom
Because cons cells are so central to Lisp, we also have a word for
@cindex parenthesis
The read syntax and printed representation for lists are identical, and
consist of a left parenthesis, an arbitrary number of elements, and a
-right parenthesis.
+right parenthesis. Here are examples of lists:
+
+@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: @code{A} and the empty list.}
+(A nil) ; @r{Equivalent to the previous.}
+((A B C)) ; @r{A list of one element}
+ ; @r{(which is a list of three elements).}
+@end example
Upon reading, each object inside the parentheses becomes an element
of the list. That is, a cons cell is made for each element. The
element in the list. The @sc{cdr} slot of the last cons cell is set to
hold @code{nil}.
+ The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
+original Lisp implementation ran on an @w{IBM 704} computer which
+divided words into two parts, called the ``address'' part and the
+``decrement''; @sc{car} was an instruction to extract the contents of
+the address part of a register, and @sc{cdr} an instruction to extract
+the contents of the decrement. By contrast, ``cons cells'' are named
+for the function @code{cons} that creates them, which in turn was named
+for its purpose, the construction of cells.
+
+@menu
+* Box Diagrams:: Drawing pictures of lists.
+* Dotted Pair Notation:: A general syntax for cons cells.
+* Association List Type:: A specially constructed list.
+@end menu
+
+@node Box Diagrams
+@subsubsection Drawing Lists as Box Diagrams
@cindex box diagrams, for lists
@cindex diagrams, boxed, for lists
+
A list can be illustrated by a diagram in which the cons cells are
shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
such an illustration; unlike the textual notation, which can be
to the symbol @code{nil}. In other words, @code{nil} is both a symbol
and a list.
- Here are examples of lists written in Lisp syntax:
-
-@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: @code{A} and the empty list.}
-(A nil) ; @r{Equivalent to the previous.}
-((A B C)) ; @r{A list of one element}
- ; @r{(which is a list of three elements).}
-@end example
-
Here is the list @code{(A ())}, or equivalently @code{(A nil)},
depicted with boxes and arrows:
@end group
@end example
-@menu
-* Dotted Pair Notation:: An alternative syntax for lists.
-* Association List Type:: A specially constructed list.
-@end menu
+ Here is a more complex illustration, showing the three-element list,
+@code{((pine needles) oak maple)}, the first element of which is a
+two-element list:
+
+@example
+@group
+ --- --- --- --- --- ---
+ | | |--> | | |--> | | |--> nil
+ --- --- --- --- --- ---
+ | | |
+ | | |
+ | --> oak --> maple
+ |
+ | --- --- --- ---
+ --> | | |--> | | |--> nil
+ --- --- --- ---
+ | |
+ | |
+ --> pine --> needles
+@end group
+@end example
+
+ The same list represented in the first box notation looks like this:
+
+@example
+@group
+ -------------- -------------- --------------
+| car | cdr | | car | cdr | | car | cdr |
+| o | o------->| oak | o------->| maple | nil |
+| | | | | | | | | |
+ -- | --------- -------------- --------------
+ |
+ |
+ | -------------- ----------------
+ | | car | cdr | | car | cdr |
+ ------>| pine | o------->| needles | nil |
+ | | | | | |
+ -------------- ----------------
+@end group
+@end example
@node Dotted Pair Notation
-@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 cons cells
-that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
+ @dfn{Dotted pair notation} is a general syntax for cons cells that
+represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
@code{(@var{a} .@: @var{b})} stands for a 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 list syntax. In the dotted
-pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
-. nil)))}. For @code{nil}-terminated lists, you can use either
-notation, but list notation is usually clearer and more convenient.
-When printing a list, the dotted pair notation is only used if the
-@sc{cdr} of a cons cell is not a list.
+pair notation is more general than list syntax because the @sc{cdr}
+does not have to be a list. However, it is more cumbersome in cases
+where list syntax would work. In dotted pair notation, the list
+@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
+@code{nil}-terminated lists, you can use either notation, but list
+notation is usually clearer and more convenient. When printing a
+list, the dotted pair notation is only used if the @sc{cdr} of a cons
+cell is not a list.
Here's an example using boxes to illustrate dotted pair notation.
This example shows the pair @code{(rose . violet)}:
All Emacs Lisp arrays are one-dimensional. (Most other programming
languages support multidimensional arrays, but they are not essential;
-you can get the same effect with an array of arrays.) Each type of
-array has its own read syntax; see the following sections for details.
+you can get the same effect with nested one-dimensional arrays.) Each
+type of array has its own read syntax; see the following sections for
+details.
The array type is contained in the sequence type and
contains the string type, the vector type, the bool-vector type, and the
@end example
@node Non-ASCII in Strings
-@subsubsection Non-@sc{ascii} Characters in Strings
+@subsubsection Non-@acronym{ASCII} Characters in Strings
- You can include a non-@sc{ascii} international character in a string
+ You can include a non-@acronym{ASCII} international character in a string
constant by writing it literally. There are two text representations
-for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
+for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
unibyte source, then the character is read as unibyte and that makes the
string unibyte.
- You can also represent a multibyte non-@sc{ascii} character with its
+ You can also represent a multibyte non-@acronym{ASCII} character with its
character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
-digits as necessary. (Multibyte non-@sc{ascii} character codes are all
+digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the next character in the string could be
interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
constant is just like backslash-newline; it does not contribute any
character to the string, but it does terminate the preceding hex escape.
- Using a multibyte hex escape forces the string to multibyte. You can
-represent a unibyte non-@sc{ascii} character with its character code,
-which must be in the range from 128 (0200 octal) to 255 (0377 octal).
-This forces a unibyte string.
+ You can represent a unibyte non-@acronym{ASCII} character with its
+character code, which must be in the range from 128 (0200 octal) to
+255 (0377 octal). If you write all such character codes in octal and
+the string contains no other characters forcing it to be multibyte,
+this produces a unibyte string. However, using any hex escape in a
+string (even for an @acronym{ASCII} character) forces the string to be
+multibyte.
@xref{Text Representations}, for more information about the two
text representations.
However, not all of the characters you can write with backslash
escape-sequences are valid in strings. The only control characters that
-a string can hold are the @sc{ascii} control characters. Strings do not
-distinguish case in @sc{ascii} control characters.
+a string can hold are the @acronym{ASCII} control characters. Strings do not
+distinguish case in @acronym{ASCII} control characters.
Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
-that provides a way to represent meta versions of @sc{ascii} characters in a
-string. If you use the @samp{\M-} syntax to indicate a meta character
-in a string constant, this sets the
+that provides a way to represent meta versions of @acronym{ASCII}
+characters in a string. If you use the @samp{\M-} syntax to indicate
+a meta character in a string constant, this sets the
@tex
@math{2^{7}}
@end tex
as a bitmap---each ``character'' in the string contains 8 bits, which
specify the next 8 elements of the bool-vector (1 stands for @code{t},
and 0 for @code{nil}). The least significant bits of the character
-correspond to the lowest indices in the bool-vector. If the length is not a
-multiple of 8, the printed representation shows extra elements, but
-these extras really make no difference.
+correspond to the lowest indices in the bool-vector.
@example
(make-bool-vector 3 t)
- @result{} #&3"\007"
+ @result{} #&3"^G"
(make-bool-vector 3 nil)
- @result{} #&3"\0"
-;; @r{These are equal since only the first 3 bits are used.}
+ @result{} #&3"^@@"
+@end example
+
+@noindent
+These results make sense, because the binary code for @samp{C-g} is
+111 and @samp{C-@@} is the character with code 0.
+
+ If the length is not a multiple of 8, the printed representation
+shows extra elements, but these extras really make no difference. For
+instance, in the next example, the two bool-vectors are equal, because
+only the first 3 bits are used:
+
+@example
(equal #&3"\377" #&3"\007")
@result{} t
@end example
A hash table is a very fast kind of lookup table, somewhat like an
alist in that it maps keys to corresponding values, but much faster.
-Hash tables are a new feature in Emacs 21; they have no read syntax, and
+Hash tables have no read syntax, and
print using hash notation. @xref{Hash Tables}.
@example
@cindex @samp{#@var{n}=} read syntax
@cindex @samp{#@var{n}#} read syntax
- In Emacs 21, to represent shared or circular structure within a
-complex of Lisp objects, you can use the reader constructs
-@samp{#@var{n}=} and @samp{#@var{n}#}.
+ To represent shared or circular structures within a complex of Lisp
+objects, you can use the reader constructs @samp{#@var{n}=} and
+@samp{#@var{n}#}.
Use @code{#@var{n}=} before an object to label it for later reference;
subsequently, you can use @code{#@var{n}#} to refer the same object in
@item functionp
@xref{Functions, functionp}.
+@item hash-table-p
+@xref{Other Hash, hash-table-p}.
+
@item integer-or-marker-p
@xref{Predicates on Markers, integer-or-marker-p}.
@end example
Comparison of strings is case-sensitive, but does not take account of
-text properties---it compares only the characters in the strings.
-A unibyte string never equals a multibyte string unless the
-contents are entirely @sc{ascii} (@pxref{Text Representations}).
+text properties---it compares only the characters in the strings. For
+technical reasons, a unibyte string and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+(@pxref{Text Representations}).
@example
@group