X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/05fd2b657637064d8a7ac7d0f55642c7a6d819df..af5a6df7b15cf2cf4da8a6aa38081725f9082479:/lispref/streams.texi

diff --git a/lispref/streams.texi b/lispref/streams.texi
index 22c9c89ae3..f459c1c821 100644
--- a/lispref/streams.texi
+++ b/lispref/streams.texi
@@ -1,6 +1,7 @@
 @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
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/streams
 @node Read and Print, Minibuffers, Debugging, Top
@@ -38,8 +39,9 @@ is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
 @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
@@ -48,16 +50,16 @@ usually produces a similar-looking object.  For example, printing the
 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.
 
@@ -66,6 +68,10 @@ One object can have multiple textual representations.  For example,
 @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
@@ -98,23 +104,34 @@ character in the string and using as many characters as required.
 
 @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
@@ -127,7 +144,7 @@ A symbol as input stream is equivalent to the symbol's function
 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
@@ -154,17 +171,11 @@ This is the@point{} contents of foo.
 @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
@@ -185,7 +196,7 @@ This is the contents of foo.
 @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
 
@@ -216,7 +227,7 @@ Lisp expression: @kbd{23 @key{RET}}
   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
@@ -246,15 +257,15 @@ Now we read using the stream thus constructed:
 
 @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
@@ -274,7 +285,7 @@ defaults to the value of @code{standard-input}.
 
 @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},
@@ -288,10 +299,10 @@ This function reads the first textual Lisp expression from the text in
 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:
 
@@ -313,7 +324,7 @@ 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,}
@@ -327,6 +338,7 @@ 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
@@ -347,16 +359,19 @@ Point advances as characters are inserted.
 @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 (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
@@ -364,15 +379,19 @@ The output characters are displayed in the echo area.
 
 @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
@@ -399,22 +418,22 @@ This is t
 @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
@@ -424,15 +443,15 @@ m
 
 @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
 
@@ -473,7 +492,7 @@ in reverse order.
 
 @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
@@ -490,10 +509,15 @@ Now we can put the output in the proper order by reversing the list:
 @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
@@ -503,22 +527,23 @@ Now we can put the output in the proper order by reversing the list:
 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))
@@ -544,13 +569,12 @@ characters are used.  @code{print} returns @var{object}.  For example:
 (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
@@ -558,14 +582,14 @@ characters are used.  @code{print} returns @var{object}.  For example:
 
 @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
-(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"
@@ -639,12 +663,36 @@ See @code{format}, in @ref{String Conversion}, for other ways to obtain
 the printed representation of a Lisp object as a string.
 @end defun
 
+@defmac with-output-to-string body...
+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
@@ -654,9 +702,9 @@ If this variable is non-@code{nil}, then newline characters in strings
 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
@@ -682,11 +730,34 @@ In the second expression, the local binding of
 @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
-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.
 
@@ -705,9 +776,63 @@ 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
 
-This variable exists in version 19 and later versions.
+@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
+
+@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