@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
@node Read and Print, Minibuffers, Debugging, Top
@sc{cdr} is the number 5.
@dfn{Printing} a Lisp object means producing text that represents that
-object---converting the object to its printed representation. Printing
-the cons cell described above produces the text @samp{(a .@: 5)}.
+object---converting the object to its @dfn{printed representation}
+(@pxref{Printed Representation}). Printing the cons cell described
+above produces the text @samp{(a .@: 5)}.
Reading and printing are more or less inverse operations: printing the
object that results from reading a given piece of text often produces
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
-two kinds of exceptions:
+ However, these two operations are not precisely inverse to each other.
+There are three kinds of exceptions:
@itemize @bullet
@item
Printing can produce text that cannot be read. For example, buffers,
-windows, frames, subprocesses and markers print into text that starts
+windows, frames, subprocesses and markers print as text that starts
with @samp{#}; if you try to read this text, you get an error. There is
no way to read those data types.
@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
@samp{(a .@: (b))} represent the same list. Reading will accept any of
the alternatives, but printing must choose one of them.
+
+@item
+Comments can appear at certain points in the middle of an object's
+read sequence without affecting the result of reading it.
@end itemize
@node Input Streams
@item @var{function}
@cindex function input stream
-The input characters are generated by @var{function}, one character per
-call. Normally @var{function} is called with no arguments, and should
-return a character.
+The input characters are generated by @var{function}, which must support
+two kinds of calls:
+
+@itemize @bullet
+@item
+When it is called with no arguments, it should return the next character.
-@cindex unreading
-Occasionally @var{function} is called with one argument (always a
-character). When that happens, @var{function} should save the argument
-and arrange to return it on the next call. This is called
-@dfn{unreading} the character; it happens when the Lisp reader reads one
-character too many and wants to ``put it back where it came from''.
+@item
+When it is called with one argument (always a character), @var{function}
+should save the argument and arrange to return it on the next call.
+This is called @dfn{unreading} the character; it happens when the Lisp
+reader reads one character too many and wants to ``put it back where it
+came from''. In this case, it makes no difference what value
+@var{function} returns.
+@end itemize
@item @code{t}
@cindex @code{t} input stream
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.
-
- In Emacs 18, reading a symbol discarded the delimiter terminating the
-symbol. Thus, point would end up at the beginning of @samp{contents}
-rather than after @samp{the}. The Emacs 19 behavior is superior because
-it correctly handles input such as @samp{bar(foo)}, where the delimiter
-that ends one object is needed as the beginning of another object.
+Note that the first read skips a space. Reading skips any amount of
+whitespace preceding the significant text.
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 remain 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 you specify
+@var{end}, then reading is forced to stop 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.
+on printing when the stream is a marker, and this kind of printing
+does not move point.
@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away. It is called with a single character as
-argument, as many times as there are characters to be output, and is
-free to do anything at all with the characters it receives.
+argument, as many times as there are characters to be output, and
+is responsible for storing the characters wherever you want to put them.
@item @code{t}
@cindex @code{t} output stream
@item @code{nil}
@cindex @code{nil} output stream
-@code{nil} specified as an output stream means to the value of
+@code{nil} specified as an output stream means to use the value of
@code{standard-output} instead; that value is the @dfn{default output
-stream}, and must be a non-@code{nil} output stream.
+stream}, and must not be @code{nil}.
@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
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 more a matter
+of how you use a Lisp object, than of different 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
---------- Buffer: foo ----------
-"This is the @point{}output"
+This is the @point{}output
---------- Buffer: foo ----------
@end group
@group
-m
- @result{} #<marker at 11 in foo>
+(setq m (copy-marker 10))
+ @result{} #<marker at 10 in foo>
@end group
@group
@group
---------- Buffer: foo ----------
-"This is t
+This is t
"More output for foo."
-he @point{}output"
+he @point{}output
---------- Buffer: foo ----------
@end group
@group
m
- @result{} #<marker at 35 in foo>
+ @result{} #<marker at 34 in foo>
@end group
@end example
@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
- This section describes the Lisp functions for printing Lisp objects.
+ This section describes the Lisp functions for printing Lisp
+objects---converting objects into their printed representation.
@cindex @samp{"} in printing
@cindex @samp{\} in printing
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.
-
- 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
-to describe a Lisp object clearly for a Lisp programmer. However, if
-the purpose of the output is to look nice for humans, then it is better
-to print without quoting.
-
- Printing a self-referent Lisp object requires an infinite amount of
-text. In certain cases, trying to produce this text leads to a stack
-overflow. Emacs detects such recursion and prints @samp{#@var{level}}
-instead of recursively printing an object already being printed. For
-example, here @samp{#0} indicates a recursive reference to the object at
-level 0 of the current print operation:
+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 you should print with
+quoting characters to avoid ambiguity. Likewise, if the purpose is to
+describe a Lisp object clearly for a Lisp programmer. However, if the
+purpose of the output is to look nice for humans, then it is usually
+better to print without quoting.
+
+ Lisp objects can refer to themselves. Printing a self-referential
+object in the normal way would require an infinite amount of text, and
+the attempt could cause infinite recursion. Emacs detects such
+recursion and prints @samp{#@var{level}} instead of recursively printing
+an object already being printed. For example, here @samp{#0} indicates
+a recursive reference to the object at level 0 of the current print
+operation:
@example
(setq foo (list nil))
@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
the printed representation of a Lisp object as a string.
@end defun
+@defmac with-output-to-string body...
+@tindex with-output-to-string
+This macro executes the @var{body} forms with @code{standard-output} set
+up to feed output into a string. Then it returns that string.
+
+For example, if the current buffer name is @samp{foo},
+
+@example
+(with-output-to-string
+ (princ "The buffer is ")
+ (princ (buffer-name)))
+@end example
+
+@noindent
+returns @code{"The buffer is foo"}.
+@end defmac
+
@node Output Variables
@section Variables Affecting Output
are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
Normally these characters are printed as actual newlines and formfeeds.
-This variable affects the print functions @code{prin1} and @code{print},
-as well as everything that uses them. It does not affect @code{princ}.
-Here is an example using @code{prin1}:
+This variable affects the print functions @code{prin1} and @code{print}
+that print with quoting. It does not affect @code{princ}. Here is an
+example using @code{prin1}:
@example
@group
@code{prin1}, but not during the printing of the result.
@end defvar
+@tindex print-escape-nonascii
+@defvar print-escape-nonascii
+If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for unibyte non-@sc{ascii}
+characters, regardless of the value of this variable, when the output
+stream is a multibyte buffer or a marker pointing into one.
+@end defvar
+
+@tindex print-escape-multibyte
+@defvar print-escape-multibyte
+If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for multibyte
+non-@sc{ascii} characters, regardless of the value of this variable,
+when the output stream is a unibyte buffer or a marker pointing into
+one.
+@end defvar
+
@defvar print-length
@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.
+The value of this variable is the maximum number of elements to print in
+any list, vector or bool-vector. If an object being printed has more
+than this many 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.
+@end defvar
+
+ These variables are used for detecting and reporting circular
+and shared structure---but they are only defined in Emacs 21.
+
+@tindex print-circle
+@defvar print-circle
+If non-@code{nil}, this variable enables detection of circular
+and shared structure in printing.
+@end defvar
-This variable exists in version 19 and later versions.
+@tindex print-gensym
+@defvar print-gensym
+If non-@code{nil}, this variable enables detection of uninterned symbols
+(@pxref{Creating Symbols}) in printing. When this is enabled,
+uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
+reader to produce an uninterned symbol.
@end defvar