The cl-difflib Reference Manual

Table of Contents

The cl-difflib Reference Manual

This is the cl-difflib Reference Manual, version 0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:42:37 2021 GMT+0.

1 Introduction

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.)

MIT License

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.

2 Systems

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

2.1 cl-difflib

Maintainer

John Wiseman <jjwiseman@yahoo.com>

Author

John Wiseman <jjwiseman@yahoo.com>

License

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

• package.lisp (file)
• difflib.lisp (file)
• license.txt (file)
• news.txt (file)

3 Files

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

3.1 Lisp

3.1.1 cl-difflib.asd

Location

cl-difflib.asd

Systems

cl-difflib (system)

3.1.2 cl-difflib/package.lisp

Parent

cl-difflib (system)

Location

package.lisp

Packages

difflib

3.1.3 cl-difflib/difflib.lisp

Dependency

package.lisp (file)

Parent

cl-difflib (system)

Location

difflib.lisp

Exported Definitions

• context-diff (function)
• get-close-matches (function)
• get-opcodes (generic function)
• get-opcodes (method)
• group-opcodes (function)
• junk-function (method)
• (setf junk-function) (method)
• make-opcode (function)
• opcode (structure)
• opcode-i1 (function)
• (setf opcode-i1) (function)
• opcode-i2 (function)
• (setf opcode-i2) (function)
• opcode-j1 (function)
• (setf opcode-j1) (function)
• opcode-j2 (function)
• (setf opcode-j2) (function)
• opcode-p (function)
• opcode-range (function)
• opcode-tag (function)
• (setf opcode-tag) (function)
• opcode= (function)
• quick-similarity-ratio (generic function)
• quick-similarity-ratio (method)
• sequence-a (method)
• (setf sequence-a) (method)
• sequence-b (method)
• (setf sequence-b) (method)
• sequence-matcher (class)
• set-sequence-a (generic function)
• set-sequence-a (method)
• set-sequence-b (generic function)
• set-sequence-b (method)
• set-sequences (generic function)
• set-sequences (method)
• similarity-ratio (generic function)
• similarity-ratio (method)
• test-function (method)
• (setf test-function) (method)
• unified-diff (function)
• very-quick-similarity-ratio (generic function)
• very-quick-similarity-ratio (method)

Internal Definitions

• b-junk-function (method)
• (setf b-junk-function) (method)
• b-popular-function (method)
• (setf b-popular-function) (method)
• b2j (method)
• (setf b2j) (method)
• calculate-similarity-ratio (function)
• chain-b (generic function)
• chain-b (method)
• copy-opcode (function)
• do-range (macro)
• enumerate (macro)
• find-longest-match (generic function)
• find-longest-match (method)
• full-b-count (method)
• (setf full-b-count) (method)
• get-matching-blocks (generic function)
• get-matching-blocks (method)
• has-key (function)
• helper (generic function)
• helper (method)
• matching-blocks (method)
• (setf matching-blocks) (method)
• opcodes (method)
• (setf opcodes) (method)

3.2 Static

3.2.1 cl-difflib/LICENSE.txt

Parent

cl-difflib (system)

Location

LICENSE.txt

3.2.2 cl-difflib/NEWS.txt

Parent

cl-difflib (system)

Location

NEWS.txt

4 Packages

Packages are listed by definition order.

4.1 difflib

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• context-diff (function)
• get-close-matches (function)
• get-opcodes (generic function)
• get-opcodes (method)
• group-opcodes (function)
• junk-function (generic function)
• junk-function (method)
• (setf junk-function) (method)
• (setf junk-function) (generic function)
• make-opcode (function)
• opcode (structure)
• opcode-i1 (function)
• (setf opcode-i1) (function)
• opcode-i2 (function)
• (setf opcode-i2) (function)
• opcode-j1 (function)
• (setf opcode-j1) (function)
• opcode-j2 (function)
• (setf opcode-j2) (function)
• opcode-p (function)
• opcode-range (function)
• opcode-tag (function)
• (setf opcode-tag) (function)
• opcode= (function)
• quick-similarity-ratio (generic function)
• quick-similarity-ratio (method)
• sequence-a (generic function)
• sequence-a (method)
• (setf sequence-a) (method)
• (setf sequence-a) (generic function)
• sequence-b (generic function)
• sequence-b (method)
• (setf sequence-b) (method)
• (setf sequence-b) (generic function)
• sequence-matcher (class)
• set-sequence-a (generic function)
• set-sequence-a (method)
• set-sequence-b (generic function)
• set-sequence-b (method)
• set-sequences (generic function)
• set-sequences (method)
• similarity-ratio (generic function)
• similarity-ratio (method)
• test-function (generic function)
• test-function (method)
• (setf test-function) (method)
• (setf test-function) (generic function)
• unified-diff (function)
• very-quick-similarity-ratio (generic function)
• very-quick-similarity-ratio (method)

Internal Definitions

• b-junk-function (generic function)
• b-junk-function (method)
• (setf b-junk-function) (method)
• (setf b-junk-function) (generic function)
• b-popular-function (generic function)
• b-popular-function (method)
• (setf b-popular-function) (method)
• (setf b-popular-function) (generic function)
• b2j (generic function)
• b2j (method)
• (setf b2j) (method)
• (setf b2j) (generic function)
• calculate-similarity-ratio (function)
• chain-b (generic function)
• chain-b (method)
• copy-opcode (function)
• do-range (macro)
• enumerate (macro)
• find-longest-match (generic function)
• find-longest-match (method)
• full-b-count (generic function)
• full-b-count (method)
• (setf full-b-count) (method)
• (setf full-b-count) (generic function)
• get-matching-blocks (generic function)
• get-matching-blocks (method)
• has-key (function)
• helper (generic function)
• helper (method)
• matching-blocks (generic function)
• matching-blocks (method)
• (setf matching-blocks) (method)
• (setf matching-blocks) (generic function)
• opcodes (generic function)
• opcodes (method)
• (setf opcodes) (method)
• (setf opcodes) (generic function)

5 Definitions

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

5.1 Exported definitions

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

difflib

Source

difflib.lisp (file)

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

Package

difflib

Source

difflib.lisp (file)

Function: group-opcodes OPCODES N

Package

difflib

Source

difflib.lisp (file)

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

Package

difflib

Source

difflib.lisp (file)

Function: opcode-i1 INSTANCE

Function: (setf opcode-i1) VALUE INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: opcode-i2 INSTANCE

Function: (setf opcode-i2) VALUE INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: opcode-j1 INSTANCE

Function: (setf opcode-j1) VALUE INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: opcode-j2 INSTANCE

Function: (setf opcode-j2) VALUE INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: opcode-p OBJECT

Package

difflib

Source

difflib.lisp (file)

Function: opcode-range OPCODE

Package

difflib

Source

difflib.lisp (file)

Function: opcode-tag INSTANCE

Function: (setf opcode-tag) VALUE INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: opcode= OP1 OP2

Tests two opcodes for equality.

Package

difflib

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

difflib

Source

difflib.lisp (file)

5.1.2 Generic functions

Generic Function: get-opcodes MATCHER

Package

difflib

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

difflib

Methods

Method: junk-function (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

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

difflib

Methods

Method: sequence-a (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

Methods

Method: sequence-b (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

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

difflib

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

difflib

Source

difflib.lisp (file)

Methods

Method: set-sequences (SELF sequence-matcher) A B &optional FORCE-P

Generic Function: similarity-ratio MATCHER

Package

difflib

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

difflib

Methods

Method: test-function (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

Source

difflib.lisp (file)

Methods

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

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

difflib

Source

difflib.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: tag

Readers

opcode-tag (function)

Writers

(setf opcode-tag) (function)

Slot: i1

Readers

opcode-i1 (function)

Writers

(setf opcode-i1) (function)

Slot: i2

Readers

opcode-i2 (function)

Writers

(setf opcode-i2) (function)

Slot: j1

Readers

opcode-j1 (function)

Writers

(setf opcode-j1) (function)

Slot: j2

Readers

opcode-j2 (function)

Writers

(setf opcode-j2) (function)

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

difflib

Source

difflib.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• very-quick-similarity-ratio (method)
• quick-similarity-ratio (method)
• similarity-ratio (method)
• get-opcodes (method)
• helper (method)
• get-matching-blocks (method)
• find-longest-match (method)
• chain-b (method)
• set-sequence-b (method)
• set-sequence-a (method)
• set-sequences (method)
• initialize-instance (method)
• full-b-count (method)
• full-b-count (method)
• matching-blocks (method)
• matching-blocks (method)
• opcodes (method)
• opcodes (method)
• b-popular-function (method)
• b-popular-function (method)
• b2j (method)
• b2j (method)
• b-junk-function (method)
• b-junk-function (method)
• test-function (method)
• test-function (method)
• junk-function (method)
• junk-function (method)
• sequence-b (method)
• sequence-b (method)
• sequence-a (method)
• sequence-a (method)

Direct slots

Slot: a

Initargs

:a

Readers

sequence-a (generic function)

Writers

(setf sequence-a) (generic function)

Slot: b

Initargs

:b

Readers

sequence-b (generic function)

Writers

(setf sequence-b) (generic function)

Slot: junk-function

Initargs

:junk-function

Readers

junk-function (generic function)

Writers

(setf junk-function) (generic function)

Slot: test-function

Initargs

:test-function

Initform

(function eql)

Readers

test-function (generic function)

Writers

(setf test-function) (generic function)

Slot: b-junk-function

Readers

b-junk-function (generic function)

Writers

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

Slot: b2j

Readers

b2j (generic function)

Writers

(setf b2j) (generic function)

Slot: b-popular-function

Readers

b-popular-function (generic function)

Writers

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

Slot: opcodes

Readers

opcodes (generic function)

Writers

(setf opcodes) (generic function)

Slot: matching-blocks

Readers

matching-blocks (generic function)

Writers

(setf matching-blocks) (generic function)

Slot: full-b-count

Readers

full-b-count (generic function)

Writers

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

5.2 Internal definitions

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

difflib

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

difflib

Source

difflib.lisp (file)

5.2.2 Functions

Function: calculate-similarity-ratio MATCHES LENGTH

Package

difflib

Source

difflib.lisp (file)

Function: copy-opcode INSTANCE

Package

difflib

Source

difflib.lisp (file)

Function: has-key KEY HASH

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

Package

difflib

Source

difflib.lisp (file)

5.2.3 Generic functions

Generic Function: b-junk-function OBJECT

Generic Function: (setf b-junk-function) NEW-VALUE OBJECT

Package

difflib

Methods

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

automatically generated reader method

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

difflib

Methods

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

automatically generated reader method

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

difflib

Methods

Method: b2j (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

Source

difflib.lisp (file)

Methods

Method: chain-b (SELF sequence-matcher)

Generic Function: find-longest-match MATCHER ALO AHI BLO BHI

Package

difflib

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

difflib

Methods

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

automatically generated reader method

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

difflib

Source

difflib.lisp (file)

Methods

Method: get-matching-blocks (SELF sequence-matcher)

Generic Function: helper MATCHER ALO AHI BLO BHI ANSWER

Package

difflib

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

difflib

Methods

Method: matching-blocks (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

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

difflib

Methods

Method: opcodes (SEQUENCE-MATCHER sequence-matcher)

automatically generated reader method

Source

difflib.lisp (file)

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

automatically generated writer method

Source

difflib.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types