--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/streams.info
+@node Read and Print, Minibuffers, Debugging, Top
+@chapter Reading and Printing Lisp Objects
+
+ @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
+objects to textual form and vice versa. They use the printed
+representations and read syntax described in @ref{Lisp Data Types}.
+
+ This chapter describes the Lisp functions for reading and printing.
+It also describes @dfn{streams}, which specify where to get the text (if
+reading) or where to put it (if printing).
+
+@menu
+* Streams Intro:: Overview of streams, reading and printing.
+* Input Streams:: Various data types that can be used as input streams.
+* Input Functions:: Functions to read Lisp objects from text.
+* Output Streams:: Various data types that can be used as output streams.
+* Output Functions:: Functions to print Lisp objects as text.
+* Output Variables:: Variables that control what the printing functions do.
+@end menu
+
+@node Streams Intro
+@section Introduction to Reading and Printing
+@cindex Lisp reader
+@cindex printing
+@cindex reading
+
+ @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
+form and producing a corresponding Lisp object. This is how Lisp
+programs get into Lisp from files of Lisp code. We call the text the
+@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
+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)}.
+
+ Reading and printing are more or less inverse operations: printing the
+object that results from reading a given piece of text often produces
+the same text, and reading the text that results from printing an object
+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 @code{a}
+and @code{b}.
+
+ However, these two operations are not precisely inverses. 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
+with @samp{#}; if you try to read this text, you get an error. There is
+no way to read those data types.
+
+@item
+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
+@section Input Streams
+@cindex stream (for reading)
+@cindex input stream
+
+ Most of the Lisp functions for reading text take an @dfn{input stream}
+as an argument. The input stream specifies where or how to get the
+characters of the text to be read. Here are the possible types of input
+stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer input stream
+The input characters are read from @var{buffer}, starting with the
+character directly after point. Point advances as characters are read.
+
+@item @var{marker}
+@cindex marker input stream
+The input characters are read from the buffer that @var{marker} is in,
+starting with the character directly after the marker. The marker
+position advances as characters are read. The value of point in the
+buffer has no effect when the stream is a marker.
+
+@item @var{string}
+@cindex string input stream
+The input characters are taken from @var{string}, starting at the first
+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.
+
+@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 @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.
+
+@item @code{nil}
+@cindex @code{nil} input stream
+@code{nil} supplied as an input stream means to use the value of
+@code{standard-input} instead; that value is the @dfn{default input
+stream}, and must be a non-@code{nil} input stream.
+
+@item @var{symbol}
+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 that is a buffer, showing
+where point is located before and after:
+
+@example
+@group
+---------- Buffer: foo ----------
+This@point{} is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(read (get-buffer "foo"))
+ @result{} is
+@end group
+@group
+(read (get-buffer "foo"))
+ @result{} the
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is the@point{} contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+@noindent
+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}.
+
+@example
+@group
+
+---------- Buffer: foo ----------
+This is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
+ @result{} #<marker at 1 in foo>
+@end group
+@group
+(read m)
+ @result{} This
+@end group
+@group
+m
+ @result{} #<marker at 5 in foo> ;; @r{Before the first space.}
+@end group
+@end example
+
+ Here we read from the contents of a string:
+
+@example
+@group
+(read "(When in) the course")
+ @result{} (When in)
+@end group
+@end example
+
+ The following example reads from the minibuffer. The
+prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
+used when you read from the stream @code{t}.) The user's input is shown
+following the prompt.
+
+@example
+@group
+(read t)
+ @result{} 23
+---------- Buffer: Minibuffer ----------
+Lisp expression: @kbd{23 @key{RET}}
+---------- Buffer: Minibuffer ----------
+@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 character in the list
+or unreads a character by adding it to the front of the list.
+
+@example
+@group
+(setq useless-list (append "XY()" nil))
+ @result{} (88 89 40 41)
+@end group
+
+@group
+(defun useless-stream (&optional unread)
+ (if unread
+ (setq useless-list (cons unread useless-list))
+ (prog1 (car useless-list)
+ (setq useless-list (cdr useless-list)))))
+ @result{} useless-stream
+@end group
+@end example
+
+@noindent
+Now we read using the stream thus constructed:
+
+@example
+@group
+(read 'useless-stream)
+ @result{} XY
+@end group
+
+@group
+useless-list
+ @result{} (40 41)
+@end group
+@end example
+
+@noindent
+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}.
+
+@ignore @c Not in XEmacs
+@defun get-file-char
+This function is used internally as an input stream to read from the
+input file opened by the function @code{load}. Don't use this function
+yourself.
+@end defun
+@end ignore
+
+@node Input Functions
+@section Input Functions
+
+ This section describes the Lisp functions and variables that pertain
+to reading.
+
+ In the functions below, @var{stream} stands for an input stream (see
+the previous section). If @var{stream} is @code{nil} or omitted, it
+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.
+
+@defun read &optional stream
+This function reads one textual Lisp expression from @var{stream},
+returning it as a Lisp object. This is the basic Lisp input function.
+@end defun
+
+@defun read-from-string string &optional start end
+@cindex string to object
+This function reads the first textual Lisp expression from the text in
+@var{string}. It returns a cons cell whose @sc{car} is that expression,
+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 just before that index, as if the rest
+of the string were not there.
+
+For example:
+
+@example
+@group
+(read-from-string "(setq x 55) (setq y 5)")
+ @result{} ((setq x 55) . 11)
+@end group
+@group
+(read-from-string "\"A short string\"")
+ @result{} ("A short string" . 16)
+@end group
+
+@group
+;; @r{Read starting at the first character.}
+(read-from-string "(list 112)" 0)
+ @result{} ((list 112) . 10)
+@end group
+@group
+;; @r{Read starting at the second character.}
+(read-from-string "(list 112)" 1)
+ @result{} (list . 5)
+@end group
+@group
+;; @r{Read starting at the seventh character,}
+;; @r{and stopping at the ninth.}
+(read-from-string "(list 112)" 6 8)
+ @result{} (11 . 8)
+@end group
+@end example
+@end defun
+
+@defvar standard-input
+This variable holds the default input stream---the stream that
+@code{read} uses when the @var{stream} argument is @code{nil}.
+@end defvar
+
+@node Output Streams
+@section Output Streams
+@cindex stream (for printing)
+@cindex output stream
+
+ An output stream specifies what to do with the characters produced
+by printing. Most print functions accept an output stream as an
+optional argument. Here are the possible types of output stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer output stream
+The output characters are inserted into @var{buffer} at point.
+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 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.
+
+@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.
+
+@item @code{t}
+@cindex @code{t} output stream
+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{standard-output} instead; that value is the @dfn{default output
+stream}, and must be a non-@code{nil} output stream.
+
+@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 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
+@samp{h}.
+
+@cindex print example
+@example
+@group
+---------- Buffer: foo ----------
+This is t@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+(print "This is the output" (get-buffer "foo"))
+ @result{} "This is the output"
+
+@group
+---------- Buffer: foo ----------
+This is t
+"This is the output"
+@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+ Now we show a use of a marker as an output stream. Initially, the
+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"
+---------- Buffer: foo ----------
+@end group
+
+@group
+m
+ @result{} #<marker at 11 in foo>
+@end group
+
+@group
+(print "More output for foo." m)
+ @result{} "More output for foo."
+@end group
+
+@group
+---------- Buffer: foo ----------
+"This is t
+"More output for foo."
+he @point{}output"
+---------- Buffer: foo ----------
+@end group
+
+@group
+m
+ @result{} #<marker at 35 in foo>
+@end group
+@end example
+
+ The following example shows output to the echo area:
+
+@example
+@group
+(print "Echo Area output" t)
+ @result{} "Echo Area output"
+---------- Echo Area ----------
+"Echo Area output"
+---------- Echo Area ----------
+@end group
+@end example
+
+ Finally, we show the use of a function as an output stream. The
+function @code{eat-output} takes each character that it is given and
+conses it onto the front of the list @code{last-output} (@pxref{Building
+Lists}). At the end, the list contains all the characters output, but
+in reverse order.
+
+@example
+@group
+(setq last-output nil)
+ @result{} nil
+@end group
+
+@group
+(defun eat-output (c)
+ (setq last-output (cons c last-output)))
+ @result{} eat-output
+@end group
+
+@group
+(print "This is the output" 'eat-output)
+ @result{} "This is the output"
+@end group
+
+@group
+last-output
+ @result{} (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
+ ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
+@end group
+@end example
+
+@noindent
+Now we can put the output in the proper order by reversing the list:
+
+@example
+@group
+(concat (nreverse last-output))
+ @result{} "
+\"This is the output\"
+"
+@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.
+
+@cindex @samp{"} in printing
+@cindex @samp{\} in printing
+@cindex quoting characters in printing
+@cindex escape characters in printing
+ Some of the XEmacs printing functions add quoting characters to the
+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 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
+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. XEmacs 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))
+ @result{} (nil)
+(setcar foo foo)
+ @result{} (#0)
+@end example
+
+ In the functions below, @var{stream} stands for an output stream.
+(See the previous section for a description of output streams.) If
+@var{stream} is @code{nil} or omitted, it defaults to the value of
+@code{standard-output}.
+
+@defun print object &optional stream
+@cindex Lisp printer
+The @code{print} function is a convenient way of printing. It outputs
+the printed representation of @var{object} to @var{stream}, printing in
+addition one newline before @var{object} and another after it. Quoting
+characters are used. @code{print} returns @var{object}. For example:
+
+@example
+@group
+(progn (print 'The\ cat\ in)
+ (print "the hat")
+ (print " came back"))
+ @print{}
+ @print{} The\ cat\ in
+ @print{}
+ @print{} "the hat"
+ @print{}
+ @print{} " came back"
+ @print{}
+ @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun prin1 object &optional stream
+This function outputs the printed representation of @var{object} to
+@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")
+ (prin1 " came back"))
+ @print{} The\ cat\ in"the hat"" came back"
+ @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun princ object &optional stream
+This function outputs the printed representation of @var{object} to
+@var{stream}. It returns @var{object}.
+
+This function is intended to produce output that is readable by people,
+not by @code{read}, so it doesn't insert quoting characters and doesn't
+put double-quotes around the contents of strings. It does not add any
+spacing between calls.
+
+@example
+@group
+(progn
+ (princ 'The\ cat)
+ (princ " in the \"hat\""))
+ @print{} The cat in the "hat"
+ @result{} " in the \"hat\""
+@end group
+@end example
+@end defun
+
+@defun terpri &optional stream
+@cindex newline in print
+This function outputs a newline to @var{stream}. The name stands
+for ``terminate print''.
+@end defun
+
+@defun write-char character &optional stream
+This function outputs @var{character} to @var{stream}. It returns
+@var{character}.
+@end defun
+
+@defun prin1-to-string object &optional noescape
+@cindex object to string
+This function returns a string containing the text that @code{prin1}
+would have printed for the same argument.
+
+@example
+@group
+(prin1-to-string 'foo)
+ @result{} "foo"
+@end group
+@group
+(prin1-to-string (mark-marker))
+ @result{} "#<marker at 2773 in strings.texi>"
+@end group
+@end example
+
+If @var{noescape} is non-@code{nil}, that inhibits use of quoting
+characters in the output. (This argument is supported in Emacs versions
+19 and later.)
+
+@example
+@group
+(prin1-to-string "foo")
+ @result{} "\"foo\""
+@end group
+@group
+(prin1-to-string "foo" t)
+ @result{} "foo"
+@end group
+@end example
+
+See @code{format}, in @ref{String Conversion}, for other ways to obtain
+the printed representation of a Lisp object as a string.
+@end defun
+
+@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}.
+@end defvar
+
+@defvar print-escape-newlines
+@cindex @samp{\n} in print
+@cindex escape characters
+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}:
+
+@example
+@group
+(prin1 "a\nb")
+ @print{} "a
+ @print{} b"
+ @result{} "a
+b"
+@end group
+
+@group
+(let ((print-escape-newlines t))
+ (prin1 "a\nb"))
+ @print{} "a\nb"
+ @result{} "a
+b"
+@end group
+@end example
+
+@noindent
+In the second expression, the local binding of
+@code{print-escape-newlines} is in effect during the call to
+@code{prin1}, but not during the printing of the result.
+@end defvar
+
+@defvar print-readably
+@cindex printing readably
+If non-@code{nil}, then all objects will be printed in a readable form.
+If an object has no readable representation, then an error is signalled.
+When @code{print-readably} is true, compiled-function objects will be
+written in @samp{#[...]} form instead of in @samp{#<compiled-function
+[...]>} form, and two-element lists of the form @samp{(quote object)}
+will be written as the equivalent @samp{'object}. Do not @emph{set}
+this variable; bind it instead.
+@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, it is abbreviated with an ellipsis.
+
+If the value is @code{nil} (the default), then there is no limit.
+
+@example
+@group
+(setq print-length 2)
+ @result{} 2
+@end group
+@group
+(print '(1 2 3 4 5))
+ @print{} (1 2 ...)
+ @result{} (1 2 ...)
+@end group
+@end example
+@end defvar
+
+@defvar print-level
+The value of this variable is the maximum depth of nesting of
+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.
+
+This variable exists in version 19 and later versions.
+@end defvar
+
+@defvar print-string-length
+@cindex string length, maximum when printing
+The value of this variable is the maximum number of characters of a string
+that will be printed. If a string being printed has more than this many
+characters, it is abbreviated with an ellipsis.
+@end defvar
+
+@defvar print-gensym
+@cindex printing uninterned symbols
+@cindex uninterned symbols, printing
+If non-@code{nil}, then uninterned symbols will be printed specially.
+Uninterned symbols are those which are not present in @code{obarray},
+that is, those which were made with @code{make-symbol} or by calling
+@code{intern} with a second argument.
+
+When @code{print-gensym} is true, such symbols will be preceded by
+@samp{#:}, which causes the reader to create a new symbol instead of
+interning and returning an existing one. Beware: The @samp{#:} syntax
+creates a new symbol each time it is seen, so if you print an object
+which contains two pointers to the same uninterned symbol, @code{read}
+will not duplicate that structure.
+
+Also, since XEmacs has no real notion of packages, there is no way for
+the printer to distinguish between symbols interned in no obarray, and
+symbols interned in an alternate obarray.
+@end defvar
+
+@defvar float-output-format
+@cindex printing floating-point numbers
+@cindex floating-point numbers, printing
+This variable holds the format descriptor string that Lisp uses to print
+floats. This is a @samp{%}-spec like those accepted by @code{printf} in
+C, but with some restrictions. It must start with the two characters
+@samp{%.}. After that comes an integer precision specification, and
+then a letter which controls the format. The letters allowed are
+@samp{e}, @samp{f} and @samp{g}.
+
+@itemize @bullet
+@item
+Use @samp{e} for exponential notation
+@samp{@var{dig}.@var{digits}e@var{expt}}.
+@item
+Use @samp{f} for decimal point notation @samp{DIGITS.DIGITS}.
+@item
+Use @samp{g} to choose the shorter of those two formats for the number
+at hand.
+@end itemize
+
+The precision in any of these cases is the number of digits following
+the decimal point. With @samp{f}, a precision of 0 means to omit the
+decimal point. 0 is not allowed with @samp{f} or @samp{g}.
+
+A value of @code{nil} means to use @samp{%.16g}.
+
+Regardless of the value of @code{float-output-format}, a floating point
+number will never be printed in such a way that it is ambiguous with an
+integer; that is, a floating-point number will always be printed with a
+decimal point and/or an exponent, even if the digits following the
+decimal point are all zero. This is to preserve read-equivalence.
+@end defvar
projects / chise / xemacs-chise.git- / blobdiff