temperance/reference/index.html @ 0f6bab39c0f4 default tip

adopt: Update site.
author Steve Losh <steve@stevelosh.com>
date Thu, 13 Jun 2024 13:05:28 -0400
parents 7f39fe8a8012
children (none)
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title> API Reference / Temperance</title>
        <link rel="stylesheet" href="../_dmedia/pygments-clean.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">Temperance</a></h1></header>
                <div class="markdown">
<h1 id="api-reference"><a href="">API Reference</a></h1><p>The following is a list of all user-facing parts of Temperance.</p>
<p>If there are backwards-incompatible changes to anything listed here, they will
be noted in the changelog and the author will feel bad.</p>
<p>Anything not listed here is subject to change at any time with no warning, so
don't touch it.</p>
<div class="toc">
<ul>
<li><a href="#package-temperance">Package TEMPERANCE</a><ul>
<li><a href="#standard-database-variable">*STANDARD-DATABASE* (variable)</a></li>
<li><a href="#fact-macro">FACT (macro)</a></li>
<li><a href="#facts-macro">FACTS (macro)</a></li>
<li><a href="#finalize-logic-frame-function">FINALIZE-LOGIC-FRAME (function)</a></li>
<li><a href="#invoke-fact-function">INVOKE-FACT (function)</a></li>
<li><a href="#invoke-facts-function">INVOKE-FACTS (function)</a></li>
<li><a href="#invoke-prove-function">INVOKE-PROVE (function)</a></li>
<li><a href="#invoke-query-function">INVOKE-QUERY (function)</a></li>
<li><a href="#invoke-query-all-function">INVOKE-QUERY-ALL (function)</a></li>
<li><a href="#invoke-query-do-function">INVOKE-QUERY-DO (function)</a></li>
<li><a href="#invoke-query-find-function">INVOKE-QUERY-FIND (function)</a></li>
<li><a href="#invoke-query-for-function">INVOKE-QUERY-FOR (function)</a></li>
<li><a href="#invoke-query-map-function">INVOKE-QUERY-MAP (function)</a></li>
<li><a href="#invoke-rule-function">INVOKE-RULE (function)</a></li>
<li><a href="#make-database-function">MAKE-DATABASE (function)</a></li>
<li><a href="#pop-logic-frame-function">POP-LOGIC-FRAME (function)</a></li>
<li><a href="#prove-macro">PROVE (macro)</a></li>
<li><a href="#push-logic-frame-function">PUSH-LOGIC-FRAME (function)</a></li>
<li><a href="#push-logic-frame-with-macro">PUSH-LOGIC-FRAME-WITH (macro)</a></li>
<li><a href="#query-macro">QUERY (macro)</a></li>
<li><a href="#query-all-macro">QUERY-ALL (macro)</a></li>
<li><a href="#query-do-macro">QUERY-DO (macro)</a></li>
<li><a href="#query-find-macro">QUERY-FIND (macro)</a></li>
<li><a href="#query-for-macro">QUERY-FOR (macro)</a></li>
<li><a href="#query-map-macro">QUERY-MAP (macro)</a></li>
<li><a href="#reset-standard-database-function">RESET-STANDARD-DATABASE (function)</a></li>
<li><a href="#rule-macro">RULE (macro)</a></li>
<li><a href="#with-database-macro">WITH-DATABASE (macro)</a></li>
<li><a href="#with-fresh-database-macro">WITH-FRESH-DATABASE (macro)</a></li>
</ul>
</li>
</ul></div>
<h2 id="package-temperance">Package <code>TEMPERANCE</code></h2>
<h3 id="standard-database-variable"><code>*STANDARD-DATABASE*</code> (variable)</h3>
<p>The standard database used when <code>t</code> is supplied as a database designator.</p>
<h3 id="fact-macro"><code>FACT</code> (macro)</h3>
<div class="codehilite"><pre><span/>(FACT DATABASE FACT)
</pre></div>


<p>Add a logical fact to <code>database</code>.</p>
<p><code>fact</code> will be wrapped in <code>(quote ...)</code>.  If you need to dynamically construct
  facts at runtime, see <code>invoke-fact</code>.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(fact t (likes kim cats))
(fact t (likes sjl cats))
</pre></div>


<h3 id="facts-macro"><code>FACTS</code> (macro)</h3>
<div class="codehilite"><pre><span/>(FACTS DATABASE
  &amp;BODY
  FACTS)
</pre></div>


<p>Add zero or more logical facts to <code>database</code>.</p>
<p>Each fact in <code>facts</code> will be wrapped in <code>(quote ...)</code>.  If you need to
  dynamically construct facts at runtime, see <code>invoke-facts</code>.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(facts t
  (successor 0 1)
  (successor 1 2)
  (successor 2 3))
</pre></div>


<h3 id="finalize-logic-frame-function"><code>FINALIZE-LOGIC-FRAME</code> (function)</h3>
<div class="codehilite"><pre><span/>(FINALIZE-LOGIC-FRAME DATABASE)
</pre></div>


<p>Finalize the top logic frame of <code>database</code>'s logic stack.</p>
<p>An error will be signaled if the logic stack is empty or the top frame is
  already finalized.</p>
<h3 id="invoke-fact-function"><code>INVOKE-FACT</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-FACT DATABASE FACT)
</pre></div>


<p>Add a logical fact to <code>database</code>.</p>
<p>The <code>fact</code> macro is a nicer interface, but this function can be useful if you
  need to build rules dynamically at runtime.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(invoke-fact t '(successor 0 1))

(defun add-cat-lover (name)
  (invoke-fact t `(likes ,name cats)))
</pre></div>


<h3 id="invoke-facts-function"><code>INVOKE-FACTS</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-FACTS DATABASE &amp;REST FACTS)
</pre></div>


<p>Add zero or more logical facts to <code>database</code>.</p>
<p>The <code>facts</code> macro is a nicer interface, but this function can be useful if you
  need to build rules dynamically at runtime.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(invoke-facts t
              '(successor 0 1)
              '(successor 1 2)
              '(successor 2 3))
</pre></div>


<h3 id="invoke-prove-function"><code>INVOKE-PROVE</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-PROVE DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-function"><code>INVOKE-QUERY</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-all-function"><code>INVOKE-QUERY-ALL</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY-ALL DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-do-function"><code>INVOKE-QUERY-DO</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY-DO DATABASE FUNCTION &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-find-function"><code>INVOKE-QUERY-FIND</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY-FIND DATABASE PREDICATE &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-for-function"><code>INVOKE-QUERY-FOR</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY-FOR DATABASE VARIABLE &amp;REST TERMS)
</pre></div>


<h3 id="invoke-query-map-function"><code>INVOKE-QUERY-MAP</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-QUERY-MAP DATABASE FUNCTION &amp;REST TERMS)
</pre></div>


<h3 id="invoke-rule-function"><code>INVOKE-RULE</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-RULE DATABASE HEAD &amp;REST BODY)
</pre></div>


<p>Add a logical rule to <code>database</code> with the given <code>head</code> and <code>body</code>.</p>
<p>The <code>rule</code> macro is a nicer interface, but this function can be useful if you
  need to build rules dynamically at runtime.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>; Sally like anyone who likes cats
(invoke-rule t '(likes sally ?who)
  '(likes ?who cats))
</pre></div>


<h3 id="make-database-function"><code>MAKE-DATABASE</code> (function)</h3>
<div class="codehilite"><pre><span/>(MAKE-DATABASE)
</pre></div>


<p>Create and return a fresh database.</p>
<h3 id="pop-logic-frame-function"><code>POP-LOGIC-FRAME</code> (function)</h3>
<div class="codehilite"><pre><span/>(POP-LOGIC-FRAME DATABASE)
</pre></div>


<p>Pop off the top logic frame of <code>database</code>'s logic stack.</p>
<p>An error will be signaled if the logic stack is empty or the top frame is
  unfinalized.</p>
<h3 id="prove-macro"><code>PROVE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(PROVE DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="push-logic-frame-function"><code>PUSH-LOGIC-FRAME</code> (function)</h3>
<div class="codehilite"><pre><span/>(PUSH-LOGIC-FRAME DATABASE)
</pre></div>


<p>Push a new, open logic frame onto <code>database</code>.</p>
<p>An error will be signaled if there is already an unfinalized logic frame on
  the top of the stack.</p>
<h3 id="push-logic-frame-with-macro"><code>PUSH-LOGIC-FRAME-WITH</code> (macro)</h3>
<div class="codehilite"><pre><span/>(PUSH-LOGIC-FRAME-WITH DATABASE
  &amp;BODY
  BODY)
</pre></div>


<p>Push a new logic frame onto <code>database</code>, run <code>body</code>, and finalize it.</p>
<p>This is a convenience macro for the common process of pushing a logic frame,
  adding some stuff to it, and finalizing it right away.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(push-logic-frame-with t
  (rule t (likes sally ?who)
    (likes ?who cats))
  (facts t
    (likes kim cats)
    (likes sjl cats)
    (likes bob dogs)))

(query-all t (likes sally ?who))
; =&gt;
((?who kim) (?who sjl))
</pre></div>


<h3 id="query-macro"><code>QUERY</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="query-all-macro"><code>QUERY-ALL</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY-ALL DATABASE &amp;REST TERMS)
</pre></div>


<h3 id="query-do-macro"><code>QUERY-DO</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY-DO DATABASE FUNCTION &amp;REST TERMS)
</pre></div>


<h3 id="query-find-macro"><code>QUERY-FIND</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY-FIND DATABASE PREDICATE &amp;REST TERMS)
</pre></div>


<h3 id="query-for-macro"><code>QUERY-FOR</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY-FOR DATABASE VARIABLE &amp;REST TERMS)
</pre></div>


<h3 id="query-map-macro"><code>QUERY-MAP</code> (macro)</h3>
<div class="codehilite"><pre><span/>(QUERY-MAP DATABASE FUNCTION &amp;REST TERMS)
</pre></div>


<h3 id="reset-standard-database-function"><code>RESET-STANDARD-DATABASE</code> (function)</h3>
<div class="codehilite"><pre><span/>(RESET-STANDARD-DATABASE)
</pre></div>


<p>Reset <code>*standard-database*</code> to a new, fresh database.</p>
<h3 id="rule-macro"><code>RULE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(RULE DATABASE
    HEAD
  &amp;BODY
  BODY)
</pre></div>


<p>Add a logical rule to <code>database</code> with the given <code>head</code> and <code>body</code>.</p>
<p><code>head</code> and <code>body</code> will be wrapped in <code>(quote ...)</code>.  If you need to
  dynamically construct rules at runtime, see <code>invoke-rule</code>.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>; Sally like anyone who likes cats
(rule t (likes sally ?who)
  (likes ?who cats))
</pre></div>


<h3 id="with-database-macro"><code>WITH-DATABASE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(WITH-DATABASE DATABASE
  &amp;BODY
  BODY)
</pre></div>


<p>Execute <code>body</code> with <code>*standard-database*</code> bound to <code>database</code>.</p>
<h3 id="with-fresh-database-macro"><code>WITH-FRESH-DATABASE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(WITH-FRESH-DATABASE
  &amp;BODY
  BODY)
</pre></div>


<p>Execute <code>body</code> with <code>*standard-database*</code> bound to a new, fresh database.</p>
                </div>
            <footer><p><i>Made with Lisp and love by <a href="http://stevelosh.com/">Steve Losh</a> in Reykjavík, Iceland.</i></p>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-15328874-3', 'auto');
  ga('send', 'pageview');

</script></footer>
        </div>
    </body>
</html>