Stack or Quote or Sequence or List…

joy.utils.stack

When talking about Joy we use the terms “stack”, “list”, “sequence”, “quote” 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.

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.)

joy.utils.stack.expression_to_string(expression)

Return a “pretty print” string for a expression.

The items are written left-to-right:

(top, (second, ...)) -> 'top second ...'

joy.utils.stack.iter_stack(stack)

Iterate through the items on the stack.

joy.utils.stack.list_to_stack(el, stack=())

Convert a Python list (or other sequence) to a Joy stack:

[1, 2, 3] -> (1, (2, (3, ())))

joy.utils.stack.pick(s, n)

Find the nth item on the stack. (Pick with zero is the same as “dup”.)

joy.utils.stack.pushback(quote, expression)

Concatinate quote onto expression.

In joy [1 2] [3 4] would become [1 2 3 4].

joy.utils.stack.stack_to_string(stack)

Return a “pretty print” string for a stack.

The items are written right-to-left:

(top, (second, ...)) -> '... second top'