diff --git a/docs/sphinx_docs/index.rst b/docs/sphinx_docs/index.rst
index 0b5f8a9..92b29ea 100644
--- a/docs/sphinx_docs/index.rst
+++ b/docs/sphinx_docs/index.rst
@@ -6,13 +6,15 @@
Thun Documentation
==================
-Hey
+Hey there!
.. toctree::
:maxdepth: 2
:caption: Contents:
-There!
+ stack
+ parser
+ pretty
.. automodule:: joy.joy
:members:
diff --git a/docs/sphinx_docs/library.rst b/docs/sphinx_docs/library.rst
new file mode 100644
index 0000000..a08d41b
--- /dev/null
+++ b/docs/sphinx_docs/library.rst
@@ -0,0 +1,9 @@
+
+Functions, Combinators and Definitions
+======================================
+
+
+. . automodule:: joy.library
+ :members:
+
+
diff --git a/docs/sphinx_docs/parser.rst b/docs/sphinx_docs/parser.rst
new file mode 100644
index 0000000..98105e6
--- /dev/null
+++ b/docs/sphinx_docs/parser.rst
@@ -0,0 +1,9 @@
+
+Parsing Text into Joy Expressions
+=================================
+
+
+.. automodule:: joy.parser
+ :members:
+
+
diff --git a/docs/sphinx_docs/pretty.rst b/docs/sphinx_docs/pretty.rst
new file mode 100644
index 0000000..f499a1e
--- /dev/null
+++ b/docs/sphinx_docs/pretty.rst
@@ -0,0 +1,9 @@
+
+Tracing Joy Execution
+=====================
+
+
+.. automodule:: joy.utils.pretty_print
+ :members:
+
+
diff --git a/docs/sphinx_docs/stack.rst b/docs/sphinx_docs/stack.rst
new file mode 100644
index 0000000..b9429e7
--- /dev/null
+++ b/docs/sphinx_docs/stack.rst
@@ -0,0 +1,9 @@
+
+Stack or Quote or Sequence or List...
+=====================================
+
+
+.. automodule:: joy.utils.stack
+ :members:
+
+
diff --git a/joy/joy.py b/joy/joy.py
index 21e4128..430a2ab 100644
--- a/joy/joy.py
+++ b/joy/joy.py
@@ -64,6 +64,12 @@ from .utils.pretty_print import TracePrinter
def joy(stack, expression, dictionary, viewer=None):
'''
Evaluate the Joy expression on the stack.
+
+ :param quote stack: The stack.
+ :param quote expression: The expression to evaluate.
+ :param dict dictionary: A `dict` mapping names to Joy functions.
+ :param function viewer: Optional viewer function.
+
'''
while expression:
diff --git a/joy/parser.py b/joy/parser.py
index bfa9377..e0dd9fc 100644
--- a/joy/parser.py
+++ b/joy/parser.py
@@ -18,45 +18,55 @@
# along with Thun. If not see .
#
'''
+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.
+
+The Symbol string class is used by the interpreter to recognize literals
+by the fact that they are not Symbol objects.
+
+A crude grammar::
+
+ joy = term*
+ term = int | float | string | '[' joy ']' | function
+
+A Joy expression is a sequence of zero or more terms
-§ Converting text to a joy expression.
-
-This module exports a single function:
-
- text_to_expression(text)
-
-As well as a single Symbol class and a single Exception type:
-
- 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.
'''
+#TODO: explain the details of float lits and strings.
from re import Scanner
from .utils.stack import list_to_stack
class Symbol(str):
+ '''A string class that represents Joy function names.'''
__repr__ = str.__str__
def text_to_expression(text):
- '''
- Convert a text to a Joy expression.
+ '''Convert a string to a Joy expression.
+
+ 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.
+
+ :param str text: Text to convert.
+ :rtype: quote
+ :raises ParseError: if the parse fails.
'''
return _parse(_tokenize(text))
-class ParseError(ValueError): pass
+class ParseError(ValueError):
+ '''Raised when there is a error while parsing text.'''
def _tokenize(text):
- '''
- Convert a text into a stream of tokens, converting symbols using
- symbol(token). Raise ValueError (with some of the failing text)
- if the scan fails.
+ '''Convert a text into a stream of tokens.
+
+ Converts function names to Symbols.
+
+ Raise ParseError (with some of the failing text) if the scan fails.
'''
tokens, rest = _scanner.scan(text)
if rest:
diff --git a/joy/utils/pretty_print.py b/joy/utils/pretty_print.py
index 6ae6be4..5f71c01 100644
--- a/joy/utils/pretty_print.py
+++ b/joy/utils/pretty_print.py
@@ -19,16 +19,6 @@
#
'''
Pretty printing support.
-
-This is what does the formatting, e.g.:
-
- . 23 18 mul 99 add
- 23 . 18 mul 99 add
- 23 18 . mul 99 add
- 414 . 99 add
- 414 99 . add
- 513 .
-
'''
# (Kinda clunky and hacky. This should be swapped out in favor of much
# smarter stuff.)
@@ -38,6 +28,18 @@ from .stack import expression_to_string, stack_to_string
class TracePrinter(object):
+ '''
+ This is what does the formatting, e.g.::
+
+ Joy? 23 18 * 99 +
+ . 23 18 mul 99 add
+ 23 . 18 mul 99 add
+ 23 18 . mul 99 add
+ 414 . 99 add
+ 414 99 . add
+ 513 .
+
+ '''
def __init__(self):
self.history = []
diff --git a/joy/utils/stack.py b/joy/utils/stack.py
index 8f11af7..c5ff7a9 100644
--- a/joy/utils/stack.py
+++ b/joy/utils/stack.py
@@ -18,64 +18,60 @@
# along with Thun. If not see .
#
'''
-
-
-§ Stack
-
-
-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.
+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 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.
+form of a stack with one or more items on it::
- ()
- (1, ())
- (2, (1, ()))
- (3, (2, (1, ())))
- ...
+ stack := () | (item, stack)
-And so on.
+Putting some numbers onto a stack::
-
-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
+ 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.)
'''
+##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.
+
+
def list_to_stack(el, stack=()):
- '''Convert a list (or other sequence) to a stack.
+ '''Convert a Python list (or other sequence) to a Joy stack::
[1, 2, 3] -> (1, (2, (3, ())))
@@ -96,9 +92,9 @@ def stack_to_string(stack):
'''
Return a "pretty print" string for a stack.
- The items are written right-to-left:
+ The items are written right-to-left::
- (top, (second, ...)) -> '... second top'
+ (top, (second, ...)) -> '... second top'
'''
f = lambda stack: reversed(list(iter_stack(stack)))
return _to_string(stack, f)
@@ -108,9 +104,9 @@ def expression_to_string(expression):
'''
Return a "pretty print" string for a expression.
- The items are written left-to-right:
+ The items are written left-to-right::
- (top, (second, ...)) -> 'top second ...'
+ (top, (second, ...)) -> 'top second ...'
'''
return _to_string(expression, iter_stack)