6 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.
8 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.
10 ### [Read-Eval-Print Loop (REPL)](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)
11 The main way to interact with the Joy interpreter is through a simple [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) that you start by running the package:
14 Joypy - Copyright © 2017 Simon Forman
15 This program comes with ABSOLUTELY NO WARRANTY; for details type "warranty".
16 This is free software, and you are welcome to redistribute it
17 under certain conditions; type "sharing" for details.
18 Type "words" to see a list of all words, and "[<name>] help" to print the
26 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](#The-TracePrinter.) will be printed followed by the stack and prompt again:
42 # Stacks (aka list, quote, sequence, etc.)
44 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](https://en.wikipedia.org/wiki/Cons#Lists) made from Python tuples.
49 import joy.utils.stack
52 print inspect.getdoc(joy.utils.stack)
58 When talking about Joy we use the terms "stack", "list", "sequence" and
59 "aggregate" to mean the same thing: a simple datatype that permits
60 certain operations such as iterating and pushing and popping values from
63 We use the venerable two-tuple recursive form of sequences where the
64 empty tuple () is the empty stack and (head, rest) gives the recursive
65 form of a stack with one or more items on it.
76 We have two very simple functions to build up a stack from a Python
77 iterable and also to iterate through a stack and yield its items
78 one-by-one in order, and two functions to generate string representations
85 expression_to_string() (prints left-to-right)
87 stack_to_string() (prints right-to-left)
90 A word about the stack data structure.
92 Python has very nice "tuple packing and unpacking" in its syntax which
93 means we can directly "unpack" the expected arguments to a Joy function.
99 return head, (head, tail)
101 We replace the argument "stack" by the expected structure of the stack,
102 in this case "(head, tail)", and Python takes care of de-structuring the
103 incoming argument and assigning values to the names. Note that Python
104 syntax doesn't require parentheses around tuples used in expressions
105 where they would be redundant.
108 ### The utility functions maintain order.
109 The 0th item in the list will be on the top of the stack and *vise versa*.
113 joy.utils.stack.list_to_stack([1, 2, 3])
125 list(joy.utils.stack.iter_stack((1, (2, (3, ())))))
135 This requires reversing the sequence (or iterating backwards) otherwise:
145 print list(joy.utils.stack.iter_stack(stack))
152 ### Purely Functional Datastructures.
153 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)*.
155 # The `joy()` function.
157 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.
159 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.)
165 print inspect.getsource(joy.joy.joy)
168 def joy(stack, expression, dictionary, viewer=None):
170 Evaluate the Joy expression on the stack.
174 if viewer: viewer(stack, expression)
176 term, expression = expression
177 if isinstance(term, Symbol):
178 term = dictionary[term]
179 stack, expression, dictionary = term(stack, expression, dictionary)
183 if viewer: viewer(stack, expression)
184 return stack, expression, dictionary
189 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.
191 ### The `TracePrinter`.
193 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.
195 ### [Continuation-Passing Style](https://en.wikipedia.org/wiki/Continuation-passing_style)
196 One day I thought, What happens if you rewrite Joy to use [CSP](https://en.wikipedia.org/wiki/Continuation-passing_style)? 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.
204 print inspect.getdoc(joy.parser)
207 § Converting text to a joy expression.
209 This module exports a single function:
211 text_to_expression(text)
213 As well as a single Symbol class and a single Exception type:
217 When supplied with a string this function returns a Python datastructure
218 that represents the Joy datastructure described by the text expression.
219 Any unbalanced square brackets will raise a ParseError.
222 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.
226 print inspect.getsource(joy.parser._parse)
231 Return a stack/list expression of the tokens.
239 stack[-1].append(frame)
244 raise ParseError('One or more extra closing brackets.')
245 frame[-1] = list_to_stack(frame[-1])
249 raise ParseError('One or more unclosed brackets.')
250 return list_to_stack(frame)
254 That's pretty much all there is to it.
258 joy.parser.text_to_expression('1 2 3 4 5') # A simple sequence.
264 (1, (2, (3, (4, (5, ())))))
270 joy.parser.text_to_expression('[1 2 3] 4 5') # Three items, the first is a list with three items
276 ((1, (2, (3, ()))), (4, (5, ())))
282 joy.parser.text_to_expression('1 23 ["four" [-5.0] cons] 8888') # A mixed bag. cons is
283 # a Symbol, no lookup at
284 # parse-time. Haiku docs.
290 (1, (23, (('four', ((-5.0, ()), (cons, ()))), (8888, ()))))
296 joy.parser.text_to_expression('[][][][][]') # Five empty lists.
302 ((), ((), ((), ((), ((), ())))))
308 joy.parser.text_to_expression('[[[[[]]]]]') # Five nested lists.
314 ((((((), ()), ()), ()), ()), ())
319 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.
325 print ' '.join(sorted(joy.library.initialize()))
328 != % & * *fraction *fraction0 + ++ - -- / < << <= <> = > >= >> ? ^ 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< roll> 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 •
331 Many of the functions are defined in Python, like `dip`:
335 print inspect.getsource(joy.library.dip)
338 def dip(stack, expression, dictionary):
339 (quote, (x, stack)) = stack
340 expression = x, expression
341 return stack, pushback(quote, expression), dictionary
345 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.
349 print joy.library.definitions
353 third == rest rest first
354 product == 1 swap [*] step
356 swoncat == swap concat
357 flatten == [] swap [concat] step
361 enstacken == stack [clear] dip
362 disenstacken == ? [uncons ?] loop pop
364 dinfrirst == dip infra first
365 nullary == [stack] dinfrirst
366 unary == [stack [pop] dip] dinfrirst
367 binary == [stack [popop] dip] dinfrirst
368 ternary == [stack [popop pop] dip] dinfrirst
372 size == 0 swap [pop ++] step
373 cleave == [i] app2 [popd] dip
374 average == [sum 1.0 *] [size] cleave /
375 gcd == 1 [tuck modulus dup 0 >] loop pop
376 least_fraction == dup [gcd] infra [div] concat map
377 *fraction == [uncons] dip uncons [swap] dip concat [*] infra [*] dip cons
378 *fraction0 == concat [[swap] dip * [*] dip] infra
379 down_to_zero == [0 >] [dup --] while
380 range_to_zero == unit [down_to_zero] infra
381 anamorphism == [pop []] swap [dip swons] genrec
382 range == [0 <=] [1 - dup] anamorphism
383 while == swap [nullary] cons dup dipd concat loop
385 primrec == [i] genrec
389 Currently, there's no function to add new definitions to the dictionary from "within" Joy code itself. Adding new definitions remains a meta-interpreter action. You have to do it yourself, in Python, and wash your hands afterward.
391 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.)
393 #### "There should be only one."
395 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.
397 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](https://en.wikipedia.org/wiki/Thundering_herd_problem) on human mentality.
399 #### Literary Code Library
401 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.
403 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.
405 There seems to be an elegance and power to the notation.