# The cl-difflib Reference Manual

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

# The cl-difflib Reference Manual

This is the cl-difflib Reference Manual, version 0.2, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:14:26 2018 GMT+0.

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

# cl-difflib

cl-difflib is a Common Lisp library for computing differences between pairs of sequences. It is nearly a transcription of Python's difflib module, which contains the following description of its algorithm:

The basic algorithm predates, and is a little fancier than, an algorithm published in the late 1980's by Ratcliff and Obershelp under the hyperbolic name "gestalt pattern matching". The basic idea is to find the longest contiguous matching subsequence that contains no "junk" elements (R-O doesn't address junk). The same idea is then applied recursively to the pieces of the sequences to the left and to the right of the matching subsequence. This does not yield minimal edit sequences, but does tend to yield matches that "look right" to people.

cl-difflib can do unified diffs:

CL-USER> (unified-diff *standard-output*
'("one" "two" "three" "four" "five" "six")
'("one" "three" "four" "seven" "six")
:test-function #'equal)
---
+++
@@ -1,6 +1,5 @@
one
-two
three
four
-five
+seven
six
; No value

And it can do context diffs:

CL-USER> (context-diff *standard-output*
'("one" "two" "three" "four" "five" "six")
'("one" "three" "four" "seven" "six")
:test-function #'equal)
***
---
***************
*** 1,6 ***
one
- two
three
four
! five
six
--- 1,5 ----
one
three
four
! seven
six
; No value

It should work on any sequence (as long as the elements can be properly kept track of in a hash table--that's what the :test-function argument is for):

CL-USER> (context-diff *standard-output*
#(1 2 3 4 5 6)
#(1 3 4 7 6)
:from-file "original.fake"
:from-file-date "Mon Sep 27 14:13:57 2004"
:to-file "modified.fake"
:to-file-date "Thu Jan 13 15:55:05 2005")
*** original.fake Mon Sep 27 14:13:57 2004
--- modified.fake Thu Jan 13 15:55:05 2005
***************
*** 1,6 ***
1
- 2
3
4
! 5
6
--- 1,5 ----
1
3
4
! 7
6
; No value

It's got some similarity measures:

CL-USER> (defparameter *lisp-symbols* '())
*LISP-SYMBOLS*
CL-USER> (do-external-symbols (sym "COMMON-LISP")
(push (symbol-name sym) *lisp-symbols*))
NIL
CL-USER> (get-close-matches "PRING" *lisp-symbols*)
("PRINC" "PRINT" "PRIN1")
CL-USER> (get-close-matches "SPROING" *lisp-symbols*)
("STRING" "PROG" "STRINGP")
CL-USER> (get-close-matches "WITH-HASHING-TABLE" *lisp-symbols*)
("HASH-TABLE" "WITH-HASH-TABLE-ITERATOR" "HASH-TABLE-P")

And it's got some lower level building blocks:

CL-USER> (let ((m (make-instance 'sequence-matcher
:a '("one" "two" "three" "four" "five" "six")
:b '("one" "three" "four" "seven" "six")
:test-function #'equal)))
(pprint (get-opcodes m)))

(#<OPCODE :EQUAL 0 1 0 1> #<OPCODE :DELETE 1 2 1 1> #<OPCODE :EQUAL 2 4 1 3>
#<OPCODE :REPLACE 4 5 3 4> #<OPCODE :EQUAL 5 6 4 5>)
; No value

Some things it doesn't have: Python difflib's Differ class, and the ndiff or restore functions (maybe someday). It also hasn't been performance tuned. It has some ugly bits of code that look a little Pythonesque. I did change a few things to be more Lispy, but most of the documentation for the Python module should still be applicable.

cl-difflib is pretty simple, but the diffs it generates look decent. It should be completely portable Lisp. And, best of all, you can download it via ASDF-INSTALL.

(Nathan Froyd has some diff code that looks more complicated than this.)

Copyright (c) 2005, 2009 John Wiseman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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

Maintainer

John Wiseman <jjwiseman@yahoo.com>

Author

John Wiseman <jjwiseman@yahoo.com>

MIT

Description

A Lisp library for computing differences between sequences.

Long Description

A Lisp library for computing differences between sequences. Based on Python’s difflib module.

Version

0.2

Source

cl-difflib.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.

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

### 3.1 Lisp

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

#### 3.1.1 cl-difflib.asd

Location

cl-difflib.asd

Systems

cl-difflib (system)

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

#### 3.1.2 cl-difflib/package.lisp

Parent

cl-difflib (system)

Location

package.lisp

Packages

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

#### 3.1.3 cl-difflib/difflib.lisp

Dependency

package.lisp (file)

Parent

cl-difflib (system)

Location

difflib.lisp

Exported Definitions
Internal Definitions

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

### 3.2 Other

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

Parent

cl-difflib (system)

Location

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

#### 3.2.2 cl-difflib/NEWS.txt

Parent

cl-difflib (system)

Location

NEWS.txt

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

## 4 Packages

Packages are listed by definition order.

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

### 4.1 difflib

Source

package.lisp (file)

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 Functions

Function: context-diff STREAM A B &key FROM-FILE TO-FILE FROM-FILE-DATE TO-FILE-DATE N TEST-FUNCTION JUNK-FUNCTION
Package
Source

difflib.lisp (file)

Function: get-close-matches WORD POSSIBILITIES &key MAX CUTOFF
Package
Source

difflib.lisp (file)

Function: group-opcodes OPCODES N
Package
Source

difflib.lisp (file)

Function: make-opcode &key (TAG TAG) (I1 I1) (I2 I2) (J1 J1) (J2 J2)
Package
Source

difflib.lisp (file)

Function: opcode-i1 INSTANCE
Function: (setf opcode-i1) VALUE INSTANCE
Package
Source

difflib.lisp (file)

Function: opcode-i2 INSTANCE
Function: (setf opcode-i2) VALUE INSTANCE
Package
Source

difflib.lisp (file)

Function: opcode-j1 INSTANCE
Function: (setf opcode-j1) VALUE INSTANCE
Package
Source

difflib.lisp (file)

Function: opcode-j2 INSTANCE
Function: (setf opcode-j2) VALUE INSTANCE
Package
Source

difflib.lisp (file)

Function: opcode-p OBJECT
Package
Source

difflib.lisp (file)

Function: opcode-range OPCODE
Package
Source

difflib.lisp (file)

Function: opcode-tag INSTANCE
Function: (setf opcode-tag) VALUE INSTANCE
Package
Source

difflib.lisp (file)

Function: opcode= OP1 OP2

Tests two opcodes for equality.

Package
Source

difflib.lisp (file)

Function: unified-diff STREAM A B &key FROM-FILE TO-FILE FROM-FILE-DATE TO-FILE-DATE N TEST-FUNCTION JUNK-FUNCTION
Package
Source

difflib.lisp (file)

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

#### 5.1.2 Generic functions

Generic Function: get-opcodes MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: get-opcodes (SELF sequence-matcher)
Generic Function: junk-function OBJECT
Generic Function: (setf junk-function) NEW-VALUE OBJECT
Package
Methods
Method: junk-function (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf junk-function) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: quick-similarity-ratio MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: quick-similarity-ratio (SELF sequence-matcher)
Generic Function: sequence-a OBJECT
Generic Function: (setf sequence-a) NEW-VALUE OBJECT
Package
Methods
Method: sequence-a (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf sequence-a) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: sequence-b OBJECT
Generic Function: (setf sequence-b) NEW-VALUE OBJECT
Package
Methods
Method: sequence-b (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf sequence-b) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: set-sequence-a MATCHER SEQ &optional FORCE-P
Package
Source

difflib.lisp (file)

Methods
Method: set-sequence-a (SELF sequence-matcher) A &optional FORCE-P
Generic Function: set-sequence-b MATCHER SEQ &optional FORCE-P
Package
Source

difflib.lisp (file)

Methods
Method: set-sequence-b (SELF sequence-matcher) B &optional FORCE-P
Generic Function: set-sequences MATCHER SEQ-A SEQ-B &optional FORCE-P
Package
Source

difflib.lisp (file)

Methods
Method: set-sequences (SELF sequence-matcher) A B &optional FORCE-P
Generic Function: similarity-ratio MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: similarity-ratio (SELF sequence-matcher)

Returns a measure of the sequences’ similarity (a value in [0, 1]).

Generic Function: test-function OBJECT
Generic Function: (setf test-function) NEW-VALUE OBJECT
Package
Methods
Method: test-function (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf test-function) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: very-quick-similarity-ratio MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: very-quick-similarity-ratio (SELF sequence-matcher)

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

#### 5.1.3 Structures

Structure: opcode ()

A single instruction for modifying sequence A into sequence B, where TAG has the following possible values and meanings:

:REPLACE a[i1:i2] should be replaced by b[j1:j2] :DELETE a[i1:i2] should be deleted
:INSERT b[j2:j2] should be inserted
:EQUAL a[i1:i2] = b[j1:j2]

Package
Source

difflib.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: tag

opcode-tag (function)

Writers

(setf opcode-tag) (function)

Slot: i1

opcode-i1 (function)

Writers

(setf opcode-i1) (function)

Slot: i2

opcode-i2 (function)

Writers

(setf opcode-i2) (function)

Slot: j1

opcode-j1 (function)

Writers

(setf opcode-j1) (function)

Slot: j2

opcode-j2 (function)

Writers

(setf opcode-j2) (function)

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

#### 5.1.4 Classes

Class: sequence-matcher ()

The sequence-matcher class compares pairs of
sequences. The main restriction is that sequence elements must be hashable (use :test-function to specify the type of hashtable).

Package
Source

difflib.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: a
Initargs

:a

sequence-a (generic function)

Writers

(setf sequence-a) (generic function)

Slot: b
Initargs

:b

sequence-b (generic function)

Writers

(setf sequence-b) (generic function)

Slot: junk-function
Initargs

:junk-function

junk-function (generic function)

Writers

(setf junk-function) (generic function)

Slot: test-function
Initargs

:test-function

Initform

(function eql)

test-function (generic function)

Writers

(setf test-function) (generic function)

Slot: b-junk-function

b-junk-function (generic function)

Writers

(setf b-junk-function) (generic function)

Slot: b2j

b2j (generic function)

Writers

(setf b2j) (generic function)

Slot: b-popular-function

b-popular-function (generic function)

Writers

(setf b-popular-function) (generic function)

Slot: opcodes

opcodes (generic function)

Writers

(setf opcodes) (generic function)

Slot: matching-blocks

matching-blocks (generic function)

Writers

(setf matching-blocks) (generic function)

Slot: full-b-count

full-b-count (generic function)

Writers

(setf full-b-count) (generic function)

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

### 5.2 Internal definitions

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

#### 5.2.1 Macros

Macro: do-range (VAR START-FORM END-FORM &optional RESULT-FORM) &body BODY

Iterates VAR through the range of integers in [START-FORM, END-FORM). Returns the value of END-FORM (at the time END-FORM is evaluated, VAR is bound to the value of END-FORM.

(do-range (i 10 (length s))
(print (elt s i)))

Package
Source

difflib.lisp (file)

Macro: enumerate (INDEX-VAR ELT-VAR SEQUENCE &optional RESULT-FORM) &body BODY

Iterates over a sequence while keeping track of an index.

(enumerate (i e ’(a b c))
(format T "~&~S ~S" i e))
=>
1 a
2 b
3 c

Package
Source

difflib.lisp (file)

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

#### 5.2.2 Functions

Function: calculate-similarity-ratio MATCHES LENGTH
Package
Source

difflib.lisp (file)

Function: copy-opcode INSTANCE
Package
Source

difflib.lisp (file)

Function: has-key KEY HASH

Checks whether a key value is present in a hash table.

Package
Source

difflib.lisp (file)

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

#### 5.2.3 Generic functions

Generic Function: b-junk-function OBJECT
Generic Function: (setf b-junk-function) NEW-VALUE OBJECT
Package
Methods
Method: b-junk-function (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf b-junk-function) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: b-popular-function OBJECT
Generic Function: (setf b-popular-function) NEW-VALUE OBJECT
Package
Methods
Method: b-popular-function (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf b-popular-function) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: b2j OBJECT
Generic Function: (setf b2j) NEW-VALUE OBJECT
Package
Methods
Method: b2j (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf b2j) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: chain-b MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: chain-b (SELF sequence-matcher)
Generic Function: find-longest-match MATCHER ALO AHI BLO BHI
Package
Source

difflib.lisp (file)

Methods
Method: find-longest-match (SELF sequence-matcher) ALO AHI BLO BHI
Generic Function: full-b-count OBJECT
Generic Function: (setf full-b-count) NEW-VALUE OBJECT
Package
Methods
Method: full-b-count (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf full-b-count) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: get-matching-blocks MATCHER
Package
Source

difflib.lisp (file)

Methods
Method: get-matching-blocks (SELF sequence-matcher)
Generic Function: helper MATCHER ALO AHI BLO BHI ANSWER
Package
Source

difflib.lisp (file)

Methods
Method: helper (SELF sequence-matcher) ALO AHI BLO BHI ANSWER
Generic Function: matching-blocks OBJECT
Generic Function: (setf matching-blocks) NEW-VALUE OBJECT
Package
Methods
Method: matching-blocks (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf matching-blocks) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

Generic Function: opcodes OBJECT
Generic Function: (setf opcodes) NEW-VALUE OBJECT
Package
Methods
Method: opcodes (SEQUENCE-MATCHER sequence-matcher)

Source

difflib.lisp (file)

Method: (setf opcodes) NEW-VALUE (SEQUENCE-MATCHER sequence-matcher)

automatically generated writer method

Source

difflib.lisp (file)

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

## Appendix A Indexes

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

### A.1 Concepts

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

### A.2 Functions

Jump to: (   B   C   D   E   F   G   H   J   M   O   Q   S   T   U   V
Jump to: (   B   C   D   E   F   G   H   J   M   O   Q   S   T   U   V

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