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 Lisp Data Types.
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).
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, the text ‘(a . 5)’
is the read syntax for 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 (see Printed Representation and Read Syntax). 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 a
and b.
However, these two operations are not precisely inverse to each other. There are three kinds of exceptions:
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, which must support two kinds of calls:
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. If Emacs is running in batch mode (see Batch Mode),
standard input is used instead of the minibuffer. For example,
(message "%s" (read t))
will in batch mode read a Lisp expression from standard input and print the result to standard output.
nil ¶nil supplied as an input stream means to use the value of
standard-input instead; that value is the default input
stream, and must be a non-nil input stream.
A symbol as input stream is equivalent to the symbol’s function definition (if any).
Here is an example of reading from a stream that 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. Reading skips any amount of whitespace preceding the significant text.
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 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 5 in foo> ;; Before 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 character 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
⇒ (40 41)
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 ‘()’ and return nil.
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 is signaled if reading encounters an
unterminated list, vector, or string.
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 you specify end, then reading is forced to stop just before 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 . 5)
;; Read starting at the seventh character, ;; and stopping at the ninth. (read-from-string "(list 112)" 6 8) ⇒ (11 . 8)
This function reads one textual expression from stream, like
read does, but additionally positions the read symbols to the
positions in stream where they occurred. Only the symbol
nil is not positioned, this for efficiency reasons.
See Symbols with Position. This function is used by the byte
compiler.
This variable holds the default input stream—the stream that
read uses when the stream argument is nil.
The default is t, meaning use the minibuffer.
If non-nil, this variable enables the reading of circular and
shared structures. See Read Syntax for Circular Objects. Its default value is
t.
When reading or writing from the standard input/output streams of the Emacs process in batch mode, it is sometimes required to make sure any arbitrary binary data will be read/written verbatim, and/or that no translation of newlines to or from CR-LF pairs is performed. This issue does not exist on POSIX hosts, only on MS-Windows and MS-DOS. The following function allows you to control the I/O mode of any standard stream of the Emacs process.
Switch stream into binary or text I/O mode. If mode is
non-nil, switch to binary mode, otherwise switch to text mode.
The value of stream can be one of stdin, stdout,
or stderr. This function flushes any pending output data of
stream as a side effect, and returns the previous value of I/O
mode for stream. On POSIX hosts, it always returns a
non-nil value and does nothing except flushing pending output.
This predicate says whether object has readable syntax,
i.e., it can be written out and then read back by the Emacs Lisp
reader. If it can’t, this function returns nil; if it can,
this function returns a printed representation (via prin1,
see Output Functions) of object.
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 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, 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).
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 responsible for storing the characters wherever you want to put them.
t ¶The output characters are displayed in the echo area. If Emacs is running in batch mode (see Batch Mode), the output is written to the standard output descriptor instead.
nil ¶nil specified as an output stream means to use the value of the
standard-output variable instead; that value is the
default output stream, and must not be nil.
A symbol as output stream is equivalent to the symbol’s function definition (if any).
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 ‘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 is in buffer foo, between the ‘t’ and the ‘h’ in
the word ‘the’. At the end, the marker has advanced over the
inserted text so that it remains positioned 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 ----------
(setq m (copy-marker 10))
⇒ #<marker at 10 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 34 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 the use of a function as an output stream. The
function eat-output takes each character that it is given and
conses it onto the front of the list last-output (see Building Cons Cells and 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\"
"
Calling concat converts the list to a string so you can see its
contents more clearly.
This function can be useful as an output stream when debugging. It writes character to the standard error stream.
For example
(print "This is the output" #'external-debugging-output) ⊣ This is the output ⇒ "This is the output"
This section describes the Lisp functions for printing Lisp objects—converting objects into their printed representation.
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 distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. See Printed Representation and Read Syntax, 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 ‘#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. Also
See external-debugging-output, a useful stream value for debugging.)
If stream is nil or omitted, it defaults to the value of
standard-output.
The print function 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 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"
If overrides is non-nil, it should either be t
(which tells prin1 to use the defaults for all printer related
variables), or a list of settings. See Overriding Output Variables, for details.
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 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.
(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”. If ensure is non-nil no newline is printed
if stream is already at the beginning of a line. Note in this
case stream can not be a function and an error is signaled if
it is. This function returns t if a newline is printed.
This function outputs character to stream. It returns character.
If you have Emacs-based batch scripts that send output to the
terminal, Emacs will automatically display the output whenever you
write a newline characters to standard-output. This function
allows you to flush to standard-output without sending a
newline character first, which enables you to display incomplete
lines.
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 overrides is non-nil, it should either be t
(which tells prin1 to use the defaults for all printer related
variables), or a list of settings. See Overriding Output Variables, for details.
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 Formatting Strings, for other ways to obtain
the printed representation of a Lisp object as a string.
This macro executes the body forms with standard-output set
up to feed output into a string. Then it returns that string.
For example, if the current buffer name is ‘foo’,
(with-output-to-string (princ "The buffer is ") (princ (buffer-name)))
returns "The buffer is foo".
This function outputs object to stream, just like
prin1, but does it in a prettier way. That is, it’ll
indent and fill the object to make it more readable for humans.
If you need to use binary I/O in batch mode, e.g., use the functions described in this section to write out arbitrary binary data or avoid conversion of newlines on non-POSIX hosts, see set-binary-mode.
The value of this variable is the default output stream—the stream
that print functions use when the stream argument is nil.
The default is t, meaning display in the echo area.
If this is non-nil, that means to print quoted forms using
abbreviated reader syntax, e.g., (quote foo) prints as
'foo, and (function foo) as #'foo. The default
is t.
If this variable is non-nil, then newline characters in strings
are printed as ‘\n’ and formfeeds are printed as ‘\f’.
Normally these characters are printed as actual newlines and formfeeds.
This variable affects the print functions prin1 and print
that print with quoting. 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.
If this variable is non-nil, control characters in strings are
printed as backslash sequences by the print functions prin1 and
print that print with quoting. If this variable and
print-escape-newlines are both non-nil, the latter takes
precedences for newlines and formfeeds.
If this variable is non-nil, then unibyte non-ASCII
characters in strings are unconditionally printed as backslash sequences
by the print functions prin1 and print that print with
quoting.
Those functions also use backslash sequences for unibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a multibyte buffer or a marker pointing into one.
If this variable is non-nil, then multibyte non-ASCII
characters in strings are unconditionally printed as backslash sequences
by the print functions prin1 and print that print with
quoting.
Those functions also use backslash sequences for multibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a unibyte buffer or a marker pointing into one.
This variable controls printing of ‘charset’ text property on printing
a string. The value should be nil, t, or
default.
If the value is nil, charset text properties are never
printed. If t, they are always printed.
If the value is default, only print charset text
properties if there is an “unexpected” charset property. For
ascii characters, all charsets are considered “expected”.
Otherwise, the expected charset property of a character is
given by char-charset.
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 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 and brackets when 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.
These are the values for print-length and print-level
used by eval-expression, and thus, indirectly, by many
interactive evaluation commands (see Evaluating
Emacs Lisp Expressions in The GNU Emacs Manual).
These variables are used for detecting and reporting circular and shared structure:
If non-nil, this variable enables detection of circular and
shared structure in printing. See Read Syntax for Circular Objects.
By default, Emacs prints unreadable objects as ‘#<...>"’. For instance:
(prin1-to-string (make-marker))
⇒ "#<marker in no buffer>"
If this variable is non-nil, it should be a function that will
be called to handle printing of these objects. The function will be
called with two arguments: the object and the noescape flag used by
the printing functions (see Output Functions).
The function should return either nil (print the object as
usual), or a string (which will be printed), or any other object
(don’t print the object). For instance:
(let ((print-unreadable-function
(lambda (object escape) "hello")))
(prin1-to-string (make-marker)))
⇒ "hello"
If non-nil, this variable enables detection of uninterned symbols
(see Creating and Interning Symbols) in printing. When this is enabled,
uninterned symbols print with the prefix ‘#:’, which tells the Lisp
reader to produce an uninterned symbol.
If non-nil, that means number continuously across print calls.
This affects the numbers printed for ‘#n=’ labels and
‘#m#’ references.
Don’t set this variable with setq; you should only bind it
temporarily to t with let. When you do that, you should
also bind print-number-table to nil.
This variable holds a vector used internally by printing to implement
the print-circle feature. You should not use it except
to bind it to nil when you bind print-continuous-numbering.
This variable specifies how to print floating-point numbers. The
default is 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 ‘%’-specification to be used
in the C function sprintf. For further restrictions on what
you can use, see the variable’s documentation string.
When this variable is non-nil, integers that represent
graphic base characters will be printed using Lisp character syntax
(see Basic Char Syntax). Other numbers are printed the usual way.
For example, the list (4 65 -1 10) would be printed as
‘(4 ?A -1 ?\n)’.
More precisely, values printed in character syntax are those representing characters belonging to the Unicode general categories Letter, Number, Punctuation, Symbol and Private-use (see Character Properties), as well as the control characters having their own escape syntax such as newline.
This user variable specifies the function used by pp to prettify
its output. By default it uses pp-fill which attempts to
strike a good balance between speed and generating natural looking output
that fits within fill-column. The previous default was
pp-28, which tends to be faster but generate output that looks
less natural and is less compact.
The previous section (see Variables Affecting Output) lists the numerous
variables that control how the Emacs Lisp printer formats data for
outputs. These are generally available for users to change, but
sometimes you want to output data in the default format, or override
the user settings in some other way. For instance, if you’re storing
Emacs Lisp data in a file, you don’t want that data to be shortened by
a print-length setting.
The prin1 and prin1-to-string functions therefore have
an optional overrides argument. This argument can either be
t (which means that all printing variables should be reset to
the default values), or a list of settings for some of the variables.
Each element in the list can be either t (which means “reset
to defaults”, and will usually be the first element of the list), or
a pair whose car is a symbol that stands for an output variable
and whose cdr is the value for that variable.
For instance, this prints using nothing but defaults:
(prin1 object nil t)
This prints object using the current printing settings, but
overrides the value of print-length to be 5:
(prin1 object nil '((length . 5)))
And finally, this prints object using only default settings, but
with print-length bound to 5:
(prin1 object nil '(t (length . 5)))
Below is a list of symbols that can be used, and which variables they map to:
lengthThis overrides print-length.
levelThis overrides print-level.
circleThis overrides print-circle.
quotedThis overrides print-quoted.
escape-newlinesThis overrides print-escape-newlines.
escape-control-charactersThis overrides print-escape-control-characters.
escape-nonasciiThis overrides print-escape-nonascii.
escape-multibyteThis overrides print-escape-multibyte.
charset-text-propertyThis overrides print-charset-text-property.
unreadable-functionThis overrides print-unreadable-function.
gensymThis overrides print-gensym.
continuous-numberingThis overrides print-continuous-numbering.
number-tableThis overrides print-number-table.
float-formatThis overrides float-output-format.
integers-as-charactersThis overrides print-integers-as-characters.
symbols-bareThis overrides print-symbols-bare.
In the future, more overrides may be offered that do not map directly to a variable, but can only be used via this parameter.