1 Introduction

#+TITLE:       utilities.print-items README
#+AUTHOR:      Jan Moringen
#+EMAIL:       jmoringe@techfak.uni-bielefeld.de
#+DESCRIPTION: Composable, unreadable printing of objects
#+KEYWORDS:    print-items, composable printing, print-object, utilities
#+LANGUAGE:    en

#+OPTIONS: num:nil

* Introduction

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

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

  #+BEGIN_SRC lisp
    (defmethod print-object ((object CLASS) stream)
      (print-unreadable-object (stream :type t :id t)
        CODE))
  #+END_SRC

  which prevents the flexibility provided by CLOS from actually being
  used:

  + Calling the next method in a ~print-object~ method would either
    wrap the final result in multiple layers of
    ~print-unreadable-object~ or some of the methods would not be
    fully functional on their own.

  + Similarly, ~:before~ and ~:after~ methods on ~print-object~ would
    produce output parts outside of the prefix and suffix produced by
    ~print-unreadable-object~.

  #+ATTR_HTML: :alt "build status image" :title Build Status :align right
  [[https://travis-ci.org/scymtym/utilities.print-items][https://travis-ci.org/scymtym/utilities.print-items.svg]]

* Tutorial

  To illustrate the problem and the solution offered by the
  =utilities.print-items= system more concretely, consider the
  following example:

  #+BEGIN_SRC lisp :exports both :results silent
    (defclass name-mixin ()
      ((%name :initarg :name :reader name)))

    (defclass value-mixin ()
      ((%value :initarg :value :reader value)))

    (defclass binding (name-mixin value-mixin)
      ())
  #+END_SRC

** The Problem

   Due to the issues mentioned [[*Introduction][above]], ~print-object~-based solutions
   are not satisfactory:

   #+BEGIN_SRC lisp :exports both :results value
     (defmethod print-object ((object name-mixin) stream)
       (format stream "~S" (name object))
       (when (next-method-p)
         (call-next-method)))

     (defmethod print-object ((object value-mixin) stream)
       (format stream "= ~S" (value object))
       (when (next-method-p)
         (call-next-method)))

     (princ-to-string (make-instance 'binding :name "foo" :value 5))
   #+END_SRC

   #+RESULTS:
   : "foo"= 5#

   This is somewhat composable and the output has all expected parts,
   but the arrangement of the output parts is completely wrong as well
   as hard to control.

   #+BEGIN_SRC lisp :exports results :results silent
     (ignore-errors
      (remove-method #'print-object (find-method #'print-object '() (list (find-class 'name-mixin) (find-class 't)))))
     (ignore-errors
      (remove-method #'print-object (find-method #'print-object '() (list (find-class 'value-mixin) (find-class 't)))))
   #+END_SRC

   The opposite approach would be:

   #+BEGIN_SRC lisp :exports both :results value
     (defmethod print-object ((object binding) stream)
       (print-unreadable-object (object stream :type t :identity t)
         (format stream "~S = ~S" (name object) (value object))))

     (princ-to-string (make-instance 'binding :name "foo" :value 5))
   #+END_SRC

   #+RESULTS:
   : #

   This produces the expected result but is not composable at all
   since every user of ~name-mixin~ and ~value-mixin~ has to do all
   the printing itself.

   #+BEGIN_SRC lisp :exports results :results silent
     (ignore-errors
      (remove-method #'print-object (find-method #'print-object '() (list (find-class binding) (find-class 't)))))
   #+END_SRC

** The Solution

   When using the =utilities.print-items= system, ~print-object~
   methods are replaced by ~print-items:print-items~ methods (note the
   ~append~ method combination) for mixin classes:

   #+BEGIN_SRC lisp :exports both :results value
     (defclass name-mixin ()
       ((%name :initarg :name :reader name)))

     (defmethod print-items:print-items append ((object name-mixin))
       `((:name "~S" ,(name object))))

     (defclass value-mixin ()
       ((%value :initarg :value :reader value)))

     (defmethod print-items:print-items append ((object value-mixin))
       `((:value "= ~S" ,(value object))))

     (defclass binding (value-mixin name-mixin)
       ())

     (defmethod print-object ((object binding) stream)
       (print-unreadable-object (object stream :type t :identity t)
         (print-items:format-items
          stream (print-items:effective-print-items object))))

     (princ-to-string (make-instance 'binding :name "foo" :value 5))
   #+END_SRC

   #+RESULTS:
   : #

   #+BEGIN_SRC lisp :exports results :results silent
     (ignore-errors
      (remove-method #'print-object (find-method #'print-object '() (list (find-class binding) (find-class 't)))))
   #+END_SRC

   This solves the problem of composability and getting all output
   parts between the prefix and suffix produced by
   ~print-unreadable-object~, but the arrangement of output parts is
   not ideal. We could improve the situation by tweaking the order of
   elements in the superclass list of ~binding~ but that would be
   intrusive and again not composable when, for example, subclasses of
   ~binding~ are defined. Furthermore, the ~print-object~ method does
   not do anything specific to ~binding~.

   The following adjustments solve both issues (changes in upper
   case):

   #+BEGIN_SRC lisp :exports both :results value
     (defmethod print-items:print-items append ((object value-mixin))
       `(((:value (:AFTER :NAME)) " = ~S" ,(value object))))

     (defclass binding (name-mixin value-mixin PRINT-ITEMS:PRINT-ITEMS-MIXIN)
       ())

     ;; no PRINT-OBJECT method for BINDING

     (princ-to-string (make-instance 'binding :name "foo" :value 5))
   #+END_SRC

   #+RESULTS:
   : #

   Constraints such as ~(:after :name)~ control the order of
   items. Constraints referring to absent items have no
   effect. Contradictory constraints cause an error to be signaled.

** Advanced Usage

*** Adjusting Items

    It is sometimes necessary to modify or suppress the print items
    produced for superclasses to get the desired printed
    representation. This can be achieved in two ways:

    1. By defining a ~print-items:print-items append~ method that
       returns replacements for the undesired items:

       #+BEGIN_SRC lisp :exports both :results value
         (defclass unnamed-binding (binding)
           ())

         (defmethod print-items:print-items append ((object unnamed-binding))
           `((:name "«unnamed»")))

         (princ-to-string (make-instance 'unnamed-binding :name nil :value 5))
       #+END_SRC

       #+RESULTS:
       : #

       #+BEGIN_SRC lisp :exports results :results silent
         (ignore-errors
          (remove-method #'print-items:print-items (find-method #'print-items:print-items '(append) (list (find-class 'unnamed-binding)))))
       #+END_SRC

    2. By defining a ~print-items:print-items :around~ method that
       explicitly modifies the complete item list:

       #+BEGIN_SRC lisp :exports both :results value
         (defclass unnamed-binding (binding)
           ())

         (defmethod print-items:print-items :around ((object unnamed-binding))
           (remove :name (call-next-method) :key #'first))

         (princ-to-string (make-instance 'unnamed-binding :name nil :value 5))
       #+END_SRC

       #+RESULTS:
       : #

       #+BEGIN_SRC lisp :exports results :results silent
         (ignore-errors
          (remove-method #'print-items:print-items (find-method #'print-items:print-items '(:around) (list (find-class 'unnamed-binding)))))
       #+END_SRC

*** Formatting Items

    When it is necessary to take full control of item formatting, the
    functions ~utilities.print-items:format-item~ and
    ~utilities.print-items:format-items~ can be used:

    #+BEGIN_SRC lisp :exports both :results value
      (defclass custom-printing-binding (binding)
        ())

      (defmethod print-object ((object custom-printing-binding) stream)
        (print-unreadable-object (object stream :type t :identity t)
          (let ((items (utilities.print-items:effective-print-items object)))
            (format stream "my name is ~/utilities.print-items:format-item/, ~
                            my value is ~/utilities.print-items:format-item/, ~
                            the normal format would be ~
                            |~/utilities.print-items:format-items/|"
                    (find :name items :key #'utilities.print-items::parse-item)
                    (find :value items :key #'utilities.print-items::parse-item)
                    items))))

      (princ-to-string (make-instance 'custom-printing-binding :name "name" :value 5))
    #+END_SRC

    #+RESULTS:
    : #

* 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

    #+BEGIN_EXAMPLE
      ITEM              ::= (KEY-AND-OPTIONS FORMAT-CONTROL ARGUMENT*)

      KEY-AND-OPTIONS   ::= KEY
                            | (KEY OPTION*)
      KEY               ::= any Lisp object
      OPTION            ::= CONSTRAINT
      CONSTRAINT        ::= ((:before | :after) KEY)

      FORMAT-CONTROL    ::= `nil'
                            | a format control string or a formatter function
      ARGUMENT          ::= any Lisp object
    #+END_EXAMPLE

    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 by subclasses to replace print items produced by
    superclasses.

    When =FORMAT-CONTROL= is =nil=, the whole item is ignored. This
    mechanism can be used by subclasses to disable print items
    produced by superclasses.

  * =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-item STREAM ITEM &optional COLON? AT? [function]=

    This utility function prints a single item in the format
    constructed by the =print-items= function to a stream.

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

    This utility function prints items in the format constructed by
    the =print-items= function to a stream.

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

2 Systems

The main system appears first, followed by any subsystem dependency.

• utilities.print-items

3 Modules

Modules are listed depth-first from the system components tree.

• utilities.print-items/code

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

• Lisp
• Static

5 Packages

Packages are listed by definition order.

• utilities.print-items

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

• Public Interface
• Internals