utilities.print-items

2016-09-29

STARTED Introduction

The utilities.print-items system provides a protocol for flexible and composable printing, primarily unreadable printing.

Why is this needed/useful? Common Lisp has the generic function cl:print-object, which is often used to print compact and useful, yet unreadable representations of objects. Thanks to CLOS, considerable flexibility and composability would, in principle, be achievable. However, a common idiom is

  (defmethod print-object ((object CLASS) stream)
    (print-unreadable-object (stream :type t :id t)
      CODE))

which prevents CLOS' flexibility from actually being used.

TODO Tutorial

STARTED Reference

The utilities.print-items system provides the following protocol for composable printing:

  • print-items:print-items OBJECT [generic function]

    Return a list of items that should appear in the printed representation of OBJECT.

    Each method should return a list of items of the form

    #+BEGINEXAMPLE (KEY VALUE [FORMAT [CONSTRAINT*]]

    #+ENDEXAMPLE

    where

    KEY        ::= any Lisp object
    VALUE      ::= any Lisp object
    FORMAT     ::= a format string (Default is \"~A\")
    
    CONSTRAINT ::= (:before | :after) KEY
    

    When multiple items have cl:eql KEY s, items appearing closer to the beginning of the item list take precedence. This mechanism can be used to replace print items produced by superclasses in subclasses.

  • print-items:print-items-mixin [class]

    This mixin class adds printing via print-items to classes.

    Subclasses can define methods on print-items:print-items to change or extend the printed representation.

  • print-items:format-print-items STREAM ITEMS &optional COLON? AT? [function]

    This utility function prints items in the format constructed by the print-items functions to a streams.

    It is used to implement the cl:print-object method for print-items-mixin.

Settings

Author
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
Maintainer
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
License
LLGPLv3