The utilities.print-tree Reference Manual

Table of Contents

The utilities.print-tree Reference Manual

This is the utilities.print-tree Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 12:33:54 2020 GMT+0.

1 Introduction

#+TITLE:       utilities.print-tree README
#+AUTHOR:      Jan Moringen
#+EMAIL:       jmoringe@techfak.uni-bielefeld.de
#+DESCRIPTION: A simple system for pretty-printing tree structures
#+KEYWORDS:    common lisp, tree, printing, pretty-printing
#+LANGUAGE:    en

* Introduction
  The =utilities.print-tree= system provides simple facilities for
  printing tree structures in an easy to read way using either ASCII
  or Unicode characters to render the parent-child relations. One
  focus is playing nicely with pretty printing.

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

  The following example shows the result of printing the
  =utilities.print-tree= ASDF system without and with additional
  details added to nodes:
  #+begin_example
  utilities.print-tree
  ├─src
  │ ├─package
  │ └─print-tree
  └─README.org
  #+end_example
  Note how pretty-printing of the "Depends-on" entry works seamlessly
  with tree printing:
  #+begin_example
  utilities.print-tree
  │ Pathname   /home/jmoringe/code/cl/utilities.print-tree/
  │ Encoding   UTF-8
  │ Depends-on ((# #
  │              #)
  │             (PREPARE-OP #)
  │             (COMPILE-OP #))
  ├─src
  │ │ Pathname   /home/jmoringe/code/cl/utilities.print-tree/src/
  │ │ Encoding   UTF-8
  │ │ Depends-on ((#
  │ │              #
  │ │              #)
  │ │             (PREPARE-OP #)
  │ │             (COMPILE-OP #))
  │ ├─package
  │ │   Pathname   /home/jmoringe/code/cl/utilities.print-tree/src/package.lisp
  │ │   Encoding   UTF-8
  │ │   Depends-on ((PREPARE-OP
  │ │                #)
  │ │               (COMPILE-OP
  │ │                #))
  │ └─print-tree
  │     Pathname   /home/jmoringe/code/cl/utilities.print-tree/src/print-tree.lisp
  │     Encoding   UTF-8
  │     Depends-on ((PREPARE-OP
  │                  #)
  │                 (COMPILE-OP
  │                  #))
  └─README.org
      Pathname   /home/jmoringe/code/cl/utilities.print-tree/README.org
      Encoding   UTF-8
      Depends-on ((PREPARE-OP #)
                  (COMPILE-OP #))
  #+end_example

  The following code produces this output:
  #+begin_src lisp
    (defmethod print-component ((target stream) (depth t) (component asdf:component))
      (princ (asdf:component-name component) target))

    (defmethod print-details ((target stream) (depth t) (component asdf:component))
      (format target "Pathname   ~A~@:_~
                      Encoding   ~A~@:_~
                      Depends-on ~A"
              (asdf:component-pathname   component)
              (asdf:component-encoding   component)
              (asdf:component-depends-on 'asdf:load-op component)))

    (defmethod asdf:component-children ((component t))
      '())

    (labels ((do-it (details?)
               (fresh-line)
               (terpri)
               (print-tree *standard-output* (asdf:find-system :utilities.print-tree)
                           (make-node-printer #'print-component
                                              (when details? #'print-details)
                                              #'asdf:component-children))))
      (do-it nil)
      (do-it t))
  #+end_src
  The full code of this example is available in [[file:examples/asdf.lisp]].
* settings                                                         :noexport:
#+STARTUP: content

# Local Variables:
# mode: org
# indent-tabs-mode: nil
# End:

2 Systems

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

2.1 utilities.print-tree

Maintainer

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

Author

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

License

LLGPLv3

Description

This system provides simple facilities for printing tree structures.

Version

0.1.0

Dependency

alexandria

Source

utilities.print-tree.asd (file)

Components

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

3 Modules

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

3.1 utilities.print-tree/src

Parent

utilities.print-tree (system)

Location

src/

Components

• package.lisp (file)
• print-tree.lisp (file)

3.2 utilities.print-tree/examples

Parent

utilities.print-tree (system)

Location

examples/

Components

• minimal.lisp (file)
• asdf.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-tree.asd

Location

utilities.print-tree.asd

Systems

utilities.print-tree (system)

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

Parent

src (module)

Location

src/package.lisp

Packages

utilities.print-tree

4.1.3 utilities.print-tree/src/print-tree.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/print-tree.lisp

Exported Definitions

• *use-unicode?* (special variable)
• make-folding-node-printer (function)
• make-node-printer (function)
• print-node-contents (function)
• print-subtree (function)
• print-tree (function)

Internal Definitions

• +tree-child/final+ (constant)
• +tree-child/final/ascii+ (constant)
• +tree-child/inner+ (constant)
• +tree-child/inner/ascii+ (constant)
• +tree-prefix/final+ (constant)
• +tree-prefix/final/ascii+ (constant)
• +tree-prefix/inner+ (constant)
• +tree-prefix/inner/ascii+ (constant)
• print-nodes (function)
• tree-child (function)
• tree-child/ascii (function)
• tree-child/unicode (function)
• tree-prefix (function)
• tree-prefix/ascii (function)
• tree-prefix/unicode (function)

4.2 Static

4.2.1 utilities.print-tree/README.org

Parent

utilities.print-tree (system)

Location

README.org

4.2.2 utilities.print-tree/examples/minimal.lisp

Parent

examples (module)

Location

examples/minimal.lisp

4.2.3 utilities.print-tree/examples/asdf.lisp

Parent

examples (module)

Location

examples/asdf.lisp

5 Packages

Packages are listed by definition order.

5.1 utilities.print-tree

This package provides functions for printing tree structures.

The main entry point is the ‘print-tree’ function. It accepts a stream, a tree object and a printer function.

In common cases, tree printer functions can be creating using ‘make-node-printer’ or ‘make-folding-node-printer’.

Source

package.lisp (file)

Use List

• alexandria
• common-lisp

Exported Definitions

• *use-unicode?* (special variable)
• make-folding-node-printer (function)
• make-node-printer (function)
• print-node-contents (function)
• print-subtree (function)
• print-tree (function)

Internal Definitions

• +tree-child/final+ (constant)
• +tree-child/final/ascii+ (constant)
• +tree-child/inner+ (constant)
• +tree-child/inner/ascii+ (constant)
• +tree-prefix/final+ (constant)
• +tree-prefix/final/ascii+ (constant)
• +tree-prefix/inner+ (constant)
• +tree-prefix/inner/ascii+ (constant)
• print-nodes (function)
• tree-child (function)
• tree-child/ascii (function)
• tree-child/unicode (function)
• tree-prefix (function)
• tree-prefix/ascii (function)
• tree-prefix/unicode (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *use-unicode?*

Package

utilities.print-tree

Source

print-tree.lisp (file)

6.1.2 Functions

Function: make-folding-node-printer FIRST-LINE-PRINTER REST-PRINTER CHILDREN PREDICATE

Like ‘make-node-printer’, return a node printer function that used FIRST-LINE-PRINTER, REST-PRINTER and CHILDREN.

PREDICATE is called to determine whether and to what extend nodes should be printed. When called with the depth of a node and node as its arguments, PREDICATE must return a list of "bits" of the node that should be printed. The following bits are recognized:

:first

Print first line of the node by calling FIRST-LINE-PRINTER?

:content

Print more details for the node by calling REST-PRINTER?

:children

Print children of the node?

:children-ellipsis

Print ellipsis of the form "…", if the node has children butlast the :children bit has not been specified?

When PREDICATE returns T, all bits are printed.

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: make-node-printer FIRST-LINE-PRINTER REST-PRINTER CHILDREN

Return a node printer function that used FIRST-LINE-PRINTER, REST-PRINTER and CHILDREN.

FIRST-LINE-PRINTER is called with the destination stream, the depth of the node and the node and should print a one-line representation of the node to the stream. The function should return true if REST-PRINTER should be called to print more details for the node.

REST-PRINTER is also called with the destination stream, the depth of the node and node. It is not restricted to only producing a single line, however.

CHILDREN is called with a node and must return a (possibly empty) list of children of the node.

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: print-node-contents STREAM PRINTER &optional FINAL? DEPTH

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: print-subtree STREAM NODES PRINTER &optional FINAL? DEPTH

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: print-tree STREAM ROOT PRINTER

Print the tree ROOT to STREAM using PRINTER.

PRINTER is called with four arguments, STREAM, ROOT, the keyword :root and the integer 0, indicating depth zero. PRINTER will usually call ‘print-node’, ‘print-subree’ and ‘print-node-contents’ to do the actual work.

Functions suitable for use as PRINTER can, for many common cases, be constructed via ‘make-node-printer’ and ‘make-folding-node-printer’.

Package

utilities.print-tree

Source

print-tree.lisp (file)

6.2 Internal definitions

6.2.1 Constants

Constant: +tree-child/final+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-child/final/ascii+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-child/inner+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-child/inner/ascii+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-prefix/final+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-prefix/final/ascii+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-prefix/inner+

Package

utilities.print-tree

Source

print-tree.lisp (file)

Constant: +tree-prefix/inner/ascii+

Package

utilities.print-tree

Source

print-tree.lisp (file)

6.2.2 Functions

Function: print-nodes STREAM NODES PRINTER DEPTH

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-child KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-child/ascii KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-child/unicode KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-prefix KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-prefix/ascii KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Function: tree-prefix/unicode KIND

Package

utilities.print-tree

Source

print-tree.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types