# Parsing Text into Joy Expressions

TODO: example…

## `joy.parser`

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 ']' | symbol

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.

exception joy.parser.ParseError

  Raised when there is a error while parsing text.

class joy.parser.Symbol

  A string class that represents Joy function names.

joy.parser.text_to_expression(text)

  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.

  Parameters

    text (str) – Text to convert.

  Return type

    stack

  Raises

    ParseError – if the parse fails.

## Parser Internals

TODO: Document things like the regular expressions used for tokenizing, and the re.Scanner, etc…