The cl-pattern Reference Manual

Table of Contents

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

The cl-pattern Reference Manual

This is the cl-pattern Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:13:23 2018 GMT+0.


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

1 Introduction

CL-PATTERN

CL-PATTERN is a very fast ML-like pattern-matching library for Common Lisp.

API

Macro: match

match value &body clauses

match macro tries to match value with clauses and raise an error if no clauses matched. A clause have to be a form of (pattern form*), where pattern is a pattern (see "Patterns").

Examples

(match '(1 2)
  ((x y) (+ x y)))
;;=> 3

(match '(x 1)
  (('x x) x))
;;=> 1

(match '(1 2)
  ((1 &optional a) a))
;;=> 2

Macro: lambda-match

lambda-match &body clauses

lambda-match is a shorthand of lambda and match. For example,

(lambda-match
  (('foo a) a))

will be expaneded to

(lambda (arg)
  (match arg
    (('foo a) a)))

Patterns

A pattern must be one of a symbol, a cons, and an atom. If the pattern is symbol, the pattern is called a variable pattern, which can be matched with any value. A body of a clause will be evaluated with using a binding of the variable and the valueThe variable can be used in a body of a. If the variable is _, any binding will not be made. Here is an example:

(match 1
  (x x))
;;=> 1

If the pattern is a cons, there is three cases you have to know. If a car of the cons is quote, the pattern is called a constant pattern, which can be matched with a same value of a cadr of the cons. Here is an example:

(match 'x
  ('x 1))
;;=> 1

Second case, if the car of the cons is &optional, the pattern is called a optional variable pattern, which can be matched with any value as same as usual variable patterns, but it can be not matched. If not matched, we say the pattern is unbound, meaning an undefined value (nil will bound to the pattern.

(match '(1)
  ((1 &optional x) x))
;;=> NIL

(match '(1 2)
  ((1 &optional x) x))
;;=> 2

Othewise, the pattern is called a structure pattern, which can be matched if a car of the pattern and a cdr of the pattern are matched with a value. Here is an example:

(match '(1 . 2)
  ((x . y) (+ x y)))
;;=> 1

As you may guess, the car of the pattern and the cdr of the pattern are also patterns. So you can nest patterns infinitely.

If the pattern is an atom, the pattern is called a constant pattern too. As we said, the pattern can be matched with a same value of the pattern. Here is an example:

(match 1
  (1 'matched))
;;=> MATCHED

Micro Benchmark

Here is a micro benchmark comparing

(match triple
  ((a &optional b c) (+ a b c)))

and

(destructuring-bind (a &optional b c)
    triple
  (+ a b c))

Allegro CL v8.2 (Express Edition)

On Allegro CL, destructuring-bind seems to be tuned properly.

MATCH
; cpu time (non-gc) 0.190000 sec user, 0.000000 sec system
; cpu time (gc)     0.000000 sec user, 0.000000 sec system
; cpu time (total)  0.190000 sec user, 0.000000 sec system
; real time  0.188305 sec
; space allocation:
;  0 cons cells, 0 other bytes, 0 static bytes
DESTRUCTURING-BIND
; cpu time (non-gc) 0.040000 sec user, 0.000000 sec system
; cpu time (gc)     0.000000 sec user, 0.000000 sec system
; cpu time (total)  0.040000 sec user, 0.000000 sec system
; real time  0.040888 sec
; space allocation:
;  0 cons cells, 0 other bytes, 0 static bytes

SBCL v1.0.47

On SBCL, even in such the simple case, destructuring-bind seems to be a very high cost operation.

MATCH
Evaluation took:
  0.007 seconds of real time
  0.010000 seconds of total run time (0.010000 user, 0.000000 system)
  142.86% CPU
  10,040,848 processor cycles
  0 bytes consed
  
DESTRUCTURING-BIND
Evaluation took:
  0.983 seconds of real time
  0.980000 seconds of total run time (0.970000 user, 0.010000 system)
  99.69% CPU
  1,568,842,248 processor cycles
  0 bytes consed

ECL v11.1.1

On ECL, match and destructuring-bind are almost same cost in this simple case.

MATCH
real time : 0.883 secs
run time  : 0.890 secs
gc count  : 2 times
consed    : 66339433 bytes
DESTRUCTURING-BIND
real time : 0.970 secs
run time  : 0.960 secs
gc count  : 1 times
consed    : 66346216 bytes

Supported Implementations


Copyright (C) 2011 Tomohiro Matsuyama <tomo@cx4a.org>.


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-pattern

Author

Tomohiro Matsuyama

License

LLGPL

Version

0.1

Dependencies
Source

cl-pattern.asd (file)

Component

src (module)


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 cl-pattern/src

Parent

cl-pattern (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.


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

4.1 Lisp


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

4.1.1 cl-pattern.asd

Location

cl-pattern.asd

Systems

cl-pattern (system)

Packages

cl-pattern-asd


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

4.1.2 cl-pattern/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-pattern


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

4.1.3 cl-pattern/src/conditions.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/conditions.lisp

Internal Definitions

%match-error (function)


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

4.1.4 cl-pattern/src/pattern.lisp

Dependency

conditions.lisp (file)

Parent

src (module)

Location

src/pattern.lisp

Internal Definitions

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

4.1.5 cl-pattern/src/case.lisp

Dependency

pattern.lisp (file)

Parent

src (module)

Location

src/case.lisp

Internal Definitions

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

4.1.6 cl-pattern/src/compile.lisp

Dependency

case.lisp (file)

Parent

src (module)

Location

src/compile.lisp

Internal Definitions

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

4.1.7 cl-pattern/src/match.lisp

Dependency

compile.lisp (file)

Parent

src (module)

Location

src/match.lisp

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-pattern-asd

Source

cl-pattern.asd

Use List

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

5.2 cl-pattern

Source

package.lisp (file)

Nickname

pattern

Use List

common-lisp

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


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

6.1.1 Macros

Macro: lambda-match &body CLAUSES
Package

cl-pattern

Source

match.lisp (file)

Macro: match ARG &body CLAUSES
Package

cl-pattern

Source

match.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Macros

Macro: %case ARG CLAUSES ELSE
Package

cl-pattern

Source

case.lisp (file)

Macro: %equal PATTERN VALUE
Package

cl-pattern

Source

pattern.lisp (file)

Macro: %match VARS CLAUSES &optional ELSE
Package

cl-pattern

Source

match.lisp (file)

Macro: match* ARGS &body CLAUSES
Package

cl-pattern

Source

match.lisp (file)


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

6.2.2 Functions

Function: %match-error &optional ARGS PATTERNS
Package

cl-pattern

Source

conditions.lisp (file)

Function: compile-case VAR CLAUSES ELSE
Package

cl-pattern

Source

case.lisp (file)

Function: compile-case-clause VAR CLAUSE ELSE
Package

cl-pattern

Source

case.lisp (file)

Function: compile-match-constant VARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-constructor VARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-empty CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-group VARS GROUP ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-groups VARS GROUPS ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-optional VARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-optional-constructor VAR RESTVARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-optional-null RESTVARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: compile-match-variable VARS CLAUSES ELSE
Package

cl-pattern

Source

compile.lisp (file)

Function: free-variables PATTERN
Package

cl-pattern

Source

pattern.lisp (file)

Function: optional-patterns PATTERN
Package

cl-pattern

Source

pattern.lisp (file)

Function: partition-match-clauses CLAUSES
Package

cl-pattern

Source

compile.lisp (file)

Function: pattern-type PATTERN
Package

cl-pattern

Source

pattern.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-pattern.asd: The cl-pattern<dot>asd file
cl-pattern/src: The cl-pattern/src module
cl-pattern/src/case.lisp: The cl-pattern/src/case<dot>lisp file
cl-pattern/src/compile.lisp: The cl-pattern/src/compile<dot>lisp file
cl-pattern/src/conditions.lisp: The cl-pattern/src/conditions<dot>lisp file
cl-pattern/src/match.lisp: The cl-pattern/src/match<dot>lisp file
cl-pattern/src/package.lisp: The cl-pattern/src/package<dot>lisp file
cl-pattern/src/pattern.lisp: The cl-pattern/src/pattern<dot>lisp file

F
File, Lisp, cl-pattern.asd: The cl-pattern<dot>asd file
File, Lisp, cl-pattern/src/case.lisp: The cl-pattern/src/case<dot>lisp file
File, Lisp, cl-pattern/src/compile.lisp: The cl-pattern/src/compile<dot>lisp file
File, Lisp, cl-pattern/src/conditions.lisp: The cl-pattern/src/conditions<dot>lisp file
File, Lisp, cl-pattern/src/match.lisp: The cl-pattern/src/match<dot>lisp file
File, Lisp, cl-pattern/src/package.lisp: The cl-pattern/src/package<dot>lisp file
File, Lisp, cl-pattern/src/pattern.lisp: The cl-pattern/src/pattern<dot>lisp file

L
Lisp File, cl-pattern.asd: The cl-pattern<dot>asd file
Lisp File, cl-pattern/src/case.lisp: The cl-pattern/src/case<dot>lisp file
Lisp File, cl-pattern/src/compile.lisp: The cl-pattern/src/compile<dot>lisp file
Lisp File, cl-pattern/src/conditions.lisp: The cl-pattern/src/conditions<dot>lisp file
Lisp File, cl-pattern/src/match.lisp: The cl-pattern/src/match<dot>lisp file
Lisp File, cl-pattern/src/package.lisp: The cl-pattern/src/package<dot>lisp file
Lisp File, cl-pattern/src/pattern.lisp: The cl-pattern/src/pattern<dot>lisp file

M
Module, cl-pattern/src: The cl-pattern/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   %  
C   F   L   M   O   P  
Index Entry  Section

%
%case: Internal macros
%equal: Internal macros
%match: Internal macros
%match-error: Internal functions

C
compile-case: Internal functions
compile-case-clause: Internal functions
compile-match-constant: Internal functions
compile-match-constructor: Internal functions
compile-match-empty: Internal functions
compile-match-group: Internal functions
compile-match-groups: Internal functions
compile-match-optional: Internal functions
compile-match-optional-constructor: Internal functions
compile-match-optional-null: Internal functions
compile-match-variable: Internal functions

F
free-variables: Internal functions
Function, %match-error: Internal functions
Function, compile-case: Internal functions
Function, compile-case-clause: Internal functions
Function, compile-match-constant: Internal functions
Function, compile-match-constructor: Internal functions
Function, compile-match-empty: Internal functions
Function, compile-match-group: Internal functions
Function, compile-match-groups: Internal functions
Function, compile-match-optional: Internal functions
Function, compile-match-optional-constructor: Internal functions
Function, compile-match-optional-null: Internal functions
Function, compile-match-variable: Internal functions
Function, free-variables: Internal functions
Function, optional-patterns: Internal functions
Function, partition-match-clauses: Internal functions
Function, pattern-type: Internal functions

L
lambda-match: Exported macros

M
Macro, %case: Internal macros
Macro, %equal: Internal macros
Macro, %match: Internal macros
Macro, lambda-match: Exported macros
Macro, match: Exported macros
Macro, match*: Internal macros
match: Exported macros
match*: Internal macros

O
optional-patterns: Internal functions

P
partition-match-clauses: Internal functions
pattern-type: Internal functions

Jump to:   %  
C   F   L   M   O   P  

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

A.3 Variables


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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-pattern: The cl-pattern system
cl-pattern: The cl-pattern package
cl-pattern-asd: The cl-pattern-asd package

P
Package, cl-pattern: The cl-pattern package
Package, cl-pattern-asd: The cl-pattern-asd package

S
System, cl-pattern: The cl-pattern system

Jump to:   C   P   S