-
§ 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::
-When talking about Joy we use the terms "stack", "list", "sequence" and
-"aggregate" 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 "tuple packing and unpacking" in its syntax which
means we can directly "unpack" 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 "stack" by the expected structure of the stack,
-in this case "(head, tail)", and Python takes care of de-structuring the
-incoming argument and assigning values to the names. Note that Python
+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.
+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
def joy(stack, expression, dictionary, viewer=None):
- '''
- Evaluate the Joy expression on the stack.
- '''
- while expression:
+ '''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)
+
+ '''
+ 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
@@ -12163,19 +12176,22 @@ where they would be redundant.
-
§ Converting text to a joy expression.
+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 | '[' joy ']' | 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.
def _parse(tokens):
- '''
- Return a stack/list expression of the tokens.
- '''
- frame = []
- stack = []
- for tok in tokens:
- if tok == '[':
- stack.append(frame)
- frame = []
- stack[-1].append(frame)
- elif tok == ']':
- try:
- frame = stack.pop()
- except IndexError:
- raise ParseError('One or more extra closing brackets.')
- frame[-1] = list_to_stack(frame[-1])
- else:
- frame.append(tok)
- if stack:
- raise ParseError('One or more unclosed brackets.')
- return list_to_stack(frame)
+ '''
+ Return a stack/list expression of the tokens.
+ '''
+ frame = []
+ stack = []
+ for tok in tokens:
+ if tok == '[':
+ stack.append(frame)
+ frame = []
+ stack[-1].append(frame)
+ elif tok == ']':
+ try:
+ frame = stack.pop()
+ except IndexError:
+ raise ParseError('Extra closing bracket.')
+ frame[-1] = list_to_stack(frame[-1])
+ else:
+ frame.append(tok)
+ if stack:
+ raise ParseError('Unclosed bracket.')
+ return list_to_stack(frame)
@@ -12455,7 +12471,7 @@ Any unbalanced square brackets will raise a ParseError.
-
!= % & * *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 •
+!= % & * *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 •
-
def dip(stack, expression, dictionary):
- (quote, (x, stack)) = stack
- expression = x, expression
- return stack, pushback(quote, expression), dictionary
+@inscribe
+@combinator_effect(_COMB_NUMS(), a1, s1)
+@FunctionWrapper
+def dip(stack, expression, dictionary):
+ '''
+ 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
+
+ '''
+ (quote, (x, stack)) = stack
+ expression = (x, expression)
+ return stack, concat(quote, expression), dictionary
-
second == rest first
-third == rest rest first
+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 >] 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 <=] [1 - dup] anamorphism
while == swap [nullary] cons dup dipd concat loop
-dudipd == dup dipd
+dupdipd == dup dipd
primrec == [i] genrec
+step_zero == 0 roll> step
+codireco == cons dip rest cons
+make_generator == [codireco] ccons
+ifte == [nullary not] dipd branch
-
[4 5 6 1 2 3]
-
+
+
+---------------------------------------------------------------------------
+KeyError Traceback (most recent call last)
+<ipython-input-22-15579491b615> in <module>()
+----> 1 J('[1 2 3] [4 5 6] swoncat')
+
+/home/sforman/Desktop/ArchLayer/System/source/Thun/docs/notebook_preamble.py in J(text, stack, dictionary)
+ 30
+ 31 def J(text, stack=S, dictionary=D):
+---> 32 print stack_to_string(run(text, stack, dictionary)[0])
+ 33
+ 34
+
+/home/sforman/Desktop/ArchLayer/System/source/Thun/venv/local/lib/python2.7/site-packages/joy/joy.pyc in run(text, stack, dictionary, viewer)
+ 77 '''
+ 78 expression = text_to_expression(text)
+---> 79 return joy(stack, expression, dictionary, viewer)
+ 80
+ 81
+
+/home/sforman/Desktop/ArchLayer/System/source/Thun/venv/local/lib/python2.7/site-packages/joy/joy.pyc in joy(stack, expression, dictionary, viewer)
+ 56 term, expression = expression
+ 57 if isinstance(term, Symbol):
+---> 58 term = dictionary[term]
+ 59 stack, expression, dictionary = term(stack, expression, dictionary)
+ 60 else:
+
+KeyError: swoncat