X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/d4241ae4cb9018ba2ad40a852dba2c0b95dc30ab..4a182c75ed86d8eea2d47feb4dc738449cf7bb99:/lispref/objects.texi diff --git a/lispref/objects.texi b/lispref/objects.texi index 4c905cb969..4a693f186d 100644 --- a/lispref/objects.texi +++ b/lispref/objects.texi @@ -42,7 +42,9 @@ it as a number; Lisp knows it is a vector, not a number. 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 @@ -66,36 +68,37 @@ to use these types can be found in later chapters. 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{} # @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, @@ -202,9 +205,11 @@ leading @samp{+} or a final @samp{.}. @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 @@ -409,8 +414,8 @@ represents the shifted-control-o character. @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 @@ -472,9 +477,10 @@ following text.) @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 @@ -515,7 +521,7 @@ Lisp, upper case and lower case letters are distinct. 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 @@ -604,18 +610,10 @@ Lisp are implicit. 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 @@ -625,7 +623,18 @@ for its purpose, the construction of cells. @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 @@ -634,8 +643,26 @@ slot refers to the next cons cell of the list, which holds the next 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 @@ -686,19 +713,6 @@ buttercup)}, sketched in a different manner: 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: @@ -713,27 +727,64 @@ 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)}: @@ -858,8 +909,9 @@ Once an array is created, its length is fixed. 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 @@ -1114,7 +1166,7 @@ only the first 3 bits are used: 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 @@ -1497,9 +1549,9 @@ positions. @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 @@ -1659,6 +1711,9 @@ with references to further information. @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}. @@ -1765,8 +1820,7 @@ describing the data type. @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 that a -change in one will be reflected by the same change in the other. +the same object, @code{nil} otherwise. @code{eq} returns @code{t} if @var{object1} and @var{object2} are integers with the same value. Also, since symbol names are normally @@ -1774,7 +1828,8 @@ unique, if the arguments are symbols with the same name, they are @code{eq}. For other types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily @code{eq} to each other: they are @code{eq} only if they are the same -object. +object, meaning that a change in the contents of one will be reflected +by the same change in the contents of the other. @example @group