Commit ca622c4d authored by Marco Antoniotti's avatar Marco Antoniotti

Updated .gitiginore and removed tracking of 'docs' folder.

parent 8ee554e6
......@@ -5,4 +5,5 @@
THUM*.DBE
docs/*html*/*
docs/
dbdb.lisp
<html>
<head>
<title>CL Control Flow</title>
<link rel="stylesheet" href="main.css">
</head>
<body marginheight="0" marginwidth="0" leftmargin="0" topmargin="0" bgcolor="#ffffff">
<table border="0" cellpadding="0" cellspacing="0" width="100%" height="100%" vspace="0" hspace="0">
<tr>
<td colspan="3">
<div class="header"
style="font-family:=Verdana,Arial,Helvetica; font-size: 18px; color: #41286f;">
<strong><i>CL Extensions: CONTROL FLOW</i><string>
<div class="navigation">
<a href="index.html" class="navigation-link-selected">Home</a>
| <a href="downloads.html" class="navigation-link">Downloads</a>
| <a href="links.html" class="navigation-link">Links</a>
</div>
</div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
<div class="middle-bar"><img src="images/shim.gif" height="5" width="1"></div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
</td>
</tr>
<tr height="100%">
<td height="100%">&nbsp;</td>
<td valign="top" width="80%" height="100%">
<div class="content">
<div class="text" style="padding-top: 10px;">
<h1>Control Flow</h1>
<p>In order to make the use of the UNIFICATION library easier, a few
utility macros are provided. The macros MATCH, MATCHING, and
MATCH-CASE can be used to unify two (or more) objects and then to
build a lexical environment where the variables present in the to
objects (or templates) are bound to the values resulting from the
application of UNIFY.</p>
<p>
<ul>
<li>MATCH is a "single shot" macro. It does one unification and
executes forms in an appropriate lexical environment.</li>
<li>MATCH-CASE is equivalent to CASE. It tries to match a single
object (or template) against a set of clauses. The forms associated
to the first clause for which there is a successful unification, are
then executed within an appropriate lexical environment.</li>
<li>MATCHING is equivalent to COND. Each clause contains a
<em>head</em> consisting of two objects to be unified. The first
clause whose head unifies sucessfully has its associated forms
executed within an appropriate lexical environment.</li>
</ul>
</p>
<p>There are also the macro MATCHF and MATCHF-CASE, which do not
evaluate the pattern; they can be used to produce more streamlined
code.</p>
<h1>Examples</h1>
<p>These macros allow the construction of interesting <em>pattern
matching</em> like code.</p>
<p>
<pre>
(defun factorial (x)
(<b>match-case</b> (x)
(0 1)
(#T(number ?n) (* ?n (factorial (1- ?n))))
(otherwise (error "Incorrect match for ~S." x))))
</pre>
</p>
<p>Or consider the more interesting piece of code from a not-so
hypothetical Red-Black tree implementation (<em>cfr.</em>&nbsp;[<a
href="#O98">O98</a>].) The function BALANCE is the key part of the
rebalancing act played by Red-Black trees.</p>
<p>
<pre>
(defstruct (tree-node (:conc-name tn-)
(:constructor mk-tn (color left elem right)))
color
left
elem
right)
(defun balance (&rest balancing-arguments)
(<b>match-case</b> (balancing-arguments)
((:black #T(tree-node tn-color :red
tn-left #T(tree-node tn-color :red
tn-left ?a
tn-elem ?x
tn-right ?b)
tn-elem ?y
tn-right ?c)
?z
?d)
(mk-tn :red (mk-tn :black ?a ?x ?b) ?y (mk-tn :black ?c ?z ?d)))
((:black #T(tree-node tn-color :red
tn-left ?a
tn-elem ?x
tn-right #T(tree-node tn-color :red
tn-left ?b
tn-elem ?y
tn-right ?c))
?z
?d)
(mk-tn :red (mk-tn :black ?a ?x ?b) ?y (mk-tn :black ?c ?z ?d)))
((:black ?a
?x
#T(tree-node tn-color :red
tn-left #T(tree-node tn-color :red
tn-left ?b
tn-elem ?y
tn-right ?c)
tn-elem ?z
tn-right ?d))
(mk-tn :red (mk-tn :black ?a ?x ?b) ?y (mk-tn :black ?c ?z ?d)))
((:black ?a
?x
#T(tree-node tn-color :red
tn-left ?b
tn-elem ?y
tn-left #T(tree-node tn-color :red
tn-left ?c
tn-elem ?z
tn-right ?d)))
(mk-tn :red (mk-tn :black ?a ?x ?b) ?y (mk-tn :black ?c ?z ?d)))
((?color ?left ?elem ?right)
(mk-tn ?color ?left ?elem ?right))))
</pre>
</p>
<p>This version of BALANCE is more verbose than the one given in [<a
href="#O98">O98</a>], but it preserves the general elegance of the
ML implementation.</p>
<h1>Control Flow Dictionary</h1>
<ul>
<li><a href="match-macro.html"><i>Macros</i> <b>MATCH</b> and <b>MATCHF</b></a>
<li><a href="match-case-macro.html"><i>Macros</i> <b>MATCH-CASE</b>
and <b>MATCHF-CASE</b></a>
<li><a href="matching-macro.html"><i>Macro</i> <b>MATCHING</b></a>
</ul>
<h1>Notes</h1>
<h2>Other Forms</h2>
<p>It would be obvious to add the macros EMATCH-CASE and
CMATCH-CASE, for symmetry with ECASE and CCASE. Also, MATCHING
could be renamed to MATCH-COND.</p>
<h2>Current Implementation Details</h2>
<p>The current implementations of MATCHING and MATCH-CASE do not
handle user supplied environments yet.</p>
<h2>References</h2>
<p>
<a name="O98">[O98]</a> C. Okasaki, <i>Purely Functional Data
Structures</i>, Cambridge University Press, 1998.
<!--
;;; Copyright (c) 2004-2013 Marco Antoniotti, All rigths reserved.
;;;
;;; Permission to use, modify, and redistribute this code is hereby
;;; granted.
;;; The code is provided AS IS with NO warranty whatsoever. The author
;;; will not be held liable etc etc etc etc etc.
-->
<!--
<h2>Site Map</h2>
<p>Enjoy!</p>
<hr>
<p>Questions? Queries? Suggestions? Comments? Please direct them
at <a href="mailto:marcoxa_PROVA_A_SPAMMARME@alu.org">me</a>.
</p>
-->
</div>
</div>
</td>
<!-- <td height="100%">&nbsp;</td> -->
</tr>
<tr height="100%">
<td height="100%">&nbsp;</td>
<td valign="top" width="80%" height="100%">
<div class="content">
<div class="text" style="padding-top: 10px;">
<!-- <h1>News</h1>
<p>News in chronological order, most recent on top.
</p>
<ul>
<li><strong>2004-10-30</strong><br>
Document created
</li>
</ul>
-->
</div>
</div>
</td>
<td height="100%">&nbsp;</td>
</tr>
<tr>
<td colspan="3" valign="bottom" align="right">
<div class="copyright">
&copy; 2003-2013, Marco Antoniotti, all rights reserved.
</div>
</td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>CL Unification Dictionary</title>
<link rel="stylesheet" href="main.css">
</head>
<body marginheight="0" marginwidth="0" leftmargin="0" topmargin="0" bgcolor="#ffffff">
<table border="0" cellpadding="0" cellspacing="0" width="100%" height="100%" vspace="0" hspace="0">
<tr>
<td colspan="3">
<div class="header"
style="font-family:=Verdana,Arial,Helvetica; font-size: 18px; color: #41286f;">
<strong><i>CL Extensions: UNIFICATION Dictionary</i><string>
<div class="navigation">
<a href="index.html" class="navigation-link">Home</a>
| <a href="index.html" class="navigation-link">Previous</a>
| <a href="index.html" class="navigation-link">Next</a>
| <a href="downloads.html" class="navigation-link">Downloads</a>
| <a href="links.html" class="navigation-link">Links</a>
</div>
</div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
<div class="middle-bar"><img src="images/shim.gif" height="5" width="1"></div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
</td>
</tr>
<tr height="100%">
<td height="100%">&nbsp;</td>
<td valign="top" width="80%" height="100%">
<div class="content">
<div class="text" style="padding-top: 10px;">
<h1>Common Lisp Extensions: UNIFICATION Dictionary</h1>
<p>The notion of <em>unification</em> originated in the field of
formal logic (e.g. Robinson, 1956) and has been used extensively in
Computer Science and Programming Languages. <strong>Prolog</strong>
obviously uses the full power of unification, however, unification
is also at the core of <em>type checking</em> algorithms in the
tradition of Milner's, and a limited form - <em>pattern
matching</em> - is available to the user in languages of the ML and
Haskell family.</p>
<p>The library presented in these pages provides a full blown
<em>unification framework</em> for <strong>Common Lisp</strong>.</p>
<p>Writing a pattern matcher or a an unifier in <strong>Common
Lisp</strong> is easy, as long as we limit ourselves to manipulate
only ATOMs and CONSes.</p>
<p>Alas, it would be much nicer if we could manipulated arbitrary
<strong>Common Lisp</strong> objects as the ML programmer can with
arbitrary ML objects.<p>
<p>The library presented here is the first one (to the best of the
author's knowledge) that is capable of manipulating arbitrary
<strong>Common Lisp</strong> objects.</p>
<p>The hope is that this library could be incorporated directly in
an implementation in order to provide better type checking.</p>
<p>This should not come as a surprise, as a compiler like CMUCL does
include a type inference engine, which does very similar things.</p>
<h2>Unification Basics</h2>
<p>The unification process makes sure that two <em>object
descriptions</em> containing some <em>holes</em>
- i.e. <em>variables</em> - can be made equal (almost in the EQUALP
sense) by assigning <em>consistent</em> values to the variables
involved.</p>
<p>Suppose we had a function U performing unification and returning
a set of <em>variable assignments</em>, often called a
<em>substitution</em>. A very simple
example involving the unification of two numbers could be
<pre>
<b>U</b>(42, 42) ==> {}
</pre>
The two numbers are EQL, so no variable is involved and the empty
substitution is returned.
<pre>
<b>U</b>(42, 123) ==> &lt;unification failure&gt;
</pre>
The two numbers are not EQL, so the unification fails.
<pre>
<b>U</b>(42, x) ==> {x -> 42}
</pre>
The only way to make the unification process to succeed is to bind
the value 42 to the variable <code>x</code>.</p>
<p>The UNIFICATION library defines all the necessary functions and a
<em>unification sub-language</em> to handle most of <strong>Common
Lisp</strong>.</p>
<h2>UNIFICATION Library</h2>
<p>The UNIFICATION library has one main entry point, the generic function
UNIFY, and a sub-language definition that allows us to talk about
<strong>Common Lisp</strong> objects.</p>
<p>The UNIFY generic function has the following signature:
<pre>
<b>unify</b> <i>x</i> <i>y</i> &amp;optional <i>substitution</i>
</pre>
Where <code><i>x</i></code> and <code><i>y</i></code> are either
arbitrary <strong>Common Lisp</strong> objects, <em>variables</em>,
or <em>object templates</em>. These items constitute the so-called
<em>extended terms</em> manipulated by the unification
machinery.</p>
<p><em>Variables</em> are symbols with a <code>#\?</code> as the
first character of the name. This is a rather traditional choice,
although a different one based on quoted symbols is possible.
Therefore, the following are examples of variables.
<pre>
?A ?s ?qwe ?42z ?a-variable-with-a-very-long-name ?_
</pre>
There are two special variables, <code>?_</code> and <code>_</code>,
which are used as anonymous place holders, they match anything, but
never appear in a substitution.</p>
<p>Hence, the above examples result in the following
<pre>
cl-prompt&gt; (<b>unify</b> 42 42)
<i>#&lt;EMPTY ENVIRONMENT xxxxxx&gt;</i>
</pre>
<pre>
cl-prompt&gt; (<b>unify</b> 42 123)
==> error: unification failure
</pre>
<pre>
cl-prompt&gt; (<b>unify</b> 42 ?x)
<i>#&lt;ENVIRONMENT xxxxxx&gt;</i>
cl-prompt&gt; (<b>find-variable-value</b> '?x *)
<i>42</i>
</pre>
</p>
Where FIND-VARIABLE-VALUE is the accessor used to find the value of
a variable in a substitution.</p>
<p>As a more complicated example, consider the usual CONS based
unification
<pre>
cl-prompt&gt; (<b>unify</b> '(foo (bar frobboz) ?baz) '(foo ?gnao 42))
<i>#&lt;ENVIRONMENT xxxxxx&gt;</i>
cl-prompt&gt; (<b>find-variable-value</b> '?gnao *)
<i>(BAR FROBBOZ)</i>
cl-prompt&gt; (<b>find-variable-value</b> '?baz **)
<i>42</i>
</pre>
<p>Of course note the following behavior
<pre>
cl-prompt&gt; (<b>unify</b> '(foo ?x 42) '(foo 42 ?x))
<i>#&lt;ENVIRONMENT xxxxxx&gt;</i>
cl-prompt&gt; (<b>unify</b> '(foo ?x 42) '(foo baz ?x))
==> error: unification failure
</pre>
</p>
<p>UNIFY works also on arrays and vectors. Strings are treated as
atomic objects
<pre>
cl-prompt&gt; (<b>unify</b> #(1 2 3) #(1 ?x ?y))
<i>#&lt;ENVIRONMENT xxxxxx&gt;</i>
cl-prompt&gt; (<b>find-variable-value</b> '?x *)
<i>2</i>
</pre>
<pre>
cl-prompt&gt; (<b>unify</b> #2A((1 2 3) (a s ?z)) #2A((1 ?x ?y) (a s d)))
<i>#&lt;ENVIRONMENT xxxxxx&gt;</i>
cl-prompt&gt; (<b>find-variable-value</b> '?z *)
<i>D</i>
</pre>
</p>
<p>So far so good, but how can you unify two structures? First of
all there is no portable way (yet) to list all the slots of a given
structure. Secondly, by allowing the unification of arbitrary
CONSes, we have created a short-circuit in the unification
machinery.</p>
<p>Dealing with object instances raises similar problems.</p>
<p>Suppose we have the following definition
<pre>
(defstruct foo a s d)
</pre>
The straighforward
<pre>
(<b>unify</b> #S(FOO A 42 S NIL D NIL) (make-foo :a 42))
</pre>
cannot be built portably, besides, we do not even have the equivalent of the
<code>#S(...)</code> notation for regular CLOS objects. Moreover we want
to do other things with other data types.</p>
<p>A simple solution is to define a <em>template sub-language</em>
to express unifications between structure objects or standard
objects (and other data types as well.) Nevertheless, the
definition of such sub-language cannot be CONS based, because in
such case, we would conflate arbitrary CONSes and the expressions of
the sub-language.</p>
<p>To circumvent this problem we resort to the usual trick a ML
programmer uses to placate the type-checker: we introduce an
"intermediate" data type. Essentially the following
<pre>
(defclass <b>template</b> ()
((spec :accessor template-spec :type (or cons symbol number) ...)))
</pre>
</p>
<p>The TEMPLATE class is accompanied by a reader macro
(<code>#T</code> for <em>template</em>, or <em>type</em>, with an
abuse of language) and an
appropriate PRINT-OBJECT method. The <code>#T</code> reader macro
expands as
<pre>
<b>#T</b><i>something</i> ==> (make-instance 'template :spec <i>something</i>)
</pre>
With this infrastructure we can
express the unification of the FOO instance as
<pre>
(<b>unify</b> #(FOO A 42 S NIL D NIL) <b>#T(foo foo-a 42)</b>)
</pre>
I.e. we use the actual structure accessor FOO-A to get to the the
value of the slot A in a FOO. This is an example of the template
language.</p>
<p>A more interesting example, which involves vectors is the
following
<pre>
cl-prompt> (<b>unify</b> #(1 2 3 4 5) <b>#T(vector 1 ?x &amp;rest ?rest)</b>) ; You get the idea...
<i>#&lt;ENVIRONMENT xxxxxxx&gt;</i>
cl-prompt> (<b>find-variable-value</b> '?rest *)
<i>#(3 4 5)</i>
</pre>
I.e. we have a DESTRUCTURING-BIND on steroids.<p>
<p>Note that separataing the templates is necessary if we want to do
something like
<pre>
cl-prompt> (<b>unify</b> '(1 2 3 4 5) <b>#T(list 1 ?x &amp;rest ?rest)</b>)
<i>#&lt;ENVIRONMENT xxxxxxx&gt;</i>
cl-prompt> (<b>find-variable-value</b> '?rest *)
<i>(3 4 5)</i>
</pre>
Without the template denoted by <code>#T(list ...)</code> the
unifier would have been utterly confused.</p>
<p>In the following the full extent of the UNIFICATION facility is
described in its main components.
</p>
<h2><a href="substitutions.html">Unifying Substitutions</a></h2>
<h2><a href="templates.html">The Template Sub-language</a></h2>
<h2><a href="templates.html">Control Flow</a></h2>
<h2><a href="unification-dictionary.html">The UNIFICATION Dictionary</a></h2>
<!--
;;; Copyright (c) 2004-2015 Marco Antoniotti, All rigths reserved.
;;;
;;; Permission to use, modify, and redistribute this code is hereby
;;; granted.
;;; The code is provided AS IS with NO warranty whatsoever. The author
;;; will not be held liable etc etc etc etc etc.
-->
<h2>Site Map</h2>
<p>Enjoy!</p>
<hr>
<p>Questions? Queries? Suggestions? Comments? Please direct them
at <a href="mailto:marcoxa_PROVA_A_SPAMMARME@alu.org">me</a>.
</p>
</div>
</div>
</td>
<!-- <td height="100%">&nbsp;</td> -->
</tr>
<tr height="100%">
<td height="100%">&nbsp;</td>
<td valign="top" width="80%" height="100%">
<div class="content">
<div class="text" style="padding-top: 10px;">
<!-- <h1>News</h1>
<p>News in chronological order, most recent on top.
</p>
<ul>
<li><strong>2004-05-05</strong><br>
Started the site.
</li>
</ul>
-->
</div>
</div>
</td>
<td height="100%">&nbsp;</td>
</tr>
<tr>
<td colspan="3" valign="bottom" align="right">
<div class="copyright">
&copy; 2003-2015, Marco Antoniotti, all rights reserved.
</div>
</td>
</tr>
</table>
</body>
</html>
<html>
<head>
<title>CL Unification: Class AREF-TEMPLATE</title>
<link rel="stylesheet" href="../main.css">
</head>
<body marginheight="0" marginwidth="0" leftmargin="0" topmargin="0" bgcolor="#ffffff">
<table border="0" cellpadding="0" cellspacing="0" width="100%" height="100%" vspace="0" hspace="0">
<tr>
<td colspan="3">
<div class="header"
style="font-family:=Verdana,Arial,Helvetica; font-size: 18px; color: #41286f;">
<strong><i>CL Unification: Class AREF-TEMPLATE</title></i></strong>
<div class="navigation">
<a href="index.html" class="navigation-link">Home</a>
| <a href="../unification-dictionary.html" class="navigation-link">Dictionary</a>
| <a href="element-template-class.html" class="navigation-link">Previous</a>
| <a href="elt-template-class.html" class="navigation-link">Next</a>
| <a href="downloads.html" class="navigation-link">Downloads</a>
| <a href="links.html" class="navigation-link">Links</a>
</div>
</div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
<div class="middle-bar"><img src="images/shim.gif" height="5" width="1"></div>
<div class="black-line"><img src="images/shim.gif" height="1" width="1"></div>
</td>
</tr>
<tr height="100%">
<td height="100%">&nbsp;</td>
<td valign="top" width="80%" height="100%">
<div class="content">
<div class="text" style="padding-top: 10px;">
<h1><i>Class</i> <strong>AREF-TEMPLATE</strong></h1>
<h2>Package:</h2>
<p><code>COMMON-LISP.EXTENSIONS.DATA-AND-CONTROL-FLOW.UNIFICATION</code></p>
<h2>Class Precedence List:</h2>
<p>
AREF-TEMPLATE, ELEMENT-TEMPLATE, EXPRESSION-TEMPLATE, TEMPLATE, STANDARD-OBJECT, T.
</p>
<h2>Known Subclasses:</h2>
<p>
None.
</p>
<h2>Slots:</h2>
<p>None.</p>
<h2>Description:</h2>
<p>The AREF-TEMPLATE class denotes those object that are used
to unify against a particular element of an ARRAY.</p>
<h3>Template Syntax:</h3>
<p>
<pre>
#T(<b>aref</b> (<i>index1</i> ... <i>indexN</i>) <i>item</i>)
</pre>
</p>
<p>
<pre>
#T(<b>aref</b> <i>index</i> <i>item</i>)
</pre>
</p>
<p>The AREF-TEMPLATE syntax denotes the <i>item</i> at
<i>index1</i> ... <i>indexN</i> of an ARRAY. An AREF-TEMPLATE must
be unified against a ARRAY object. <i>item</i> is <em>unified</em>
against the element extracted from the sequence object at
<i>index1</i> ... <i>indexN</i> by the standard function AREF.</p>
<p>The second form is a shorthand.</p>
<p>
<pre>
#T(<b>aref</b> <i>index</i> <i>item</i>) <==> #T(<b>aref</b> (<i>index</i>) <i>item</i>)
</pre>
</p>
<h2>Examples:</h2>
<p>
<pre>
cl-prompt> (setf e (unify #(0 1 42 3 4 5) #T(<b>aref</b> 2 ?x)))
#&lt;ENVIRONMENT xxx&gt;
cl-prompt> (find-variable-value '?x e)
42
cl-prompt> (setq e (unify #(0 1 42 3 4 5) #T(<b>aref</b> 42 ?x)))
--> Error: index 42 out of bounds.
cl-prompt> (setq e (unify 42 #T(<b>aref</b> 42 ?x)))
--> Error: UNIFICATION-FAILURE
cl-prompt> (setq e (unify "This is a string!" #T(<b>aref</b> 4 ?x)))
#&lt;ENVIRONMENT xxx&gt;
cl-prompt> (find-variable-value '?x e)
#\Space
cl-prompt> (setq e (unify #2A((1 0) (foo bar)) #T(<b>aref</b> (1 1) ?x)))
#&lt;ENVIRONMENT xxx&gt;
cl-prompt> (find-variable-value '?x e)
BAR