The utilities.print-items Reference Manual

Table of Contents

The utilities.print-items Reference Manual

This is the utilities.print-items Reference Manual, version 0.1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:44:15 2018 GMT+0.

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

* 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

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

  which prevents CLOS' flexibility from actually being used.

  #+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]]

* 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

    #+BEGIN_EXAMPLE
   (KEY VALUE [FORMAT [CONSTRAINT*]]
    #+END_EXAMPLE

    where

    #+BEGIN_EXAMPLE
    KEY        ::= any Lisp object
    VALUE      ::= any Lisp object
    FORMAT     ::= a format string (Default is \"~A\")

    CONSTRAINT ::= (:before | :after) KEY
    #+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 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                                                         :noexport:

#+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc

2 Systems

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

2.1 utilities.print-items

Maintainer

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

Author

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

License

LLGPLv3

Description

A protocol for flexible and composable printing.

Version

0.1.0

Dependencies

• alexandria
• let-plus (at least version 0.2)
• iterate

Source

utilities.print-items.asd (file)

Components

• src (module)
• readme.org (file)

3 Modules

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

3.1 utilities.print-items/src

Parent

utilities.print-items (system)

Location

src/

Components

• package.lisp (file)
• util.lisp (file)
• protocol.lisp (file)

4 Files

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

4.1 Lisp

4.1.1 utilities.print-items.asd

Location

utilities.print-items.asd

Systems

utilities.print-items (system)

4.1.2 utilities.print-items/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

print-items

4.1.3 utilities.print-items/src/util.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/util.lisp

Internal Definitions

• item-< (function)
• sort-with-partial-order (function)

4.1.4 utilities.print-items/src/protocol.lisp

Dependency

util.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions

• format-print-items (function)
• print-items (generic function)
• print-items (method)
• print-items-mixin (class)

4.2 Other

4.2.1 utilities.print-items/README.org

Parent

utilities.print-items (system)

Location

README.org

5 Packages

Packages are listed by definition order.

5.1 print-items

This package contains the utilities.print-items system for composable printing. The interface consists of

* ‘print-items’ [generic function]

Methods extend the printed representation of an object in a composable manner.

* ‘print-items-mixin’ [class]

Can be used to make subclasses the print items mechanism when passed to ‘print-object’.

* ‘format-print-items’ [function]

Utility function for formatting print items onto a stream.

Source

package.lisp (file)

Use List

• iterate
• let-plus
• alexandria.0.dev
• common-lisp

Exported Definitions

• format-print-items (function)
• print-items (generic function)
• print-items (method)
• print-items-mixin (class)

Internal Definitions

• item-< (function)
• sort-with-partial-order (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Functions

Function: format-print-items STREAM ITEMS &optional COLON? AT?

Print ITEMS onto STREAM.

ITEMS is a list of items of the form

(KEY VALUE [FORMAT [CONSTRAINT*]]

where

KEY ::= any Lisp object
VALUE ::= any Lisp object
FORMAT ::= a format string (Default is "~A")

CONSTRAINT ::= (:before | :after) KEY

Package

print-items

Source

protocol.lisp (file)

6.1.2 Generic functions

Generic Function: print-items OBJECT

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

(KEY VALUE [FORMAT [CONSTRAINT*]]

where

KEY ::= any Lisp object
VALUE ::= any Lisp object
FORMAT ::= a format string (Default is "~A")

CONSTRAINT ::= (:before | :after) KEY

When multiple items have ‘eql’ KEYs, 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.

Package

print-items

Source

protocol.lisp (file)

Method Combination

append (short method combination)

Options: :most-specific-first

Methods

Method: print-items OBJECT append

Default behavior is to not return any print items for OBJECT.

6.1.3 Classes

Class: print-items-mixin ()

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

Package

print-items

Source

protocol.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

print-object (method)

6.2 Internal definitions

6.2.1 Functions

Function: item-< G0 G1

Return non-nil if the left item should be placed before the right.

Package

print-items

Source

util.lisp (file)

Function: sort-with-partial-order LIST PREDICATE

Package

print-items

Source

util.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types