2 Printing

This chapter describes some enhancements to Emacs Lisp’s printing, the action of representing Lisp objects in text form. The functions documented here are intended to produce output more for human readers than the standard printing functions such as prin1 and princ (see Output Functions in GNU Emacs Lisp Reference Manual).

Several of these functions have a parameter stream; this specifies what to do with the characters printing produces. For example, it might be a buffer, a marker, nil (meaning use standard output), or t (use the echo area). See Output Streams in GNU Emacs Lisp Reference Manual, for a full description.

Variable: cl-print-readably ¶

When this variable is non-nil, cl-prin1 and other functions described here try to produce output which can later be read by the Lisp reader (see Input Functions in GNU Emacs Lisp Reference Manual).

Variable: cl-print-compiled ¶

This variable controls how to print byte-compiled functions. Valid values are:

nil

The default: Just an internal hex identifier is printed.

static

The internal hex identifier together with the function’s constant vector are printed.

disassemble

The byte code gets disassembled.

raw

The raw form of the function is printed by prin1.

Sometimes, a button is set on the output to allow you to disassemble the function. See cl-print-compile-button.

Variable: cl-print-compile-button ¶

When this variable is non-nil and a byte-compiled function has been printed to a buffer, you can click with the mouse or type RET on that output to disassemble the code. This doesn’t apply when cl-print-compiled is set to disassemble.

Variable: cl-print-string-length ¶

The maximum length of a string to print before abbreviating it. A value of nil, the default, means no limit.

When the CL printing functions abbreviate a string, they print the first cl-print-string-length characters of the string, followed by “...”. When the printing is to a buffer, you can click with the mouse or type RET on this ellipsis to expand the string.

This variable has effect only in the cl-prin* functions, not in primitives such as prin1.

Function: cl-prin1 object &option stream ¶

cl-print1 prints object on stream (see above) according to its type and the settings described above. The variables print-length and print-level and the other standard Emacs settings also affect the printing (see Output Variables in GNU Emacs Lisp Reference Manual).

Function: cl-prin1-to-string object ¶

This function is like cl-prin1, except the output characters are returned as a string from this function rather than being passed to a stream.

Function: cl-print-to-string-with-limit print-function value limit ¶

This function returns a string containing a printed representation of value. It attempts to get the length of the returned string under limit characters with successively more restrictive settings of print-level, print-length, and cl-print-string-length. It uses print-function to print, a function which should take the arguments value and a stream (see above), and which should respect print-length, print-level, and cl-print-string-length. limit may be nil or zero, in which case print-function will be called with these settings bound to nil; it can also be t, in which case print-function will be called with their current values.

Use this function with cl-prin1 to print an object, possibly abbreviating it with one or more ellipses to fit within the size limit.

Function: cl-print-object object stream ¶

This function prints object on stream (see above). It is actually a cl-defgeneric (see Generic Functions in GNU Emacs Lisp Reference Manual), which is defined for several types of object. Normally, you just call cl-prin1 to print an object rather than calling this function directly.

You can write cl-print-object cl-defmethods for other types of object, thus extending cl-prin1. If such a method uses ellipses, you should also write a cl-print-object-contents method for the same type. For examples of these methods, see emacs-lisp/cl-print.el in the Emacs source directory.

Function: cl-print-object-contents object start stream ¶

This function replaces an ellipsis in stream beginning at start with the text from the partially printed object it represents. It is also a cl-defgeneric defined for several types of object. stream is a buffer containing the text with the ellipsis. start specifies the starting position of the ellipsis in a manner dependent on the type; it will have been obtained from a text property on the ellipsis, having been put there by cl-print-insert-ellipsis.

Function: cl-print-insert-ellipsis object start stream ¶

This function prints an ellipsis (“…”) to stream (see above). When stream is a buffer, the ellipsis will be given the cl-print-ellipsis text property. The value of the text property will contain state (including start) in order to print the elided part of object later. start should be nil if the whole object is being elided, otherwise it should be an index or other pointer into the internals of object which can be passed to cl-print-object-contents at a later time.

Variable: cl-print-expand-ellipsis-function ¶

This variable holds a function which expands an ellipsis in the current buffer. The function takes four arguments: begin and end, which are the bounds of the ellipsis; value, which is the value of the cl-print-ellipsis text property on the ellipsis (typically set earlier by cl-prin1); and line-length, the desired maximum length of the output. Its return value is the buffer position after the expanded text.

Command: cl-print-expand-ellipsis &optional button ¶

This command expands the ellipsis at point. Non-interactively, if button is non-nil, it should be either a buffer position or a button made by cl-print-insert-ellipsis (see Buttons in GNU Emacs Lisp Reference Manual), which indicates the position of the ellipsis. The return value is the buffer position after the expanded text.