symbol @code{foo} produces the text @samp{foo}, and reading that text
returns the symbol @code{foo}. Printing a list whose elements are
@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
-text produces a list (but not the same list) with elements are @code{a}
+text produces a list (but not the same list) with elements @code{a}
and @code{b}.
However, these two operations are not precisely inverses. There are
definition (if any).
@end table
- Here is an example of reading from a stream which is a buffer, showing
+ Here is an example of reading from a stream that is a buffer, showing
where point is located before and after:
@example
@end example
@noindent
-Note that the first read skips a space at the beginning of the buffer.
-Reading skips any amount of whitespace preceding the significant text.
+Note that the first read skips a space. Reading skips any amount of
+whitespace preceding the significant text.
In Emacs 18, reading a symbol discarded the delimiter terminating the
symbol. Thus, point would end up at the beginning of @samp{contents}
that ends one object is needed as the beginning of another object.
Here is an example of reading from a stream that is a marker,
-initialized to point at the beginning of the buffer shown. The value
+initially positioned at the beginning of the buffer shown. The value
read is the symbol @code{This}.
@example
@end group
@group
m
- @result{} #<marker at 6 in foo> ;; @r{After the first space.}
+ @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
@end group
@end example
Finally, here is an example of a stream that is a function, named
@code{useless-stream}. Before we use the stream, we initialize the
variable @code{useless-list} to a list of characters. Then each call to
-the function @code{useless-stream} obtains the next characters in the list
+the function @code{useless-stream} obtains the next character in the list
or unreads a character by adding it to the front of the list.
@example
@group
useless-list
- @result{} (41)
+ @result{} (40 41)
@end group
@end example
@noindent
-Note that the close parenthesis remains in the list. The reader has
-read it, discovered that it ended the input, and unread it. Another
-attempt to read from the stream at this point would get an error due to
-the unmatched close parenthesis.
+Note that the open and close parentheses remains in the list. The Lisp
+reader encountered the open parenthesis, decided that it ended the
+input, and unread it. Another attempt to read from the stream at this
+point would read @samp{()} and return @code{nil}.
@defun get-file-char
This function is used internally as an input stream to read from the
@kindex end-of-file
An @code{end-of-file} error is signaled if reading encounters an
-unterminated list, vector or string.
+unterminated list, vector, or string.
@defun read &optional stream
This function reads one textual Lisp expression from @var{stream},
and whose @sc{cdr} is an integer giving the position of the next
remaining character in the string (i.e., the first one not read).
-If @var{start} is supplied, then reading begins at index @var{start} in the
-string (where the first character is at index 0). If @var{end} is also
-supplied, then reading stops at that index as if the rest of the string
-were not there.
+If @var{start} is supplied, then reading begins at index @var{start} in
+the string (where the first character is at index 0). If @var{end} is
+also supplied, then reading stops just before that index, as if the rest
+of the string were not there.
For example:
@group
;; @r{Read starting at the second character.}
(read-from-string "(list 112)" 1)
- @result{} (list . 6)
+ @result{} (list . 5)
@end group
@group
;; @r{Read starting at the seventh character,}
@item @var{marker}
@cindex marker output stream
The output characters are inserted into the buffer that @var{marker}
-points into, at the marker position. The position advances as
+points into, at the marker position. The marker position advances as
characters are inserted. The value of point in the buffer has no effect
on printing when the stream is a marker.
definition (if any).
@end table
+ Many of the valid output streams are also valid as input streams. The
+difference between input and output streams is therefore mostly one of
+how you use a Lisp object, not a distinction of types of object.
+
Here is an example of a buffer used as an output stream. Point is
initially located as shown immediately before the @samp{h} in
@samp{the}. At the end, point is located directly before that same
@end example
Now we show a use of a marker as an output stream. Initially, the
-marker points in buffer @code{foo}, between the @samp{t} and the
-@samp{h} in the word @samp{the}. At the end, the marker has been
-advanced over the inserted text so that it still points before the same
-@samp{h}. Note that the location of point, shown in the usual fashion,
-has no effect.
+marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
+the word @samp{the}. At the end, the marker has advanced over the
+inserted text so that it remains positioned before the same @samp{h}.
+Note that the location of point, shown in the usual fashion, has no
+effect.
@example
@group
@end group
@end example
+@noindent
+Calling @code{concat} converts the list to a string so you can see its
+contents more clearly.
+
@node Output Functions
@section Output Functions
output when necessary so that it can be read properly. The quoting
characters used are @samp{"} and @samp{\}; they distinguish strings from
symbols, and prevent punctuation characters in strings and symbols from
-being taken as delimiters. @xref{Printed Representation}, for full
-details. You specify quoting or no quoting by the choice of printing
-function.
+being taken as delimiters when reading. @xref{Printed Representation},
+for full details. You specify quoting or no quoting by the choice of
+printing function.
If the text is to be read back into Lisp, then it is best to print
with quoting characters to avoid ambiguity. Likewise, if the purpose is
@defun prin1 object &optional stream
This function outputs the printed representation of @var{object} to
-@var{stream}. It does not print any spaces or newlines to separate
-output as @code{print} does, but it does use quoting characters just
-like @code{print}. It returns @var{object}.
+@var{stream}. It does not print newlines to separate output as
+@code{print} does, but it does use quoting characters just like
+@code{print}. It returns @var{object}.
@example
@group
@cindex printing limits
The value of this variable is the maximum number of elements of a list
that will be printed. If a list being printed has more than this many
-elements, then it is abbreviated with an ellipsis.
+elements, it is abbreviated with an ellipsis.
If the value is @code{nil} (the default), then there is no limit.
@defvar print-level
The value of this variable is the maximum depth of nesting of
-parentheses that will be printed. Any list or vector at a depth
+parentheses and brackets when printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
@code{nil} (which is the default) means no limit.
projects / emacs.git / commitdiff