hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title> API Reference / Chancery</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="..">Chancery</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 Chancery.</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-chancery">Package CHANCERY</a><ul>
<li><a href="#random-variable">*RANDOM* (variable)</a></li>
<li><a href="#a-function">A (function)</a></li>
<li><a href="#cap-function">CAP (function)</a></li>
<li><a href="#cap-all-function">CAP-ALL (function)</a></li>
<li><a href="#create-rule-function">CREATE-RULE (function)</a></li>
<li><a href="#create-string-function">CREATE-STRING (function)</a></li>
<li><a href="#define-rule-macro">DEFINE-RULE (macro)</a></li>
<li><a href="#define-string-macro">DEFINE-STRING (macro)</a></li>
<li><a href="#generate-macro">GENERATE (macro)</a></li>
<li><a href="#generate-string-macro">GENERATE-STRING (macro)</a></li>
<li><a href="#invoke-generate-function">INVOKE-GENERATE (function)</a></li>
<li><a href="#invoke-generate-string-function">INVOKE-GENERATE-STRING (function)</a></li>
<li><a href="#pos-function">POS (function)</a></li>
<li><a href="#s-function">S (function)</a></li>
</ul>
</li>
</ul></div>
<h2 id="package-chancery">Package <code>CHANCERY</code></h2>
<h3 id="random-variable"><code>*RANDOM*</code> (variable)</h3>
<p>The random number generation function to use (default: <code>CL:RANDOM</code>).</p>
<h3 id="a-function"><code>A</code> (function)</h3>
<div class="codehilite"><pre><span/>(A STRING)
</pre></div>


<p>Add an indefinite article (a or an) to the front of <code>string</code>.</p>
<h3 id="cap-function"><code>CAP</code> (function)</h3>
<div class="codehilite"><pre><span/>(CAP STRING)
</pre></div>


<p>Capitalize the first character of <code>string</code>.</p>
<h3 id="cap-all-function"><code>CAP-ALL</code> (function)</h3>
<div class="codehilite"><pre><span/>(CAP-ALL STRING)
</pre></div>


<p>Capitalize each word of <code>string</code>.</p>
<h3 id="create-rule-function"><code>CREATE-RULE</code> (function)</h3>
<div class="codehilite"><pre><span/>(CREATE-RULE EXPRESSIONS &amp;REST OPTIONS)
</pre></div>


<p>Return a function that will return random elements of <code>expressions</code>.</p>
<p><code>options</code> should be of the form:</p>
<div class="codehilite"><pre><span/>(&amp;key documentation (distribution :uniform) (arguments '()))
</pre></div>


<p><code>documentation</code> will be used as a docstring for the resulting function.</p>
<p><code>distribution</code> denotes the distribution of elements returned.</p>
<p><code>arguments</code> is the arglist of the resulting function.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(create-rule (list :blue :red :green))

(create-rule (list :copper :silver :gold :platinum)
  :documentation "Return a random metal."
  :distribution :zipf)
</pre></div>


<p>See the full documentation for more information.</p>
<h3 id="create-string-function"><code>CREATE-STRING</code> (function)</h3>
<div class="codehilite"><pre><span/>(CREATE-STRING EXPRESSIONS &amp;REST OPTIONS)
</pre></div>


<p>Return a function that will return random stringified elements of <code>expressions</code>.</p>
<p><code>options</code> should be of the form:</p>
<div class="codehilite"><pre><span/>(&amp;key documentation (distribution :uniform) (arguments '()))
</pre></div>


<p><code>documentation</code> will be used as a docstring for the resulting function.</p>
<p><code>distribution</code> denotes the distribution of elements returned.</p>
<p><code>arguments</code> is the arglist of the resulting function.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(create-string (list "white" "gray" "black"))

(create-string '((100 (color "cat"))
                 (100 (color "dog"))
                 (100 (color "dragon")))
  :distribution :weighted)
</pre></div>


<p>See the full documentation for more information.</p>
<h3 id="define-rule-macro"><code>DEFINE-RULE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(DEFINE-RULE NAME-AND-OPTIONS &amp;REST EXPRESSIONS)
</pre></div>


<p>Define a function that will return random elements of <code>expressions</code>.</p>
<p><code>name-and-options</code> should be of the form:</p>
<div class="codehilite"><pre><span/>(name &amp;key documentation (distribution :uniform) (arguments '()))
</pre></div>


<p>If no options are needed a bare symbol can be given.</p>
<p><code>name</code> is the symbol under which the resulting function will be defined.</p>
<p><code>documentation</code> will be used as a docstring for the resulting function.</p>
<p><code>distribution</code> denotes the distribution of elements returned.</p>
<p><code>arguments</code> is the arglist of the resulting function.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(define-rule color
  :blue
  :green
  :red)

(define-rule (metal :documentation "Return a random metal."
                    :distribution :zipf)
  :copper
  :silver
  :gold
  :platinum)
</pre></div>


<p>See the full documentation for more information.</p>
<h3 id="define-string-macro"><code>DEFINE-STRING</code> (macro)</h3>
<div class="codehilite"><pre><span/>(DEFINE-STRING NAME-AND-OPTIONS &amp;REST EXPRESSIONS)
</pre></div>


<p>Define a function that will return random stringified elements of <code>expressions</code>.</p>
<p><code>name-and-options</code> should be of the form:</p>
<div class="codehilite"><pre><span/>(name &amp;key documentation (distribution :uniform) (arguments '()))
</pre></div>


<p>If no options are needed a bare symbol can be given.</p>
<p><code>name</code> is the symbol under which the resulting function will be defined.</p>
<p><code>documentation</code> will be used as a docstring for the resulting function.</p>
<p><code>distribution</code> denotes the distribution of elements returned.</p>
<p><code>arguments</code> is the arglist of the resulting function.</p>
<p>Examples:</p>
<div class="codehilite"><pre><span/>(define-string color "white" "gray" "black")

(define-string (animal :distribution :weighted)
  (100 (color "cat"))
  (100 (color "dog"))
  (100 (color "dragon")))
</pre></div>


<p>See the full documentation for more information.</p>
<h3 id="generate-macro"><code>GENERATE</code> (macro)</h3>
<div class="codehilite"><pre><span/>(GENERATE EXPRESSION)
</pre></div>


<p>Generate a single Chancery expression.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(define-rule x 1 2 3)

(generate (x x x))
; =&gt; (1 3 1)
</pre></div>


<h3 id="generate-string-macro"><code>GENERATE-STRING</code> (macro)</h3>
<div class="codehilite"><pre><span/>(GENERATE-STRING EXPRESSION)
</pre></div>


<p>Generate and stringify a single Chancery string expression.</p>
<p>Example:</p>
<div class="codehilite"><pre><span/>(define-string x 1 2 3)

(generate-string (x x x))
; =&gt; "1 3 1"
</pre></div>


<h3 id="invoke-generate-function"><code>INVOKE-GENERATE</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-GENERATE EXPRESSION)
</pre></div>


<p>Generate a single Chancery expression.</p>
<p>THIS FUNCTION IS EXPERIMENTAL AND SUBJECT TO CHANGE IN THE FUTURE.</p>
<p>Because this is a function, not a macro, you'll need to do the quoting
  yourself:</p>
<div class="codehilite"><pre><span/>(define-rule x 1 2 3)

(generate (x x x))
; =&gt; (1 3 3)

(invoke-generate '(x x x))
; =&gt; (2 1 2)
</pre></div>


<h3 id="invoke-generate-string-function"><code>INVOKE-GENERATE-STRING</code> (function)</h3>
<div class="codehilite"><pre><span/>(INVOKE-GENERATE-STRING EXPRESSION)
</pre></div>


<p>Generate and stringify a single Chancery expression.</p>
<p>THIS FUNCTION IS EXPERIMENTAL AND SUBJECT TO CHANGE IN THE FUTURE.</p>
<p>Because this is a function, not a macro, you'll need to do the quoting
  yourself:</p>
<div class="codehilite"><pre><span/>(define-string x 1 2 3)

(generate-string (x x x))
; =&gt; "1 3 3"

(invoke-generate-string '(x x x))
; =&gt; "2 1 2"
</pre></div>


<h3 id="pos-function"><code>POS</code> (function)</h3>
<div class="codehilite"><pre><span/>(POS STRING)
</pre></div>


<p>Make <code>string</code> posessive by adding an apostrophe (and possibly an s).</p>
<h3 id="s-function"><code>S</code> (function)</h3>
<div class="codehilite"><pre><span/>(S STRING)
</pre></div>


<p>Pluralize <code>string</code>.</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>
author	Steve Losh <steve@stevelosh.com>
date	Fri, 17 May 2019 23:13:24 -0400
parents	54ebe659726f
children	15eb4bbf6d54