docs/sphinx_docs/_build/html/_modules/joy/library.html

   1
   2 <!DOCTYPE html>
   3
   4 <html>
   5   <head>
   6     <meta charset="utf-8" />
   7     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   8     <title>joy.library &#8212; Thun 0.4.1 documentation</title>
   9     <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
  10     <link rel="stylesheet" type="text/css" href="../../_static/alabaster.css" />
  11     <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
  12     <script src="../../_static/jquery.js"></script>
  13     <script src="../../_static/underscore.js"></script>
  14     <script src="../../_static/doctools.js"></script>
  15     <link rel="index" title="Index" href="../../genindex.html" />
  16     <link rel="search" title="Search" href="../../search.html" />
  17
  18   <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
  19
  20
  21   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  22
  23   </head><body>
  24
  25
  26     <div class="document">
  27       <div class="documentwrapper">
  28         <div class="bodywrapper">
  29
  30
  31           <div class="body" role="main">
  32
  33   <h1>Source code for joy.library</h1><div class="highlight"><pre>
  34 <span></span><span class="c1"># -*- coding: utf-8 -*-</span>
  35 <span class="c1">#</span>
  36 <span class="c1">#    Copyright © 2014-2020 Simon Forman</span>
  37 <span class="c1">#</span>
  38 <span class="c1">#    This file is part of Thun</span>
  39 <span class="c1">#</span>
  40 <span class="c1">#    Thun is free software: you can redistribute it and/or modify</span>
  41 <span class="c1">#    it under the terms of the GNU General Public License as published by</span>
  42 <span class="c1">#    the Free Software Foundation, either version 3 of the License, or</span>
  43 <span class="c1">#    (at your option) any later version.</span>
  44 <span class="c1">#</span>
  45 <span class="c1">#    Thun is distributed in the hope that it will be useful,</span>
  46 <span class="c1">#    but WITHOUT ANY WARRANTY; without even the implied warranty of</span>
  47 <span class="c1">#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the</span>
  48 <span class="c1">#    GNU General Public License for more details.</span>
  49 <span class="c1">#</span>
  50 <span class="c1">#    You should have received a copy of the GNU General Public License</span>
  51 <span class="c1">#    along with Thun.  If not see &lt;http://www.gnu.org/licenses/&gt;. </span>
  52 <span class="c1">#</span>
  53 <span class="sd">&#39;&#39;&#39;</span>
  54 <span class="sd">This module contains the Joy function infrastructure and a library of</span>
  55 <span class="sd">functions.  Its main export is a Python function initialize() that</span>
  56 <span class="sd">returns a dictionary of Joy functions suitable for use with the joy()</span>
  57 <span class="sd">function.</span>
  58 <span class="sd">&#39;&#39;&#39;</span>
  59 <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getdoc</span><span class="p">,</span> <span class="n">getmembers</span><span class="p">,</span> <span class="n">isfunction</span>
  60 <span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">wraps</span>
  61 <span class="kn">from</span> <span class="nn">itertools</span> <span class="kn">import</span> <span class="n">count</span>
  62 <span class="kn">import</span> <span class="nn">operator</span><span class="o">,</span> <span class="nn">math</span>
  63
  64 <span class="kn">from</span> <span class="nn">.parser</span> <span class="kn">import</span> <span class="n">text_to_expression</span><span class="p">,</span> <span class="n">Symbol</span>
  65 <span class="kn">from</span> <span class="nn">.utils</span> <span class="kn">import</span> <span class="n">generated_library</span> <span class="k">as</span> <span class="n">genlib</span>
  66 <span class="kn">from</span> <span class="nn">.utils.errors</span> <span class="kn">import</span> <span class="p">(</span>
  67     <span class="n">NotAListError</span><span class="p">,</span>
  68     <span class="n">NotAnIntError</span><span class="p">,</span>
  69     <span class="n">StackUnderflowError</span><span class="p">,</span>
  70     <span class="p">)</span>
  71 <span class="kn">from</span> <span class="nn">.utils.stack</span> <span class="kn">import</span> <span class="p">(</span>
  72     <span class="n">concat</span><span class="p">,</span>
  73     <span class="n">expression_to_string</span><span class="p">,</span>
  74     <span class="n">iter_stack</span><span class="p">,</span>
  75     <span class="n">list_to_stack</span><span class="p">,</span>
  76     <span class="n">pick</span><span class="p">,</span>
  77     <span class="p">)</span>
  78
  79
  80 <span class="n">HELP_TEMPLATE</span> <span class="o">=</span> <span class="s1">&#39;&#39;&#39;</span><span class="se">\</span>
  81
  82 <span class="s1">==== Help on </span><span class="si">%s</span><span class="s1"> ====</span>
  83
  84 <span class="si">%s</span><span class="s1"></span>
  85
  86 <span class="s1">---- end (</span><span class="si">%s</span><span class="s1">)</span>
  87 <span class="s1">&#39;&#39;&#39;</span>
  88
  89
  90 <span class="c1"># This is the main dict we&#39;re building.</span>
  91 <span class="n">_dictionary</span> <span class="o">=</span> <span class="p">{}</span>
  92
  93
  94 <div class="viewcode-block" id="inscribe"><a class="viewcode-back" href="../../library.html#joy.library.inscribe">[docs]</a><span class="k">def</span> <span class="nf">inscribe</span><span class="p">(</span><span class="n">function</span><span class="p">):</span>
  95     <span class="sd">&#39;&#39;&#39;A decorator to inscribe functions into the default dictionary.&#39;&#39;&#39;</span>
  96     <span class="n">_dictionary</span><span class="p">[</span><span class="n">function</span><span class="o">.</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">function</span>
  97     <span class="k">return</span> <span class="n">function</span></div>
  98
  99
 100 <div class="viewcode-block" id="initialize"><a class="viewcode-back" href="../../library.html#joy.library.initialize">[docs]</a><span class="k">def</span> <span class="nf">initialize</span><span class="p">():</span>
 101     <span class="sd">&#39;&#39;&#39;Return a dictionary of Joy functions for use with joy().&#39;&#39;&#39;</span>
 102     <span class="k">return</span> <span class="n">_dictionary</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span></div>
 103
 104
 105 <span class="n">ALIASES</span> <span class="o">=</span> <span class="p">(</span>
 106     <span class="p">(</span><span class="s1">&#39;add&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;+&#39;</span><span class="p">]),</span>
 107     <span class="p">(</span><span class="s1">&#39;and&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&amp;&#39;</span><span class="p">]),</span>
 108     <span class="p">(</span><span class="s1">&#39;bool&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;truthy&#39;</span><span class="p">]),</span>
 109     <span class="p">(</span><span class="s1">&#39;mul&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;*&#39;</span><span class="p">]),</span>
 110     <span class="p">(</span><span class="s1">&#39;floordiv&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;/floor&#39;</span><span class="p">,</span> <span class="s1">&#39;//&#39;</span><span class="p">,</span> <span class="s1">&#39;/&#39;</span><span class="p">,</span> <span class="s1">&#39;div&#39;</span><span class="p">]),</span>
 111     <span class="p">(</span><span class="s1">&#39;mod&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;%&#39;</span><span class="p">,</span> <span class="s1">&#39;rem&#39;</span><span class="p">,</span> <span class="s1">&#39;remainder&#39;</span><span class="p">,</span> <span class="s1">&#39;modulus&#39;</span><span class="p">]),</span>
 112     <span class="p">(</span><span class="s1">&#39;eq&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;=&#39;</span><span class="p">]),</span>
 113     <span class="p">(</span><span class="s1">&#39;ge&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&gt;=&#39;</span><span class="p">]),</span>
 114     <span class="p">(</span><span class="s1">&#39;getitem&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;pick&#39;</span><span class="p">,</span> <span class="s1">&#39;at&#39;</span><span class="p">]),</span>
 115     <span class="p">(</span><span class="s1">&#39;gt&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&gt;&#39;</span><span class="p">]),</span>
 116     <span class="p">(</span><span class="s1">&#39;le&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&lt;=&#39;</span><span class="p">]),</span>
 117     <span class="p">(</span><span class="s1">&#39;lshift&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&lt;&lt;&#39;</span><span class="p">]),</span>
 118     <span class="p">(</span><span class="s1">&#39;lt&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&lt;&#39;</span><span class="p">]),</span>
 119     <span class="p">(</span><span class="s1">&#39;ne&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&lt;&gt;&#39;</span><span class="p">,</span> <span class="s1">&#39;!=&#39;</span><span class="p">]),</span>
 120     <span class="p">(</span><span class="s1">&#39;rshift&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;&gt;&gt;&#39;</span><span class="p">]),</span>
 121     <span class="p">(</span><span class="s1">&#39;sub&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;-&#39;</span><span class="p">]),</span>
 122     <span class="p">(</span><span class="s1">&#39;xor&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;^&#39;</span><span class="p">]),</span>
 123     <span class="p">(</span><span class="s1">&#39;succ&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;++&#39;</span><span class="p">]),</span>
 124     <span class="p">(</span><span class="s1">&#39;pred&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;--&#39;</span><span class="p">]),</span>
 125     <span class="p">(</span><span class="s1">&#39;rolldown&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;roll&lt;&#39;</span><span class="p">]),</span>
 126     <span class="p">(</span><span class="s1">&#39;rollup&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;roll&gt;&#39;</span><span class="p">]),</span>
 127     <span class="p">(</span><span class="s1">&#39;eh&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;?&#39;</span><span class="p">]),</span>
 128     <span class="p">(</span><span class="s1">&#39;id&#39;</span><span class="p">,</span> <span class="p">[</span><span class="sa">u</span><span class="s1">&#39;•&#39;</span><span class="p">]),</span>
 129     <span class="p">)</span>
 130
 131
 132 <div class="viewcode-block" id="add_aliases"><a class="viewcode-back" href="../../library.html#joy.library.add_aliases">[docs]</a><span class="k">def</span> <span class="nf">add_aliases</span><span class="p">(</span><span class="n">D</span><span class="p">,</span> <span class="n">A</span><span class="p">):</span>
 133     <span class="sd">&#39;&#39;&#39;</span>
 134 <span class="sd">    Given a dict and a iterable of (name, [alias, ...]) pairs, create</span>
 135 <span class="sd">    additional entries in the dict mapping each alias to the named function</span>
 136 <span class="sd">    if it&#39;s in the dict.  Aliases for functions not in the dict are ignored.</span>
 137 <span class="sd">    &#39;&#39;&#39;</span>
 138     <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">aliases</span> <span class="ow">in</span> <span class="n">A</span><span class="p">:</span>
 139         <span class="k">try</span><span class="p">:</span>
 140             <span class="n">F</span> <span class="o">=</span> <span class="n">D</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
 141         <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
 142             <span class="k">continue</span>
 143         <span class="k">for</span> <span class="n">alias</span> <span class="ow">in</span> <span class="n">aliases</span><span class="p">:</span>
 144             <span class="n">D</span><span class="p">[</span><span class="n">alias</span><span class="p">]</span> <span class="o">=</span> <span class="n">F</span></div>
 145
 146
 147 <span class="n">definitions</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;&#39;&#39;</span><span class="se">\</span>
 148 <span class="s1">? == dup truthy</span>
 149 <span class="s1">*fraction == [uncons] dip uncons [swap] dip concat [*] infra [*] dip cons</span>
 150 <span class="s1">*fraction0 == concat [[swap] dip * [*] dip] infra</span>
 151 <span class="s1">anamorphism == [pop []] swap [dip swons] genrec</span>
 152 <span class="s1">average == [sum 1.0 *] [size] cleave /</span>
 153 <span class="s1">binary == nullary [popop] dip</span>
 154 <span class="s1">cleave == fork [popd] dip</span>
 155 <span class="s1">codireco == cons dip rest cons</span>
 156 <span class="s1">dinfrirst == dip infra first</span>
 157 <span class="s1">unstack == ? [uncons ?] loop pop</span>
 158 <span class="s1">down_to_zero == [0 &gt;] [dup --] while</span>
 159 <span class="s1">dupdipd == dup dipd</span>
 160 <span class="s1">enstacken == stack [clear] dip</span>
 161 <span class="s1">flatten == [] swap [concat] step</span>
 162 <span class="s1">fork == [i] app2</span>
 163 <span class="s1">gcd == 1 [tuck modulus dup 0 &gt;] loop pop</span>
 164 <span class="s1">ifte == [nullary not] dipd branch</span>
 165 <span class="s1">ii == [dip] dupdip i</span>
 166 <span class="s1">least_fraction == dup [gcd] infra [div] concat map</span>
 167 <span class="s1">make_generator == [codireco] ccons</span>
 168 <span class="s1">nullary == [stack] dinfrirst</span>
 169 <span class="s1">of == swap at</span>
 170 <span class="s1">pam == [i] map</span>
 171 <span class="s1">tailrec == [i] genrec</span>
 172 <span class="s1">product == 1 swap [*] step</span>
 173 <span class="s1">quoted == [unit] dip</span>
 174 <span class="s1">range == [0 &lt;=] [1 - dup] anamorphism</span>
 175 <span class="s1">range_to_zero == unit [down_to_zero] infra</span>
 176 <span class="s1">run == [] swap infra</span>
 177 <span class="s1">size == 0 swap [pop ++] step</span>
 178 <span class="s1">sqr == dup mul</span>
 179 <span class="s1">step_zero == 0 roll&gt; step</span>
 180 <span class="s1">swoncat == swap concat</span>
 181 <span class="s1">tailrec == [i] genrec</span>
 182 <span class="s1">ternary == unary [popop] dip</span>
 183 <span class="s1">unary == nullary popd</span>
 184 <span class="s1">unquoted == [i] dip</span>
 185 <span class="s1">while == swap [nullary] cons dup dipd concat loop</span>
 186 <span class="s1">&#39;&#39;&#39;</span>
 187 <span class="c1">#</span>
 188 <span class="c1">#</span>
 189 <span class="c1"># ifte == [nullary] dipd swap branch</span>
 190 <span class="c1"># genrec == [[genrec] cons cons cons cons] nullary swons concat ifte</span>
 191
 192 <span class="c1"># Another definition for while. FWIW</span>
 193 <span class="c1"># while == over [[i] dip nullary] ccons [nullary] dip loop</span>
 194
 195 <span class="c1">##ccons == cons cons</span>
 196 <span class="c1">##unit == [] cons</span>
 197 <span class="c1">##second == rest first</span>
 198 <span class="c1">##third == rest rest first</span>
 199 <span class="c1">##swons == swap cons</span>
 200
 201 <span class="c1">##Zipper</span>
 202 <span class="c1">##z-down == [] swap uncons swap</span>
 203 <span class="c1">##z-up == swons swap shunt</span>
 204 <span class="c1">##z-right == [swons] cons dip uncons swap</span>
 205 <span class="c1">##z-left == swons [uncons swap] dip swap</span>
 206
 207 <span class="c1">##Quadratic Formula</span>
 208 <span class="c1">##divisor == popop 2 *</span>
 209 <span class="c1">##minusb == pop neg</span>
 210 <span class="c1">##radical == swap dup * rollup * 4 * - sqrt</span>
 211 <span class="c1">##root1 == + swap /</span>
 212 <span class="c1">##root2 == - swap /</span>
 213 <span class="c1">##q0 == [[divisor] [minusb] [radical]] pam</span>
 214 <span class="c1">##q1 == [[root1] [root2]] pam</span>
 215 <span class="c1">##quadratic == [q0] ternary i [q1] ternary</span>
 216
 217 <span class="c1"># Project Euler</span>
 218 <span class="c1">##&#39;&#39;&#39;\</span>
 219 <span class="c1">##PE1.1 == + dup [+] dip</span>
 220 <span class="c1">##PE1.2 == dup [3 &amp; PE1.1] dip 2 &gt;&gt;</span>
 221 <span class="c1">##PE1.3 == 14811 swap [PE1.2] times pop</span>
 222 <span class="c1">##PE1 == 0 0 66 [7 PE1.3] times 4 PE1.3 pop</span>
 223 <span class="c1">##&#39;&#39;&#39;</span>
 224 <span class="c1">#PE1.2 == [PE1.1] step</span>
 225 <span class="c1">#PE1 == 0 0 66 [[3 2 1 3 1 2 3] PE1.2] times [3 2 1 3] PE1.2 pop</span>
 226 <span class="p">)</span>
 227
 228
 229 <div class="viewcode-block" id="FunctionWrapper"><a class="viewcode-back" href="../../library.html#joy.library.FunctionWrapper">[docs]</a><span class="k">def</span> <span class="nf">FunctionWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
 230     <span class="sd">&#39;&#39;&#39;Set name attribute.&#39;&#39;&#39;</span>
 231     <span class="k">if</span> <span class="ow">not</span> <span class="n">f</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">:</span>
 232         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;Function </span><span class="si">%s</span><span class="s1"> must have doc string.&#39;</span> <span class="o">%</span> <span class="n">f</span><span class="o">.</span><span class="vm">__name__</span><span class="p">)</span>
 233     <span class="n">f</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="vm">__name__</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s1">&#39;_&#39;</span><span class="p">)</span>  <span class="c1"># Don&#39;t shadow builtins.</span>
 234     <span class="k">return</span> <span class="n">f</span></div>
 235
 236
 237 <div class="viewcode-block" id="SimpleFunctionWrapper"><a class="viewcode-back" href="../../library.html#joy.library.SimpleFunctionWrapper">[docs]</a><span class="k">def</span> <span class="nf">SimpleFunctionWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
 238     <span class="sd">&#39;&#39;&#39;</span>
 239 <span class="sd">    Wrap functions that take and return just a stack.</span>
 240 <span class="sd">    &#39;&#39;&#39;</span>
 241     <span class="nd">@FunctionWrapper</span>
 242     <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
 243     <span class="k">def</span> <span class="nf">inner</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 244         <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="n">stack</span><span class="p">),</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
 245     <span class="k">return</span> <span class="n">inner</span></div>
 246
 247
 248 <div class="viewcode-block" id="BinaryBuiltinWrapper"><a class="viewcode-back" href="../../library.html#joy.library.BinaryBuiltinWrapper">[docs]</a><span class="k">def</span> <span class="nf">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
 249     <span class="sd">&#39;&#39;&#39;</span>
 250 <span class="sd">    Wrap functions that take two arguments and return a single result.</span>
 251 <span class="sd">    &#39;&#39;&#39;</span>
 252     <span class="nd">@FunctionWrapper</span>
 253     <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
 254     <span class="k">def</span> <span class="nf">inner</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 255         <span class="k">try</span><span class="p">:</span>
 256             <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
 257         <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
 258             <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
 259         <span class="k">if</span> <span class="p">(</span><span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
 260             <span class="ow">or</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
 261             <span class="ow">or</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="nb">bool</span><span class="p">)</span>  <span class="c1"># Because bools are ints in Python.</span>
 262             <span class="ow">or</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="nb">bool</span><span class="p">)</span>
 263             <span class="p">):</span>
 264             <span class="k">raise</span> <span class="n">NotAnIntError</span>
 265         <span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
 266         <span class="k">return</span> <span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
 267     <span class="k">return</span> <span class="n">inner</span></div>
 268
 269
 270 <div class="viewcode-block" id="UnaryBuiltinWrapper"><a class="viewcode-back" href="../../library.html#joy.library.UnaryBuiltinWrapper">[docs]</a><span class="k">def</span> <span class="nf">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
 271     <span class="sd">&#39;&#39;&#39;</span>
 272 <span class="sd">    Wrap functions that take one argument and return a single result.</span>
 273 <span class="sd">    &#39;&#39;&#39;</span>
 274     <span class="nd">@FunctionWrapper</span>
 275     <span class="nd">@wraps</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
 276     <span class="k">def</span> <span class="nf">inner</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 277         <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
 278         <span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
 279         <span class="k">return</span> <span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
 280     <span class="k">return</span> <span class="n">inner</span></div>
 281
 282
 283 <div class="viewcode-block" id="DefinitionWrapper"><a class="viewcode-back" href="../../library.html#joy.library.DefinitionWrapper">[docs]</a><span class="k">class</span> <span class="nc">DefinitionWrapper</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
 284     <span class="sd">&#39;&#39;&#39;</span>
 285 <span class="sd">    Provide implementation of defined functions, and some helper methods.</span>
 286 <span class="sd">    &#39;&#39;&#39;</span>
 287
 288     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">body_text</span><span class="p">,</span> <span class="n">doc</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
 289         <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">=</span> <span class="n">name</span>
 290         <span class="bp">self</span><span class="o">.</span><span class="n">body</span> <span class="o">=</span> <span class="n">text_to_expression</span><span class="p">(</span><span class="n">body_text</span><span class="p">)</span>
 291         <span class="bp">self</span><span class="o">.</span><span class="n">_body</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">body</span><span class="p">))</span>
 292         <span class="bp">self</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">doc</span> <span class="ow">or</span> <span class="n">body_text</span>
 293         <span class="bp">self</span><span class="o">.</span><span class="n">_compiled</span> <span class="o">=</span> <span class="kc">None</span>
 294
 295     <span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 296         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_compiled</span><span class="p">:</span>
 297             <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_compiled</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">)</span>  <span class="c1"># pylint: disable=E1102</span>
 298         <span class="n">expression</span> <span class="o">=</span> <span class="n">list_to_stack</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_body</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
 299         <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
 300
 301 <div class="viewcode-block" id="DefinitionWrapper.parse_definition"><a class="viewcode-back" href="../../library.html#joy.library.DefinitionWrapper.parse_definition">[docs]</a>    <span class="nd">@classmethod</span>
 302     <span class="k">def</span> <span class="nf">parse_definition</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="n">defi</span><span class="p">):</span>
 303         <span class="sd">&#39;&#39;&#39;</span>
 304 <span class="sd">        Given some text describing a Joy function definition parse it and</span>
 305 <span class="sd">        return a DefinitionWrapper.</span>
 306 <span class="sd">        &#39;&#39;&#39;</span>
 307         <span class="c1"># At some point I decided that the definitions file should NOT</span>
 308         <span class="c1"># use &#39;==&#39; to separate the name from the body.  But somehow the</span>
 309         <span class="c1"># xerblin\gui\default_joy_home\definitions.txt file didn&#39;t get</span>
 310         <span class="c1"># the memo.  Nor did the load_definitions() method.</span>
 311         <span class="c1"># So I think the simplest way forward at the moment will be to</span>
 312         <span class="c1"># edit this function to expect &#39;==&#39;.</span>
 313
 314         <span class="n">name</span><span class="p">,</span> <span class="n">part</span><span class="p">,</span> <span class="n">body</span> <span class="o">=</span> <span class="n">defi</span><span class="o">.</span><span class="n">partition</span><span class="p">(</span><span class="s1">&#39;==&#39;</span><span class="p">)</span>
 315         <span class="k">if</span> <span class="n">part</span><span class="p">:</span>
 316             <span class="k">return</span> <span class="n">class_</span><span class="p">(</span><span class="n">name</span><span class="o">.</span><span class="n">strip</span><span class="p">(),</span> <span class="n">body</span><span class="o">.</span><span class="n">strip</span><span class="p">())</span>
 317         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;No &#39;==&#39; in definition text </span><span class="si">%r</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">defi</span><span class="p">,))</span></div>
 318
 319         <span class="c1"># return class_(*(n.strip() for n in defi.split(None, 1)))</span>
 320
 321 <div class="viewcode-block" id="DefinitionWrapper.add_definitions"><a class="viewcode-back" href="../../library.html#joy.library.DefinitionWrapper.add_definitions">[docs]</a>    <span class="nd">@classmethod</span>
 322     <span class="k">def</span> <span class="nf">add_definitions</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="n">defs</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 323         <span class="sd">&#39;&#39;&#39;</span>
 324 <span class="sd">        Scan multi-line string defs for definitions and add them to the</span>
 325 <span class="sd">        dictionary.</span>
 326 <span class="sd">        &#39;&#39;&#39;</span>
 327         <span class="k">for</span> <span class="n">definition</span> <span class="ow">in</span> <span class="n">_text_to_defs</span><span class="p">(</span><span class="n">defs</span><span class="p">):</span>
 328             <span class="n">class_</span><span class="o">.</span><span class="n">add_def</span><span class="p">(</span><span class="n">definition</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">)</span></div>
 329
 330 <div class="viewcode-block" id="DefinitionWrapper.add_def"><a class="viewcode-back" href="../../library.html#joy.library.DefinitionWrapper.add_def">[docs]</a>    <span class="nd">@classmethod</span>
 331     <span class="k">def</span> <span class="nf">add_def</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="n">definition</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">fail_fails</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
 332         <span class="sd">&#39;&#39;&#39;</span>
 333 <span class="sd">        Add the definition to the dictionary.</span>
 334 <span class="sd">        &#39;&#39;&#39;</span>
 335         <span class="n">F</span> <span class="o">=</span> <span class="n">class_</span><span class="o">.</span><span class="n">parse_definition</span><span class="p">(</span><span class="n">definition</span><span class="p">)</span>
 336         <span class="n">dictionary</span><span class="p">[</span><span class="n">F</span><span class="o">.</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">F</span></div>
 337
 338     <span class="nd">@classmethod</span>
 339     <span class="k">def</span> <span class="nf">load_definitions</span><span class="p">(</span><span class="n">class_</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 340         <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
 341             <span class="n">lines</span> <span class="o">=</span> <span class="p">[</span><span class="n">line</span> <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span> <span class="k">if</span> <span class="s1">&#39;==&#39;</span> <span class="ow">in</span> <span class="n">line</span><span class="p">]</span>
 342         <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span>
 343             <span class="n">class_</span><span class="o">.</span><span class="n">add_def</span><span class="p">(</span><span class="n">line</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">)</span></div>
 344
 345
 346 <span class="k">def</span> <span class="nf">_text_to_defs</span><span class="p">(</span><span class="n">text</span><span class="p">):</span>
 347     <span class="k">return</span> <span class="p">(</span>
 348         <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
 349         <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">text</span><span class="o">.</span><span class="n">splitlines</span><span class="p">()</span>
 350         <span class="k">if</span> <span class="n">line</span>
 351            <span class="ow">and</span> <span class="ow">not</span> <span class="n">line</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">&#39;#&#39;</span><span class="p">)</span>
 352            <span class="ow">and</span> <span class="s1">&#39;==&#39;</span> <span class="ow">in</span> <span class="n">line</span>
 353         <span class="p">)</span>
 354
 355
 356 <span class="c1">#</span>
 357 <span class="c1"># Functions</span>
 358 <span class="c1">#</span>
 359
 360
 361 <div class="viewcode-block" id="inscribe_"><a class="viewcode-back" href="../../library.html#joy.library.inscribe_">[docs]</a><span class="nd">@inscribe</span>
 362 <span class="nd">@FunctionWrapper</span>
 363 <span class="k">def</span> <span class="nf">inscribe_</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 364     <span class="sd">&#39;&#39;&#39;</span>
 365 <span class="sd">    Create a new Joy function definition in the Joy dictionary.  A</span>
 366 <span class="sd">    definition is given as a string with a name followed by a double</span>
 367 <span class="sd">    equal sign then one or more Joy functions, the body. for example:</span>
 368
 369 <span class="sd">        sqr == dup mul</span>
 370
 371 <span class="sd">    If you want the definition to persist over restarts, enter it into</span>
 372 <span class="sd">    the definitions.txt resource.</span>
 373 <span class="sd">    &#39;&#39;&#39;</span>
 374     <span class="n">definition</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
 375     <span class="n">DefinitionWrapper</span><span class="o">.</span><span class="n">add_def</span><span class="p">(</span><span class="n">definition</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">,</span> <span class="n">fail_fails</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
 376     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
 377
 378
 379 <div class="viewcode-block" id="parse"><a class="viewcode-back" href="../../library.html#joy.library.parse">[docs]</a><span class="nd">@inscribe</span>
 380 <span class="nd">@SimpleFunctionWrapper</span>
 381 <span class="k">def</span> <span class="nf">parse</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 382     <span class="sd">&#39;&#39;&#39;Parse the string on the stack to a Joy expression.&#39;&#39;&#39;</span>
 383     <span class="n">text</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
 384     <span class="n">expression</span> <span class="o">=</span> <span class="n">text_to_expression</span><span class="p">(</span><span class="n">text</span><span class="p">)</span>
 385     <span class="k">return</span> <span class="n">expression</span><span class="p">,</span> <span class="n">stack</span></div>
 386
 387
 388 <span class="c1"># @inscribe</span>
 389 <span class="c1"># @SimpleFunctionWrapper</span>
 390 <span class="c1"># def infer_(stack):</span>
 391 <span class="c1">#     &#39;&#39;&#39;Attempt to infer the stack effect of a Joy expression.&#39;&#39;&#39;</span>
 392 <span class="c1">#     E, stack = stack</span>
 393 <span class="c1">#     effects = infer_expression(E)</span>
 394 <span class="c1">#     e = list_to_stack([(fi, (fo, ())) for fi, fo in effects])</span>
 395 <span class="c1">#     return e, stack</span>
 396
 397
 398 <div class="viewcode-block" id="getitem"><a class="viewcode-back" href="../../library.html#joy.library.getitem">[docs]</a><span class="nd">@inscribe</span>
 399 <span class="nd">@SimpleFunctionWrapper</span>
 400 <span class="k">def</span> <span class="nf">getitem</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 401     <span class="sd">&#39;&#39;&#39;</span>
 402 <span class="sd">    ::</span>
 403
 404 <span class="sd">        getitem == drop first</span>
 405
 406 <span class="sd">    Expects an integer and a quote on the stack and returns the item at the</span>
 407 <span class="sd">    nth position in the quote counting from 0.</span>
 408 <span class="sd">    ::</span>
 409
 410 <span class="sd">           [a b c d] 0 getitem</span>
 411 <span class="sd">        -------------------------</span>
 412 <span class="sd">            a</span>
 413
 414 <span class="sd">    &#39;&#39;&#39;</span>
 415     <span class="n">n</span><span class="p">,</span> <span class="p">(</span><span class="n">Q</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
 416     <span class="k">return</span> <span class="n">pick</span><span class="p">(</span><span class="n">Q</span><span class="p">,</span> <span class="n">n</span><span class="p">),</span> <span class="n">stack</span></div>
 417
 418
 419 <div class="viewcode-block" id="drop"><a class="viewcode-back" href="../../library.html#joy.library.drop">[docs]</a><span class="nd">@inscribe</span>
 420 <span class="nd">@SimpleFunctionWrapper</span>
 421 <span class="k">def</span> <span class="nf">drop</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 422     <span class="sd">&#39;&#39;&#39;</span>
 423 <span class="sd">    ::</span>
 424
 425 <span class="sd">        drop == [rest] times</span>
 426
 427 <span class="sd">    Expects an integer and a quote on the stack and returns the quote with</span>
 428 <span class="sd">    n items removed off the top.</span>
 429 <span class="sd">    ::</span>
 430
 431 <span class="sd">           [a b c d] 2 drop</span>
 432 <span class="sd">        ----------------------</span>
 433 <span class="sd">               [c d]</span>
 434
 435 <span class="sd">    &#39;&#39;&#39;</span>
 436     <span class="n">n</span><span class="p">,</span> <span class="p">(</span><span class="n">Q</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
 437     <span class="k">while</span> <span class="n">n</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
 438         <span class="k">try</span><span class="p">:</span>
 439             <span class="n">_</span><span class="p">,</span> <span class="n">Q</span> <span class="o">=</span> <span class="n">Q</span>
 440         <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
 441             <span class="k">raise</span> <span class="ne">IndexError</span>
 442         <span class="n">n</span> <span class="o">-=</span> <span class="mi">1</span>
 443     <span class="k">return</span> <span class="n">Q</span><span class="p">,</span> <span class="n">stack</span></div>
 444
 445
 446 <div class="viewcode-block" id="take"><a class="viewcode-back" href="../../library.html#joy.library.take">[docs]</a><span class="nd">@inscribe</span>
 447 <span class="nd">@SimpleFunctionWrapper</span>
 448 <span class="k">def</span> <span class="nf">take</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 449     <span class="sd">&#39;&#39;&#39;</span>
 450 <span class="sd">    Expects an integer and a quote on the stack and returns the quote with</span>
 451 <span class="sd">    just the top n items in reverse order (because that&#39;s easier and you can</span>
 452 <span class="sd">    use reverse if needed.)</span>
 453 <span class="sd">    ::</span>
 454
 455 <span class="sd">           [a b c d] 2 take</span>
 456 <span class="sd">        ----------------------</span>
 457 <span class="sd">               [b a]</span>
 458
 459 <span class="sd">    &#39;&#39;&#39;</span>
 460     <span class="n">n</span><span class="p">,</span> <span class="p">(</span><span class="n">Q</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
 461     <span class="n">x</span> <span class="o">=</span> <span class="p">()</span>
 462     <span class="k">while</span> <span class="n">n</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
 463         <span class="k">try</span><span class="p">:</span>
 464             <span class="n">item</span><span class="p">,</span> <span class="n">Q</span> <span class="o">=</span> <span class="n">Q</span>
 465         <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
 466             <span class="k">raise</span> <span class="ne">IndexError</span>
 467         <span class="n">x</span> <span class="o">=</span> <span class="n">item</span><span class="p">,</span> <span class="n">x</span>
 468         <span class="n">n</span> <span class="o">-=</span> <span class="mi">1</span>
 469     <span class="k">return</span> <span class="n">x</span><span class="p">,</span> <span class="n">stack</span></div>
 470
 471
 472 <div class="viewcode-block" id="choice"><a class="viewcode-back" href="../../library.html#joy.library.choice">[docs]</a><span class="nd">@inscribe</span>
 473 <span class="nd">@SimpleFunctionWrapper</span>
 474 <span class="k">def</span> <span class="nf">choice</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 475     <span class="sd">&#39;&#39;&#39;</span>
 476 <span class="sd">    Use a Boolean value to select one of two items.</span>
 477 <span class="sd">    ::</span>
 478
 479 <span class="sd">           A B False choice</span>
 480 <span class="sd">        ----------------------</span>
 481 <span class="sd">           A</span>
 482
 483
 484 <span class="sd">           A B True choice</span>
 485 <span class="sd">        ---------------------</span>
 486 <span class="sd">             B</span>
 487
 488 <span class="sd">    Currently Python semantics are used to evaluate the &quot;truthiness&quot; of the</span>
 489 <span class="sd">    Boolean value (so empty string, zero, etc. are counted as false, etc.)</span>
 490 <span class="sd">    &#39;&#39;&#39;</span>
 491     <span class="p">(</span><span class="n">if_</span><span class="p">,</span> <span class="p">(</span><span class="n">then</span><span class="p">,</span> <span class="p">(</span><span class="n">else_</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span> <span class="o">=</span> <span class="n">stack</span>
 492     <span class="k">return</span> <span class="n">then</span> <span class="k">if</span> <span class="n">if_</span> <span class="k">else</span> <span class="n">else_</span><span class="p">,</span> <span class="n">stack</span></div>
 493
 494
 495 <div class="viewcode-block" id="select"><a class="viewcode-back" href="../../library.html#joy.library.select">[docs]</a><span class="nd">@inscribe</span>
 496 <span class="nd">@SimpleFunctionWrapper</span>
 497 <span class="k">def</span> <span class="nf">select</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 498     <span class="sd">&#39;&#39;&#39;</span>
 499 <span class="sd">    Use a Boolean value to select one of two items from a sequence.</span>
 500 <span class="sd">    ::</span>
 501
 502 <span class="sd">           [A B] False select</span>
 503 <span class="sd">        ------------------------</span>
 504 <span class="sd">            A</span>
 505
 506
 507 <span class="sd">           [A B] True select</span>
 508 <span class="sd">        -----------------------</span>
 509 <span class="sd">              B</span>
 510
 511 <span class="sd">    The sequence can contain more than two items but not fewer.</span>
 512 <span class="sd">    Currently Python semantics are used to evaluate the &quot;truthiness&quot; of the</span>
 513 <span class="sd">    Boolean value (so empty string, zero, etc. are counted as false, etc.)</span>
 514 <span class="sd">    &#39;&#39;&#39;</span>
 515     <span class="p">(</span><span class="n">flag</span><span class="p">,</span> <span class="p">(</span><span class="n">choices</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
 516     <span class="p">(</span><span class="n">else_</span><span class="p">,</span> <span class="p">(</span><span class="n">then</span><span class="p">,</span> <span class="n">_</span><span class="p">))</span> <span class="o">=</span> <span class="n">choices</span>
 517     <span class="k">return</span> <span class="n">then</span> <span class="k">if</span> <span class="n">flag</span> <span class="k">else</span> <span class="n">else_</span><span class="p">,</span> <span class="n">stack</span></div>
 518
 519
 520 <div class="viewcode-block" id="max_"><a class="viewcode-back" href="../../library.html#joy.library.max_">[docs]</a><span class="nd">@inscribe</span>
 521 <span class="nd">@SimpleFunctionWrapper</span>
 522 <span class="k">def</span> <span class="nf">max_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 523     <span class="sd">&#39;&#39;&#39;Given a list find the maximum.&#39;&#39;&#39;</span>
 524     <span class="n">tos</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">S</span>
 525     <span class="k">return</span> <span class="nb">max</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">)),</span> <span class="n">stack</span></div>
 526
 527
 528 <div class="viewcode-block" id="min_"><a class="viewcode-back" href="../../library.html#joy.library.min_">[docs]</a><span class="nd">@inscribe</span>
 529 <span class="nd">@SimpleFunctionWrapper</span>
 530 <span class="k">def</span> <span class="nf">min_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 531     <span class="sd">&#39;&#39;&#39;Given a list find the minimum.&#39;&#39;&#39;</span>
 532     <span class="n">tos</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">S</span>
 533     <span class="k">return</span> <span class="nb">min</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">)),</span> <span class="n">stack</span></div>
 534
 535
 536 <div class="viewcode-block" id="sum_"><a class="viewcode-back" href="../../library.html#joy.library.sum_">[docs]</a><span class="nd">@inscribe</span>
 537 <span class="nd">@SimpleFunctionWrapper</span>
 538 <span class="k">def</span> <span class="nf">sum_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 539     <span class="sd">&#39;&#39;&#39;</span>
 540 <span class="sd">    Given a quoted sequence of numbers return the sum.</span>
 541 <span class="sd">    ::</span>
 542
 543 <span class="sd">        sum == 0 swap [+] step</span>
 544
 545 <span class="sd">    &#39;&#39;&#39;</span>
 546     <span class="n">tos</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">S</span>
 547     <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">)),</span> <span class="n">stack</span></div>
 548
 549
 550 <div class="viewcode-block" id="remove"><a class="viewcode-back" href="../../library.html#joy.library.remove">[docs]</a><span class="nd">@inscribe</span>
 551 <span class="nd">@SimpleFunctionWrapper</span>
 552 <span class="k">def</span> <span class="nf">remove</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 553     <span class="sd">&#39;&#39;&#39;</span>
 554 <span class="sd">    Expects an item on the stack and a quote under it and removes that item</span>
 555 <span class="sd">    from the the quote.  The item is only removed once.</span>
 556 <span class="sd">    ::</span>
 557
 558 <span class="sd">           [1 2 3 1] 1 remove</span>
 559 <span class="sd">        ------------------------</span>
 560 <span class="sd">             [2 3 1]</span>
 561
 562 <span class="sd">    &#39;&#39;&#39;</span>
 563     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
 564     <span class="n">l</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">second</span><span class="p">))</span>
 565     <span class="n">l</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">tos</span><span class="p">)</span>
 566     <span class="k">return</span> <span class="n">list_to_stack</span><span class="p">(</span><span class="n">l</span><span class="p">),</span> <span class="n">stack</span></div>
 567
 568
 569 <div class="viewcode-block" id="unique"><a class="viewcode-back" href="../../library.html#joy.library.unique">[docs]</a><span class="nd">@inscribe</span>
 570 <span class="nd">@SimpleFunctionWrapper</span>
 571 <span class="k">def</span> <span class="nf">unique</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 572     <span class="sd">&#39;&#39;&#39;Given a list remove duplicate items.&#39;&#39;&#39;</span>
 573     <span class="n">tos</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">S</span>
 574     <span class="n">I</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">))</span>
 575     <span class="k">return</span> <span class="n">list_to_stack</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">I</span><span class="p">),</span> <span class="n">key</span><span class="o">=</span><span class="n">I</span><span class="o">.</span><span class="n">index</span><span class="p">)),</span> <span class="n">stack</span></div>
 576
 577
 578 <div class="viewcode-block" id="sort_"><a class="viewcode-back" href="../../library.html#joy.library.sort_">[docs]</a><span class="nd">@inscribe</span>
 579 <span class="nd">@SimpleFunctionWrapper</span>
 580 <span class="k">def</span> <span class="nf">sort_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 581     <span class="sd">&#39;&#39;&#39;Given a list return it sorted.&#39;&#39;&#39;</span>
 582     <span class="n">tos</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">S</span>
 583     <span class="k">return</span> <span class="n">list_to_stack</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">))),</span> <span class="n">stack</span></div>
 584
 585
 586 <div class="viewcode-block" id="clear"><a class="viewcode-back" href="../../library.html#joy.library.clear">[docs]</a><span class="nd">@inscribe</span>
 587 <span class="nd">@SimpleFunctionWrapper</span>
 588 <span class="k">def</span> <span class="nf">clear</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 589     <span class="sd">&#39;&#39;&#39;Clear everything from the stack.</span>
 590 <span class="sd">    ::</span>
 591
 592 <span class="sd">        clear == stack [pop stack] loop</span>
 593
 594 <span class="sd">           ... clear</span>
 595 <span class="sd">        ---------------</span>
 596
 597 <span class="sd">    &#39;&#39;&#39;</span>
 598     <span class="k">return</span> <span class="p">()</span></div>
 599
 600
 601 <div class="viewcode-block" id="disenstacken"><a class="viewcode-back" href="../../library.html#joy.library.disenstacken">[docs]</a><span class="nd">@inscribe</span>
 602 <span class="nd">@SimpleFunctionWrapper</span>
 603 <span class="k">def</span> <span class="nf">disenstacken</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 604     <span class="sd">&#39;&#39;&#39;</span>
 605 <span class="sd">    The disenstacken operator expects a list on top of the stack and makes that</span>
 606 <span class="sd">    the stack discarding the rest of the stack.</span>
 607 <span class="sd">    &#39;&#39;&#39;</span>
 608     <span class="k">return</span> <span class="n">stack</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span></div>
 609
 610
 611 <div class="viewcode-block" id="reverse"><a class="viewcode-back" href="../../library.html#joy.library.reverse">[docs]</a><span class="nd">@inscribe</span>
 612 <span class="nd">@SimpleFunctionWrapper</span>
 613 <span class="k">def</span> <span class="nf">reverse</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 614     <span class="sd">&#39;&#39;&#39;</span>
 615 <span class="sd">    Reverse the list on the top of the stack.</span>
 616 <span class="sd">    ::</span>
 617
 618 <span class="sd">        reverse == [] swap shunt</span>
 619 <span class="sd">    &#39;&#39;&#39;</span>
 620     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">S</span>
 621     <span class="n">res</span> <span class="o">=</span> <span class="p">()</span>
 622     <span class="k">for</span> <span class="n">term</span> <span class="ow">in</span> <span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">):</span>
 623         <span class="n">res</span> <span class="o">=</span> <span class="n">term</span><span class="p">,</span> <span class="n">res</span>
 624     <span class="k">return</span> <span class="n">res</span><span class="p">,</span> <span class="n">stack</span></div>
 625
 626
 627 <div class="viewcode-block" id="concat_"><a class="viewcode-back" href="../../library.html#joy.library.concat_">[docs]</a><span class="nd">@inscribe</span>
 628 <span class="nd">@SimpleFunctionWrapper</span>
 629 <span class="k">def</span> <span class="nf">concat_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 630     <span class="sd">&#39;&#39;&#39;</span>
 631 <span class="sd">    Concatinate the two lists on the top of the stack.</span>
 632 <span class="sd">    ::</span>
 633
 634 <span class="sd">           [a b c] [d e f] concat</span>
 635 <span class="sd">        ----------------------------</span>
 636 <span class="sd">               [a b c d e f]</span>
 637
 638 <span class="sd">    &#39;&#39;&#39;</span>
 639     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
 640     <span class="k">return</span> <span class="n">concat</span><span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="n">tos</span><span class="p">),</span> <span class="n">stack</span></div>
 641
 642
 643 <div class="viewcode-block" id="shunt"><a class="viewcode-back" href="../../library.html#joy.library.shunt">[docs]</a><span class="nd">@inscribe</span>
 644 <span class="nd">@SimpleFunctionWrapper</span>
 645 <span class="k">def</span> <span class="nf">shunt</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 646     <span class="sd">&#39;&#39;&#39;</span>
 647 <span class="sd">    Like concat but reverses the top list into the second.</span>
 648 <span class="sd">    ::</span>
 649
 650 <span class="sd">        shunt == [swons] step == reverse swap concat</span>
 651
 652 <span class="sd">           [a b c] [d e f] shunt</span>
 653 <span class="sd">        ---------------------------</span>
 654 <span class="sd">               [f e d a b c] </span>
 655
 656 <span class="sd">    &#39;&#39;&#39;</span>
 657     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
 658     <span class="k">while</span> <span class="n">tos</span><span class="p">:</span>
 659         <span class="n">term</span><span class="p">,</span> <span class="n">tos</span> <span class="o">=</span> <span class="n">tos</span>
 660         <span class="n">second</span> <span class="o">=</span> <span class="n">term</span><span class="p">,</span> <span class="n">second</span>
 661     <span class="k">return</span> <span class="n">second</span><span class="p">,</span> <span class="n">stack</span></div>
 662
 663
 664 <div class="viewcode-block" id="zip_"><a class="viewcode-back" href="../../library.html#joy.library.zip_">[docs]</a><span class="nd">@inscribe</span>
 665 <span class="nd">@SimpleFunctionWrapper</span>
 666 <span class="k">def</span> <span class="nf">zip_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 667     <span class="sd">&#39;&#39;&#39;</span>
 668 <span class="sd">    Replace the two lists on the top of the stack with a list of the pairs</span>
 669 <span class="sd">    from each list.  The smallest list sets the length of the result list.</span>
 670 <span class="sd">    &#39;&#39;&#39;</span>
 671     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="p">(</span><span class="n">second</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
 672     <span class="n">accumulator</span> <span class="o">=</span> <span class="p">[</span>
 673         <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="p">()))</span>
 674         <span class="k">for</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">iter_stack</span><span class="p">(</span><span class="n">tos</span><span class="p">),</span> <span class="n">iter_stack</span><span class="p">(</span><span class="n">second</span><span class="p">))</span>
 675         <span class="p">]</span>
 676     <span class="k">return</span> <span class="n">list_to_stack</span><span class="p">(</span><span class="n">accumulator</span><span class="p">),</span> <span class="n">stack</span></div>
 677
 678
 679 <div class="viewcode-block" id="succ"><a class="viewcode-back" href="../../library.html#joy.library.succ">[docs]</a><span class="nd">@inscribe</span>
 680 <span class="nd">@SimpleFunctionWrapper</span>
 681 <span class="k">def</span> <span class="nf">succ</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 682     <span class="sd">&#39;&#39;&#39;Increment TOS.&#39;&#39;&#39;</span>
 683     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">S</span>
 684     <span class="k">return</span> <span class="n">tos</span> <span class="o">+</span> <span class="mi">1</span><span class="p">,</span> <span class="n">stack</span></div>
 685
 686
 687 <div class="viewcode-block" id="pred"><a class="viewcode-back" href="../../library.html#joy.library.pred">[docs]</a><span class="nd">@inscribe</span>
 688 <span class="nd">@SimpleFunctionWrapper</span>
 689 <span class="k">def</span> <span class="nf">pred</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 690     <span class="sd">&#39;&#39;&#39;Decrement TOS.&#39;&#39;&#39;</span>
 691     <span class="p">(</span><span class="n">tos</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">S</span>
 692     <span class="k">return</span> <span class="n">tos</span> <span class="o">-</span> <span class="mi">1</span><span class="p">,</span> <span class="n">stack</span></div>
 693
 694
 695 <div class="viewcode-block" id="pm"><a class="viewcode-back" href="../../library.html#joy.library.pm">[docs]</a><span class="nd">@inscribe</span>
 696 <span class="nd">@SimpleFunctionWrapper</span>
 697 <span class="k">def</span> <span class="nf">pm</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 698     <span class="sd">&#39;&#39;&#39;</span>
 699 <span class="sd">    Plus or minus</span>
 700 <span class="sd">    ::</span>
 701
 702 <span class="sd">           a b pm</span>
 703 <span class="sd">        -------------</span>
 704 <span class="sd">           a+b a-b</span>
 705
 706 <span class="sd">    &#39;&#39;&#39;</span>
 707     <span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
 708     <span class="n">p</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="o">=</span> <span class="n">b</span> <span class="o">+</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span> <span class="o">-</span> <span class="n">a</span>
 709     <span class="k">return</span> <span class="n">m</span><span class="p">,</span> <span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span></div>
 710
 711
 712 <div class="viewcode-block" id="floor"><a class="viewcode-back" href="../../library.html#joy.library.floor">[docs]</a><span class="k">def</span> <span class="nf">floor</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
 713     <span class="k">return</span> <span class="nb">int</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">floor</span><span class="p">(</span><span class="n">n</span><span class="p">))</span></div>
 714
 715 <span class="n">floor</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">floor</span><span class="o">.</span><span class="vm">__doc__</span>
 716
 717
 718 <div class="viewcode-block" id="divmod_"><a class="viewcode-back" href="../../library.html#joy.library.divmod_">[docs]</a><span class="nd">@inscribe</span>
 719 <span class="nd">@SimpleFunctionWrapper</span>
 720 <span class="k">def</span> <span class="nf">divmod_</span><span class="p">(</span><span class="n">S</span><span class="p">):</span>
 721     <span class="sd">&#39;&#39;&#39;</span>
 722 <span class="sd">    divmod(x, y) -&gt; (quotient, remainder)</span>
 723
 724 <span class="sd">    Return the tuple (x//y, x%y).  Invariant: div*y + mod == x.</span>
 725 <span class="sd">    &#39;&#39;&#39;</span>
 726     <span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">S</span>
 727     <span class="n">d</span><span class="p">,</span> <span class="n">m</span> <span class="o">=</span> <span class="nb">divmod</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
 728     <span class="k">return</span> <span class="n">d</span><span class="p">,</span> <span class="p">(</span><span class="n">m</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span></div>
 729
 730
 731 <div class="viewcode-block" id="sqrt"><a class="viewcode-back" href="../../library.html#joy.library.sqrt">[docs]</a><span class="k">def</span> <span class="nf">sqrt</span><span class="p">(</span><span class="n">a</span><span class="p">):</span>
 732     <span class="sd">&#39;&#39;&#39;</span>
 733 <span class="sd">    Return the square root of the number a.</span>
 734 <span class="sd">    Negative numbers return complex roots.</span>
 735 <span class="sd">    &#39;&#39;&#39;</span>
 736     <span class="k">try</span><span class="p">:</span>
 737         <span class="n">r</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
 738     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
 739         <span class="k">assert</span> <span class="n">a</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
 740         <span class="n">r</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="o">-</span><span class="n">a</span><span class="p">)</span> <span class="o">*</span> <span class="mi">1</span><span class="n">j</span>
 741     <span class="k">return</span> <span class="n">r</span></div>
 742
 743
 744 <span class="c1">#def execute(S):</span>
 745 <span class="c1">#  (text, stack) = S</span>
 746 <span class="c1">#  if isinstance(text, str):</span>
 747 <span class="c1">#    return run(text, stack)</span>
 748 <span class="c1">#  return stack</span>
 749
 750
 751 <div class="viewcode-block" id="id_"><a class="viewcode-back" href="../../library.html#joy.library.id_">[docs]</a><span class="nd">@inscribe</span>
 752 <span class="nd">@SimpleFunctionWrapper</span>
 753 <span class="k">def</span> <span class="nf">id_</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 754     <span class="sd">&#39;&#39;&#39;The identity function.&#39;&#39;&#39;</span>
 755     <span class="k">return</span> <span class="n">stack</span></div>
 756
 757
 758 <div class="viewcode-block" id="void"><a class="viewcode-back" href="../../library.html#joy.library.void">[docs]</a><span class="nd">@inscribe</span>
 759 <span class="nd">@SimpleFunctionWrapper</span>
 760 <span class="k">def</span> <span class="nf">void</span><span class="p">(</span><span class="n">stack</span><span class="p">):</span>
 761     <span class="sd">&#39;&#39;&#39;True if the form on TOS is void otherwise False.&#39;&#39;&#39;</span>
 762     <span class="n">form</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
 763     <span class="k">return</span> <span class="n">_void</span><span class="p">(</span><span class="n">form</span><span class="p">),</span> <span class="n">stack</span></div>
 764
 765
 766 <span class="k">def</span> <span class="nf">_void</span><span class="p">(</span><span class="n">form</span><span class="p">):</span>
 767     <span class="k">return</span> <span class="nb">any</span><span class="p">(</span><span class="ow">not</span> <span class="n">_void</span><span class="p">(</span><span class="n">i</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">iter_stack</span><span class="p">(</span><span class="n">form</span><span class="p">))</span>
 768
 769
 770
 771 <span class="c1">##  transpose</span>
 772 <span class="c1">##  sign</span>
 773 <span class="c1">##  take</span>
 774
 775
 776 <div class="viewcode-block" id="words"><a class="viewcode-back" href="../../library.html#joy.library.words">[docs]</a><span class="nd">@inscribe</span>
 777 <span class="nd">@FunctionWrapper</span>
 778 <span class="k">def</span> <span class="nf">words</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 779     <span class="sd">&#39;&#39;&#39;Print all the words in alphabetical order.&#39;&#39;&#39;</span>
 780     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39; &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="n">dictionary</span><span class="p">)))</span>
 781     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
 782
 783
 784 <div class="viewcode-block" id="sharing"><a class="viewcode-back" href="../../library.html#joy.library.sharing">[docs]</a><span class="nd">@inscribe</span>
 785 <span class="nd">@FunctionWrapper</span>
 786 <span class="k">def</span> <span class="nf">sharing</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 787     <span class="sd">&#39;&#39;&#39;Print redistribution information.&#39;&#39;&#39;</span>
 788     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;You may convey verbatim copies of the Program&#39;s source code as&quot;</span>
 789     <span class="s1">&#39; you receive it, in any medium, provided that you conspicuously&#39;</span>
 790     <span class="s1">&#39; and appropriately publish on each copy an appropriate copyright&#39;</span>
 791     <span class="s1">&#39; notice; keep intact all notices stating that this License and&#39;</span>
 792     <span class="s1">&#39; any non-permissive terms added in accord with section 7 apply&#39;</span>
 793     <span class="s1">&#39; to the code; keep intact all notices of the absence of any&#39;</span>
 794     <span class="s1">&#39; warranty; and give all recipients a copy of this License along&#39;</span>
 795     <span class="s1">&#39; with the Program.&#39;</span>
 796     <span class="s1">&#39; You should have received a copy of the GNU General Public License&#39;</span>
 797     <span class="s1">&#39; along with Thun.  If not see &lt;http://www.gnu.org/licenses/&gt;.&#39;</span><span class="p">)</span>
 798     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
 799
 800
 801 <div class="viewcode-block" id="warranty"><a class="viewcode-back" href="../../library.html#joy.library.warranty">[docs]</a><span class="nd">@inscribe</span>
 802 <span class="nd">@FunctionWrapper</span>
 803 <span class="k">def</span> <span class="nf">warranty</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 804     <span class="sd">&#39;&#39;&#39;Print warranty information.&#39;&#39;&#39;</span>
 805     <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY&#39;</span>
 806     <span class="s1">&#39; APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE&#39;</span>
 807     <span class="s1">&#39; COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM&#39;</span>
 808     <span class="s1">&#39; &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR&#39;</span>
 809     <span class="s1">&#39; IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES&#39;</span>
 810     <span class="s1">&#39; OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE&#39;</span>
 811     <span class="s1">&#39; ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS&#39;</span>
 812     <span class="s1">&#39; WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE&#39;</span>
 813     <span class="s1">&#39; COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.&#39;</span><span class="p">)</span>
 814     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
 815
 816
 817 <span class="c1"># def simple_manual(stack):</span>
 818 <span class="c1">#   &#39;&#39;&#39;</span>
 819 <span class="c1">#   Print words and help for each word.</span>
 820 <span class="c1">#   &#39;&#39;&#39;</span>
 821 <span class="c1">#   for name, f in sorted(FUNCTIONS.items()):</span>
 822 <span class="c1">#     d = getdoc(f)</span>
 823 <span class="c1">#     boxline = &#39;+%s+&#39; % (&#39;-&#39; * (len(name) + 2))</span>
 824 <span class="c1">#     print(&#39;\n&#39;.join((</span>
 825 <span class="c1">#       boxline,</span>
 826 <span class="c1">#       &#39;| %s |&#39; % (name,),</span>
 827 <span class="c1">#       boxline,</span>
 828 <span class="c1">#       d if d else &#39;   ...&#39;,</span>
 829 <span class="c1">#       &#39;&#39;,</span>
 830 <span class="c1">#       &#39;--&#39; * 40,</span>
 831 <span class="c1">#       &#39;&#39;,</span>
 832 <span class="c1">#       )))</span>
 833 <span class="c1">#   return stack</span>
 834
 835
 836 <div class="viewcode-block" id="help_"><a class="viewcode-back" href="../../library.html#joy.library.help_">[docs]</a><span class="nd">@inscribe</span>
 837 <span class="nd">@FunctionWrapper</span>
 838 <span class="k">def</span> <span class="nf">help_</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 839     <span class="sd">&#39;&#39;&#39;Accepts a quoted symbol on the top of the stack and prints its docs.&#39;&#39;&#39;</span>
 840     <span class="p">((</span><span class="n">symbol</span><span class="p">,</span> <span class="n">_</span><span class="p">),</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">S</span>
 841     <span class="n">word</span> <span class="o">=</span> <span class="n">dictionary</span><span class="p">[</span><span class="n">symbol</span><span class="p">]</span>
 842     <span class="nb">print</span><span class="p">(</span><span class="n">HELP_TEMPLATE</span> <span class="o">%</span> <span class="p">(</span><span class="n">symbol</span><span class="p">,</span> <span class="n">getdoc</span><span class="p">(</span><span class="n">word</span><span class="p">),</span> <span class="n">symbol</span><span class="p">))</span>
 843     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
 844
 845
 846 <span class="c1">#</span>
 847 <span class="c1"># § Combinators</span>
 848 <span class="c1">#</span>
 849
 850
 851 <span class="c1"># Several combinators depend on other words in their definitions,</span>
 852 <span class="c1"># we use symbols to prevent hard-coding these, so in theory, you</span>
 853 <span class="c1"># could change the word in the dictionary to use different semantics.</span>
 854 <span class="n">S_choice</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;choice&#39;</span><span class="p">)</span>
 855 <span class="n">S_first</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;first&#39;</span><span class="p">)</span>
 856 <span class="n">S_genrec</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;genrec&#39;</span><span class="p">)</span>
 857 <span class="n">S_getitem</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;getitem&#39;</span><span class="p">)</span>
 858 <span class="n">S_i</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;i&#39;</span><span class="p">)</span>
 859 <span class="n">S_ifte</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;ifte&#39;</span><span class="p">)</span>
 860 <span class="n">S_infra</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;infra&#39;</span><span class="p">)</span>
 861 <span class="n">S_loop</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;loop&#39;</span><span class="p">)</span>
 862 <span class="n">S_pop</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;pop&#39;</span><span class="p">)</span>
 863 <span class="n">S_primrec</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;primrec&#39;</span><span class="p">)</span>
 864 <span class="n">S_step</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;step&#39;</span><span class="p">)</span>
 865 <span class="n">S_swaack</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;swaack&#39;</span><span class="p">)</span>
 866 <span class="n">S_times</span> <span class="o">=</span> <span class="n">Symbol</span><span class="p">(</span><span class="s1">&#39;times&#39;</span><span class="p">)</span>
 867
 868
 869 <div class="viewcode-block" id="i"><a class="viewcode-back" href="../../library.html#joy.library.i">[docs]</a><span class="nd">@inscribe</span>
 870 <span class="nd">@FunctionWrapper</span>
 871 <span class="k">def</span> <span class="nf">i</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 872     <span class="sd">&#39;&#39;&#39;</span>
 873 <span class="sd">    The i combinator expects a quoted program on the stack and unpacks it</span>
 874 <span class="sd">    onto the pending expression for evaluation.</span>
 875 <span class="sd">    ::</span>
 876
 877 <span class="sd">           [Q] i</span>
 878 <span class="sd">        -----------</span>
 879 <span class="sd">            Q</span>
 880
 881 <span class="sd">    &#39;&#39;&#39;</span>
 882     <span class="k">try</span><span class="p">:</span>
 883         <span class="n">quote</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
 884     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
 885         <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
 886     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
 887
 888
 889 <div class="viewcode-block" id="x"><a class="viewcode-back" href="../../library.html#joy.library.x">[docs]</a><span class="nd">@inscribe</span>
 890 <span class="nd">@FunctionWrapper</span>
 891 <span class="k">def</span> <span class="nf">x</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 892     <span class="sd">&#39;&#39;&#39;</span>
 893 <span class="sd">    ::</span>
 894
 895 <span class="sd">        x == dup i</span>
 896
 897 <span class="sd">        ... [Q] x = ... [Q] dup i</span>
 898 <span class="sd">        ... [Q] x = ... [Q] [Q] i</span>
 899 <span class="sd">        ... [Q] x = ... [Q]  Q</span>
 900
 901 <span class="sd">    &#39;&#39;&#39;</span>
 902     <span class="n">quote</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">stack</span>
 903     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
 904
 905
 906 <div class="viewcode-block" id="b"><a class="viewcode-back" href="../../library.html#joy.library.b">[docs]</a><span class="nd">@inscribe</span>
 907 <span class="nd">@FunctionWrapper</span>
 908 <span class="k">def</span> <span class="nf">b</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 909     <span class="sd">&#39;&#39;&#39;</span>
 910 <span class="sd">    ::</span>
 911
 912 <span class="sd">        b == [i] dip i</span>
 913
 914 <span class="sd">        ... [P] [Q] b == ... [P] i [Q] i</span>
 915 <span class="sd">        ... [P] [Q] b == ... P Q</span>
 916
 917 <span class="sd">    &#39;&#39;&#39;</span>
 918     <span class="n">q</span><span class="p">,</span> <span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="p">(</span><span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
 919     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">q</span><span class="p">,</span> <span class="n">expression</span><span class="p">)),</span> <span class="n">dictionary</span></div>
 920
 921
 922 <div class="viewcode-block" id="dupdip"><a class="viewcode-back" href="../../library.html#joy.library.dupdip">[docs]</a><span class="nd">@inscribe</span>
 923 <span class="nd">@FunctionWrapper</span>
 924 <span class="k">def</span> <span class="nf">dupdip</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 925     <span class="sd">&#39;&#39;&#39;</span>
 926 <span class="sd">    ::</span>
 927
 928 <span class="sd">        [F] dupdip == dup [F] dip</span>
 929
 930 <span class="sd">        ... a [F] dupdip</span>
 931 <span class="sd">        ... a dup [F] dip</span>
 932 <span class="sd">        ... a a   [F] dip</span>
 933 <span class="sd">        ... a F a</span>
 934
 935 <span class="sd">    &#39;&#39;&#39;</span>
 936     <span class="n">F</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
 937     <span class="n">a</span> <span class="o">=</span> <span class="n">stack</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
 938     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="p">(</span><span class="n">a</span><span class="p">,</span>  <span class="n">expression</span><span class="p">)),</span> <span class="n">dictionary</span></div>
 939
 940
 941 <div class="viewcode-block" id="infra"><a class="viewcode-back" href="../../library.html#joy.library.infra">[docs]</a><span class="nd">@inscribe</span>
 942 <span class="nd">@FunctionWrapper</span>
 943 <span class="k">def</span> <span class="nf">infra</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 944     <span class="sd">&#39;&#39;&#39;</span>
 945 <span class="sd">    Accept a quoted program and a list on the stack and run the program</span>
 946 <span class="sd">    with the list as its stack.  Does not affect the rest of the stack.</span>
 947 <span class="sd">    ::</span>
 948
 949 <span class="sd">           ... [a b c] [Q] . infra</span>
 950 <span class="sd">        -----------------------------</span>
 951 <span class="sd">            c b a . Q [...] swaack</span>
 952
 953 <span class="sd">    &#39;&#39;&#39;</span>
 954     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">aggregate</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
 955     <span class="k">return</span> <span class="n">aggregate</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="p">(</span><span class="n">S_swaack</span><span class="p">,</span> <span class="n">expression</span><span class="p">))),</span> <span class="n">dictionary</span></div>
 956
 957
 958 <div class="viewcode-block" id="genrec"><a class="viewcode-back" href="../../library.html#joy.library.genrec">[docs]</a><span class="nd">@inscribe</span>
 959 <span class="nd">@FunctionWrapper</span>
 960 <span class="k">def</span> <span class="nf">genrec</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
 961     <span class="sd">&#39;&#39;&#39;</span>
 962 <span class="sd">    General Recursion Combinator.</span>
 963 <span class="sd">    ::</span>
 964
 965 <span class="sd">                  [if] [then] [rec1] [rec2] genrec</span>
 966 <span class="sd">        ---------------------------------------------------------------------</span>
 967 <span class="sd">           [if] [then] [rec1 [[if] [then] [rec1] [rec2] genrec] rec2] ifte</span>
 968
 969 <span class="sd">    From &quot;Recursion Theory and Joy&quot; (j05cmp.html) by Manfred von Thun:</span>
 970 <span class="sd">    &quot;The genrec combinator takes four program parameters in addition to</span>
 971 <span class="sd">    whatever data parameters it needs. Fourth from the top is an if-part,</span>
 972 <span class="sd">    followed by a then-part. If the if-part yields true, then the then-part</span>
 973 <span class="sd">    is executed and the combinator terminates. The other two parameters are</span>
 974 <span class="sd">    the rec1-part and the rec2-part. If the if-part yields false, the</span>
 975 <span class="sd">    rec1-part is executed. Following that the four program parameters and</span>
 976 <span class="sd">    the combinator are again pushed onto the stack bundled up in a quoted</span>
 977 <span class="sd">    form. Then the rec2-part is executed, where it will find the bundled</span>
 978 <span class="sd">    form. Typically it will then execute the bundled form, either with i or</span>
 979 <span class="sd">    with app2, or some other combinator.&quot;</span>
 980
 981 <span class="sd">    The way to design one of these is to fix your base case [then] and the</span>
 982 <span class="sd">    test [if], and then treat rec1 and rec2 as an else-part &quot;sandwiching&quot;</span>
 983 <span class="sd">    a quotation of the whole function.</span>
 984
 985 <span class="sd">    For example, given a (general recursive) function &#39;F&#39;:</span>
 986 <span class="sd">    ::</span>
 987
 988 <span class="sd">        F == [I] [T] [R1] [R2] genrec</span>
 989
 990 <span class="sd">    If the [I] if-part fails you must derive R1 and R2 from:</span>
 991 <span class="sd">    ::</span>
 992
 993 <span class="sd">        ... R1 [F] R2</span>
 994
 995 <span class="sd">    Just set the stack arguments in front, and figure out what R1 and R2</span>
 996 <span class="sd">    have to do to apply the quoted [F] in the proper way.  In effect, the</span>
 997 <span class="sd">    genrec combinator turns into an ifte combinator with a quoted copy of</span>
 998 <span class="sd">    the original definition in the else-part:</span>
 999 <span class="sd">    ::</span>
1000
1001 <span class="sd">        F == [I] [T] [R1]   [R2] genrec</span>
1002 <span class="sd">          == [I] [T] [R1 [F] R2] ifte</span>
1003
1004 <span class="sd">    Primitive recursive functions are those where R2 == i.</span>
1005 <span class="sd">    ::</span>
1006
1007 <span class="sd">        P == [I] [T] [R] tailrec</span>
1008 <span class="sd">          == [I] [T] [R [P] i] ifte</span>
1009 <span class="sd">          == [I] [T] [R P] ifte</span>
1010
1011 <span class="sd">    &#39;&#39;&#39;</span>
1012     <span class="p">(</span><span class="n">rec2</span><span class="p">,</span> <span class="p">(</span><span class="n">rec1</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
1013     <span class="p">(</span><span class="n">then</span><span class="p">,</span> <span class="p">(</span><span class="n">if_</span><span class="p">,</span> <span class="n">_</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
1014     <span class="n">F</span> <span class="o">=</span> <span class="p">(</span><span class="n">if_</span><span class="p">,</span> <span class="p">(</span><span class="n">then</span><span class="p">,</span> <span class="p">(</span><span class="n">rec1</span><span class="p">,</span> <span class="p">(</span><span class="n">rec2</span><span class="p">,</span> <span class="p">(</span><span class="n">S_genrec</span><span class="p">,</span> <span class="p">())))))</span>
1015     <span class="n">else_</span> <span class="o">=</span> <span class="n">concat</span><span class="p">(</span><span class="n">rec1</span><span class="p">,</span> <span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="n">rec2</span><span class="p">))</span>
1016     <span class="k">return</span> <span class="p">(</span><span class="n">else_</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="p">(</span><span class="n">S_ifte</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1017
1018
1019 <div class="viewcode-block" id="map_"><a class="viewcode-back" href="../../library.html#joy.library.map_">[docs]</a><span class="nd">@inscribe</span>
1020 <span class="nd">@FunctionWrapper</span>
1021 <span class="k">def</span> <span class="nf">map_</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1022     <span class="sd">&#39;&#39;&#39;</span>
1023 <span class="sd">    Run the quoted program on TOS on the items in the list under it, push a</span>
1024 <span class="sd">    new list with the results in place of the program and original list.</span>
1025 <span class="sd">    &#39;&#39;&#39;</span>
1026     <span class="c1"># (quote, (aggregate, stack)) = S</span>
1027     <span class="c1"># results = list_to_stack([</span>
1028     <span class="c1"># joy((term, stack), quote, dictionary)[0][0]</span>
1029     <span class="c1"># for term in iter_stack(aggregate)</span>
1030     <span class="c1"># ])</span>
1031     <span class="c1"># return (results, stack), expression, dictionary</span>
1032     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">aggregate</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
1033     <span class="k">if</span> <span class="ow">not</span> <span class="n">aggregate</span><span class="p">:</span>
1034         <span class="k">return</span> <span class="p">(</span><span class="n">aggregate</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
1035     <span class="n">batch</span> <span class="o">=</span> <span class="p">()</span>
1036     <span class="k">for</span> <span class="n">term</span> <span class="ow">in</span> <span class="n">iter_stack</span><span class="p">(</span><span class="n">aggregate</span><span class="p">):</span>
1037         <span class="n">s</span> <span class="o">=</span> <span class="n">term</span><span class="p">,</span> <span class="n">stack</span>
1038         <span class="n">batch</span> <span class="o">=</span> <span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span> <span class="n">batch</span><span class="p">))))</span>
1039     <span class="n">stack</span> <span class="o">=</span> <span class="p">(</span><span class="n">batch</span><span class="p">,</span> <span class="p">((),</span> <span class="n">stack</span><span class="p">))</span>
1040     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1041
1042
1043 <div class="viewcode-block" id="primrec"><a class="viewcode-back" href="../../library.html#joy.library.primrec">[docs]</a><span class="nd">@inscribe</span>
1044 <span class="nd">@FunctionWrapper</span>
1045 <span class="k">def</span> <span class="nf">primrec</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1046     <span class="sd">&#39;&#39;&#39;</span>
1047 <span class="sd">    From the &quot;Overview of the language JOY&quot;:</span>
1048
1049 <span class="sd">    &gt; The primrec combinator expects two quoted programs in addition to a</span>
1050 <span class="sd">    data parameter. For an integer data parameter it works like this: If</span>
1051 <span class="sd">    the data parameter is zero, then the first quotation has to produce</span>
1052 <span class="sd">    the value to be returned. If the data parameter is positive then the</span>
1053 <span class="sd">    second has to combine the data parameter with the result of applying</span>
1054 <span class="sd">    the function to its predecessor.::</span>
1055
1056 <span class="sd">        5  [1]  [*]  primrec</span>
1057
1058 <span class="sd">    &gt; Then primrec tests whether the top element on the stack (initially</span>
1059 <span class="sd">    the 5) is equal to zero. If it is, it pops it off and executes one of</span>
1060 <span class="sd">    the quotations, the [1] which leaves 1 on the stack as the result.</span>
1061 <span class="sd">    Otherwise it pushes a decremented copy of the top element and</span>
1062 <span class="sd">    recurses. On the way back from the recursion it uses the other</span>
1063 <span class="sd">    quotation, [*], to multiply what is now a factorial on top of the</span>
1064 <span class="sd">    stack by the second element on the stack.::</span>
1065
1066 <span class="sd">        n [Base] [Recur] primrec</span>
1067
1068 <span class="sd">           0 [Base] [Recur] primrec</span>
1069 <span class="sd">        ------------------------------</span>
1070 <span class="sd">              Base</span>
1071
1072 <span class="sd">             n [Base] [Recur] primrec</span>
1073 <span class="sd">        ------------------------------------------ n &gt; 0</span>
1074 <span class="sd">           n (n-1) [Base] [Recur] primrec Recur</span>
1075
1076 <span class="sd">    &#39;&#39;&#39;</span>
1077     <span class="n">recur</span><span class="p">,</span> <span class="p">(</span><span class="n">base</span><span class="p">,</span> <span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
1078     <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;=</span> <span class="mi">0</span><span class="p">:</span>
1079         <span class="n">expression</span> <span class="o">=</span> <span class="n">concat</span><span class="p">(</span><span class="n">base</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1080     <span class="k">else</span><span class="p">:</span>
1081         <span class="n">expression</span> <span class="o">=</span> <span class="n">S_primrec</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">recur</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1082         <span class="n">stack</span> <span class="o">=</span> <span class="n">recur</span><span class="p">,</span> <span class="p">(</span><span class="n">base</span><span class="p">,</span> <span class="p">(</span><span class="n">n</span> <span class="o">-</span> <span class="mi">1</span><span class="p">,</span> <span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span>
1083     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1084
1085
1086 <span class="c1">#def cleave(S, expression, dictionary):</span>
1087 <span class="c1">#  &#39;&#39;&#39;</span>
1088 <span class="c1">#  The cleave combinator expects two quotations, and below that an item X.</span>
1089 <span class="c1">#  It first executes [P], with X on top, and saves the top result element.</span>
1090 <span class="c1">#  Then it executes [Q], again with X, and saves the top result.</span>
1091 <span class="c1">#  Finally it restores the stack to what it was below X and pushes the two</span>
1092 <span class="c1">#  results P(X) and Q(X).</span>
1093 <span class="c1">#  &#39;&#39;&#39;</span>
1094 <span class="c1">#  (Q, (P, (x, stack))) = S</span>
1095 <span class="c1">#  p = joy((x, stack), P, dictionary)[0][0]</span>
1096 <span class="c1">#  q = joy((x, stack), Q, dictionary)[0][0]</span>
1097 <span class="c1">#  return (q, (p, stack)), expression, dictionary</span>
1098
1099
1100 <div class="viewcode-block" id="branch"><a class="viewcode-back" href="../../library.html#joy.library.branch">[docs]</a><span class="nd">@inscribe</span>
1101 <span class="nd">@FunctionWrapper</span>
1102 <span class="k">def</span> <span class="nf">branch</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1103     <span class="sd">&#39;&#39;&#39;</span>
1104 <span class="sd">    Use a Boolean value to select one of two quoted programs to run.</span>
1105
1106 <span class="sd">    ::</span>
1107
1108 <span class="sd">        branch == roll&lt; choice i</span>
1109
1110 <span class="sd">    ::</span>
1111
1112 <span class="sd">           False [F] [T] branch</span>
1113 <span class="sd">        --------------------------</span>
1114 <span class="sd">              F</span>
1115
1116 <span class="sd">           True [F] [T] branch</span>
1117 <span class="sd">        -------------------------</span>
1118 <span class="sd">                 T</span>
1119
1120 <span class="sd">    &#39;&#39;&#39;</span>
1121     <span class="p">(</span><span class="n">then</span><span class="p">,</span> <span class="p">(</span><span class="n">else_</span><span class="p">,</span> <span class="p">(</span><span class="n">flag</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span> <span class="o">=</span> <span class="n">stack</span>
1122     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">then</span> <span class="k">if</span> <span class="n">flag</span> <span class="k">else</span> <span class="n">else_</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1123
1124
1125 <span class="c1">##@inscribe</span>
1126 <span class="c1">##@FunctionWrapper</span>
1127 <span class="c1">##def ifte(stack, expression, dictionary):</span>
1128 <span class="c1">##  &#39;&#39;&#39;</span>
1129 <span class="c1">##  If-Then-Else Combinator</span>
1130 <span class="c1">##  ::</span>
1131 <span class="c1">##</span>
1132 <span class="c1">##                  ... [if] [then] [else] ifte</span>
1133 <span class="c1">##       ---------------------------------------------------</span>
1134 <span class="c1">##          ... [[else] [then]] [...] [if] infra select i</span>
1135 <span class="c1">##</span>
1136 <span class="c1">##</span>
1137 <span class="c1">##</span>
1138 <span class="c1">##</span>
1139 <span class="c1">##                ... [if] [then] [else] ifte</span>
1140 <span class="c1">##       -------------------------------------------------------</span>
1141 <span class="c1">##          ... [else] [then] [...] [if] infra first choice i</span>
1142 <span class="c1">##</span>
1143 <span class="c1">##</span>
1144 <span class="c1">##  Has the effect of grabbing a copy of the stack on which to run the</span>
1145 <span class="c1">##  if-part using infra.</span>
1146 <span class="c1">##  &#39;&#39;&#39;</span>
1147 <span class="c1">##  (else_, (then, (if_, stack))) = stack</span>
1148 <span class="c1">##  expression = (S_infra, (S_first, (S_choice, (S_i, expression))))</span>
1149 <span class="c1">##  stack = (if_, (stack, (then, (else_, stack))))</span>
1150 <span class="c1">##  return stack, expression, dictionary</span>
1151
1152
1153 <div class="viewcode-block" id="cond"><a class="viewcode-back" href="../../library.html#joy.library.cond">[docs]</a><span class="nd">@inscribe</span>
1154 <span class="nd">@FunctionWrapper</span>
1155 <span class="k">def</span> <span class="nf">cond</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1156     <span class="sd">&#39;&#39;&#39;</span>
1157 <span class="sd">    This combinator works like a case statement.  It expects a single quote</span>
1158 <span class="sd">    on the stack that must contain zero or more condition quotes and a </span>
1159 <span class="sd">    default quote.  Each condition clause should contain a quoted predicate</span>
1160 <span class="sd">    followed by the function expression to run if that predicate returns</span>
1161 <span class="sd">    true.  If no predicates return true the default function runs.</span>
1162
1163 <span class="sd">    It works by rewriting into a chain of nested `ifte` expressions, e.g.::</span>
1164
1165 <span class="sd">              [[[B0] T0] [[B1] T1] [D]] cond</span>
1166 <span class="sd">        -----------------------------------------</span>
1167 <span class="sd">           [B0] [T0] [[B1] [T1] [D] ifte] ifte</span>
1168
1169 <span class="sd">    &#39;&#39;&#39;</span>
1170     <span class="n">conditions</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
1171     <span class="k">if</span> <span class="n">conditions</span><span class="p">:</span>
1172         <span class="n">expression</span> <span class="o">=</span> <span class="n">_cond</span><span class="p">(</span><span class="n">conditions</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1173         <span class="k">try</span><span class="p">:</span>
1174             <span class="c1"># Attempt to preload the args to first ifte.</span>
1175             <span class="p">(</span><span class="n">P</span><span class="p">,</span> <span class="p">(</span><span class="n">T</span><span class="p">,</span> <span class="p">(</span><span class="n">E</span><span class="p">,</span> <span class="n">expression</span><span class="p">)))</span> <span class="o">=</span> <span class="n">expression</span>
1176         <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
1177             <span class="c1"># If, for any reason, the argument to cond should happen to contain</span>
1178             <span class="c1"># only the default clause then this optimization will fail.</span>
1179             <span class="k">pass</span>
1180         <span class="k">else</span><span class="p">:</span>
1181             <span class="n">stack</span> <span class="o">=</span> <span class="p">(</span><span class="n">E</span><span class="p">,</span> <span class="p">(</span><span class="n">T</span><span class="p">,</span> <span class="p">(</span><span class="n">P</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span>
1182     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1183
1184
1185 <span class="k">def</span> <span class="nf">_cond</span><span class="p">(</span><span class="n">conditions</span><span class="p">,</span> <span class="n">expression</span><span class="p">):</span>
1186     <span class="p">(</span><span class="n">clause</span><span class="p">,</span> <span class="n">rest</span><span class="p">)</span> <span class="o">=</span> <span class="n">conditions</span>
1187     <span class="k">if</span> <span class="ow">not</span> <span class="n">rest</span><span class="p">:</span>  <span class="c1"># clause is [D]</span>
1188         <span class="k">return</span> <span class="n">clause</span>
1189     <span class="n">P</span><span class="p">,</span> <span class="n">T</span> <span class="o">=</span> <span class="n">clause</span>
1190     <span class="k">return</span> <span class="p">(</span><span class="n">P</span><span class="p">,</span> <span class="p">(</span><span class="n">T</span><span class="p">,</span> <span class="p">(</span><span class="n">_cond</span><span class="p">(</span><span class="n">rest</span><span class="p">,</span> <span class="p">()),</span> <span class="p">(</span><span class="n">S_ifte</span><span class="p">,</span> <span class="n">expression</span><span class="p">))))</span>
1191
1192
1193 <div class="viewcode-block" id="dip"><a class="viewcode-back" href="../../library.html#joy.library.dip">[docs]</a><span class="nd">@inscribe</span>
1194 <span class="nd">@FunctionWrapper</span>
1195 <span class="k">def</span> <span class="nf">dip</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1196     <span class="sd">&#39;&#39;&#39;</span>
1197 <span class="sd">    The dip combinator expects a quoted program on the stack and below it</span>
1198 <span class="sd">    some item, it hoists the item into the expression and runs the program</span>
1199 <span class="sd">    on the rest of the stack.</span>
1200 <span class="sd">    ::</span>
1201
1202 <span class="sd">           ... x [Q] dip</span>
1203 <span class="sd">        -------------------</span>
1204 <span class="sd">             ... Q x</span>
1205
1206 <span class="sd">    &#39;&#39;&#39;</span>
1207     <span class="k">try</span><span class="p">:</span>
1208         <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
1209     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
1210         <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
1211     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1212     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1213
1214
1215 <div class="viewcode-block" id="dipd"><a class="viewcode-back" href="../../library.html#joy.library.dipd">[docs]</a><span class="nd">@inscribe</span>
1216 <span class="nd">@FunctionWrapper</span>
1217 <span class="k">def</span> <span class="nf">dipd</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1218     <span class="sd">&#39;&#39;&#39;</span>
1219 <span class="sd">    Like dip but expects two items.</span>
1220 <span class="sd">    ::</span>
1221
1222 <span class="sd">           ... y x [Q] dip</span>
1223 <span class="sd">        ---------------------</span>
1224 <span class="sd">             ... Q y x</span>
1225
1226 <span class="sd">    &#39;&#39;&#39;</span>
1227     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span> <span class="o">=</span> <span class="n">S</span>
1228     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">expression</span><span class="p">))</span>
1229     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1230
1231
1232 <div class="viewcode-block" id="dipdd"><a class="viewcode-back" href="../../library.html#joy.library.dipdd">[docs]</a><span class="nd">@inscribe</span>
1233 <span class="nd">@FunctionWrapper</span>
1234 <span class="k">def</span> <span class="nf">dipdd</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1235     <span class="sd">&#39;&#39;&#39;</span>
1236 <span class="sd">    Like dip but expects three items.</span>
1237 <span class="sd">    ::</span>
1238
1239 <span class="sd">           ... z y x [Q] dip</span>
1240 <span class="sd">        -----------------------</span>
1241 <span class="sd">             ... Q z y x</span>
1242
1243 <span class="sd">    &#39;&#39;&#39;</span>
1244     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="p">(</span><span class="n">z</span><span class="p">,</span> <span class="n">stack</span><span class="p">))))</span> <span class="o">=</span> <span class="n">S</span>
1245     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">z</span><span class="p">,</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">expression</span><span class="p">)))</span>
1246     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">),</span> <span class="n">dictionary</span></div>
1247
1248
1249 <div class="viewcode-block" id="app1"><a class="viewcode-back" href="../../library.html#joy.library.app1">[docs]</a><span class="nd">@inscribe</span>
1250 <span class="nd">@FunctionWrapper</span>
1251 <span class="k">def</span> <span class="nf">app1</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1252     <span class="sd">&#39;&#39;&#39;</span>
1253 <span class="sd">    Given a quoted program on TOS and anything as the second stack item run</span>
1254 <span class="sd">    the program and replace the two args with the first result of the</span>
1255 <span class="sd">    program.</span>
1256 <span class="sd">    ::</span>
1257
1258 <span class="sd">             ... x [Q] . app1</span>
1259 <span class="sd">        -----------------------------------</span>
1260 <span class="sd">           ... [x ...] [Q] . infra first</span>
1261
1262 <span class="sd">    &#39;&#39;&#39;</span>
1263     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
1264     <span class="n">stack</span> <span class="o">=</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">stack</span><span class="p">))</span>
1265     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span> <span class="n">expression</span><span class="p">))</span>
1266     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1267
1268
1269 <div class="viewcode-block" id="app2"><a class="viewcode-back" href="../../library.html#joy.library.app2">[docs]</a><span class="nd">@inscribe</span>
1270 <span class="nd">@FunctionWrapper</span>
1271 <span class="k">def</span> <span class="nf">app2</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1272     <span class="sd">&#39;&#39;&#39;Like app1 with two items.</span>
1273 <span class="sd">    ::</span>
1274
1275 <span class="sd">               ... y x [Q] . app2</span>
1276 <span class="sd">        -----------------------------------</span>
1277 <span class="sd">           ... [y ...] [Q] . infra first</span>
1278 <span class="sd">               [x ...] [Q]   infra first</span>
1279
1280 <span class="sd">    &#39;&#39;&#39;</span>
1281     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">stack</span><span class="p">)))</span> <span class="o">=</span> <span class="n">S</span>
1282     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span>
1283         <span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span>
1284             <span class="n">expression</span><span class="p">))))))</span>
1285     <span class="n">stack</span> <span class="o">=</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">((</span><span class="n">y</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">stack</span><span class="p">))</span>
1286     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1287
1288
1289 <div class="viewcode-block" id="app3"><a class="viewcode-back" href="../../library.html#joy.library.app3">[docs]</a><span class="nd">@inscribe</span>
1290 <span class="nd">@FunctionWrapper</span>
1291 <span class="k">def</span> <span class="nf">app3</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1292     <span class="sd">&#39;&#39;&#39;Like app1 with three items.</span>
1293 <span class="sd">    ::</span>
1294
1295 <span class="sd">             ... z y x [Q] . app3</span>
1296 <span class="sd">        -----------------------------------</span>
1297 <span class="sd">           ... [z ...] [Q] . infra first</span>
1298 <span class="sd">               [y ...] [Q]   infra first</span>
1299 <span class="sd">               [x ...] [Q]   infra first</span>
1300
1301 <span class="sd">    &#39;&#39;&#39;</span>
1302     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="p">(</span><span class="n">z</span><span class="p">,</span> <span class="n">stack</span><span class="p">))))</span> <span class="o">=</span> <span class="n">S</span>
1303     <span class="n">expression</span> <span class="o">=</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span>
1304         <span class="p">((</span><span class="n">y</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span>
1305         <span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_infra</span><span class="p">,</span> <span class="p">(</span><span class="n">S_first</span><span class="p">,</span>
1306             <span class="n">expression</span><span class="p">))))))))))</span>
1307     <span class="n">stack</span> <span class="o">=</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">((</span><span class="n">z</span><span class="p">,</span> <span class="n">stack</span><span class="p">),</span> <span class="n">stack</span><span class="p">))</span>
1308     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1309
1310
1311 <div class="viewcode-block" id="step"><a class="viewcode-back" href="../../library.html#joy.library.step">[docs]</a><span class="nd">@inscribe</span>
1312 <span class="nd">@FunctionWrapper</span>
1313 <span class="k">def</span> <span class="nf">step</span><span class="p">(</span><span class="n">S</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1314     <span class="sd">&#39;&#39;&#39;</span>
1315 <span class="sd">    Run a quoted program on each item in a sequence.</span>
1316 <span class="sd">    ::</span>
1317
1318 <span class="sd">           ... [] [Q] . step</span>
1319 <span class="sd">        -----------------------</span>
1320 <span class="sd">              ... .</span>
1321
1322
1323 <span class="sd">           ... [a] [Q] . step</span>
1324 <span class="sd">        ------------------------</span>
1325 <span class="sd">             ... a . Q</span>
1326
1327
1328 <span class="sd">           ... [a b c] [Q] . step</span>
1329 <span class="sd">        ----------------------------------------</span>
1330 <span class="sd">                 ... a . Q [b c] [Q] step</span>
1331
1332 <span class="sd">    The step combinator executes the quotation on each member of the list</span>
1333 <span class="sd">    on top of the stack.</span>
1334 <span class="sd">    &#39;&#39;&#39;</span>
1335     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">aggregate</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">S</span>
1336     <span class="k">if</span> <span class="ow">not</span> <span class="n">aggregate</span><span class="p">:</span>
1337         <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
1338     <span class="n">head</span><span class="p">,</span> <span class="n">tail</span> <span class="o">=</span> <span class="n">aggregate</span>
1339     <span class="n">stack</span> <span class="o">=</span> <span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">head</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span>
1340     <span class="k">if</span> <span class="n">tail</span><span class="p">:</span>
1341         <span class="n">expression</span> <span class="o">=</span> <span class="n">tail</span><span class="p">,</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_step</span><span class="p">,</span> <span class="n">expression</span><span class="p">))</span>
1342     <span class="n">expression</span> <span class="o">=</span> <span class="n">S_i</span><span class="p">,</span> <span class="n">expression</span>
1343     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1344
1345
1346 <div class="viewcode-block" id="times"><a class="viewcode-back" href="../../library.html#joy.library.times">[docs]</a><span class="nd">@inscribe</span>
1347 <span class="nd">@FunctionWrapper</span>
1348 <span class="k">def</span> <span class="nf">times</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1349     <span class="sd">&#39;&#39;&#39;</span>
1350 <span class="sd">    times == [-- dip] cons [swap] infra [0 &gt;] swap while pop</span>
1351 <span class="sd">    ::</span>
1352
1353 <span class="sd">           ... n [Q] . times</span>
1354 <span class="sd">        ---------------------  w/ n &lt;= 0</span>
1355 <span class="sd">             ... .</span>
1356
1357
1358 <span class="sd">           ... 1 [Q] . times</span>
1359 <span class="sd">        -----------------------</span>
1360 <span class="sd">             ... . Q</span>
1361
1362
1363 <span class="sd">           ... n [Q] . times</span>
1364 <span class="sd">        -------------------------------------  w/ n &gt; 1</span>
1365 <span class="sd">             ... . Q (n - 1) [Q] times</span>
1366
1367 <span class="sd">    &#39;&#39;&#39;</span>
1368     <span class="c1"># times == [-- dip] cons [swap] infra [0 &gt;] swap while pop</span>
1369     <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">stack</span><span class="p">))</span> <span class="o">=</span> <span class="n">stack</span>
1370     <span class="k">if</span> <span class="n">n</span> <span class="o">&lt;=</span> <span class="mi">0</span><span class="p">:</span>
1371         <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span>
1372     <span class="n">n</span> <span class="o">-=</span> <span class="mi">1</span>
1373     <span class="k">if</span> <span class="n">n</span><span class="p">:</span>
1374         <span class="n">expression</span> <span class="o">=</span> <span class="n">n</span><span class="p">,</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_times</span><span class="p">,</span> <span class="n">expression</span><span class="p">))</span>
1375     <span class="n">expression</span> <span class="o">=</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1376     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1377
1378
1379 <span class="c1"># The current definition above works like this:</span>
1380
1381 <span class="c1">#             [P] [Q] while</span>
1382 <span class="c1"># --------------------------------------</span>
1383 <span class="c1">#    [P] nullary [Q [P] nullary] loop</span>
1384
1385 <span class="c1">#   while == [pop i not] [popop] [dudipd] tailrec</span>
1386
1387 <span class="c1">#def while_(S, expression, dictionary):</span>
1388 <span class="c1">#  &#39;&#39;&#39;[if] [body] while&#39;&#39;&#39;</span>
1389 <span class="c1">#  (body, (if_, stack)) = S</span>
1390 <span class="c1">#  while joy(stack, if_, dictionary)[0][0]:</span>
1391 <span class="c1">#    stack = joy(stack, body, dictionary)[0]</span>
1392 <span class="c1">#  return stack, expression, dictionary</span>
1393
1394
1395 <div class="viewcode-block" id="loop"><a class="viewcode-back" href="../../library.html#joy.library.loop">[docs]</a><span class="nd">@inscribe</span>
1396 <span class="nd">@FunctionWrapper</span>
1397 <span class="k">def</span> <span class="nf">loop</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1398     <span class="sd">&#39;&#39;&#39;</span>
1399 <span class="sd">    Basic loop combinator.</span>
1400 <span class="sd">    ::</span>
1401
1402 <span class="sd">           ... True [Q] loop</span>
1403 <span class="sd">        -----------------------</span>
1404 <span class="sd">              ... Q [Q] loop</span>
1405
1406 <span class="sd">           ... False [Q] loop</span>
1407 <span class="sd">        ------------------------</span>
1408 <span class="sd">              ...</span>
1409
1410 <span class="sd">    &#39;&#39;&#39;</span>
1411     <span class="k">try</span><span class="p">:</span>
1412         <span class="n">quote</span><span class="p">,</span> <span class="n">stack</span> <span class="o">=</span> <span class="n">stack</span>
1413     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
1414         <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
1415     <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">):</span>
1416         <span class="k">raise</span> <span class="n">NotAListError</span><span class="p">(</span><span class="s1">&#39;Loop body not a list.&#39;</span><span class="p">)</span>
1417     <span class="k">try</span><span class="p">:</span>
1418         <span class="p">(</span><span class="n">flag</span><span class="p">,</span> <span class="n">stack</span><span class="p">)</span> <span class="o">=</span> <span class="n">stack</span>
1419     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
1420         <span class="k">raise</span> <span class="n">StackUnderflowError</span><span class="p">(</span><span class="s1">&#39;Not enough values on stack.&#39;</span><span class="p">)</span>
1421     <span class="k">if</span> <span class="n">flag</span><span class="p">:</span>
1422         <span class="n">expression</span> <span class="o">=</span> <span class="n">concat</span><span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">quote</span><span class="p">,</span> <span class="p">(</span><span class="n">S_loop</span><span class="p">,</span> <span class="n">expression</span><span class="p">)))</span>
1423     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1424
1425
1426 <div class="viewcode-block" id="cmp_"><a class="viewcode-back" href="../../library.html#joy.library.cmp_">[docs]</a><span class="nd">@inscribe</span>
1427 <span class="nd">@FunctionWrapper</span>
1428 <span class="k">def</span> <span class="nf">cmp_</span><span class="p">(</span><span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span><span class="p">):</span>
1429     <span class="sd">&#39;&#39;&#39;</span>
1430 <span class="sd">    cmp takes two values and three quoted programs on the stack and runs</span>
1431 <span class="sd">    one of the three depending on the results of comparing the two values:</span>
1432 <span class="sd">    ::</span>
1433
1434 <span class="sd">           a b [G] [E] [L] cmp</span>
1435 <span class="sd">        ------------------------- a &gt; b</span>
1436 <span class="sd">            G</span>
1437
1438 <span class="sd">           a b [G] [E] [L] cmp</span>
1439 <span class="sd">        ------------------------- a = b</span>
1440 <span class="sd">                E</span>
1441
1442 <span class="sd">           a b [G] [E] [L] cmp</span>
1443 <span class="sd">        ------------------------- a &lt; b</span>
1444 <span class="sd">                L</span>
1445 <span class="sd">    &#39;&#39;&#39;</span>
1446     <span class="n">L</span><span class="p">,</span> <span class="p">(</span><span class="n">E</span><span class="p">,</span> <span class="p">(</span><span class="n">G</span><span class="p">,</span> <span class="p">(</span><span class="n">b</span><span class="p">,</span> <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">stack</span><span class="p">))))</span> <span class="o">=</span> <span class="n">stack</span>
1447     <span class="n">expression</span> <span class="o">=</span> <span class="n">concat</span><span class="p">(</span><span class="n">G</span> <span class="k">if</span> <span class="n">a</span> <span class="o">&gt;</span> <span class="n">b</span> <span class="k">else</span> <span class="n">L</span> <span class="k">if</span> <span class="n">a</span> <span class="o">&lt;</span> <span class="n">b</span> <span class="k">else</span> <span class="n">E</span><span class="p">,</span> <span class="n">expression</span><span class="p">)</span>
1448     <span class="k">return</span> <span class="n">stack</span><span class="p">,</span> <span class="n">expression</span><span class="p">,</span> <span class="n">dictionary</span></div>
1449
1450
1451 <span class="c1">#  FunctionWrapper(cleave),</span>
1452 <span class="c1">#  FunctionWrapper(while_),</span>
1453
1454
1455 <span class="k">for</span> <span class="n">F</span> <span class="ow">in</span> <span class="p">(</span>
1456
1457     <span class="c1">#divmod_ = pm = __(n2, n1), __(n4, n3)</span>
1458
1459     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">eq</span><span class="p">),</span>
1460     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ge</span><span class="p">),</span>
1461     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">gt</span><span class="p">),</span>
1462     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">le</span><span class="p">),</span>
1463     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lt</span><span class="p">),</span>
1464     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">ne</span><span class="p">),</span>
1465
1466     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">xor</span><span class="p">),</span>
1467     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">lshift</span><span class="p">),</span>
1468     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">rshift</span><span class="p">),</span>
1469
1470     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">and_</span><span class="p">),</span>
1471     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">or_</span><span class="p">),</span>
1472
1473     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">add</span><span class="p">),</span>
1474     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">floordiv</span><span class="p">),</span>
1475     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mod</span><span class="p">),</span>
1476     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">mul</span><span class="p">),</span>
1477     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">pow</span><span class="p">),</span>
1478     <span class="n">BinaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">sub</span><span class="p">),</span>
1479 <span class="c1">##    BinaryBuiltinWrapper(operator.truediv),</span>
1480
1481     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="nb">bool</span><span class="p">),</span>
1482     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">not_</span><span class="p">),</span>
1483
1484     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="nb">abs</span><span class="p">),</span>
1485     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">operator</span><span class="o">.</span><span class="n">neg</span><span class="p">),</span>
1486     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">sqrt</span><span class="p">),</span>
1487
1488     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="n">floor</span><span class="p">),</span>
1489     <span class="n">UnaryBuiltinWrapper</span><span class="p">(</span><span class="nb">round</span><span class="p">),</span>
1490     <span class="p">):</span>
1491     <span class="n">inscribe</span><span class="p">(</span><span class="n">F</span><span class="p">)</span>
1492 <span class="k">del</span> <span class="n">F</span>  <span class="c1"># Otherwise Sphinx autodoc will pick it up.</span>
1493
1494
1495 <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">primitive</span> <span class="ow">in</span> <span class="n">getmembers</span><span class="p">(</span><span class="n">genlib</span><span class="p">,</span> <span class="n">isfunction</span><span class="p">):</span>
1496     <span class="n">inscribe</span><span class="p">(</span><span class="n">SimpleFunctionWrapper</span><span class="p">(</span><span class="n">primitive</span><span class="p">))</span>
1497
1498
1499 <span class="n">add_aliases</span><span class="p">(</span><span class="n">_dictionary</span><span class="p">,</span> <span class="n">ALIASES</span><span class="p">)</span>
1500
1501
1502 <span class="n">DefinitionWrapper</span><span class="o">.</span><span class="n">add_definitions</span><span class="p">(</span><span class="n">definitions</span><span class="p">,</span> <span class="n">_dictionary</span><span class="p">)</span>
1503 </pre></div>
1504
1505           </div>
1506
1507         </div>
1508       </div>
1509       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
1510         <div class="sphinxsidebarwrapper">
1511 <h1 class="logo"><a href="../../index.html">Thun</a></h1>
1512
1513
1514
1515
1516
1517
1518
1519
1520 <h3>Navigation</h3>
1521 <ul>
1522 <li class="toctree-l1"><a class="reference internal" href="../../notebooks/Intro.html">Thun: Joy in Python</a></li>
1523 <li class="toctree-l1"><a class="reference internal" href="../../joy.html">Joy Interpreter</a></li>
1524 <li class="toctree-l1"><a class="reference internal" href="../../stack.html">Stack or Quote or Sequence or List…</a></li>
1525 <li class="toctree-l1"><a class="reference internal" href="../../parser.html">Parsing Text into Joy Expressions</a></li>
1526 <li class="toctree-l1"><a class="reference internal" href="../../pretty.html">Tracing Joy Execution</a></li>
1527 <li class="toctree-l1"><a class="reference internal" href="../../library.html">Function Reference</a></li>
1528 <li class="toctree-l1"><a class="reference internal" href="../../lib.html">Functions Grouped by, er, Function with Examples</a></li>
1529 <li class="toctree-l1"><a class="reference internal" href="../../types.html">Type Inference of Joy Expressions</a></li>
1530 <li class="toctree-l1"><a class="reference internal" href="../../notebooks/index.html">Essays about Programming in Joy</a></li>
1531 </ul>
1532
1533 <div class="relations">
1534 <h3>Related Topics</h3>
1535 <ul>
1536   <li><a href="../../index.html">Documentation overview</a><ul>
1537   <li><a href="../index.html">Module code</a><ul>
1538   </ul></li>
1539   </ul></li>
1540 </ul>
1541 </div>
1542 <div id="searchbox" style="display: none" role="search">
1543   <h3 id="searchlabel">Quick search</h3>
1544     <div class="searchformwrapper">
1545     <form class="search" action="../../search.html" method="get">
1546       <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
1547       <input type="submit" value="Go" />
1548     </form>
1549     </div>
1550 </div>
1551 <script>$('#searchbox').show(0);</script>
1552
1553
1554
1555
1556
1557
1558
1559
1560         </div>
1561       </div>
1562       <div class="clearer"></div>
1563     </div>
1564     <div class="footer" role="contentinfo">
1565 <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
1566 <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" />
1567 </a>
1568 <br />
1569 <span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">Thun Documentation</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://joypy.osdn.io/" property="cc:attributionName" rel="cc:attributionURL">Simon Forman</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://osdn.net/projects/joypy/" rel="dct:source">https://osdn.net/projects/joypy/</a>.
1570       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.3.0.
1571     </div>
1572
1573   </body>
1574 </html>