⟦d56eab8e5⟧

TextFile

@setfilename ../info/streams
@node Streams, Minibuffers, Debugging, Top
@comment  node-name,  next,  previous,  up
@chapter Reading and Printing Lisp Objects
@cindex Lisp reader

  @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
objects to textual form and vice versa.  They use the printed
representations and syntax described in @ref{Types of Lisp Object}.

  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::
* Input Streams::	
* Input Functions::
* Output Streams::	
* Output Functions::
@end menu

@node Streams Intro, Input Streams, Streams, Streams
@section Introduction to Reading and Printing

  @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.  For example, reading
the text @samp{(a .@: 5)} returns a cons cell whose @sc{car} is @code{a} and
whose @sc{cdr} is the number 5.

  @dfn{Printing} a Lisp object means producing the text which represents
that object.  Printing that cons cell produces the text @samp{(a .@: 5)}.

  Generally speaking, reading and printing are inverse operations.
Printing the object that results from reading a given piece of text
usually 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 are @code{a} and @code{b}.

  However, these two operations are not precisely inverses.  There are
two kinds of exceptions:

@itemize @bullet
@item
Printing can produce text that cannot be read.  For example, buffers,
windows, 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 evidently printing must choose one of them.
@end itemize

@node Input Streams, Input Functions, Streams Intro, Streams
@section Input Streams

  Most of the Lisp functions for reading text take an @dfn{input stream}
as 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.  Its 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 advancing through as many character as required.

@item @var{function}
@cindex function input stream
The input characters are generated by @var{function}, one per call.

In version 18, @var{function} is always called with no arguments
and should return a character.

@ignore
In version 19, the @var{function} is usually called with no arguments,
and should return a character; but sometimes it is called with one
argument (always a character).  When that happens, @var{function} should
save the argument and return it on the next call.

When @var{function} receives a character as argument, this is called
@dfn{unreading}.  It happens when the Lisp reader reads one character
too many and want to ``put it back where it came from''.
@end ignore

@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 which is then used as the
input stream.

@item @code{nil}
@cindex @code{nil} input stream
@code{nil} used as a stream means that the
value of @code{standard-input} should be used instead; that value must
be a non-@code{nil} input stream.
@end table

@findex read @r{example}
  Here is an example of reading from a stream which is a buffer.
We show where point is before and after.

@example
---------- Buffer: foo ----------
This@point{} is the contents of foo.
---------- Buffer: foo ----------

(read (get-buffer "foo"))
@result{} is
(read (get-buffer "foo"))
@result{} the

---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------
@end example

@noindent
Note that the first read skips a space at the beginning.  Reading always
skips any amount of whitespace preceding the significant text.

Note also how the second read skips the space which terminates the
symbol @code{the}.  It has to read this space in order to know that no
more letters follow.
@ignore
Change this in version 19.
@end ignore

  Here is an example of reading from a stream which is a marker.  The
marker is initialized to point at the beginning of the buffer shown.
The value of the read is the symbol @code{This}.

@example
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------

(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
@result{} #<marker at 1 in foo>
(read m)
@result{} This
m
@result{} #<marker at 6 in foo>   ;; @r{After the first space.}
@end example

  Here we read from the text of a string:

@example
(read "(When in) the course")
@result{} (When in)
@end example

  The following example reads from the minibuffer, prompting with
@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
(read t)
@result{} 23
---------- Buffer: Minibuffer ----------
Lisp expression: @b{23 @key{RET}}
@end example

  Finally, here is an example of a stream which is a function, named
@code{useless-stream}.  The variable @code{useless-list} is initialized to
a list of characters.  Each call to the function @code{useless-stream}
produces the next letter in the list.

@example
(setq useless-list (append "XY()" nil))
@result{} (88 89 40 41)

(defun useless-stream ()
  (prog1 (car useless-list)
         (setq useless-list (cdr useless-list))))
@result{} useless-stream
@end example

  Now we read using this stream.

@example
(read 'useless-stream)
@result{} XY

useless-list
@result{} (41)
@end example

@noindent
Note that only the close-parenthesis remains in the list.  This is because
the open-parenthesis was read before the Lisp reader knew it had found
the end of the symbol.  A second attempt to read from the stream at this
point would get an error due to the unmatched close-parenthesis.

@ignore
  As shown in the above example, when reading a lisp expression, the
reader must sometimes read one character too many so that it can
determine when certain tokens have ended.  In version 19, this extra
character is automatically unread for streams that are buffers, markers,
strings, and minibuffers.  But function streams are called with the
character as argument so that the function may store it for later use.
A function stream will never be called more than once in succession with
a non-@code{nil} argument.

(show correction for useless-stream!!)
@end ignore

@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

@node Input Functions, Output Streams, Input Streams, Streams
@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 for a description of input streams.  If
@var{stream} is @code{nil} or omitted, it defaults to the value of
@code{standard-input}.

@defvar standard-input
This global variable is the stream that @code{read} reads from
when the @var{stream} argument is @code{nil}.
@end defvar

@defun read &optional stream
This function reads one 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 Lisp-expression from the text in
@var{string}.  It then returns a cons cell whose @sc{car} is that expression
and and whose @sc{cdr} is an integer, giving the position of the next
character in the string (the first one not read).

If @var{start} is supplied, then reading begins at that index in the
string (where the first character is at index 0).  If @var{end} is also
supplied, then reading ends at that index, as if the rest of the string
were not there.

@cindex end-of-file error
An @code{end-of-file} error will result if an unterminated list or vector
is found.

@example
(read-from-string "(setq x 55) (setq y 5)")
@result{} ((setq x 55) . 11)
(read-from-string "\"A short string\"")
("A short string" . 16)

;; @r{Read starting at the first character.}
(read-from-string "(list 112)" 0)
((list 112) . 10)
;; @r{Read starting at the second character.}
(read-from-string "(list 112)" 1)
(list . 6)
;; @r{Read starting at the seventh character, and ending at the ninth.}
(read-from-string "(list 112)" 6 8)
(11 . 8)
@end example
@end defun

@node Output Streams, Output Functions, Input Functions, Streams
@section Output Streams

  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 the 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} is
in at the marker position.  The position advances as characters are
inserted.  The value of point in the buffer has no effect when the
stream is a marker.

@item @var{function}
@cindex function output stream
@var{function} is called with one output character as the argument.  It is
called as many times as there are characters to be output.  The function
is free to do anything at all with the characters.

@item @code{t}
@cindex @code{t} output stream
@code{t} as an output stream means that the output characters should be
printed in the echo area.

@item @code{nil}
@cindex @code{nil} output stream
@code{nil} specified as an output stream means that the value of
@code{standard-output} should be used as the output stream; that value
must be a non-@code{nil} output stream.
@end table

  Here is an example of a buffer as output stream.
At the end, the point is located directly before that same @kbd{h}.

@cindex print example
@example
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
---------- Buffer: foo ----------

(print "This is the output" (get-buffer "foo"))
@result{} "This is the output"

---------- Buffer: foo ----------
This is t
"This is the output"
@point{}he contents of foo.
---------- Buffer: foo ----------
@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}.

@example
---------- Buffer: foo ----------
"This is t@point{}he output"
---------- Buffer: foo ----------

m
@result{} #<marker at 11 in foo>

(print "More output for foo." marker)
@result{} "More output for foo."

---------- Buffer: foo ----------
"This is t
"More output for foo."
@point{}he output"
---------- Buffer: foo ----------

m
@result{} #<marker at 35 in foo>
@end example

  This example shows output to the echo area.

@example
(print "Echo Area output" t)
@result{} "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
@end example

  Finally, we show an output stream which is a function.  The function
@code{eat-output} takes each character that it is given and conses it
onto the front of the list @code{last-output}.  At the end, the list
contains all the characters output, but in reverse order.

@example
(setq last-output nil)
@result{} nil

(defun eat-output (c)
  (setq last-output (cons c last-output)))
@result{} eat-output

(print "This is the output" 'eat-output)
@result{} "This is the output"

last-output
@result{} (10 34 116 117 112 116 117 111 32 101 104 116 32 115 105
    32 115 105 104 84 34 10)
@end example

@noindent
Now we can put the output in the proper order by reversing the list:

@example
(concat (nreverse last-output))
@result{} "
\"This is the output\"
"
@end example

@node Output Functions, , Output Streams, Streams
@subsection Output Functions

  This section describes the Lisp functions and variables that pertain
to printing.

@cindex @samp{"} in print
@cindex @samp{\} in print
@cindex quoting characters
@cindex escape characters
  There are actually two different ways of printing a Lisp object,
depending on the purpose of printing: with or without quoting
characters.  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.  (The quoting characters
used are @samp{\} and @samp{"}.)  @xref{Print Representation and Read
Syntax}, for the details of how quoting characters are used.

  However, if the purpose of the output is to look nice for humans, then
it is better print without quoting.

  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}.

@defvar standard-output
The value of this variable is default output stream, used when the
@var{stream} argument is omitted.
@end defvar

@defun print object &optional stream
@cindex Lisp printer
This function is the most convenient and simple interface to printing.
It outputs the printed representation of @var{object} to @var{stream}.
It also prints one newline before @var{object} and another after it.  It
returns @var{object}.

The output of @code{print} includes any escape and quoting characters
(@samp{\} and @samp{"}) required to allow the object to be read back in.

@example
(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 example
@end defun

@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}.

@example
(progn (prin1 'The\ cat\ in) 
       (prin1 "the hat") 
       (prin1 " came back"))
@print{} The\ cat\ in"the hat"" came back"
@result{} " came back"
@end example
@end defun

@defun prin1-to-string object
@cindex object to string
This function returns a string which is what the function @code{prin1}
would have printed.  See @code{format}, in @ref{Conversion of Characters and Strings}, for other ways to convert objects to string representation.

@example
(prin1-to-string 'foo)
@result{} "foo"
(prin1-to-string (mark-marker))
@result{} "#<marker at 2773 in strings.texinfo>"
@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 @code{read}, so no quoting characters are used, and double quotes are not
printed around the contents of strings.  It does not add any spacing between
calls.

@example
(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
@print{} The cat in the "hat"
@result{} " in the \"hat\""
@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

@defvar print-escape-newlines
@cindex @samp{\n} in print
@cindex escape characters
Non-@code{nil} means print newlines in strings as @samp{\n}.
Normally they are printed as actual newlines.

This variable affects all the print functions.  Here is an example
using @code{princ}:

@example
(princ "a\nb")
@print{} a
@print{} b
@result{} "a
@result{} b"

(let ((print-escape-newlines t))
  (princ "a\nb"))
@print{} a\nb
@result{} "a
@result{} b"
@end example

@noindent
In the second expression, the local binding of
@code{print-escape-newlines} is in effect during the call to
@code{princ} but not during the printing of the result.
@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 the list being printed is longer than this,
then it is abbreviated with an ellipsis.

If the value is @code{nil} (the default), then there is no limit.

@example
(setq print-length 2)
@result{} 2
(print '(1 2 3 4 5))
@result{} (1 2 ...)
@result{} (1 2 ...)
@end example
@end defvar

@defun write-char character &optional stream
This function outputs @var{character} to @var{stream}.  It returns
@var{character}.
@end defun
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦d56eab8e5⟧ TextFile

Derivation

TextFile
