[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Printing and 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{Types of Lisp Object}.
This chapter describes the Lisp functions for reading and printing. It also describes streams, which specify where to get the text (if reading) or where to put it (if printing).
1.1 Introduction to Reading and Printing | Overview of streams, reading and printing. | |
1.2 Input Streams | Various data types that can be used as input streams. | |
1.3 Input Functions | Functions to read Lisp objects from text. | |
1.4 Output Streams | Various data types that can be used as output streams. | |
1.5 Output Functions | Functions to print Lisp objects as text. | |
1.6 Variables Affecting Output | Variables that control what the printing functions do. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
read syntax of the object. For example, reading the text ‘(a
. 5)’ returns a cons cell whose CAR is a
and whose
CDR is the number 5.
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 ‘(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 foo
produces the text ‘foo’, and reading that text
returns the symbol foo
. Printing a list whose elements are
a
and b
produces the text ‘(a b)’, and reading that
text produces a list (but not the same list) with elements are a
and b
.
However, these two operations are not precisely inverses. There are two kinds of exceptions:
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most of the Lisp functions for reading text take an 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:
The input characters are read from buffer, starting with the character directly after point. Point advances as characters are read.
The input characters are read from the buffer that 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.
The input characters are taken from string, starting at the first character in the string and using as many characters as required.
The input characters are generated by function, one character per call. Normally function is called with no arguments, and should return a character.
Occasionally function is called with one argument (always a character). When that happens, function should save the argument and arrange to return it on the next call. This is called unreading the character; it happens when the Lisp reader reads one character too many and want to “put it back where it came from”.
t
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.
nil
nil
used as a stream means that the value of
standard-input
should be used instead; that value is the
default input stream, and must be a non-nil
input stream.
A symbol as output stream is equivalent to the symbol’s function definition (if any).
Here is an example of reading from a stream which is a buffer, showing where point is located before and after:
---------- Buffer: foo ---------- This∗ is the contents of foo. ---------- Buffer: foo ----------
(read (get-buffer "foo")) ⇒ is
(read (get-buffer "foo")) ⇒ the
---------- Buffer: foo ---------- This is the∗ contents of foo. ---------- Buffer: foo ----------
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 ‘contents’ rather than after ‘the’. The Emacs 19 behavior is superior because it correctly handles input such as ‘bar(foo)’ where the delimiter 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,
initialized to point at the beginning of the buffer shown. The value
read is the symbol This
.
---------- Buffer: foo ---------- This is the contents of foo. ---------- Buffer: foo ----------
(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) ⇒ #<marker at 1 in foo>
(read m) ⇒ This
m
⇒ #<marker at 6 in foo> ;; After the first space.
Here we read from the contents of a string:
(read "(When in) the course") ⇒ (When in)
The following example reads from the minibuffer. The
prompt is: ‘Lisp expression: ’. (That is always the prompt
used when you read from the stream t
.) The user’s input is shown
following the prompt.
(read t) ⇒ 23 ---------- Buffer: Minibuffer ---------- Lisp expression: 23 <RET> ---------- Buffer: Minibuffer ----------
Finally, here is an example of a stream that is a function, named
useless-stream
. Before we use the stream, we initialize the
variable useless-list
to a list of characters. Then each call to
the function useless-stream
obtains the next characters in the list
or unreads a character by adding it to the front of the list.
(setq useless-list (append "XY()" nil)) ⇒ (88 89 40 41)
(defun useless-stream (&optional unread) (if unread (setq useless-list (cons unread useless-list)) (prog1 (car useless-list) (setq useless-list (cdr useless-list))))) ⇒ useless-stream
Now we read using the stream thus constructed:
(read 'useless-stream) ⇒ XY
useless-list ⇒ (41)
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.
This function is used internally as an input stream to read from the
input file opened by the function load
. Don’t use this function
yourself.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the Lisp functions and variables that pertain to reading.
In the functions below, stream stands for an input stream (see
the previous section). If stream is nil
or omitted, it
defaults to the value of standard-input
.
An end-of-file
error results if an unterminated list or
vector is found.
This function reads one textual Lisp expression from stream, returning it as a Lisp object. This is the basic Lisp input function.
This function reads the first textual Lisp expression from the text in string. It returns a cons cell whose CAR is that expression, and whose CDR is an integer giving the position of the next remaining character in the string (i.e., the first one not read).
If start is supplied, then reading begins at index start in the string (where the first character is at index 0). If end is also supplied, then reading stops at that index as if the rest of the string were not there.
For example:
(read-from-string "(setq x 55) (setq y 5)") ⇒ ((setq x 55) . 11)
(read-from-string "\"A short string\"") ⇒ ("A short string" . 16)
;; Read starting at the first character.
(read-from-string "(list 112)" 0)
⇒ ((list 112) . 10)
;; Read starting at the second character.
(read-from-string "(list 112)" 1)
⇒ (list . 6)
;; Read starting at the seventh character, ;; and stopping at the ninth. (read-from-string "(list 112)" 6 8) ⇒ (11 . 8)
This variable holds the default input stream: the stream that
read
uses when the stream argument is nil
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
The output characters are inserted into buffer at point. Point advances as characters are inserted.
The output characters are inserted into the buffer that 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.
The output characters are passed to 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.
t
The output characters are displayed in the echo area.
nil
nil
specified as an output stream means that the value of
standard-output
should be used as the output stream; that value
is the default output stream, and must be a non-nil
output
stream.
A symbol as output stream is equivalent to the symbol’s function definition (if any).
Here is an example of a buffer used as an output stream. Point is initially located as shown immediately before the ‘h’ in ‘the’. At the end, point is located directly before that same ‘h’.
---------- Buffer: foo ---------- This is t∗he contents of foo. ---------- Buffer: foo ----------
(print "This is the output" (get-buffer "foo")) ⇒ "This is the output"
---------- Buffer: foo ---------- This is t "This is the output" ∗he contents of foo. ---------- Buffer: foo ----------
Now we show a use of a marker as an output stream. Initially, the
marker points in buffer foo
, between the ‘t’ and the
‘h’ in the word ‘the’. At the end, the marker has been
advanced over the inserted text so that it still points before the same
‘h’. Note that the location of point, shown in the usual fashion,
has no effect.
---------- Buffer: foo ---------- "This is the ∗output" ---------- Buffer: foo ----------
m ⇒ #<marker at 11 in foo>
(print "More output for foo." m) ⇒ "More output for foo."
---------- Buffer: foo ---------- "This is t "More output for foo." he ∗output" ---------- Buffer: foo ----------
m ⇒ #<marker at 35 in foo>
The following example shows output to the echo area:
(print "Echo Area output" t) ⇒ "Echo Area output" ---------- Echo Area ---------- "Echo Area output" ---------- Echo Area ----------
Finally, we show an output stream which is a function. The function
eat-output
takes each character that it is given and conses it
onto the front of the list last-output
(@pxref{Building Lists}).
At the end, the list contains all the characters output, but in reverse
order.
(setq last-output nil) ⇒ nil
(defun eat-output (c) (setq last-output (cons c last-output))) ⇒ eat-output
(print "This is the output" 'eat-output) ⇒ "This is the output"
last-output ⇒ (10 34 116 117 112 116 117 111 32 101 104 116 32 115 105 32 115 105 104 84 34 10)
Now we can put the output in the proper order by reversing the list:
(concat (nreverse last-output)) ⇒ " \"This is the output\" "
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the Lisp functions for printing Lisp objects.
Some of the Emacs printing functions add quoting characters to the output when necessary so that it can be read properly. The quoting characters used are ‘\’ and ‘"’; they are used to distinguish strings from symbols, and to 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 ‘#level’ instead of recursively printing an object already being printed. For example, here ‘#0’ indicates a recursive reference to the object at level 0 of the current print operation:
(setq foo (list nil)) ⇒ (nil) (setcar foo foo) ⇒ (#0)
In the functions below, stream stands for an output stream.
(See the previous section for a description of output streams.) If
stream is nil
or omitted, it defaults to the value of
standard-output
.
The print
is a convenient way of printing. It outputs the
printed representation of object to stream, printing in
addition one newline before object and another after it. Quoting
characters are used. print
returns object. For example:
(progn (print 'The\ cat\ in) (print "the hat") (print " came back")) -| -| The\ cat\ in -| -| "the hat" -| -| " came back" -| ⇒ " came back"
This function outputs the printed representation of object to
stream. It does not print any spaces or newlines to separate
output as print
does, but it does use quoting characters just
like print
. It returns object.
(progn (prin1 'The\ cat\ in) (prin1 "the hat") (prin1 " came back")) -| The\ cat\ in"the hat"" came back" ⇒ " came back"
This function outputs the printed representation of object to stream. It returns object.
This function is intended to produce output that is readable by people,
not by read
, so quoting characters are not used and double-quotes
are not printed around the contents of strings. It does not add any
spacing between calls.
(progn (princ 'The\ cat) (princ " in the \"hat\"")) -| The cat in the "hat" ⇒ " in the \"hat\""
This function outputs a newline to stream. The name stands for “terminate print”.
This function outputs character to stream. It returns character.
This function returns a string containing the text that prin1
would have printed for the same argument.
(prin1-to-string 'foo) ⇒ "foo"
(prin1-to-string (mark-marker)) ⇒ "#<marker at 2773 in strings.texi>"
If noescape is non-nil
, that inhibits use of quoting
characters in the output. (This argument is supported in Emacs versions
19 and later.)
(prin1-to-string "foo") ⇒ "\"foo\""
(prin1-to-string "foo" t) ⇒ "foo"
See format
, in @ref{String Conversion}, for other ways to obtain
the printed representation of a Lisp object as a string.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The value of this variable is the default output stream, used when the
stream argument is omitted or nil
.
If this variable is non-nil
, then newline characters in strings
are printed as ‘\n’. Normally they are printed as actual newlines.
This variable affects the print functions prin1
and print
,
as well as everything that uses them. It does not affect princ
.
Here is an example using prin1
:
(prin1 "a\nb") -| "a -| b" ⇒ "a ⇒ b"
(let ((print-escape-newlines t)) (prin1 "a\nb")) -| "a\nb" ⇒ "a ⇒ b"
In the second expression, the local binding of
print-escape-newlines
is in effect during the call to
prin1
, but not during the printing of the result.
The value of this variable is the maximum number of elements of a list that will be printed. If the list being printed has more than this many elements, then it is abbreviated with an ellipsis.
If the value is nil
(the default), then there is no limit.
(setq print-length 2) ⇒ 2
(print '(1 2 3 4 5)) -| (1 2 ...) ⇒ (1 2 ...)
The value of this variable is the maximum depth of nesting of
parentheses that will be printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
nil
(which is the default) means no limit.
This variable exists in version 19 and later versions.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on January 16, 2023 using texi2html 5.0.