File: cust-print.el.html
This package provides a general print handler for prin1 and princ that supports print-level and print-circle, and by the way, print-length since the standard routines are being replaced. Also, to print custom types constructed from lists and vectors, use custom-print-list and custom-print-vector. See the documentation strings of these variables for more details.
If the results of your expressions contain circular references to
other parts of the same structure, the standard Emacs print
subroutines may fail to print with an untrappable error,
"Apparently circular structure being printed". If you only use cdr
circular lists (where cdrs of lists point back; what is the right
term here?), you can limit the length of printing with
print-length. But car circular lists and circular vectors generate
the above mentioned error in Emacs version 18. Version
19 supports print-level, but it is often useful to get a better
print representation of circular and shared structures; the print-circle
option may be used to print more concise representations.
There are three main ways to use this package. First, you may replace prin1, princ, and some subroutines that use them by calling install-custom-print so that any use of these functions in Lisp code will be affected; you can later reset with uninstall-custom-print. Second, you may temporarily install these functions with the macro with-custom-print. Third, you could call the custom routines directly, thus only affecting the printing that requires them.
Note that subroutines which call print subroutines directly will not use the custom print functions. In particular, the evaluation functions like eval-region call the print subroutines directly. Therefore, if you evaluate (aref circ-list 0), where circ-list is a circular list rather than an array, aref calls error directly which will jump to the top level instead of printing the circular list.
Uninterned symbols are recognized when print-circle is non-nil, but they are not printed specially here. Use the cl-packages package to print according to print-gensym.
Obviously the right way to implement this custom-print facility is in C or with hooks into the standard printer. Please volunteer since I don't have the time or need. More CL-like printing capabilities could be added in the future.
Implementation design: we want to use the same list and vector processing algorithm for all versions of prin1 and princ, since how the processing is done depends on print-length, print-level, and print-circle. For circle printing, a preprocessing step is required before the final printing. Thanks to Jamie Zawinski for motivation and algorithms.
Defined variables (4)
custom-print-vectors | Non-nil if printing of vectors should obey ‘print-level’ and ‘print-length’. |
custom-printers | An alist for custom printing of any type. |
print-circle | Controls the printing of recursive structures. |
print-level | Controls how many levels deep a nested data object will print. |