# HG changeset patch # User Richard M. Stallman # Date 1108376556 0 # Node ID d1e94109daa413ae5579779bab91ed53dcc30afe # Parent d262f544d0bff8e7b19889a40abe6fff1300831f (Printed Representation): Clarify read syntax vs print. (Floating Point Type): Explain meaning better. (Symbol Type): Explain uniqueness better. (Cons Cell Type): Explain empty list sooner. CAR and CDR later. List examples sooner. (Box Diagrams): New subnode broken out. Some examples moved from old Lists as Boxes node. (Dotted Pair Notation): Clarify intro. (Array Type): Clarify. (Type Predicates): Add hash-table-p. diff -r d262f544d0bf -r d1e94109daa4 lispref/objects.texi --- a/lispref/objects.texi Mon Feb 14 10:19:36 2005 +0000 +++ b/lispref/objects.texi Mon Feb 14 10:22:36 2005 +0000 @@ -68,14 +68,30 @@ 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}. +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}. - 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. +@cindex hash notation + 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 @@ -83,21 +99,6 @@ emphasize this distinction, but you must keep it in the back of your mind, or you will occasionally be very confused. -@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 - -@example -(current-buffer) - @result{} # -@end example - 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, @@ -204,9 +205,11 @@ @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 @@ -474,9 +477,10 @@ @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 @@ -606,9 +610,38 @@ 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. +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 +``an object which is not a cons cell''. These objects are called +@dfn{atoms}. + +@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. 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 +@sc{car} slot of the cons cell holds the element, and its @sc{cdr} +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 @@ -619,25 +652,17 @@ for the function @code{cons} that creates them, which in turn was named for its purpose, the construction of cells. -@cindex atom - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called -@dfn{atoms}. +@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 -@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. - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} slot of the cons cell holds the element, and its @sc{cdr} -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}. - +@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 @@ -688,19 +713,6 @@ 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: @@ -715,27 +727,64 @@ @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)}: @@ -860,8 +909,9 @@ 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 @@ -1661,6 +1711,9 @@ @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}.