@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, 1999, 2002, 2003, 2004,
+@c 2005, 2006 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
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
-three 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.
@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:
-@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''.
+@itemize @bullet
+@item
+When it is called with no arguments, it should return the next character.
+
+@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
@code{t} used as a stream means that the input is read from the
minibuffer. In fact, the minibuffer is invoked once and the text
given by the user is made into a string that is then used as the
-input stream.
+input stream. If Emacs is running in batch mode, standard input is used
+instead of the minibuffer. For example,
+@example
+(message "%s" (read t))
+@end example
+will read a Lisp expression from standard input and print the result
+to standard output.
@item @code{nil}
@cindex @code{nil} input stream
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}
-rather than after @samp{the}. The Emacs 19 behavior is superior because
-it correctly handles input such as @samp{bar(foo)}, where the
-open-parenthesis 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,
initially positioned at the beginning of the buffer shown. The value
read is the symbol @code{This}.
@end example
@noindent
-Note that the open and close parentheses remains in the list. The Lisp
+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}.
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 just before that index, as if the rest
-of the string were not there.
+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:
@defvar standard-input
This variable holds the default input stream---the stream that
@code{read} uses when the @var{stream} argument is @code{nil}.
+The default is @code{t}, meaning use the minibuffer.
@end defvar
@node Output Streams
The output characters are inserted into the buffer that @var{marker}
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 (except that if the marker points at or before the
+position of point, point advances with the surrounding text, as
+usual).
@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
@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.
+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
@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
@group
last-output
- @result{} (10 34 116 117 112 116 117 111 32 101 104
+ @result{} (10 34 116 117 112 116 117 111 32 101 104
116 32 115 105 32 115 105 104 84 34 10)
@end group
@end example
@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
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.
+ 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.
- 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:
+ 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))
(progn (print 'The\ cat\ in)
(print "the hat")
(print " came back"))
- @print{}
+ @print{}
@print{} The\ cat\ in
- @print{}
+ @print{}
@print{} "the hat"
- @print{}
+ @print{}
@print{} " came back"
- @print{}
@result{} " came back"
@end group
@end example
@example
@group
-(progn (prin1 'The\ cat\ in)
- (prin1 "the hat")
+(progn (prin1 'The\ cat\ in)
+ (prin1 "the hat")
(prin1 " came back"))
@print{} The\ cat\ in"the hat"" came back"
@result{} " came back"
@end group
@end example
-See @code{format}, in @ref{String Conversion}, for other ways to obtain
+See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
the printed representation of a Lisp object as a string.
@end defun
+@defmac with-output-to-string body@dots{}
+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
@defvar standard-output
The value of this variable is the default output stream---the stream
that print functions use when the @var{stream} argument is @code{nil}.
+The default is @code{t}, meaning display in the echo area.
+@end defvar
+
+@defvar print-quoted
+If this is non-@code{nil}, that means to print quoted forms using
+abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo},
+@code{(function foo)} as @code{#'foo}, and backquoted forms print
+using modern backquote syntax.
@end defvar
@defvar print-escape-newlines
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
+@defvar print-escape-nonascii
+If this variable is non-@code{nil}, then unibyte non-@acronym{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-@acronym{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
+
+@defvar print-escape-multibyte
+If this variable is non-@code{nil}, then multibyte non-@acronym{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-@acronym{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,
-vector or bitvector that will be printed. If an object being printed has
-more than this many elements, 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.
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
+
+@defopt eval-expression-print-length
+@defoptx eval-expression-print-level
+These are the values for @code{print-length} and @code{print-level}
+used by @code{eval-expression}, and thus, indirectly, by many
+interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
+Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
+@end defopt
+
+ These variables are used for detecting and reporting circular
+and shared structure:
+
+@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
+
+@defvar print-continuous-numbering
+If non-@code{nil}, that means number continuously across print calls.
+This affects the numbers printed for @samp{#@var{n}=} labels and
+@samp{#@var{m}#} references.
+
+Don't set this variable with @code{setq}; you should only bind it
+temporarily to @code{t} with @code{let}. When you do that, you should
+also bind @code{print-number-table} to @code{nil}.
+@end defvar
+
+@defvar print-number-table
+This variable holds a vector used internally by printing to implement
+the @code{print-circle} feature. You should not use it except
+to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
+@end defvar
+
+@defvar float-output-format
+This variable specifies how to print floating point numbers. Its
+default value is @code{nil}, meaning use the shortest output
+that represents the number without losing information.
+
+To control output format more precisely, you can put a string in this
+variable. The string should hold a @samp{%}-specification to be used
+in the C function @code{sprintf}. For further restrictions on what
+you can use, see the variable's documentation string.
+@end defvar
+
+@ignore
+ arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
+@end ignore