[Emacs-diffs] Changes to emacs/lispref/objects.texi

[Richard M . Stallman]

Index: emacs/lispref/objects.texi
diff -c emacs/lispref/objects.texi:1.44 emacs/lispref/objects.texi:1.45
*** emacs/lispref/objects.texi:1.44     Thu Feb 10 06:50:59 2005
--- emacs/lispref/objects.texi  Mon Feb 14 10:22:36 2005
***************
*** 68,103 ****
  
    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.
  
  @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{} #<buffer objects.texi>
  @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,
--- 68,104 ----
  
    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.  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
!   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,
***************
*** 204,212 ****
  @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.
  
    The printed representation for floating point numbers requires either
  a decimal point (with at least one digit following), an exponent, or
--- 205,215 ----
  @subsection Floating Point Type
  
    Floating point numbers are the computer equivalent of scientific
! 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,482 ****
  @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 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
--- 477,486 ----
  @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 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,623 ****
  
    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.
  
  @cindex atom
    Because cons cells are so central to Lisp, we also have a word for
--- 610,619 ----
  
    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.  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
***************
*** 627,633 ****
  @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
--- 623,640 ----
  @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
***************
*** 636,643 ****
--- 643,668 ----
  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
***************
*** 688,706 ****
  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,718 ----
***************
*** 715,741 ****
  @end group
  @end example
  
! @menu
! * Dotted Pair Notation::        An alternative syntax for lists.
! * Association List Type::       A specially constructed list.
! @end menu
  
  @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,
  @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.
  
    Here's an example using boxes to illustrate dotted pair notation.
  This example shows the pair @code{(rose . violet)}:
--- 727,790 ----
  @end group
  @end example
  
!   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
  @subsubsection Dotted Pair Notation
  @cindex dotted pair notation
  @cindex @samp{.} in lists
  
!   @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 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,867 ****
  
    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.
  
    The array type is contained in the sequence type and
  contains the string type, the vector type, the bool-vector type, and the
--- 909,917 ----
  
    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 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,1666 ****
--- 1711,1719 ----
  @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}.