docs/reference/FuncRef.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
   3 <head>
   4   <meta charset="utf-8" />
   5   <meta name="generator" content="pandoc" />
   6   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
   7   <title>Functor-Reference</title>
   8   <style>
   9     html {
  10       line-height: 1.5;
  11       font-family: Georgia, serif;
  12       font-size: 20px;
  13       color: #1a1a1a;
  14       background-color: #fdfdfd;
  15     }
  16     body {
  17       margin: 0 auto;
  18       max-width: 36em;
  19       padding-left: 50px;
  20       padding-right: 50px;
  21       padding-top: 50px;
  22       padding-bottom: 50px;
  23       hyphens: auto;
  24       word-wrap: break-word;
  25       text-rendering: optimizeLegibility;
  26       font-kerning: normal;
  27     }
  28     @media (max-width: 600px) {
  29       body {
  30         font-size: 0.9em;
  31         padding: 1em;
  32       }
  33     }
  34     @media print {
  35       body {
  36         background-color: transparent;
  37         color: black;
  38         font-size: 12pt;
  39       }
  40       p, h2, h3 {
  41         orphans: 3;
  42         widows: 3;
  43       }
  44       h2, h3, h4 {
  45         page-break-after: avoid;
  46       }
  47     }
  48     p {
  49       margin: 1em 0;
  50     }
  51     a {
  52       color: #1a1a1a;
  53     }
  54     a:visited {
  55       color: #1a1a1a;
  56     }
  57     img {
  58       max-width: 100%;
  59     }
  60     h1, h2, h3, h4, h5, h6 {
  61       margin-top: 1.4em;
  62     }
  63     h5, h6 {
  64       font-size: 1em;
  65       font-style: italic;
  66     }
  67     h6 {
  68       font-weight: normal;
  69     }
  70     ol, ul {
  71       padding-left: 1.7em;
  72       margin-top: 1em;
  73     }
  74     li > ol, li > ul {
  75       margin-top: 0;
  76     }
  77     blockquote {
  78       margin: 1em 0 1em 1.7em;
  79       padding-left: 1em;
  80       border-left: 2px solid #e6e6e6;
  81       color: #606060;
  82     }
  83     code {
  84       font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
  85       font-size: 85%;
  86       margin: 0;
  87     }
  88     pre {
  89       margin: 1em 0;
  90       overflow: auto;
  91     }
  92     pre code {
  93       padding: 0;
  94       overflow: visible;
  95     }
  96     .sourceCode {
  97      background-color: transparent;
  98      overflow: visible;
  99     }
 100     hr {
 101       background-color: #1a1a1a;
 102       border: none;
 103       height: 1px;
 104       margin: 1em 0;
 105     }
 106     table {
 107       margin: 1em 0;
 108       border-collapse: collapse;
 109       width: 100%;
 110       overflow-x: auto;
 111       display: block;
 112       font-variant-numeric: lining-nums tabular-nums;
 113     }
 114     table caption {
 115       margin-bottom: 0.75em;
 116     }
 117     tbody {
 118       margin-top: 0.5em;
 119       border-top: 1px solid #1a1a1a;
 120       border-bottom: 1px solid #1a1a1a;
 121     }
 122     th {
 123       border-top: 1px solid #1a1a1a;
 124       padding: 0.25em 0.5em 0.25em 0.5em;
 125     }
 126     td {
 127       padding: 0.125em 0.5em 0.25em 0.5em;
 128     }
 129     header {
 130       margin-bottom: 4em;
 131       text-align: center;
 132     }
 133     #TOC li {
 134       list-style: none;
 135     }
 136     #TOC a:not(:hover) {
 137       text-decoration: none;
 138     }
 139     code{white-space: pre-wrap;}
 140     span.smallcaps{font-variant: small-caps;}
 141     span.underline{text-decoration: underline;}
 142     div.column{display: inline-block; vertical-align: top; width: 50%;}
 143     div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
 144     ul.task-list{list-style: none;}
 145     .display.math{display: block; text-align: center; margin: 0.5rem auto;}
 146   </style>
 147   <!--[if lt IE 9]>
 148     <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
 149   <![endif]-->
 150 </head>
 151 <body>
 152 <nav id="TOC" role="doc-toc">
 153 <ul>
 154 <li><a href="#functor-reference">Functor Reference</a>
 155 <ul>
 156 <li><a href="#section">!-</a></li>
 157 <li><a href="#app1">app1</a></li>
 158 <li><a href="#b">b</a></li>
 159 <li><a href="#binary">binary</a></li>
 160 <li><a href="#ccons">ccons</a></li>
 161 <li><a href="#cons">cons</a></li>
 162 <li><a href="#i">i</a></li>
 163 <li><a href="#infra">infra</a></li>
 164 <li><a href="#nullary">nullary</a></li>
 165 <li><a href="#ternary">ternary</a></li>
 166 <li><a href="#unary">unary</a></li>
 167 <li><a href="#uncons">uncons</a></li>
 168 <li><a href="#x">x</a></li>
 169 </ul></li>
 170 </ul>
 171 </nav>
 172 <h1 id="functor-reference">Functor Reference</h1>
 173 <p>Version -10.0.0</p>
 174 <p>Each function, combinator, or definition should be documented here.</p>
 175 <hr />
 176 <h2 id="section">!-</h2>
 177 <p>&#x201C;not negative&#x201D;</p>
 178 <p>(Function, Boolean Predicate)</p>
 179 <p>Integer on top of stack is replaced by Boolean value indicating whether it is non-negative.</p>
 180 <pre><code>    N !-
 181 -----------  N &lt; 0
 182    false
 183
 184    N !-
 185 ----------  N &gt;= 0
 186    true</code></pre>
 187 <h3 id="definition">Definition</h3>
 188 <pre><code>0 &gt;=</code></pre>
 189 <hr />
 190 <h2 id="app1">app1</h2>
 191 <p>&#x201C;apply one&#x201D;</p>
 192 <p>(Combinator)</p>
 193 <p>Given a quoted program on TOS and anything as the second stack item run the program without disturbing the stack and replace the two args with the first result of the program.</p>
 194 <pre><code>         ... x [Q] app1
 195 ---------------------------------
 196    ... [x ...] [Q] infra first</code></pre>
 197 <h3 id="definition-1">Definition</h3>
 198 <pre><code>nullary popd</code></pre>
 199 <h3 id="discussion">Discussion</h3>
 200 <p>Just a specialization of <code>nullary</code> really. Its parallelizable cousins are more useful.</p>
 201 <hr />
 202 <h2 id="b">b</h2>
 203 <p>(Combinator)</p>
 204 <p>Run two quoted programs</p>
 205 <pre><code>   [P] [Q] b
 206 ---------------
 207       P Q</code></pre>
 208 <h3 id="definition-2">Definition</h3>
 209 <pre><code>[i] dip i</code></pre>
 210 <h3 id="derivation">Derivation</h3>
 211 <pre><code>[P] [Q] b
 212 [P] [Q] [i] dip i
 213 [P] i [Q] i
 214  P    [Q] i
 215  P     Q</code></pre>
 216 <h3 id="discussion-1">Discussion</h3>
 217 <p>This combinator comes in handy.</p>
 218 <h3 id="crosslinks">Crosslinks</h3>
 219 <p><a href="#dupdip">dupdip</a> <a href="#ii">ii</a></p>
 220 <hr />
 221 <h2 id="binary">binary</h2>
 222 <p>(Combinator)</p>
 223 <p>Run a quoted program using exactly two stack values and leave the first item of the result on the stack.</p>
 224 <pre><code>   ... y x [P] binary
 225 -----------------------
 226         ... A</code></pre>
 227 <h3 id="definition-3">Definition</h3>
 228 <pre><code>unary popd</code></pre>
 229 <h3 id="discussion-2">Discussion</h3>
 230 <p>Runs any other quoted function and returns its first result while consuming exactly two items from the stack.</p>
 231 <h3 id="crosslinks-1">Crosslinks</h3>
 232 <p><a href="#nullary">nullary</a> <a href="#ternary">ternary</a> <a href="#unary">unary</a></p>
 233 <hr />
 234 <h2 id="ccons">ccons</h2>
 235 <p>(Function)</p>
 236 <p>Given two items and a list, append the items to the list to make a new list.</p>
 237 <pre><code>   B A [...] ccons
 238 ---------------------
 239       [B A ...]</code></pre>
 240 <h3 id="definition-4">Definition</h3>
 241 <pre><code>cons cons</code></pre>
 242 <h3 id="discussion-3">Discussion</h3>
 243 <p>Does <code>cons</code> twice.</p>
 244 <h3 id="crosslinks-2">Crosslinks</h3>
 245 <p><a href="#cons">cons</a></p>
 246 <hr />
 247 <h2 id="cons">cons</h2>
 248 <p>(Basis Function)</p>
 249 <p>Given an item and a list, append the item to the list to make a new list.</p>
 250 <pre><code>   A [...] cons
 251 ------------------
 252      [A ...]</code></pre>
 253 <h3 id="source">Source</h3>
 254 <pre><code>func(cons, [list(A), B|S], [list([B|A])|S]).</code></pre>
 255 <h3 id="discussion-4">Discussion</h3>
 256 <p>Cons is a venerable old function from Lisp. It doesn&#x2019;t inspect the item but it will not cons onto a non-list. It&#x2019;s inverse operation is called <code>uncons</code>.</p>
 257 <h3 id="crosslinks-3">Crosslinks</h3>
 258 <p><a href="#ccons">ccons</a> <a href="#uncons">uncons</a></p>
 259 <hr />
 260 <h2 id="i">i</h2>
 261 <p>(Basis Combinator)</p>
 262 <p>Append a quoted expression onto the pending expression.</p>
 263 <pre><code>   [Q] i
 264 -----------
 265     Q</code></pre>
 266 <h3 id="source-1">Source</h3>
 267 <pre><code>combo(i, [list(P)|S], S, Ei, Eo) :- append(P, Ei, Eo).</code></pre>
 268 <h3 id="discussion-5">Discussion</h3>
 269 <p>This is probably the fundamental combinator. You wind up using it in all kinds of places (for example, the <code>x</code> combinator can be defined as <code>dup i</code>.)</p>
 270 <hr />
 271 <h2 id="infra">infra</h2>
 272 <p>(Combinator)</p>
 273 <p>Accept a quoted program and a list on the stack and run the program with the list as its stack. Does not affect the stack (below the list.)</p>
 274 <pre><code>   ... [a b c] [Q] infra
 275 ---------------------------
 276     c b a Q [...] swaack</code></pre>
 277 <h3 id="definition-5">Definition</h3>
 278 <pre><code>swons swaack [i] dip swaack</code></pre>
 279 <h3 id="discussion-6">Discussion</h3>
 280 <p>This is one of the more useful combinators. It allows a quoted expression to serve as a stack for a program, effectively running it in a kind of &#x201C;pocket universe&#x201D;. If the list represents a datastructure then <code>infra</code> lets you work on its internal structure.</p>
 281 <h3 id="crosslinks-4">Crosslinks</h3>
 282 <p><a href="#swaack">swaack</a></p>
 283 <hr />
 284 <h2 id="nullary">nullary</h2>
 285 <p>(Combinator)</p>
 286 <p>Run a quoted program without using any stack values and leave the first item of the result on the stack.</p>
 287 <pre><code>   ... [P] nullary
 288 ---------------------
 289         ... A</code></pre>
 290 <h3 id="definition-6">Definition</h3>
 291 <pre><code>[stack] dip infra first</code></pre>
 292 <h3 id="derivation-1">Derivation</h3>
 293 <pre><code>... [P] nullary
 294 ... [P] [stack] dip infra first
 295 ... stack [P] infra first
 296 ... [...] [P] infra first
 297 ... [A ...] first
 298 ...  A</code></pre>
 299 <h3 id="discussion-7">Discussion</h3>
 300 <p>A very useful function that runs any other quoted function and returns it&#x2019;s first result without disturbing the stack (under the quoted program.)</p>
 301 <h3 id="crosslinks-5">Crosslinks</h3>
 302 <p><a href="#unary">unary</a> <a href="#binary">binary</a> <a href="#ternary">ternary</a></p>
 303 <hr />
 304 <h2 id="ternary">ternary</h2>
 305 <p>(Combinator)</p>
 306 <p>Run a quoted program using exactly three stack values and leave the first item of the result on the stack.</p>
 307 <pre><code>   ... z y x [P] unary
 308 -------------------------
 309          ... A</code></pre>
 310 <h3 id="definition-7">Definition</h3>
 311 <pre><code>binary popd</code></pre>
 312 <h3 id="discussion-8">Discussion</h3>
 313 <p>Runs any other quoted function and returns its first result while consuming exactly three items from the stack.</p>
 314 <h3 id="crosslinks-6">Crosslinks</h3>
 315 <p><a href="#binary">binary</a> <a href="#nullary">nullary</a> <a href="#unary">unary</a></p>
 316 <hr />
 317 <h2 id="unary">unary</h2>
 318 <p>(Combinator)</p>
 319 <p>Run a quoted program using exactly one stack value and leave the first item of the result on the stack.</p>
 320 <pre><code>   ... x [P] unary
 321 ---------------------
 322        ... A</code></pre>
 323 <h3 id="definition-8">Definition</h3>
 324 <pre><code>nullary popd</code></pre>
 325 <h3 id="discussion-9">Discussion</h3>
 326 <p>Runs any other quoted function and returns its first result while consuming exactly one item from the stack.</p>
 327 <h3 id="crosslinks-7">Crosslinks</h3>
 328 <p><a href="#binary">binary</a> <a href="#nullary">nullary</a> <a href="#ternary">ternary</a></p>
 329 <hr />
 330 <h2 id="uncons">uncons</h2>
 331 <p>(Basis Function)</p>
 332 <p>Removes an item from a list and leaves it on the stack under the rest of the list. You cannot <code>uncons</code> an item from an empty list.</p>
 333 <pre><code>   [A ...] uncons
 334 --------------------
 335       A [...]</code></pre>
 336 <h3 id="source-2">Source</h3>
 337 <pre><code>func(uncons, Si, So) :- func(cons, So, Si).</code></pre>
 338 <h3 id="discussion-10">Discussion</h3>
 339 <p>This is the inverse of <code>cons</code>.</p>
 340 <h3 id="crosslinks-8">Crosslinks</h3>
 341 <p><a href="#cons">cons</a></p>
 342 <hr />
 343 <h2 id="x">x</h2>
 344 <p>(Combinator)</p>
 345 <pre><code>   [F] x
 346 -----------
 347    [F] F</code></pre>
 348 <h3 id="definition-9">Definition</h3>
 349 <pre><code>dup i</code></pre>
 350 <h3 id="discussion-11">Discussion</h3>
 351 <p>The <code>x</code> combinator &#x2026;</p>
 352 </body>
 353 </html>