diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..27eae21 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,27 @@ +#docs := $(wildcard *.ipynb) +#docs_html := $(patsubst %.ipynb,%.html,$(docs)) + +.PHONY: poop nospaces yesspaces + +# https://stackoverflow.com/a/45531875 +# Make cannot handle spaces in filenames, so temporarily rename them +nospaces: + rename -v 's/ /%20/g' *\ * + +# After Make is done, rename files back to having spaces +yesspaces: + rename -v 's/%20/ /g' *%20* + + +poop: *.ipynb + make "$(patsubst %.ipynb,%.html,$<)" + +%.html : %.ipynb + python -m nbconvert --to html $< + +%.md : %.ipynb + python -m nbconvert --to markdown $< + +%.rst : %.ipynb + python -m nbconvert --to rst $< + diff --git a/docs/Replacing.html b/docs/Replacing.html new file mode 100644 index 0000000..657674b --- /dev/null +++ b/docs/Replacing.html @@ -0,0 +1,12025 @@ + + + +Replacing + + + + + + + + + + + + + + + + + + + +
+
+ +
+
+
+
+

Replacing Functions in the Dictionary

+
+
+
+
+
+
In [1]:
+
+
+
from notebook_preamble import D, J, V
+
+ +
+
+
+ +
+
+
+
+
+

A long trace

+
+
+
+
+
+
In [2]:
+
+
+
V('[23 18] average')
+
+ +
+
+
+ +
+
+ + +
+ +
+ + +
+
                                  . [23 18] average
+                          [23 18] . average
+                          [23 18] . [sum 1.0 *] [size] cleave /
+              [23 18] [sum 1.0 *] . [size] cleave /
+       [23 18] [sum 1.0 *] [size] . cleave /
+       [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip /
+   [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip /
+[23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip /
+              [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                          [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                               41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                           41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                             41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                   41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                   [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip /
+                     [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip /
+    [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip /
+[23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip /
+                   [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip /
+                          [23 18] . size [41.0 [23 18]] swaack first [popd] dip /
+                          [23 18] . 0 swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                        [23 18] 0 . swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                        0 [23 18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+               0 [23 18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip /
+                    0 23 [pop ++] . i [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                             0 23 . pop ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                                0 . ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                                1 . [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                           1 [18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip /
+                  1 [18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip /
+                    1 18 [pop ++] . i [41.0 [23 18]] swaack first [popd] dip /
+                             1 18 . pop ++ [41.0 [23 18]] swaack first [popd] dip /
+                                1 . ++ [41.0 [23 18]] swaack first [popd] dip /
+                                2 . [41.0 [23 18]] swaack first [popd] dip /
+                 2 [41.0 [23 18]] . swaack first [popd] dip /
+                 [23 18] 41.0 [2] . first [popd] dip /
+                   [23 18] 41.0 2 . [popd] dip /
+            [23 18] 41.0 2 [popd] . dip /
+                     [23 18] 41.0 . popd 2 /
+                             41.0 . 2 /
+                           41.0 2 . /
+                             20.5 . 
+
+
+
+ +
+
+ +
+
+
+
+
+

Replacing size with a Python version

Both sum and size each convert a sequence to a single value.

+ +
+
+
+
+
+
+
+ +
 sum == 0 swap [+] step
+size == 0 swap [pop ++] step
+ +
+
+
+
+
+
+
+

An efficient sum function is already in the library. But for size we can use a “compiled” version hand-written in Python to speed up evaluation and make the trace more readable.

+ +
+
+
+
+
+
In [3]:
+
+
+
from joy.library import SimpleFunctionWrapper
+from joy.utils.stack import iter_stack
+
+
+@SimpleFunctionWrapper
+def size(stack):
+    '''Return the size of the sequence on the stack.'''
+    sequence, stack = stack
+    n = 0
+    for _ in iter_stack(sequence):
+        n += 1
+    return n, stack
+
+ +
+
+
+ +
+
+
+
+
+

Now we replace the old version in the dictionary with the new version, and re-evaluate the expression.

+ +
+
+
+
+
+
In [4]:
+
+
+
D['size'] = size
+
+ +
+
+
+ +
+
+
+
+
+

A shorter trace

You can see that size now executes in a single step.

+ +
+
+
+
+
+
In [5]:
+
+
+
V('[23 18] average')
+
+ +
+
+
+ +
+
+ + +
+ +
+ + +
+
                                  . [23 18] average
+                          [23 18] . average
+                          [23 18] . [sum 1.0 *] [size] cleave /
+              [23 18] [sum 1.0 *] . [size] cleave /
+       [23 18] [sum 1.0 *] [size] . cleave /
+       [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip /
+   [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip /
+[23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip /
+              [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                          [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                               41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                           41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                             41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                   41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip /
+                   [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip /
+                     [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip /
+    [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip /
+[23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip /
+                   [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip /
+                          [23 18] . size [41.0 [23 18]] swaack first [popd] dip /
+                                2 . [41.0 [23 18]] swaack first [popd] dip /
+                 2 [41.0 [23 18]] . swaack first [popd] dip /
+                 [23 18] 41.0 [2] . first [popd] dip /
+                   [23 18] 41.0 2 . [popd] dip /
+            [23 18] 41.0 2 [popd] . dip /
+                     [23 18] 41.0 . popd 2 /
+                             41.0 . 2 /
+                           41.0 2 . /
+                             20.5 . 
+
+
+
+ +
+
+ +
+
+
+ + + + + + diff --git a/docs/Replacing.md b/docs/Replacing.md new file mode 100644 index 0000000..aa7eabe --- /dev/null +++ b/docs/Replacing.md @@ -0,0 +1,129 @@ + +# Replacing Functions in the Dictionary + + +```python +from notebook_preamble import D, J, V +``` + +## A long trace + + +```python +V('[23 18] average') +``` + + . [23 18] average + [23 18] . average + [23 18] . [sum 1.0 *] [size] cleave / + [23 18] [sum 1.0 *] . [size] cleave / + [23 18] [sum 1.0 *] [size] . cleave / + [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip / + [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip / + [23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip / + [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip / + [23 18] . size [41.0 [23 18]] swaack first [popd] dip / + [23 18] . 0 swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + [23 18] 0 . swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 [23 18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 [23 18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip / + 0 23 [pop ++] . i [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 23 . pop ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 . ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 . [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 [18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 [18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip / + 1 18 [pop ++] . i [41.0 [23 18]] swaack first [popd] dip / + 1 18 . pop ++ [41.0 [23 18]] swaack first [popd] dip / + 1 . ++ [41.0 [23 18]] swaack first [popd] dip / + 2 . [41.0 [23 18]] swaack first [popd] dip / + 2 [41.0 [23 18]] . swaack first [popd] dip / + [23 18] 41.0 [2] . first [popd] dip / + [23 18] 41.0 2 . [popd] dip / + [23 18] 41.0 2 [popd] . dip / + [23 18] 41.0 . popd 2 / + 41.0 . 2 / + 41.0 2 . / + 20.5 . + + +## Replacing `size` with a Python version + +Both `sum` and `size` each convert a sequence to a single value. + + sum == 0 swap [+] step + size == 0 swap [pop ++] step + +An efficient `sum` function is already in the library. But for `size` we can use a “compiled” version hand-written in Python to speed up evaluation and make the trace more readable. + + +```python +from joy.library import SimpleFunctionWrapper +from joy.utils.stack import iter_stack + + +@SimpleFunctionWrapper +def size(stack): + '''Return the size of the sequence on the stack.''' + sequence, stack = stack + n = 0 + for _ in iter_stack(sequence): + n += 1 + return n, stack +``` + +Now we replace the old version in the dictionary with the new version, and re-evaluate the expression. + + +```python +D['size'] = size +``` + +## A shorter trace +You can see that `size` now executes in a single step. + + +```python +V('[23 18] average') +``` + + . [23 18] average + [23 18] . average + [23 18] . [sum 1.0 *] [size] cleave / + [23 18] [sum 1.0 *] . [size] cleave / + [23 18] [sum 1.0 *] [size] . cleave / + [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip / + [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip / + [23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip / + [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip / + [23 18] . size [41.0 [23 18]] swaack first [popd] dip / + 2 . [41.0 [23 18]] swaack first [popd] dip / + 2 [41.0 [23 18]] . swaack first [popd] dip / + [23 18] 41.0 [2] . first [popd] dip / + [23 18] 41.0 2 . [popd] dip / + [23 18] 41.0 2 [popd] . dip / + [23 18] 41.0 . popd 2 / + 41.0 . 2 / + 41.0 2 . / + 20.5 . + diff --git a/docs/Replacing.rst b/docs/Replacing.rst new file mode 100644 index 0000000..5ed8d14 --- /dev/null +++ b/docs/Replacing.rst @@ -0,0 +1,140 @@ + +Replacing Functions in the Dictionary +===================================== + +.. code:: ipython2 + + from notebook_preamble import D, J, V + +A long trace +------------ + +.. code:: ipython2 + + V('[23 18] average') + + +.. parsed-literal:: + + . [23 18] average + [23 18] . average + [23 18] . [sum 1.0 *] [size] cleave / + [23 18] [sum 1.0 *] . [size] cleave / + [23 18] [sum 1.0 *] [size] . cleave / + [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip / + [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip / + [23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip / + [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip / + [23 18] . size [41.0 [23 18]] swaack first [popd] dip / + [23 18] . 0 swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + [23 18] 0 . swap [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 [23 18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 [23 18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip / + 0 23 [pop ++] . i [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 23 . pop ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 0 . ++ [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 . [18] [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 [18] . [pop ++] step [41.0 [23 18]] swaack first [popd] dip / + 1 [18] [pop ++] . step [41.0 [23 18]] swaack first [popd] dip / + 1 18 [pop ++] . i [41.0 [23 18]] swaack first [popd] dip / + 1 18 . pop ++ [41.0 [23 18]] swaack first [popd] dip / + 1 . ++ [41.0 [23 18]] swaack first [popd] dip / + 2 . [41.0 [23 18]] swaack first [popd] dip / + 2 [41.0 [23 18]] . swaack first [popd] dip / + [23 18] 41.0 [2] . first [popd] dip / + [23 18] 41.0 2 . [popd] dip / + [23 18] 41.0 2 [popd] . dip / + [23 18] 41.0 . popd 2 / + 41.0 . 2 / + 41.0 2 . / + 20.5 . + + +Replacing ``size`` with a Python version +---------------------------------------- + +Both ``sum`` and ``size`` each convert a sequence to a single value. + +:: + + sum == 0 swap [+] step + size == 0 swap [pop ++] step + +An efficient ``sum`` function is already in the library. But for +``size`` we can use a “compiled” version hand-written in Python to speed +up evaluation and make the trace more readable. + +.. code:: ipython2 + + from joy.library import SimpleFunctionWrapper + from joy.utils.stack import iter_stack + + + @SimpleFunctionWrapper + def size(stack): + '''Return the size of the sequence on the stack.''' + sequence, stack = stack + n = 0 + for _ in iter_stack(sequence): + n += 1 + return n, stack + +Now we replace the old version in the dictionary with the new version, +and re-evaluate the expression. + +.. code:: ipython2 + + D['size'] = size + +A shorter trace +--------------- + +You can see that ``size`` now executes in a single step. + +.. code:: ipython2 + + V('[23 18] average') + + +.. parsed-literal:: + + . [23 18] average + [23 18] . average + [23 18] . [sum 1.0 *] [size] cleave / + [23 18] [sum 1.0 *] . [size] cleave / + [23 18] [sum 1.0 *] [size] . cleave / + [23 18] [sum 1.0 *] [size] . [i] app2 [popd] dip / + [23 18] [sum 1.0 *] [size] [i] . app2 [popd] dip / + [23 18] [[sum 1.0 *] [23 18]] [i] . infra first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [sum 1.0 *] . i [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] . sum 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 . 1.0 * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41 1.0 . * [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 . [[23 18]] swaack first [[size] [23 18]] [i] infra first [popd] dip / + 41.0 [[23 18]] . swaack first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] [41.0] . first [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 . [[size] [23 18]] [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] . [i] infra first [popd] dip / + [23 18] 41.0 [[size] [23 18]] [i] . infra first [popd] dip / + [23 18] [size] . i [41.0 [23 18]] swaack first [popd] dip / + [23 18] . size [41.0 [23 18]] swaack first [popd] dip / + 2 . [41.0 [23 18]] swaack first [popd] dip / + 2 [41.0 [23 18]] . swaack first [popd] dip / + [23 18] 41.0 [2] . first [popd] dip / + [23 18] 41.0 2 . [popd] dip / + [23 18] 41.0 2 [popd] . dip / + [23 18] 41.0 . popd 2 / + 41.0 . 2 / + 41.0 2 . / + 20.5 . +