square_spiral [_p] [_then] [_else] ifte
_p [_p0] [_p1] &&
@@ -71,13 +71,13 @@ _else [pop !-] [--] [++] ifte
Documentation
This document describes Joy in a general way below, however most of the
-documentation is in the form of Jupyter Notebooks
+documentation is in the form of Jupyter Notebooks
that go into more detail.
-
-There's also a Function Reference that lists each
+
+There's also a Function Reference that lists each
function and combinator by name and gives a brief description. (It's
usually out of date, I'm working on it.)
-
+
Building the Docs
Run make in the docs directory. (This is a lie, it's more complex than
that. Really you need to run (GNU) make in the docs/notebooks and
diff --git a/docs/html/notebooks/0._This_Implementation_of_Joy_in_Python.html b/docs/html/notebooks/0._This_Implementation_of_Joy_in_Python.html
index f55bf84..b61401c 100644
--- a/docs/html/notebooks/0._This_Implementation_of_Joy_in_Python.html
+++ b/docs/html/notebooks/0._This_Implementation_of_Joy_in_Python.html
@@ -3,12624 +3,11322 @@
-0._This_Implementation_of_Joy_in_Python
-
-
-
+0._This_Implementation_of_Joy_in_Python
-
-
-
-
+
-
-
+
-
+
+
+
-
-
-
-
-
-
+
+
+
Joypy¶
Joy in Python¶
This implementation is meant as a tool for exploring the programming model and method of Joy. Python seems like a great implementation language for Joy for several reasons. We can lean on the Python immutable types for our basic semantics and types: ints, floats, strings, and tuples, which enforces functional purity. We get garbage collection for free. Compilation via Cython. Glue language with loads of libraries.
-
-
-
-
-
-
-
+
+
+
Read-Eval-Print Loop (REPL)¶
The main way to interact with the Joy interpreter is through a simple REPL that you start by running the package:
+
$ python -m joy
Joypy - Copyright © 2017 Simon Forman
-This program comes with ABSOLUTELY NO WARRANTY; for details type "warranty".
+This program comes with ABSOLUTELY NO WARRANTY; for details type "warranty".
This is free software, and you are welcome to redistribute it
-under certain conditions; type "sharing" for details.
-Type "words" to see a list of all words, and "[<name>] help" to print the
+under certain conditions; type "sharing" for details.
+Type "words" to see a list of all words, and "[<name>] help" to print the
docs for a word.
@@ -14621,6 +13114,7 @@ joy? _
The <-top marker points to the top of the (initially empty) stack. You can enter Joy notation at the prompt and a trace of evaluation will be printed followed by the stack and prompt again:
+
joy? 23 sqr 18 +
. 23 sqr 18 +
23 . sqr 18 +
@@ -14632,151 +13126,120 @@ joy? _
547 <-top
-joy?
-
+joy?
-
-
-
-
-
-
-
+
+
+
Stacks (aka list, quote, sequence, etc.)¶
In Joy, in addition to the types Boolean, integer, float, and string, there is a single sequence type represented by enclosing a sequence of terms in brackets [...]. This sequence type is used to represent both the stack and the expression. It is a cons list made from Python tuples.
-
-
-
-
-
-
-
+
+
+
The utility functions maintain order.¶
The 0th item in the list will be on the top of the stack and vise versa.
-
-
-
-
-
-In [1]:
-
-
+
+
+In [1]:
+
+
from joy.utils.stack import iter_stack, list_to_stack
-
-
+
-
-
-
-
-In [2]:
-
-
+
+
+In [2]:
+
+
list_to_stack([1, 2, 3])
-
-
+
-
-
-
+
+
-
-
-
- Out[2]:
+
+
+ Out[2]:
-
+
-
-
-
-
-
-In [3]:
-
-
+
+
+In [3]:
+
+
list(iter_stack((1, (2, (3, ())))))
-
-
+
-
-
-
+
+
-
-
-
- Out[3]:
+
+
+ Out[3]:
-
+
-
-
-
-
-
-
-
+
+
+
This requires reversing the sequence (or iterating backwards) otherwise:
-
-
-
-
-
-In [4]:
-
-
+
+
+In [4]:
+
+
stack = ()
for n in (1, 2, 3):
@@ -14786,23 +13249,20 @@ joy?
print(list(iter_stack(stack)))
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
+
+
+
Purely Functional Datastructures.¶
Because Joy lists are made out of Python tuples they are immutable, so all Joy datastructures are purely functional.
-
-
-
-
-
-
-
+
+
+
The joy() function.¶
An Interpreter¶
The joy() function is extrememly simple. It accepts a stack, an expression, and a dictionary, and it iterates through the expression putting values onto the stack and delegating execution to functions it looks up in the dictionary.
Each function is passed the stack, expression, and dictionary and returns them. Whatever the function returns becomes the new stack, expression, and dictionary. (The dictionary is passed to enable e.g. writing words that let you enter new words into the dictionary at runtime, which nothing does yet and may be a bad idea, and the help command.)
@@ -14839,443 +13291,347 @@ joy?
-
-
-
-
-
-
-
-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.
+
+
+
+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.
-
-
-
-
-
-
-
-The TracePrinter.¶
A viewer records each step of the evaluation of a Joy program. The TracePrinter has a facility for printing out a trace of the evaluation, one line per step. Each step is aligned to the current interpreter position, signified by a period separating the stack on the left from the pending expression ("continuation") on the right.
+
+
+
+The TracePrinter.¶
A viewer records each step of the evaluation of a Joy program. The TracePrinter has a facility for printing out a trace of the evaluation, one line per step. Each step is aligned to the current interpreter position, signified by a period separating the stack on the left from the pending expression ("continuation") on the right.
-
-
-
-
-
-
-
+
+
+
Continuation-Passing Style¶
One day I thought, What happens if you rewrite Joy to use CSP? I made all the functions accept and return the expression as well as the stack and found that all the combinators could be rewritten to work by modifying the expression rather than making recursive calls to the joy() function.
-
-
-
-
-
-
-
+
+
+
Parser¶
-
-
-
-
-
-In [5]:
-
-
+
+
+In [5]:
+
+
from joy.parser import text_to_expression
-
-
+
-
-
-
-
-
-
+
+
+
The parser is extremely simple, the undocumented re.Scanner class does most of the tokenizing work and then you just build the tuple structure out of the tokens. There's no Abstract Syntax Tree or anything like that.
-
-
-
-
-
-
-
+
+
+
A simple sequence.
-
-
-
-
-
-In [6]:
-
-
-text_to_expression('1 2 3 4 5')
+
+
+In [6]:
+
+
+text_to_expression('1 2 3 4 5')
-
-
+
-
-
-
+
+
-
-
-
- Out[6]:
+
+
+ Out[6]:
-
+
-
-
-
-
-
-
-
+
+
+
Three items, the first is a list with three items
-
-
-
-
-
-In [7]:
-
-
-text_to_expression('[1 2 3] 4 5')
+
+
+In [7]:
+
+
+text_to_expression('[1 2 3] 4 5')
-
-
+
-
-
-
+
+
-
-
-
- Out[7]:
+
+
+ Out[7]:
-
+
-
-
-
-
-
-
-
+
+
+
A mixed bag.
-
-
-
-
-
-In [8]:
-
-
-text_to_expression('1 23 ["four" [-5.0] cons] 8888')
+
+
+In [8]:
+
+
+text_to_expression('1 23 ["four" [-5.0] cons] 8888')
-
-
+
-
-
-
+
+
-
-
-
- Out[8]:
+
+
+ Out[8]:
-
+
-
-
-
-
-
-
-
+
+
+
Five empty lists.
-
-
-
-
-
-In [9]:
-
-
-text_to_expression('[][][][][]')
+
+
+In [9]:
+
+
+text_to_expression('[][][][][]')
-
-
+
-
-
-
+
+
-
-
-
- Out[9]:
+
+
+ Out[9]:
-
+
-
-
-
-
-
-
-
+
+
+
Five nested lists.
-
-
-
-
-
-In [10]:
-
-
-text_to_expression('[[[[[]]]]]')
+
+
+In [10]:
+
+
+text_to_expression('[[[[[]]]]]')
-
-
+
-
-
-
+
+
-
-
-
- Out[10]:
+
+
+ Out[10]:
-
+
-
-
-
-
-
-
-
-Library¶
The Joy library of functions (aka commands, or "words" after Forth usage) encapsulates all the actual functionality (no pun intended) of the Joy system. There are simple functions such as addition add (or +, the library module supports aliases), and combinators which provide control-flow and higher-order operations.
+
+
+
+Library¶
The Joy library of functions (aka commands, or "words" after Forth usage) encapsulates all the actual functionality (no pun intended) of the Joy system. There are simple functions such as addition add (or +, the library module supports aliases), and combinators which provide control-flow and higher-order operations.
-
-
-
-
-
-In [11]:
-
-
+
+
+In [11]:
+
+
import joy.library
-print(' '.join(sorted(joy.library.initialize())))
+print(' '.join(sorted(joy.library.initialize())))
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
+
+
+
Many of the functions are defined in Python, like dip:
-
-
-
-
-
-In [12]:
-
-
+
+
+In [12]:
+
+
import inspect
-
-
+
-
-
-
-
-In [13]:
-
-
+
+
+In [13]:
+
+
print(inspect.getdoc(joy.library.dip))
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
+
+
+
The code (I was using inspect.getsource() here to automatically print the souce but it was not as nice-looking that way due to lack of syntax highlighting and the docstring being too long for the width of the element and wrapping in an ungainly way. SO now, instead, I'm just including it as a Python cell in the notebook):
-
-
-
-
-
-In [14]:
-
-
+
+
+In [14]:
+
+
def dip(stack, expression, dictionary):
try:
(quote, (x, stack)) = stack
except ValueError:
- raise StackUnderflowError('Not enough values on stack.')
+ raise StackUnderflowError('Not enough values on stack.')
return stack, concat(quote, (x, expression)), dictionary
-
-
+
-
-
-
-
-
-
+
+
+
Some functions are defined in equations in terms of other functions. When the interpreter executes a definition function that function just pushes its body expression onto the pending expression (the continuation) and returns control to the interpreter.
(Note that the embedded joy.library.definitions is going away in favor of a def.txt file that would be read in at start-time. See
Ticket: thun-der#7)
@@ -15339,34 +13684,28 @@ on the rest of the stack.
-
-
-
-
-
-In [15]:
-
-
+
+
+In [15]:
+
+
print(joy.library.definitions)
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
-Currently, there's no function to add new definitions to the dictionary from "within" Joy code itself. (Actually there is, it's called inscribe, but don't use it, eh? :) Adding new definitions remains a meta-interpreter action. You have to do it yourself, in Python, and wash your hands afterward.
+
+
+
+Currently, there's no function to add new definitions to the dictionary from "within" Joy code itself. (Actually there is, it's called inscribe, but don't use it, eh? :) Adding new definitions remains a meta-interpreter action. You have to do it yourself, in Python, and wash your hands afterward.
It would be simple enough to define one, but it would open the door to name binding and break the idea that all state is captured in the stack and expression. There's an implicit standard dictionary that defines the actual semantics of the syntactic stack and expression datastructures (which only contain symbols, not the actual functions. Pickle some and see for yourself.)
-"There should be only one."¶
Which brings me to talking about one of my hopes and dreams for this notation: "There should be only one." What I mean is that there should be one universal standard dictionary of commands, and all bespoke work done in a UI for purposes takes place by direct interaction and macros. There would be a Grand Refactoring biannually (two years, not six months, that's semi-annually) where any new definitions factored out of the usage and macros of the previous time, along with new algorithms and such, were entered into the dictionary and posted to e.g. IPFS.
-Code should not burgeon wildly, as it does today. The variety of code should map more-or-less to the well-factored variety of human computably-solvable problems. There shouldn't be dozens of chat apps, JS frameworks, programming languages. It's a waste of time, a fractal "thundering herd" attack on human mentality.
+"There should be only one."¶
Which brings me to talking about one of my hopes and dreams for this notation: "There should be only one." What I mean is that there should be one universal standard dictionary of commands, and all bespoke work done in a UI for purposes takes place by direct interaction and macros. There would be a Grand Refactoring biannually (two years, not six months, that's semi-annually) where any new definitions factored out of the usage and macros of the previous time, along with new algorithms and such, were entered into the dictionary and posted to e.g. IPFS.
+Code should not burgeon wildly, as it does today. The variety of code should map more-or-less to the well-factored variety of human computably-solvable problems. There shouldn't be dozens of chat apps, JS frameworks, programming languages. It's a waste of time, a fractal "thundering herd" attack on human mentality.
Literary Code Library¶
If you read over the other notebooks you'll see that developing code in Joy is a lot like doing simple mathematics, and the descriptions of the code resemble math papers. The code also works the first time, no bugs. If you have any experience programming at all, you are probably skeptical, as I was, but it seems to work: deriving code mathematically seems to lead to fewer errors.
But my point now is that this great ratio of textual explanation to wind up with code that consists of a few equations and could fit on an index card is highly desirable. Less code has fewer errors. The structure of Joy engenders a kind of thinking that seems to be very effective for developing structured processes.
There seems to be an elegance and power to the notation.
@@ -15432,13 +13767,14 @@ while == swap [nullary] cons dup dipd concat loop
-
+
+
-
+
diff --git a/docs/html/notebooks/1._Basic_Use_of_Joy_in_a_Notebook.html b/docs/html/notebooks/1._Basic_Use_of_Joy_in_a_Notebook.html
index 6fc48a4..fb4f926 100644
--- a/docs/html/notebooks/1._Basic_Use_of_Joy_in_a_Notebook.html
+++ b/docs/html/notebooks/1._Basic_Use_of_Joy_in_a_Notebook.html
@@ -3,12624 +3,11322 @@
-1._Basic_Use_of_Joy_in_a_Notebook
-
-
-
+1._Basic_Use_of_Joy_in_a_Notebook
-
-
-
-
+
-
-
+
-
+
+
+
-
-
-
-
-
-
+
+
+
Preamble¶
First, import what we need.
-
-
-
-
-
-In [1]:
-
-
+
+
+In [1]:
+
+
from joy.joy import run
from joy.library import initialize
from joy.utils.stack import stack_to_string
from joy.utils.pretty_print import TracePrinter
-
-
+
-
-
-
-
-
-
+
+
+
Define a dictionary, an initial stack, and two helper functions to run Joy code and print results for us.
-
-
-
-
-
-In [2]:
-
-
+
+
+In [2]:
+
+
D = initialize()
S = ()
@@ -14651,136 +13137,110 @@ body[data-format='mobile'] .jp-OutputArea-child .jp-OutputArea-output {
tp.print_()
-
-
+
-
-
-
-
-
-
+
+
+
Run some simple programs¶
-
-
-
-
-
-In [3]:
-
-
-J('23 18 +')
+
+
+In [3]:
+
+
+J('23 18 +')
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-In [4]:
-
-
-J('45 30 gcd')
+
+
+In [4]:
+
+
+J('45 30 gcd')
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
-With Viewer¶
A viewer records each step of the evaluation of a Joy program. The TracePrinter has a facility for printing out a trace of the evaluation, one line per step. Each step is aligned to the current interpreter position, signified by a period separating the stack on the left from the pending expression ("continuation") on the right. I find these traces beautiful, like a kind of art.
+
+
+
+With Viewer¶
A viewer records each step of the evaluation of a Joy program. The TracePrinter has a facility for printing out a trace of the evaluation, one line per step. Each step is aligned to the current interpreter position, signified by a period separating the stack on the left from the pending expression ("continuation") on the right. I find these traces beautiful, like a kind of art.
-
-
-
-
-
-In [5]:
-
-
-V('23 18 +')
+
+
+In [5]:
+
+
+V('23 18 +')
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-In [6]:
-
-
-V('45 30 gcd')
+
+
+In [6]:
+
+
+V('45 30 gcd')
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
-
-
-
-
-
-
+
+
+
Here's a longer trace.
-
-
-
-
-
-In [7]:
-
-
-V('96 27 gcd')
+
+
+In [7]:
+
+
+V('96 27 gcd')
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
+
-
+
+
-
+
diff --git a/docs/html/notebooks/2._Library_Examples.html b/docs/html/notebooks/2._Library_Examples.html
index cbb3c56..b346385 100644
--- a/docs/html/notebooks/2._Library_Examples.html
+++ b/docs/html/notebooks/2._Library_Examples.html
@@ -3,12624 +3,11322 @@
-2._Library_Examples
-
-
-
+2._Library_Examples
-
-
-
-
+
-
-
+
-
+
+
+
-
-
-
-
-
-
+
+
+
Examples (and some documentation) for the Words in the Library¶
-
-
-
-
-
-In [1]:
-
-
-from notebook_preamble import J, V
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Stack Chatter¶
This is what I like to call the functions that just rearrange things on the stack. (One thing I want to mention is that during a hypothetical compilation phase these "stack chatter" words effectively disappear, because we can map the logical stack locations to registers that remain static for the duration of the computation. This remains to be done but it's "off the shelf" technology.)
+
+
+
+Stack Chatter¶
This is what I like to call the functions that just rearrange things on the stack. (One thing I want to mention is that during a hypothetical compilation phase these "stack chatter" words effectively disappear, because we can map the logical stack locations to registers that remain static for the duration of the computation. This remains to be done but it's "off the shelf" technology.)
-
-
-
-
-
-
-
+
+
+
clear¶
-
-
-
-
-
-In [2]:
-
-
-J('1 2 3 clear')
+
+
+In [132]:
+
+
+1 2 3
-
-
+
-
-
-
+
+
-
-
-
-
+
+
+
-
-
-
+
-
-
-
-
+
+
+In [133]:
+
+