20. Reading and Printing Lisp Objects

• Introduction to Reading and Printing
• Input Streams
• Input Functions
• Output Streams
• Output Functions
• Variables Affecting Output

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 section 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).

^top next
20.1. Introduction to Reading and 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 section 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 inverses. There are three kinds of exceptions:

• Printing can produce text that cannot be read. For example, buffers, windows, frames, subprocesses and markers print as text that starts with `#'; if you try to read this text, you get an error. There is no way to read those data types.
• One object can have multiple textual representations. For example, `1' and `01' represent the same integer, and `(a b)' and `(a . (b))' represent the same list. Reading will accept any of the alternatives, but printing must choose one of them.
• Comments can appear at certain points in the middle of an object's read sequence without affecting the result of reading it.

^{top next prev}
20.2. Input Streams

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:

^topbuffer

The input characters are read from buffer, starting with the character directly after point. Point advances as characters are read.

^topmarker

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.

^topstring

The input characters are taken from string, starting at the first character in the string and using as many characters as required.

^topfunction

The input characters are generated by function, which must support two kinds of calls:

• When it is called with no arguments, it should return the next character.
• When it is called with one argument (always a character), 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 wants to "put it back where it came from". In this case, it makes no difference what value function returns.

^topt

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.

^topnil

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.

^topsymbol

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.

^topFunction: get-file-char

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.

^{top next prev}
20.3. Input Functions

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.

^topFunction: read &optional stream

This function reads one textual Lisp expression from stream, returning it as a Lisp object. This is the basic Lisp input function.

^topFunction: read-from-string string &optional start end

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)

^topVariable: standard-input

This variable holds the default input stream--the stream that read uses when the stream argument is nil.

^{top next prev}
20.4. 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:

^topbuffer

The output characters are inserted into buffer at point. Point advances as characters are inserted.

^topmarker

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.

^topfunction

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.

^topt

The output characters are displayed in the echo area.

^topnil

nil specified as an output stream means to use the value of standard-output instead; that value is the default output stream, and must not be nil.

^topsymbol

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

^{top next prev}
20.5. Output Functions

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 section 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.) If stream is nil or omitted, it defaults to the value of standard-output.

^topFunction: print object &optional stream

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"

^topFunction: prin1 object &optional stream

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"

^topFunction: princ object &optional stream

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\""

^topFunction: terpri &optional stream

This function outputs a newline to stream. The name stands for "terminate print".

^topFunction: write-char character &optional stream

This function outputs character to stream. It returns character.

^topFunction: prin1-to-string object &optional noescape

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 section Conversion of Characters and Strings, for other ways to obtain the printed representation of a Lisp object as a string.

^topMacro: with-output-to-string body...

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

^top prev
20.6. Variables Affecting Output

^topVariable: standard-output

The value of this variable is the default output stream--the stream that print functions use when the stream argument is nil.

^topVariable: print-escape-newlines

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.

^topVariable: print-escape-nonascii

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.

^topVariable: print-escape-multibyte

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.

^topVariable: print-length

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

^topVariable: 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 nil (which is the default) means no limit.