worked on documentation and added an optional environment parameter

improved/interpreter.py

@@ -5,7 +5,7 @@ from .tokenize import tokenize
 class ParseError(Exception):
     pass
 
-def callIMP(chars):
+def callIMP(chars, env=None):
     """
         The entry point for everyone who wants to call
         IMP from within Python. The function either
@@ -13,6 +13,8 @@ def callIMP(chars):
         succeed.
 
         chars -- the string to evaluate
+        env   -- a environment to bootstrap the imp
+                 environment with
 
         returns -- the IMP environment | None
     """
@@ -22,6 +24,6 @@ def callIMP(chars):
     parsed = parse(tokens)
     if not parsed or not parsed.value: raise ParseError("tokens could not be parsed")
     ast = parsed.value
-    env = {}
+    if not env: env = {}
     ast.eval(env)
     return env

improved/parser.py

@@ -213,7 +213,20 @@ def statements():
     return Exp(statement(), sep)
 
 def parser():
+    """
+        Builds a parser for Imp.
+
+        returns -- a parser for the Imp language
+    """
     return Phrase(statements())
 
 def parse(tokens):
+    """
+        The parser entry point, takes a list of tokens and
+        transforms them into an AST.
+
+        tokens -- the token list
+
+        returns -- the AST
+    """
     return parser()(tokens, 0)