The utilities.print-items Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The utilities.print-items Reference Manual

This is the utilities.print-items Reference Manual, version 0.1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:29:29 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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
Source

utilities.print-items.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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


Previous: , Up: Modules   [Contents][Index]

3.1 utilities.print-items/src

Parent

utilities.print-items (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Next: , Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 utilities.print-items.asd

Location

utilities.print-items.asd

Systems

utilities.print-items (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Parent

src (module)

Location

src/package.lisp

Packages

print-items


Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

package.lisp (file)

Parent

src (module)

Location

src/util.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

util.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions

Previous: , Up: Files   [Contents][Index]

4.2 Other


Previous: , Up: Other files   [Contents][Index]

4.2.1 utilities.print-items/README.org

Parent

utilities.print-items (system)

Location

README.org


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

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
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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.


Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   O   U  
Index Entry  Section

F
File, Lisp, utilities.print-items.asd: The utilities<dot>print-items<dot>asd file
File, Lisp, utilities.print-items/src/package.lisp: The utilities<dot>print-items/src/package<dot>lisp file
File, Lisp, utilities.print-items/src/protocol.lisp: The utilities<dot>print-items/src/protocol<dot>lisp file
File, Lisp, utilities.print-items/src/util.lisp: The utilities<dot>print-items/src/util<dot>lisp file
File, other, utilities.print-items/README.org: The utilities<dot>print-items/readme<dot>org file

L
Lisp File, utilities.print-items.asd: The utilities<dot>print-items<dot>asd file
Lisp File, utilities.print-items/src/package.lisp: The utilities<dot>print-items/src/package<dot>lisp file
Lisp File, utilities.print-items/src/protocol.lisp: The utilities<dot>print-items/src/protocol<dot>lisp file
Lisp File, utilities.print-items/src/util.lisp: The utilities<dot>print-items/src/util<dot>lisp file

M
Module, utilities.print-items/src: The utilities<dot>print-items/src module

O
Other File, utilities.print-items/README.org: The utilities<dot>print-items/readme<dot>org file

U
utilities.print-items.asd: The utilities<dot>print-items<dot>asd file
utilities.print-items/README.org: The utilities<dot>print-items/readme<dot>org file
utilities.print-items/src: The utilities<dot>print-items/src module
utilities.print-items/src/package.lisp: The utilities<dot>print-items/src/package<dot>lisp file
utilities.print-items/src/protocol.lisp: The utilities<dot>print-items/src/protocol<dot>lisp file
utilities.print-items/src/util.lisp: The utilities<dot>print-items/src/util<dot>lisp file

Jump to:   F   L   M   O   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   F   G   I   M   P   S  
Index Entry  Section

F
format-print-items: Exported functions
Function, format-print-items: Exported functions
Function, item-<: Internal functions
Function, sort-with-partial-order: Internal functions

G
Generic Function, print-items: Exported generic functions

I
item-<: Internal functions

M
Method, print-items: Exported generic functions

P
print-items: Exported generic functions
print-items: Exported generic functions

S
sort-with-partial-order: Internal functions

Jump to:   F   G   I   M   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   U  
Index Entry  Section

C
Class, print-items-mixin: Exported classes

P
Package, print-items: The print-items package
print-items: The print-items package
print-items-mixin: Exported classes

S
System, utilities.print-items: The utilities<dot>print-items system

U
utilities.print-items: The utilities<dot>print-items system

Jump to:   C   P   S   U