From 385c35f5064587119f93fd8853e3a70bce8e2742 Mon Sep 17 00:00:00 2001
From: Erez Sh <erezshin@gmail.com>
Date: Sat, 17 Apr 2021 12:43:21 -0500
Subject: [PATCH] Examples: Better doc for create_ast

---
 examples/advanced/create_ast.py | 12 +++++++++++-
 lark/ast_utils.py               |  3 ++-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/examples/advanced/create_ast.py b/examples/advanced/create_ast.py
index e20b7e6..d0f8074 100644
--- a/examples/advanced/create_ast.py
+++ b/examples/advanced/create_ast.py
@@ -1,6 +1,9 @@
 """
     This example demonstrates how to transform a parse-tree into an AST using `lark.ast_utils`.
 
+    create_transformer() collects every subclass of `Ast` subclass from the module,
+    and creates a Lark transformer that builds the AST with no extra code.
+
     This example only works with Python 3.
 """
 
@@ -17,9 +20,11 @@ this_module = sys.modules[__name__]
 #   Define AST
 #
 class _Ast(ast_utils.Ast):
+    # This will be skipped by create_transformer(), because it starts with an underscore
     pass
 
 class _Statement(_Ast):
+    # This will be skipped by create_transformer(), because it starts with an underscore
     pass
 
 @dataclass
@@ -32,6 +37,7 @@ class Name(_Ast):
 
 @dataclass
 class CodeBlock(_Ast, ast_utils.AsList):
+    # Corresponds to code_block in the grammar
     statements: List[_Statement]
 
 @dataclass
@@ -41,6 +47,7 @@ class If(_Statement):
 
 @dataclass
 class SetVar(_Statement):
+    # Corresponds to set_var in the grammar
     name: str
     value: Value
 
@@ -50,6 +57,8 @@ class Print(_Statement):
 
 
 class ToAst(Transformer):
+    # Define extra transformation functions, for rules that don't correspond to an AST class.
+
     def STRING(self, s):
         # Remove quotation marks
         return s[1:-1]
@@ -89,7 +98,8 @@ parser = Lark("""
 transformer = ast_utils.create_transformer(this_module, ToAst())
 
 def parse(text):
-    return transformer.transform(parser.parse(text))
+    tree = parser.parse(text)
+    return transformer.transform(tree)
 
 #
 #   Test
diff --git a/lark/ast_utils.py b/lark/ast_utils.py
index 27b00a3..0f2e498 100644
--- a/lark/ast_utils.py
+++ b/lark/ast_utils.py
@@ -33,9 +33,10 @@ def create_transformer(ast_module, transformer=None):
     For each class, we create a corresponding rule in the transformer, with a matching name.
     CamelCase names will be converted into snake_case. Example: "CodeBlock" -> "code_block".
 
+    Classes starting with an underscore (`_`) will be skipped.
+
     Parameters:
         ast_module - A Python module containing all the subclasses of `ast_utils.Ast`
-                     Classes starting with an underscore (`_`) will be skipped.
         transformer (Optional[Transformer]) - An initial transformer. Its attributes may be overwritten.
     """
     t = transformer or Transformer()