The cl-digraph Reference Manual

Table of Contents

The cl-digraph Reference Manual

This is the cl-digraph Reference Manual, version 1.2.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:03:34 2018 GMT+0.

1 Introduction

cl-digraph is an implementation of a mutable directed graph data structure for Common Lisp.

• License: MIT
• Documentation: https://sjl.bitbucket.io/cl-digraph/
• Mercurial: http://bitbucket.org/sjl/cl-digraph/
• Git: http://github.com/sjl/cl-digraph/

cl-digraph focuses on simplicity, correctness, and usability. Performance is not terrible, but is not a high priority.

It is currently not thread-safe, but this may happen in the future.

The test suite currently passes in SBCL, CCL, ECL, and ABCL on OS X and Debian. Further testing is welcome.

2 Systems

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

2.1 cl-digraph

Author

Steve Losh <steve@stevelosh.com>

Home Page

https://sjl.bitbucket.io/cl-digraph/

License

MIT/X11

Description

Simple directed graphs for Common Lisp.

Version

1.2.0

Source

cl-digraph.asd (file)

Components

• vendor (module)
• package.lisp (file)
• src (module)

3 Modules

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

3.1 cl-digraph/vendor

Parent

cl-digraph (system)

Location

vendor/

Components

• quickutils-package.lisp (file)
• quickutils.lisp (file)

3.2 cl-digraph/src

Dependency

package.lisp (file)

Parent

cl-digraph (system)

Location

src/

Component

directed-graph.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 cl-digraph.asd

Location

cl-digraph.asd

Systems

cl-digraph (system)

4.1.2 cl-digraph/vendor/quickutils-package.lisp

Parent

vendor (module)

Location

vendor/quickutils-package.lisp

Packages

digraph.quickutils

Internal Definitions

*utilities* (special variable)

4.1.3 cl-digraph/vendor/quickutils.lisp

Dependency

quickutils-package.lisp (file)

Parent

vendor (module)

Location

vendor/quickutils.lisp

Exported Definitions

• appendf (macro)
• compose (compiler macro)
• compose (function)
• curry (compiler macro)
• curry (function)
• dohash (macro)
• ensure-boolean (function)
• ensure-gethash (macro)
• ensure-list (function)
• hash-table-keys (function)
• maphash-keys (function)
• mkstr (function)
• once-only (macro)
• rcurry (function)
• removef (macro)
• symb (function)
• with-gensyms (macro)
• with-unique-names (macro)

Internal Definitions

• ensure-function (function)
• make-gensym-list (function)
• remove/swapped-arguments (function)
• string-designator (type)

4.1.4 cl-digraph/package.lisp

Dependency

vendor (module)

Parent

cl-digraph (system)

Location

package.lisp

Packages

digraph

4.1.5 cl-digraph/src/directed-graph.lisp

Parent

src (module)

Location

src/directed-graph.lisp

Exported Definitions

• contains-edge-p (function)
• contains-vertex-p (function)
• copy-digraph (function)
• count-edges (function)
• count-vertices (function)
• degree (function)
• degree-in (function)
• degree-out (function)
• digraph (class)
• edges (function)
• emptyp (function)
• insert-edge (function)
• insert-vertex (function)
• leafp (function)
• leafs (function)
• make-digraph (function)
• map-breadth-first (function)
• map-depth-first (function)
• map-edges (function)
• map-vertices (function)
• mapc-breadth-first (function)
• mapc-depth-first (function)
• mapc-edges (function)
• mapc-vertices (function)
• neighbors (function)
• predecessors (function)
• reachablep (function)
• remove-edge (function)
• remove-vertex (function)
• rootp (function)
• roots (function)
• successors (function)
• topological-sort (function)
• vertices (function)

Internal Definitions

• digraph-hash-function (method)
• digraph-nodes (method)
• digraph-test (method)
• do-edges (macro)
• do-vertices (macro)
• insert-chain (function)
• make-hash-table-portably (function)
• make-test-digraph (function)
• pred (macro)
• succ (macro)
• topological-sort% (function)

5 Packages

Packages are listed by definition order.

5.1 digraph.quickutils

Package that contains Quickutil utility functions.

Source

quickutils-package.lisp (file)

Use List

common-lisp

Used By List

digraph

Exported Definitions

• appendf (macro)
• compose (compiler macro)
• compose (function)
• curry (compiler macro)
• curry (function)
• dohash (macro)
• ensure-boolean (function)
• ensure-gethash (macro)
• ensure-list (function)
• hash-table-keys (function)
• maphash-keys (function)
• mkstr (function)
• once-only (macro)
• rcurry (function)
• removef (macro)
• symb (function)
• with-gensyms (macro)
• with-unique-names (macro)

Internal Definitions

• *utilities* (special variable)
• ensure-function (function)
• make-gensym-list (function)
• remove/swapped-arguments (function)
• string-designator (type)

5.2 digraph

Source

package.lisp (file)

Use List

• digraph.quickutils
• common-lisp

Exported Definitions

• contains-edge-p (function)
• contains-vertex-p (function)
• copy-digraph (function)
• count-edges (function)
• count-vertices (function)
• degree (function)
• degree-in (function)
• degree-out (function)
• digraph (class)
• edges (function)
• emptyp (function)
• insert-edge (function)
• insert-vertex (function)
• leafp (function)
• leafs (function)
• make-digraph (function)
• map-breadth-first (function)
• map-depth-first (function)
• map-edges (function)
• map-vertices (function)
• mapc-breadth-first (function)
• mapc-depth-first (function)
• mapc-edges (function)
• mapc-vertices (function)
• neighbors (function)
• predecessors (function)
• reachablep (function)
• remove-edge (function)
• remove-vertex (function)
• rootp (function)
• roots (function)
• successors (function)
• topological-sort (function)
• vertices (function)

Internal Definitions

• digraph-hash-function (generic function)
• digraph-hash-function (method)
• digraph-nodes (generic function)
• digraph-nodes (method)
• digraph-test (generic function)
• digraph-test (method)
• do-edges (macro)
• do-vertices (macro)
• insert-chain (function)
• make-hash-table-portably (function)
• make-test-digraph (function)
• pred (macro)
• succ (macro)
• topological-sort% (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: appendf PLACE &rest LISTS

Modify-macro for ‘append‘. Appends ‘lists‘ to the place designated by the first argument.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: dohash (KEY VALUE TABLE &optional RESULT) &body BODY

Iterate over the hash table ‘table‘, executing ‘body‘, with ‘key‘ and ‘value‘ bound to the keys and values of the hash table respectively. Return ‘result‘ from the iteration form.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: ensure-gethash KEY HASH-TABLE &optional DEFAULT

Like ‘gethash‘, but if ‘key‘ is not found in the ‘hash-table‘ saves the ‘default‘ under key before returning it. Secondary return value is true if key was already in the table.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: once-only SPECS &body FORMS

Evaluates ‘forms‘ with symbols specified in ‘specs‘ rebound to temporary variables, ensuring that each initform is evaluated only once.

Each of ‘specs‘ must either be a symbol naming the variable to be rebound, or of the form:

(symbol initform)

Bare symbols in ‘specs‘ are equivalent to

(symbol symbol)

Example:

(defmacro cons1 (x) (once-only (x) ‘(cons ,x ,x)))
(let ((y 0)) (cons1 (incf y))) => (1 . 1)

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: removef PLACE ITEM &rest REMOVE-KEYWORDS

Modify-macro for ‘remove‘. Sets place designated by the first argument to the result of calling ‘remove‘ with ‘item‘, place, and the ‘keyword-arguments‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: with-gensyms NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Macro: with-unique-names NAMES &body FORMS

Binds each variable named by a symbol in ‘names‘ to a unique symbol around ‘forms‘. Each of ‘names‘ must either be either a symbol, or of the form:

(symbol string-designator)

Bare symbols appearing in ‘names‘ are equivalent to:

(symbol symbol)

The string-designator is used as the argument to ‘gensym‘ when constructing the unique symbol the named variable will be bound to.

Package

digraph.quickutils

Source

quickutils.lisp (file)

6.1.2 Compiler macros

Compiler Macro: compose FUNCTION &rest MORE-FUNCTIONS

Package

digraph.quickutils

Source

quickutils.lisp (file)

Compiler Macro: curry FUNCTION &rest ARGUMENTS

Package

digraph.quickutils

Source

quickutils.lisp (file)

6.1.3 Functions

Function: compose FUNCTION &rest MORE-FUNCTIONS

Returns a function composed of ‘function‘ and ‘more-functions‘ that applies its ; arguments to to each in turn, starting from the rightmost of ‘more-functions‘, and then calling the next one with the primary value of the last.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: contains-edge-p DIGRAPH PREDECESSOR SUCCESSOR

Return whether the graph contains an edge from ‘predecessor‘ to ‘successor‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: contains-vertex-p DIGRAPH VERTEX

Return whether the graph contains ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: copy-digraph DIGRAPH

Create a fresh copy of ‘digraph‘.

The vertex objects themselves are not copied, but everything else is.

Package

digraph

Source

directed-graph.lisp (file)

Function: count-edges DIGRAPH

Return the number of edges in ‘digraph‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: count-vertices DIGRAPH

Return the number of vertices in ‘digraph‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: curry FUNCTION &rest ARGUMENTS

Returns a function that applies ‘arguments‘ and the arguments it is called with to ‘function‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: degree DIGRAPH VERTEX

Return the number of neighbors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: degree-in DIGRAPH VERTEX

Return the number of predecessors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: degree-out DIGRAPH VERTEX

Return the number of successors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: edges DIGRAPH

Return a fresh list of the edges of ‘digraph‘.

Each edge will be a cons of the form ‘(predecessor . successor)‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: emptyp DIGRAPH

Return ‘t‘ if ‘digraph‘ has no vertices or edges, ‘nil‘ otherwise.

Package

digraph

Source

directed-graph.lisp (file)

Function: ensure-boolean X

Convert ‘x‘ into a Boolean value.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: ensure-list LIST

If ‘list‘ is a list, it is returned. Otherwise returns the list designated by ‘list‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: hash-table-keys TABLE

Returns a list containing the keys of hash table ‘table‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: insert-edge DIGRAPH PREDECESSOR SUCCESSOR

Insert an edge from ‘predecessor‘ to ‘successor‘ if not already present.

The ‘predecessor‘ and ‘successor‘ vertices must exist in the graph already.

Returns ‘t‘ if the edge was already in the graph, or ‘nil‘ if it was inserted.

Package

digraph

Source

directed-graph.lisp (file)

Function: insert-vertex DIGRAPH VERTEX

Insert ‘vertex‘ into the graph if it is not already a member.

Returns ‘t‘ if the vertex was already in the graph, or ‘nil‘ if it was inserted.

Package

digraph

Source

directed-graph.lisp (file)

Function: leafp DIGRAPH VERTEX

Return whether ‘vertex‘ is a leaf vertex in ‘digraph‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: leafs DIGRAPH

Return all leaf vertices in ‘digraph‘.

This is currently O(vertices).

A root is a vertex with no outgoing edges (i.e. out-degree 0).

Package

digraph

Source

directed-graph.lisp (file)

Function: make-digraph &key INITIAL-VERTICES TEST HASH-FUNCTION

Create and return a new digraph.

‘initial-vertices‘ can be a sequence of vertices to add to the graph.

‘test‘ should be one of the hash table equality predicates.

If your Lisp implementation supports the ‘:hash-function‘ argument for creating hash tables with custom predicates, you can specify one with ‘hash-function‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: map-breadth-first FUNCTION DIGRAPH START-VERTEX

Apply ‘function‘ to the vertices of a breadth-first traversal of ‘digraph‘.

Returns a fresh list with the results.

Vertices are processed in breadth-first order, beginning at ‘start-vertex‘, and the resulting list has this order as well.

Cycles in the graph will not be traversed into.

Package

digraph

Source

directed-graph.lisp (file)

Function: map-depth-first FUNCTION DIGRAPH START-VERTEX

Apply ‘function‘ to the vertices of a breadth-first traversal of ‘digraph‘.

Returns a fresh list with the results.

Vertices are processed in depth-first order, beginning at ‘start-vertex‘, and the resulting list has this order as well.

Cycles in the graph will not be traversed into.

Package

digraph

Source

directed-graph.lisp (file)

Function: map-edges FUNCTION DIGRAPH

Return a fresh list with the results of calling ‘function‘ on each edge.

For each edge, ‘function‘ will be called once with two arguments:

(function predecessor successor)

The order of the resulting list is unspecified.

Package

digraph

Source

directed-graph.lisp (file)

Function: map-vertices FUNCTION DIGRAPH

Return a fresh list with the results of calling ‘function‘ on each vertex.

The order of the resulting list is unspecified.

Package

digraph

Source

directed-graph.lisp (file)

Function: mapc-breadth-first FUNCTION DIGRAPH START-VERTEX

Apply ‘function‘ to the vertices of a breadth-first traversal of ‘digraph‘.

Returns ‘nil‘.

Vertices are processed in breadth-first order, beginning at ‘start-vertex‘.

Cycles in the graph will not be traversed into.

Package

digraph

Source

directed-graph.lisp (file)

Function: mapc-depth-first FUNCTION DIGRAPH START-VERTEX

Apply ‘function‘ to the vertices of a depth-first traversal of ‘digraph‘.

Returns ‘nil‘.

Vertices are processed in depth-first order, beginning at ‘start-vertex‘.

Cycles in the graph will not be traversed into.

Package

digraph

Source

directed-graph.lisp (file)

Function: mapc-edges FUNCTION DIGRAPH

Call ‘function‘ on each edge in ‘digraph‘.

For each edge, ‘function‘ will be called once with two arguments:

(function predecessor successor)

The order in which the edges are processed is unspecified.

Returns ‘nil‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: mapc-vertices FUNCTION DIGRAPH

Call ‘function‘ on each vertex in ‘digraph‘.

The order in which the vertices are processed is unspecified.

Returns ‘nil‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: maphash-keys FUNCTION TABLE

Like ‘maphash‘, but calls ‘function‘ with each key in the hash table ‘table‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: mkstr &rest ARGS

Receives any number of objects (string, symbol, keyword, char, number), extracts all printed representations, and concatenates them all into one string.

Extracted from _On Lisp_, chapter 4.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: neighbors DIGRAPH VERTEX

Return a fresh list of the neighbors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: predecessors DIGRAPH VERTEX

Return a fresh list of the predecessors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: rcurry FUNCTION &rest ARGUMENTS

Returns a function that applies the arguments it is called with and ‘arguments‘ to ‘function‘.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: reachablep DIGRAPH START TARGET &key STRATEGY

Return ‘t‘ if it is possible to reach ‘target‘ from ‘start‘, otherwise ‘nil‘.

All vertices are reachable from themselves.

Otherwise a ‘target‘ is reachable from ‘start‘ if a directed path exists from the start to the target.

‘strategy‘ will be used to determine how to traverse the graph when searching for a path, and can be one of ‘:breadth-first‘ or ‘:depth-first‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: remove-edge DIGRAPH PREDECESSOR SUCCESSOR

Remove an edge from ‘predecessor‘ to ‘successor‘ if present.

Returns ‘t‘ if there was such an edge, or ‘nil‘ if not.

Package

digraph

Source

directed-graph.lisp (file)

Function: remove-vertex DIGRAPH VERTEX

Remove ‘vertex‘ from the graph if present.

If there are any edges to/from ‘vertex‘ they will be automatically removed.

Returns ‘t‘ if there was such a vertex, or ‘nil‘ if not.

Package

digraph

Source

directed-graph.lisp (file)

Function: rootp DIGRAPH VERTEX

Return whether ‘vertex‘ is a root vertex in ‘digraph‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: roots DIGRAPH

Return all root vertices in ‘digraph‘.

This is currently O(vertices).

A root is a vertex with no incoming edges (i.e. in-degree 0).

Package

digraph

Source

directed-graph.lisp (file)

Function: successors DIGRAPH VERTEX

Return a fresh list of the successors of ‘vertex‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: symb &rest ARGS

Receives any number of objects, concatenates all into one string with ‘#’mkstr‘ and converts them to symbol.

Extracted from _On Lisp_, chapter 4.

See also: ‘symbolicate‘

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: topological-sort DIGRAPH

Return a fresh list of the vertices of ‘digraph‘ in topological order.

Edges are treated as meaning "depends on", so an edge ‘A –> B‘ means "A depends on B" and that B must come before A in the resulting list. Aside from this restriction, the order of the resulting list is arbitrary.

The order in which the vertices are processed is unspecified.

An error will be signaled if the graph contains a cycle.

Package

digraph

Source

directed-graph.lisp (file)

Function: vertices DIGRAPH

Return a fresh list of the vertices of ‘digraph‘.

Package

digraph

Source

directed-graph.lisp (file)

6.1.4 Classes

Class: digraph ()

A directed graph. Use ‘make-digraph‘ to create one.

Package

digraph

Source

directed-graph.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• print-object (method)
• digraph-hash-function (method)
• digraph-test (method)
• digraph-nodes (method)

Direct slots

Slot: nodes

Initargs

:nodes

Readers

digraph-nodes (generic function)

Slot: test

Initargs

:test

Readers

digraph-test (generic function)

Slot: hash-function

Initargs

:hash-function

Readers

digraph-hash-function (generic function)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *utilities*

Package

digraph.quickutils

Source

quickutils-package.lisp (file)

6.2.2 Macros

Macro: do-edges (PREDECESSOR-SYMBOL SUCCESSOR-SYMBOL DIGRAPH) &body BODY

Package

digraph

Source

directed-graph.lisp (file)

Macro: do-vertices (SYMBOL DIGRAPH) &body BODY

Package

digraph

Source

directed-graph.lisp (file)

Macro: pred DIGRAPH OBJECT

Package

digraph

Source

directed-graph.lisp (file)

Macro: succ DIGRAPH OBJECT

Package

digraph

Source

directed-graph.lisp (file)

6.2.3 Functions

Function: ensure-function FUNCTION-DESIGNATOR

Returns the function designated by ‘function-designator‘:
if ‘function-designator‘ is a function, it is returned, otherwise it must be a function name and its ‘fdefinition‘ is returned.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: insert-chain DIGRAPH PREDECESSOR SUCCESSOR &rest LATER-SUCCESSORS

Insert edges between a series of vertices.

Give a series of vertices ‘V0 V1 ... Vn‘, edges between each will be inserted if not already present:

V0 -> V1 -> ... -> Vn

All vertices must exist in the graph already.

Returns ‘nil‘.

Package

digraph

Source

directed-graph.lisp (file)

Function: make-gensym-list LENGTH &optional X

Returns a list of ‘length‘ gensyms, each generated as if with a call to ‘make-gensym‘, using the second (optional, defaulting to ‘"G"‘) argument.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: make-hash-table-portably &key SIZE TEST HASH-FUNCTION

Package

digraph

Source

directed-graph.lisp (file)

Function: make-test-digraph ()

Package

digraph

Source

directed-graph.lisp (file)

Function: remove/swapped-arguments SEQUENCE ITEM &rest KEYWORD-ARGUMENTS

Package

digraph.quickutils

Source

quickutils.lisp (file)

Function: topological-sort% FUNCTION DIGRAPH

Package

digraph

Source

directed-graph.lisp (file)

6.2.4 Generic functions

Generic Function: digraph-hash-function OBJECT

Package

digraph

Methods

Method: digraph-hash-function (DIGRAPH digraph)

automatically generated reader method

Source

directed-graph.lisp (file)

Generic Function: digraph-nodes OBJECT

Package

digraph

Methods

Method: digraph-nodes (DIGRAPH digraph)

automatically generated reader method

Source

directed-graph.lisp (file)

Generic Function: digraph-test OBJECT

Package

digraph

Methods

Method: digraph-test (DIGRAPH digraph)

automatically generated reader method

Source

directed-graph.lisp (file)

6.2.5 Types

Type: string-designator ()

A string designator type. A string designator is either a string, a symbol, or a character.

Package

digraph.quickutils

Source

quickutils.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types