The cl-algebraic-data-type Reference Manual

Table of Contents

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

The cl-algebraic-data-type Reference Manual

This is the cl-algebraic-data-type Reference Manual, version 1.1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 07:51:13 2018 GMT+0.


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

1 Introduction

                        CL-ALGEBRAIC-DATA-TYPE
                        ======================
                        
                             Robert Smith

CL-ALGEBRAIC-DATA-TYPE, or ADT, is a library for defining algebraic
data types in a similar spirit to Haskell or Standard ML, as well as
for operating on them.

We can define ADTs using DEFDATA:

(adt:defdata maybe
  (just t)
  nothing)

which will define a new type MAYBE, with a unary constructor JUST, and
a nullary constructor (a simple symbol) NOTHING. The T represents the
data type of that field.

> (just 5)
(JUST 5)
> nothing
NOTHING

We can define our own version of a list via

(adt:defdata liszt
  (kons t liszt)
  knil)

which defines the binary constructor KONS and the nullary constructor
KNIL.

> (kons 1 (kons 2 knil))
(KONS 1 (KONS 2 KNIL))

At the end we will define KAR and KDR.

For efficiency, we might specify the types more exactly. For a POINT
type that supports rectangular and polar coordinates, which is also
mutable, we might have:

(adt:defdata (point :mutable t)
  (rectangular float float)
  (polar float float))

The :MUTABLE keyword signifies that the data is mutable.

When we have constructed a value, we can extract data out of it using MATCH:

> (let ((pt (rectangular 1.0 2.0)))
    (adt:match point pt
      ((rectangular x y) (+ x y))
      ((polar _ _) nil)))

=> 3.0
      
If we did not include the POLAR case, we would get a warning.

> (let ((pt (rectangular 1.0 2.0)))
    (adt:match point pt
      ((rectangular x y) (+ x y))))
; caught WARNING:
;   Non-exhaustive match. Missing cases: (POLAR)
=> 3.0

We can also specify a fall-through:

> (let ((pt (rectangular 1.0 2.0)))
    (adt:match point pt
      ((rectangular x y) (+ x y))
      (_ nil)))

=> 3.0

Since POINT is mutable, we can efficiently modify its fields using
SET-DATA.

> (defun mirror-point! (pt)
    (adt:with-data (rectangular x y) pt
      (adt:set-data pt (rectangular y x))))

> (let ((pt (rectangular 1.0 2.0)))
   (mirror-point! pt)
   (adt:match point pt
     ((rectangular x y) (format t "point is (~A, ~A)" x y))
     (_ nil))

will print "point is (2.0, 1.0)".

See examples.txt for examples.


Frequently Asked Questions
--------------------------

Q. How do we define KAR and KDR for LISZT?

A. Easy.

(defun kar (l)
  (adt:match liszt l
    ((kons a _) a)
    (knil knil)))

(defun kdr (l)
  (adt:match liszt l
    ((kons _ b) b)
    (knil knil)))


Q. Can we do parametric ADTs like I can in Haskell?

A. Not unless you want things to be inefficient.


Q. Why doesn't deeper pattern matching work?

A. It's not implemented, and it would be hard to implement.


Q. Can I get the constructors dynamically for a particular ADT?

A. Yes. You can get the constructors and associated arity by calling
the GET-CONSTRUCTORS function, which will return a list of
(constructor arity) pairs. For example, given the LISZT example above, we have

CL-USER> (adt:get-constructors 'liszt)
((KONS 2) (KNIL 0))
T

The T represents the fact that the ADT is known and exists.

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 cl-algebraic-data-type

Author

Robert Smith <quad@symbo1ics.com>

License

BSD 3-clause

Description

A library for algebraic data types.

Version

1.1.0

Source

cl-algebraic-data-type.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 cl-algebraic-data-type.asd

Location

cl-algebraic-data-type.asd

Systems

cl-algebraic-data-type (system)


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

3.1.2 cl-algebraic-data-type/package.lisp

Parent

cl-algebraic-data-type (system)

Location

package.lisp

Packages

cl-algebraic-data-type


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

3.1.3 cl-algebraic-data-type/utilities.lisp

Dependency

package.lisp (file)

Parent

cl-algebraic-data-type (system)

Location

utilities.lisp

Exported Definitions
Internal Definitions

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

3.1.4 cl-algebraic-data-type/defdata.lisp

Dependency

utilities.lisp (file)

Parent

cl-algebraic-data-type (system)

Location

defdata.lisp

Exported Definitions

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

3.1.5 cl-algebraic-data-type/match.lisp

Dependency

defdata.lisp (file)

Parent

cl-algebraic-data-type (system)

Location

match.lisp

Exported Definitions

match (macro)

Internal Definitions

duplicates (function)


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

4 Packages

Packages are listed by definition order.


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

4.1 cl-algebraic-data-type

A package for defining algebraic data types.

Source

package.lisp (file)

Nickname

adt

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Macros

Macro: defdata ADT-NAME &body CONSTRUCTORS

Define a new ADT. ADT-name has the following grammar:

ADT-NAME := <symbol>
| (<symbol>)
| (<symbol> :MUTABLE {T, NIL})

There is no difference between specifying it as a symbol or as a singleton list. Specifying :MUTABLE as T will make DEFDATA mutable, allowing the use of SET-DATA.

Constructors is a list of clauses with the following grammar:

<clause> := <symbol>
| (<symbol> <type-specifier>*)

Each clause defines a constructor for the ADT. Nullary constructors will define constants and all other constructors will define functions.

Package

cl-algebraic-data-type

Source

defdata.lisp (file)

Macro: match ADT OBJ &body CLAUSES

Perform pattern matching on OBJ with (adt-type) ADT.

Each clause must have the following syntax:

<var> := <symbol> | ’_’
<lhs> := ’_’
| (<symbol> <var>*)
<clause> := (<lhs> <lisp code>)

The symbol ’_’ denotes a wildcard, as well as a fallthough.

Note that pattern matching is only shallow (patterns are one-level deep).

Package

cl-algebraic-data-type

Source

match.lisp (file)

Macro: set-data OBJ (NAME &rest NEW-VALUES)

Mutate the fields of the ADT value OBJ whose constructor is NAME and whose updated values are NEW-VALUES based on order. If the symbol ’_’ is used as a value, that field is not updated. Trailing ’_’ may be omitted.

Package

cl-algebraic-data-type

Source

defdata.lisp (file)

Macro: with-data (NAME &rest VARS) OBJ &body BODY

Destructure the ADT value OBJ, whose constructor is NAME. VARS must be symbol which will be bound, or they must be the symbol ’_’, which means the value will not be bound.

Package

cl-algebraic-data-type

Source

defdata.lisp (file)


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

5.1.2 Functions

Function: algebraic-data-type-p TYPE

Is TYPE a known algebraic data type?

Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: algebraic-data-value-p VALUE

Is the value VALUE that of some algebraic data type?

Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: get-constructors ADT

Get the constructors and their arity for the adt ADT. Two values will be returned:

1. If the ADT exists, then a list of pairs

(CONSTRUCTOR-SYMBOL ARITY).

If the ARITY is zero, then the CONSTRUCTOR-SYMBOL is a value as opposed to a function.

2. T if the ADT exists, NIL otherwise. This mimics the behavior of GETHASH.

Package

cl-algebraic-data-type

Source

utilities.lisp (file)


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

5.1.3 Structures

Structure: algebraic-data-type ()

Abstract type for all algebraic data types, primarily used to identify such types.

Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Direct superclasses

structure-object (structure)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *constructors*
Package

cl-algebraic-data-type

Source

utilities.lisp (file)


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

5.2.2 Macros

Macro: define-constant NAME VALUE
Package

cl-algebraic-data-type

Source

utilities.lisp (file)


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

5.2.3 Functions

Function: duplicates SEQUENCE &key TEST
Package

cl-algebraic-data-type

Source

match.lisp (file)

Function: ensure-car X
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: ensure-list X
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: field NAME N
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: gen-names N
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: internal S
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: set-constructors ADT CONSTRUCTORS
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: unsplice X
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: unwrap-singletons LIST
Package

cl-algebraic-data-type

Source

utilities.lisp (file)

Function: wild? S
Package

cl-algebraic-data-type

Source

utilities.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-algebraic-data-type.asd: The cl-algebraic-data-type<dot>asd file
cl-algebraic-data-type/defdata.lisp: The cl-algebraic-data-type/defdata<dot>lisp file
cl-algebraic-data-type/match.lisp: The cl-algebraic-data-type/match<dot>lisp file
cl-algebraic-data-type/package.lisp: The cl-algebraic-data-type/package<dot>lisp file
cl-algebraic-data-type/utilities.lisp: The cl-algebraic-data-type/utilities<dot>lisp file

F
File, Lisp, cl-algebraic-data-type.asd: The cl-algebraic-data-type<dot>asd file
File, Lisp, cl-algebraic-data-type/defdata.lisp: The cl-algebraic-data-type/defdata<dot>lisp file
File, Lisp, cl-algebraic-data-type/match.lisp: The cl-algebraic-data-type/match<dot>lisp file
File, Lisp, cl-algebraic-data-type/package.lisp: The cl-algebraic-data-type/package<dot>lisp file
File, Lisp, cl-algebraic-data-type/utilities.lisp: The cl-algebraic-data-type/utilities<dot>lisp file

L
Lisp File, cl-algebraic-data-type.asd: The cl-algebraic-data-type<dot>asd file
Lisp File, cl-algebraic-data-type/defdata.lisp: The cl-algebraic-data-type/defdata<dot>lisp file
Lisp File, cl-algebraic-data-type/match.lisp: The cl-algebraic-data-type/match<dot>lisp file
Lisp File, cl-algebraic-data-type/package.lisp: The cl-algebraic-data-type/package<dot>lisp file
Lisp File, cl-algebraic-data-type/utilities.lisp: The cl-algebraic-data-type/utilities<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   A   D   E   F   G   I   M   S   U   W  
Index Entry  Section

A
algebraic-data-type-p: Exported functions
algebraic-data-value-p: Exported functions

D
defdata: Exported macros
define-constant: Internal macros
duplicates: Internal functions

E
ensure-car: Internal functions
ensure-list: Internal functions

F
field: Internal functions
Function, algebraic-data-type-p: Exported functions
Function, algebraic-data-value-p: Exported functions
Function, duplicates: Internal functions
Function, ensure-car: Internal functions
Function, ensure-list: Internal functions
Function, field: Internal functions
Function, gen-names: Internal functions
Function, get-constructors: Exported functions
Function, internal: Internal functions
Function, set-constructors: Internal functions
Function, unsplice: Internal functions
Function, unwrap-singletons: Internal functions
Function, wild?: Internal functions

G
gen-names: Internal functions
get-constructors: Exported functions

I
internal: Internal functions

M
Macro, defdata: Exported macros
Macro, define-constant: Internal macros
Macro, match: Exported macros
Macro, set-data: Exported macros
Macro, with-data: Exported macros
match: Exported macros

S
set-constructors: Internal functions
set-data: Exported macros

U
unsplice: Internal functions
unwrap-singletons: Internal functions

W
wild?: Internal functions
with-data: Exported macros

Jump to:   A   D   E   F   G   I   M   S   U   W  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*constructors*: Internal special variables

S
Special Variable, *constructors*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   A   C   P   S  
Index Entry  Section

A
algebraic-data-type: Exported structures

C
cl-algebraic-data-type: The cl-algebraic-data-type system
cl-algebraic-data-type: The cl-algebraic-data-type package

P
Package, cl-algebraic-data-type: The cl-algebraic-data-type package

S
Structure, algebraic-data-type: Exported structures
System, cl-algebraic-data-type: The cl-algebraic-data-type system

Jump to:   A   C   P   S