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

Rebuild docs with Python 3 and Sphinx 3.0.2.

Browse Source
This commit is contained in:
Simon Forman
2020-04-28 15:37:49 -07:00
parent 176e427116
commit 7f6fcf6e09
150 changed files with 51415 additions and 41305 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/0._This_Implementation_of_Joy_in_Python.md
+32 -136
View File
@@ -1,4 +1,3 @@
# Joypy
## Joy in Python
@@ -52,58 +51,6 @@ import joy.utils.stack
print inspect.getdoc(joy.utils.stack)
```
When talking about Joy we use the terms "stack", "quote", "sequence",
"list", 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 "Stack" 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::
stack := () | (item, stack)
Putting some numbers onto a stack::
()
(1, ())
(2, (1, ()))
(3, (2, (1, ())))
...
Python has very nice "tuple packing and unpacking" in its syntax which
means we can directly "unpack" the expected arguments to a Joy function.
For example::
def dup((head, tail)):
return head, (head, tail)
We replace the argument "stack" by the expected structure of the stack,
in this case "(head, tail)", and Python takes care of unpacking the
incoming tuple and assigning values to the names. (Note that Python
syntax doesn't require parentheses around tuples used in expressions
where they would be redundant.)
Unfortunately, the Sphinx documentation generator, which is used to generate this
web page, doesn'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
### The utility functions maintain order.
The 0th item in the list will be on the top of the stack and *vise versa*.
@@ -113,24 +60,10 @@ joy.utils.stack.list_to_stack([1, 2, 3])
```
(1, (2, (3, ())))
```python
list(joy.utils.stack.iter_stack((1, (2, (3, ())))))
```
[1, 2, 3]
This requires reversing the sequence (or iterating backwards) otherwise:
@@ -144,10 +77,6 @@ print stack
print list(joy.utils.stack.iter_stack(stack))
```
(3, (2, (1, ())))
[3, 2, 1]
### Purely Functional Datastructures.
Because Joy lists are made out of Python tuples they are immutable, so all Joy datastructures are *[purely functional](https://en.wikipedia.org/wiki/Purely_functional_data_structure)*.
@@ -164,40 +93,6 @@ import joy.joy
print inspect.getsource(joy.joy.joy)
```
def joy(stack, expression, dictionary, viewer=None):
'''Evaluate a Joy expression on a stack.
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.
The viewer is a function that is called with the stack and expression
on every iteration, its return value is ignored.
: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)
'''
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
### View function
The `joy()` function accepts a "viewer" function which it calls on each iteration passing the current stack and expression just before evaluation. This can be used for tracing, breakpoints, retrying after exceptions, or interrupting an evaluation and saving to disk or sending over the network to resume later. The stack and expression together contain all the state of the computation at each step.
@@ -341,7 +236,7 @@ import joy.library
print ' '.join(sorted(joy.library.initialize()))
```
!= % & * *fraction *fraction0 + ++ - -- / // /floor < << <= <> = > >= >> ? ^ _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< roll> 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 •
!= % & * *fraction *fraction0 + ++ - -- / // /floor < << <= <> = > >= >> ? ^ _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< roll> 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 swoncat swons take ternary third times truediv truthy tuck unary uncons unique unit unquoted unstack unswons void warranty while words x xor zip •
Many of the functions are defined in Python, like `dip`:
@@ -379,42 +274,43 @@ Some functions are defined in equations in terms of other functions. When the i
print joy.library.definitions
```
ii == [dip] dupdip i
of == swap at
product == 1 swap [*] step
flatten == [] swap [concat] step
quoted == [unit] dip
unquoted == [i] dip
enstacken == stack [clear] dip
? == dup truthy
disenstacken == ? [uncons ?] loop pop
dinfrirst == dip infra first
nullary == [stack] 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
fork == [i] app2
cleave == fork [popd] dip
average == [sum 1.0 *] [size] cleave /
gcd == 1 [tuck modulus dup 0 >] loop pop
least_fraction == dup [gcd] infra [div] concat map
*fraction == [uncons] dip uncons [swap] dip concat [*] infra [*] dip cons
*fraction0 == concat [[swap] dip * [*] dip] infra
down_to_zero == [0 >] [dup --] while
range_to_zero == unit [down_to_zero] infra
anamorphism == [pop []] swap [dip swons] genrec
range == [0 <=] [1 - dup] anamorphism
while == swap [nullary] cons dup dipd concat loop
dupdipd == dup dipd
primrec == [i] genrec
step_zero == 0 roll> step
average == [sum 1.0 *] [size] cleave /
binary == nullary [popop] dip
cleave == fork [popd] dip
codireco == cons dip rest cons
make_generator == [codireco] ccons
dinfrirst == dip infra first
unstack == ? [uncons ?] loop pop
down_to_zero == [0 >] [dup --] while
dupdipd == dup dipd
enstacken == stack [clear] dip
flatten == [] swap [concat] step
fork == [i] app2
gcd == 1 [tuck modulus dup 0 >] loop pop
ifte == [nullary not] dipd branch
ii == [dip] dupdip i
least_fraction == dup [gcd] infra [div] concat map
make_generator == [codireco] ccons
nullary == [stack] dinfrirst
of == swap at
pam == [i] map
primrec == [i] genrec
product == 1 swap [*] step
quoted == [unit] dip
range == [0 <=] [1 - dup] anamorphism
range_to_zero == unit [down_to_zero] infra
run == [] swap infra
size == 0 swap [pop ++] step
sqr == dup mul
step_zero == 0 roll> step
swoncat == swap concat
ternary == unary [popop] dip
unary == nullary popd
unquoted == [i] dip
while == swap [nullary] cons dup dipd concat loop