diff --git a/README.md b/README.md index d90acda..4e0a33a 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,6 @@ Documentation 1. [Introduction](doc/0_Introduction.markdown) 2. [Usage of basic components](doc/2_Usage_of_basic_components.markdown) 3. [Other node tree representations](doc/3_Other_node_tree_representations.markdown) - 4. [Code generation](doc/4_Code_generation.markdown) Component documentation: @@ -195,6 +194,8 @@ Component documentation: * Converting AST back to PHP code * Customizing formatting * Formatting-preserving code transformations + * [AST builders](component/AST_builders.markdown) + * Fluent builders for AST nodes * [Lexer](doc/component/Lexer.markdown) * Lexer options * Token and file positions for nodes diff --git a/doc/README.md b/doc/README.md index e32cac8..1fe1013 100644 --- a/doc/README.md +++ b/doc/README.md @@ -7,7 +7,6 @@ Guide 1. [Introduction](0_Introduction.markdown) 2. [Usage of basic components](2_Usage_of_basic_components.markdown) 3. [Other node tree representations](3_Other_node_tree_representations.markdown) - 4. [Code generation](4_Code_generation.markdown) Component documentation ----------------------- @@ -19,6 +18,8 @@ Component documentation * Converting AST back to PHP code * Customizing formatting * Formatting-preserving code transformations + * [AST builders](component/AST_builders.markdown) + * Fluent builders for AST nodes * [Lexer](component/Lexer.markdown) * Lexer options * Token and file positions for nodes diff --git a/doc/4_Code_generation.markdown b/doc/component/AST_builders.markdown similarity index 64% rename from doc/4_Code_generation.markdown rename to doc/component/AST_builders.markdown index ac9e498..e0fd8e2 100644 --- a/doc/4_Code_generation.markdown +++ b/doc/component/AST_builders.markdown @@ -1,9 +1,17 @@ -Code generation -=============== +AST builders +============ -It is also possible to generate code using the parser, by first creating an Abstract Syntax Tree and then using the -pretty printer to convert it to PHP code. To simplify code generation, the project comes with builders which allow -creating node trees using a fluid interface, instead of instantiating all nodes manually. Builders are available for +When PHP-Parser is used to generate (or modify) code, by first creating an Abstract Syntax Tree and +then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often +be tedious to manually construct AST nodes. The project provides a number of utilities to simplify +the construction of common AST nodes. + +Fluent builders +--------------- + +The library comes with a number of builders, which allow creating node trees using a fluent +interface. Builders are created using the `BuilderFactory` and the final constructed node is +accessed through `getNode()`. Fluent builders are available for the following syntactic elements: * namespaces and use statements @@ -82,3 +90,17 @@ abstract class SomeOtherClass extends SomeClass implements A\Few, \Interfaces } } ``` + +Additional helper methods +------------------------- + +The `BuilderFactory` also provides a number of additional helper methods, which directly return +nodes. The following methods are currently available: + + * `val($value)`: Creates an AST node for a literal value like `42` or `[1, 2, 3]`. + * `args(array $args)`: Creates an array of function/method arguments, including the required `Arg` + wrappers. Also converts literals to AST nodes. + * `concat(...$exprs)`: Create a tree of `BinaryOp\Concat` nodes for the given expressions. + +These methods may be expanded on an as-needed basis. Please open an issue or PR if a common +operation is missing. \ No newline at end of file