sforman/Thun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rebuilt some sphinx docs.

Browse Source
This commit is contained in:
Simon Forman
2020-04-24 17:21:08 -07:00
parent ff6d427b2f
commit d7d6114963
13 changed files with 665 additions and 3864 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0._This_Implementation_of_Joy_in_Python.html
+130 -98
View File
@@ -11854,57 +11854,56 @@ joy? </code></pre>
<div class="output_subarea output_stream output_stdout output_text">
<pre>§ Stack
<pre>When talking about Joy we use the terms &#34;stack&#34;, &#34;quote&#34;, &#34;sequence&#34;,
&#34;list&#34;, and others to mean the same thing: a simple linear datatype that
permits certain operations such as iterating and pushing and popping
values from (at least) one end.
There is no &#34;Stack&#34; Python class, instead we use the `cons list`_, a
venerable two-tuple recursive sequence datastructure, where the
empty tuple ``()`` is the empty stack and ``(head, rest)`` gives the recursive
form of a stack with one or more items on it::
When talking about Joy we use the terms &#34;stack&#34;, &#34;list&#34;, &#34;sequence&#34; and
&#34;aggregate&#34; to mean the same thing: a simple datatype that permits
certain operations such as iterating and pushing and popping values from
(at least) one end.
stack := () | (item, stack)
We use the venerable two-tuple recursive form of sequences where the
empty tuple () is the empty stack and (head, rest) gives the recursive
form of a stack with one or more items on it.
Putting some numbers onto a stack::
()
(1, ())
(2, (1, ()))
(3, (2, (1, ())))
...
And so on.
We have two very simple functions to build up a stack from a Python
iterable and also to iterate through a stack and yield its items
one-by-one in order, and two functions to generate string representations
of stacks:
list_to_stack()
iter_stack()
expression_to_string() (prints left-to-right)
stack_to_string() (prints right-to-left)
A word about the stack data structure.
()
(1, ())
(2, (1, ()))
(3, (2, (1, ())))
...
Python has very nice &#34;tuple packing and unpacking&#34; in its syntax which
means we can directly &#34;unpack&#34; the expected arguments to a Joy function.
For example:
For example::
def dup(stack):
head, tail = stack
return head, (head, tail)
def dup((head, tail)):
return head, (head, tail)
We replace the argument &#34;stack&#34; by the expected structure of the stack,
in this case &#34;(head, tail)&#34;, and Python takes care of de-structuring the
incoming argument and assigning values to the names. Note that Python
in this case &#34;(head, tail)&#34;, and Python takes care of unpacking the
incoming tuple and assigning values to the names. (Note that Python
syntax doesn&#39;t require parentheses around tuples used in expressions
where they would be redundant.
where they would be redundant.)
Unfortunately, the Sphinx documentation generator, which is used to generate this
web page, doesn&#39;t handle tuples in the function parameters. And in Python 3, this
syntax was removed entirely. Instead you would have to write::
def dup(stack):
head, tail = stack
return head, (head, tail)
We have two very simple functions, one to build up a stack from a Python
iterable and another to iterate through a stack and yield its items
one-by-one in order. There are also two functions to generate string representations
of stacks. They only differ in that one prints the terms in stack from left-to-right while the other prints from right-to-left. In both functions *internal stacks* are
printed left-to-right. These functions are written to support :doc:`../pretty`.
.. _cons list: https://en.wikipedia.org/wiki/Cons#Lists
</pre>
</div>
</div>
@@ -12079,22 +12078,36 @@ where they would be redundant.
<div class="output_subarea output_stream output_stdout output_text">
<pre>def joy(stack, expression, dictionary, viewer=None):
&#39;&#39;&#39;
Evaluate the Joy expression on the stack.
&#39;&#39;&#39;
while expression:
&#39;&#39;&#39;Evaluate a Joy expression on a stack.
if viewer: viewer(stack, expression)
This function iterates through a sequence of terms which are either
literals (strings, numbers, sequences of terms) or function symbols.
Literals are put onto the stack and functions are looked up in the
disctionary and executed.
term, expression = expression
if isinstance(term, Symbol):
term = dictionary[term]
stack, expression, dictionary = term(stack, expression, dictionary)
else:
stack = term, stack
The viewer is a function that is called with the stack and expression
on every iteration, its return value is ignored.
if viewer: viewer(stack, expression)
return stack, expression, dictionary
:param stack stack: The stack.
:param stack expression: The expression to evaluate.
:param dict dictionary: A ``dict`` mapping names to Joy functions.
:param function viewer: Optional viewer function.
:rtype: (stack, (), dictionary)
&#39;&#39;&#39;
while expression:
if viewer: viewer(stack, expression)
term, expression = expression
if isinstance(term, Symbol):
term = dictionary[term]
stack, expression, dictionary = term(stack, expression, dictionary)
else:
stack = term, stack
if viewer: viewer(stack, expression)
return stack, expression, dictionary
</pre>
</div>
@@ -12163,19 +12176,22 @@ where they would be redundant.
<div class="output_subarea output_stream output_stdout output_text">
<pre>§ Converting text to a joy expression.
<pre>This module exports a single function for converting text to a joy
expression as well as a single Symbol class and a single Exception type.
This module exports a single function:
The Symbol string class is used by the interpreter to recognize literals
by the fact that they are not Symbol objects.
text_to_expression(text)
A crude grammar::
As well as a single Symbol class and a single Exception type:
joy = term*
term = int | float | string | &#39;[&#39; joy &#39;]&#39; | symbol
ParseError
When supplied with a string this function returns a Python datastructure
that represents the Joy datastructure described by the text expression.
Any unbalanced square brackets will raise a ParseError.
A Joy expression is a sequence of zero or more terms. A term is a
literal value (integer, float, string, or Joy expression) or a function
symbol. Function symbols are unquoted strings and cannot contain square
brackets. Terms must be separated by blanks, which can be omitted
around square brackets.
</pre>
</div>
</div>
@@ -12216,27 +12232,27 @@ Any unbalanced square brackets will raise a ParseError.
<div class="output_subarea output_stream output_stdout output_text">
<pre>def _parse(tokens):
&#39;&#39;&#39;
Return a stack/list expression of the tokens.
&#39;&#39;&#39;
frame = []
stack = []
for tok in tokens:
if tok == &#39;[&#39;:
stack.append(frame)
frame = []
stack[-1].append(frame)
elif tok == &#39;]&#39;:
try:
frame = stack.pop()
except IndexError:
raise ParseError(&#39;One or more extra closing brackets.&#39;)
frame[-1] = list_to_stack(frame[-1])
else:
frame.append(tok)
if stack:
raise ParseError(&#39;One or more unclosed brackets.&#39;)
return list_to_stack(frame)
&#39;&#39;&#39;
Return a stack/list expression of the tokens.
&#39;&#39;&#39;
frame = []
stack = []
for tok in tokens:
if tok == &#39;[&#39;:
stack.append(frame)
frame = []
stack[-1].append(frame)
elif tok == &#39;]&#39;:
try:
frame = stack.pop()
except IndexError:
raise ParseError(&#39;Extra closing bracket.&#39;)
frame[-1] = list_to_stack(frame[-1])
else:
frame.append(tok)
if stack:
raise ParseError(&#39;Unclosed bracket.&#39;)
return list_to_stack(frame)
</pre>
</div>
@@ -12455,7 +12471,7 @@ Any unbalanced square brackets will raise a ParseError.
<div class="output_subarea output_stream output_stdout output_text">
<pre>!= % &amp; * *fraction *fraction0 + ++ - -- / &lt; &lt;&lt; &lt;= &lt;&gt; = &gt; &gt;= &gt;&gt; ? ^ add anamorphism and app1 app2 app3 average b binary branch choice clear cleave concat cons dinfrirst dip dipd dipdd disenstacken div down_to_zero dudipd dup dupd dupdip enstacken eq first flatten floordiv gcd ge genrec getitem gt help i id ifte infra le least_fraction loop lshift lt map min mod modulus mul ne neg not nullary or over pam parse pm pop popd popdd popop pow pred primrec product quoted range range_to_zero rem remainder remove rest reverse roll&lt; roll&gt; rolldown rollup rshift run second select sharing shunt size sqr sqrt stack step sub succ sum swaack swap swoncat swons ternary third times truediv truthy tuck unary uncons unit unquoted unstack void warranty while words x xor zip •
<pre>!= % &amp; * *fraction *fraction0 + ++ - -- / // /floor &lt; &lt;&lt; &lt;= &lt;&gt; = &gt; &gt;= &gt;&gt; ? ^ _Tree_add_Ee _Tree_delete_R0 _Tree_delete_clear_stuff _Tree_get_E abs add anamorphism and app1 app2 app3 at average b binary bool branch ccons choice clear cleave cmp codireco concat cond cons dinfrirst dip dipd dipdd disenstacken divmod down_to_zero drop dup dupd dupdd dupdip dupdipd enstacken eq first first_two flatten floor floordiv fork fourth gcd ge genrec getitem gt help i id ifte ii infer infra inscribe le least_fraction loop lshift lt make_generator map max min mod modulus mul ne neg not nullary of or over pam parse pick pm pop popd popdd popop popopd popopdd pow pred primrec product quoted range range_to_zero rem remainder remove rest reverse roll&lt; roll&gt; rolldown rollup round rrest rshift run second select sharing shunt size sort sqr sqrt stack step step_zero stuncons stununcons sub succ sum swaack swap swons take ternary third times truediv truthy tuck unary uncons unique unit unquoted unstack unswons void warranty while words x xor zip •
</pre>
</div>
</div>
@@ -12495,10 +12511,24 @@ Any unbalanced square brackets will raise a ParseError.
<div class="output_subarea output_stream output_stdout output_text">
<pre>def dip(stack, expression, dictionary):
(quote, (x, stack)) = stack
expression = x, expression
return stack, pushback(quote, expression), dictionary
<pre>@inscribe
@combinator_effect(_COMB_NUMS(), a1, s1)
@FunctionWrapper
def dip(stack, expression, dictionary):
&#39;&#39;&#39;
The dip combinator expects a quoted program on the stack and below it
some item, it hoists the item into the expression and runs the program
on the rest of the stack.
::
... x [Q] dip
-------------------
... Q x
&#39;&#39;&#39;
(quote, (x, stack)) = stack
expression = (x, expression)
return stack, concat(quote, expression), dictionary
</pre>
</div>
@@ -12539,28 +12569,26 @@ Any unbalanced square brackets will raise a ParseError.
<div class="output_subarea output_stream output_stdout output_text">
<pre>second == rest first
third == rest rest first
<pre>ii == [dip] dupdip i
of == swap at
product == 1 swap [*] step
swons == swap cons
swoncat == swap concat
flatten == [] swap [concat] step
unit == [] cons
quoted == [unit] dip
unquoted == [i] dip
enstacken == stack [clear] dip
disenstacken == ? [uncons ?] loop pop
? == dup truthy
disenstacken == ? [uncons ?] loop pop
dinfrirst == dip infra first
nullary == [stack] dinfrirst
unary == [stack [pop] dip] dinfrirst
binary == [stack [popop] dip] dinfrirst
ternary == [stack [popop pop] dip] dinfrirst
unary == nullary popd
binary == nullary [popop] dip
ternary == unary [popop] dip
pam == [i] map
run == [] swap infra
sqr == dup mul
size == 0 swap [pop ++] step
cleave == [i] app2 [popd] dip
fork == [i] app2
cleave == fork [popd] dip
average == [sum 1.0 *] [size] cleave /
gcd == 1 [tuck modulus dup 0 &gt;] loop pop
least_fraction == dup [gcd] infra [div] concat map
@@ -12571,8 +12599,12 @@ range_to_zero == unit [down_to_zero] infra
anamorphism == [pop []] swap [dip swons] genrec
range == [0 &lt;=] [1 - dup] anamorphism
while == swap [nullary] cons dup dipd concat loop
dudipd == dup dipd
dupdipd == dup dipd
primrec == [i] genrec
step_zero == 0 roll&gt; step
codireco == cons dip rest cons
make_generator == [codireco] ccons
ifte == [nullary not] dipd branch
</pre>
</div>