From: Simon Forman Date: Mon, 23 Apr 2018 05:44:49 +0000 (-0700) Subject: Sphinx docs coming along. X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=93b35593d4d0dfda618ef634acf6c394c99ef0e0;p=joypy%2FThun.git Sphinx docs coming along. It's so pretty! Make me want to write more docs. :-) Some weird bug parsing the library.py module though. D'oh! --- 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. -§ Converting text to a joy expression. +A crude grammar:: -This module exports a single function: + joy = term* + term = int | float | string | '[' joy ']' | function - text_to_expression(text) +A Joy expression is a sequence of zero or more terms -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. - - () - (1, ()) - (2, (1, ())) - (3, (2, (1, ()))) - ... - -And so on. - +form of a stack with one or more items on it:: -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: + stack := () | (item, stack) - list_to_stack() +Putting some numbers onto a 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)