add section about Tree->HCL2 reconstruction to the README.md

README.md

@@ -42,6 +42,14 @@ with open('foo.tf', 'r') as file:
     dict = hcl2.load(file)
 ```
 
+### Parse Tree to HCL2 reconstruction
+
+With version 5.0.0 the possibility of HCL2 reconstruction from Lark Parse Tree was introduced.
+
+Example of manipulating Lark Parse Tree and reconstructing it back into valid HCL2 can be found in [tree-to-hcl2-reconstruction.md](tree-to-hcl2-reconstruction.md) file.
+
+More details about reconstruction implementation can be found in this [PR](https://github.com/amplify-education/python-hcl2/pull/169).
+
 ## Building From Source
 
 For development, `tox>=4.0.9` is recommended.

tree-to-hcl2-reconstruction.md

@@ -0,0 +1,128 @@
+Given `example.tf` file with following content
+
+```terraform
+resource "aws_s3_bucket" "bucket" {
+  bucket = "bucket_id"
+  force_destroy   = true
+}
+```
+
+below code will add a `tags` object to the S3 bucket definition. The code can also be used to print out readable representation of any Parse Tree (any valid HCL2 file), which can be useful when working on your own logic for arbitrary Parse Tree manipulation.
+
+```python
+from copy import deepcopy
+from lark import Token, Tree
+import hcl2
+
+
+def build_tags_tree(base_indent: int = 0) -> Tree:
+    # build Tree representing following HCL2 structure
+    # tags = {
+    #   Name = "My bucket"
+    #   Environment = "Dev"
+    # }
+    return Tree('attribute', [
+        Tree('identifier', [
+            Token('NAME', 'tags')
+        ]),
+        Token('EQ', '='),
+        Tree('expr_term', [
+            Tree('object', [
+                Tree('new_line_or_comment', [
+                    Token('NL_OR_COMMENT', '\n' + '  ' * (base_indent + 1)),
+                ]),
+                Tree('object_elem', [
+                    Tree('identifier', [
+                        Token('NAME', 'Name')
+                    ]),
+                    Token('EQ', '='),
+                    Tree('expr_term', [
+                        Token('STRING_LIT', '"My bucket"')
+                    ])
+                ]),
+                Tree('new_line_and_or_comma', [
+                    Tree('new_line_or_comment', [
+                        Token('NL_OR_COMMENT', '\n' + '  ' * (base_indent + 1)),
+                    ]),
+                ]),
+                Tree('object_elem', [
+                    Tree('identifier', [
+                        Token('NAME', 'Environment')
+                    ]),
+                    Token('EQ', '='),
+                    Tree('expr_term', [
+                        Token('STRING_LIT', '"Dev"')
+                    ])
+                ]),
+                Tree('new_line_and_or_comma', [
+                    Tree('new_line_or_comment', [
+                        Token('NL_OR_COMMENT', '\n' + '  ' * base_indent),
+                    ]),
+                ]),
+            ]),
+        ])
+    ])
+
+
+def is_bucket_block(tree: Tree) -> bool:
+    # check whether given Tree represents `resource "aws_s3_bucket" "bucket"`
+    try:
+        return tree.data == 'block' and tree.children[2].value == '"bucket"'
+    except IndexError:
+        return False
+
+
+def insert_tags(tree: Tree, indent: int = 0) -> Tree:
+    # Insert tags tree and adjust surruonding whitespaces to match indentation
+    new_children = [*tree.children.copy(), build_tags_tree(indent)]
+    # add indentation before tags tree
+    new_children[len(tree.children) - 1] = Tree('new_line_or_comment', [
+        Token('NL_OR_COMMENT', '\n  ')
+    ])
+    # move closing bracket to the new line
+    new_children.append(
+        Tree('new_line_or_comment', [
+            Token('NL_OR_COMMENT', '\n')
+        ])
+    )
+    return Tree(tree.data, new_children)
+
+
+def process_token(node: Token, indent=0):
+    # Print details of this token and return its copy
+    print(f'[{indent}] (token)\t|', ' ' * indent, node.type, node.value)
+    return deepcopy(node)
+
+
+def process_tree(node: Tree, depth=0) -> Tree:
+    # Recursively iterate over trees children
+    # the depth parameter represent recursion depth,
+    # it's used to deduce indentation for printing tree and for adjusting whitespace after adding tags
+    new_children = []
+    print(f'[{depth}] (tree)\t|', ' ' * depth, node.data)
+    for child in node.children:
+        if isinstance(child, Tree):
+            if is_bucket_block(child):
+                block_children = child.children.copy()
+                block_children[3] = insert_tags(block_children[3], depth)  # this child is the Tree representing blocks actual body
+                # replace original Tree with new one including the modified body
+                child = Tree(child.data, block_children)
+
+            new_children.append(process_tree(child, depth + 1))
+
+        else:
+            new_children.append(process_token(child, depth + 1))
+
+    return Tree(node.data, new_children)
+
+
+def main():
+    tree = hcl2.parse(open('iam.tf'))
+    new_tree = process_tree(tree)
+    reconstructed = hcl2.writes(new_tree)
+    open('example_reconstructed.tf', 'w').write(reconstructed)
+
+
+if __name__ == "__main__":
+    main()
+```