Add parent tracking and mutation to AST visitors

Fixes #916
2014-12-26 11:32:30 -06:00
parent 8babe05953
commit 9ff3daf785
3 changed files with 192 additions and 38 deletions
@@ -204,6 +204,12 @@ var scanner = new ImportScanner();
 scanner.accept(ast);
 ```

+The current node's ancestors will be maintained in the `parents` array, with the most recent parent listed first.
+
+The visitor may also be configured to operate in mutation mode by setting the `mutation` field to true. When in this mode, handler methods may return any valid AST node and it will replace the one they are currently operating on. Returning `false` will remove the given value (if valid) and returning `undefined` will leave the node in tact. This return structure only apply to mutation mode and non-mutation mode visitors are free to return whatever values they wish.
+
+Implementors that may need to support mutation mode are encouraged to utilize the `acceptKey`, `acceptRequired` and `acceptArray` helpers which provide the conditional overwrite behavior as well as implement sanity checks where pertinent.
+
 ## JavaScript Compiler

 The `Handlebars.JavaScriptCompiler` object has a number of methods that may be customized to alter the output of the compiler: