diff --git a/README.md b/README.md index f6def187..65340475 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,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) Component documentation: diff --git a/doc/2_Usage_of_basic_components.markdown b/doc/2_Usage_of_basic_components.markdown index a3e746d1..a5c8a438 100644 --- a/doc/2_Usage_of_basic_components.markdown +++ b/doc/2_Usage_of_basic_components.markdown @@ -50,10 +50,18 @@ Subsequently you can pass PHP code (including the opening `create(ParserFactory::PREFER_PHP7); try { @@ -66,27 +74,68 @@ try { A parser instance can be reused to parse multiple files. -Node tree ---------- +Node dumping +------------ -If you use the above code with `$code = "dump($stmts), "\n"; +``` + +For the sample code from the previous section, this will produce the following output: ``` array( - 0: Stmt_Echo( - exprs: array( - 0: Scalar_String( - value: Hi + 0: Stmt_Function( + byRef: false + name: Identifier( + name: printLine + ) + params: array( + 0: Param( + type: null + byRef: false + variadic: false + var: Expr_Variable( + name: msg + ) + default: null ) - 1: Expr_FuncCall( - name: Name( - parts: array( - 0: hi - 1: getTarget + ) + returnType: null + stmts: array( + 0: Stmt_Echo( + exprs: array( + 0: Expr_Variable( + name: msg + ) + 1: Scalar_String( + value: + ) ) - args: array( + ) + ) + ) + 1: Stmt_Expression( + expr: Expr_FuncCall( + name: Name( + parts: array( + 0: printLine + ) + ) + args: array( + 0: Arg( + value: Scalar_String( + value: Hello World!!! + ) + byRef: false + unpack: false ) ) ) @@ -94,8 +143,28 @@ array( ) ``` -Thus `$stmts` will contain an array with only one node, with this node being an instance of -`PhpParser\Node\Stmt\Echo_`. +You can also use the `php-parse` script to obtain such a node dump by calling it either with a file +name or code string: + +```sh +vendor/bin/php-parse file.php +vendor/bin/php-parse " PhpParser\Node\Stmt\Function_` + * `Stmt_Expression -> PhpParser\Node\Stmt\Expression` + +The additional `_` at the end of the first class name is necessary, because `Function` is a +reserved keyword. Many node class names in this library have a trailing `_` to avoid clashing with +a keyword. As PHP is a large language there are approximately 140 different nodes. In order to make work with them easier they are grouped into three categories: @@ -113,8 +182,9 @@ with them easier they are grouped into three categories: * There are some nodes not in either of these groups, for example names (`PhpParser\Node\Name`) and call arguments (`PhpParser\Node\Arg`). -Some node class names have a trailing `_`. This is used whenever the class name would otherwise clash -with a PHP keyword. +The `Node\Stmt\Expression` node is somewhat confusing in that it contains both the terms "statement" +and "expression". This node distinguishes `expr`, which is a `Node\Expr`, from `expr;`, which is +an "expression statement" represented by `Node\Stmt\Expression` and containing `expr` as a sub-node. Every node has a (possibly zero) number of subnodes. You can access subnodes by writing `$node->subNodeName`. The `Stmt\Echo_` node has only one subnode `exprs`. So in order to access it diff --git a/doc/3_Other_node_tree_representations.markdown b/doc/3_Other_node_tree_representations.markdown deleted file mode 100644 index 7eb4599a..00000000 --- a/doc/3_Other_node_tree_representations.markdown +++ /dev/null @@ -1,92 +0,0 @@ -Other node tree representations -=============================== - -It is possible to convert the AST into several textual representations, which serve different uses. - -Simple serialization --------------------- - -It is possible to serialize the node tree using `serialize()` and also unserialize it using -`unserialize()`. The output is not human readable and not easily processable from anything -but PHP, but it is compact and generates quickly. The main application thus is in caching. - -Human readable dumping ----------------------- - -Furthermore it is possible to dump nodes into a human readable format using the `dump` method of -`PhpParser\NodeDumper`. This can be used for debugging. - -```php -$code = <<<'CODE' -create(PhpParser\ParserFactory::PREFER_PHP7); -$nodeDumper = new PhpParser\NodeDumper; - -try { - $stmts = $parser->parse($code); - - echo $nodeDumper->dump($stmts), "\n"; -} catch (PhpParser\Error $e) { - echo 'Parse Error: ', $e->getMessage(); -} -``` - -The above script will have an output looking roughly like this: - -``` -array( - 0: Stmt_Function( - byRef: false - params: array( - 0: Param( - name: msg - default: null - type: null - byRef: false - ) - ) - stmts: array( - 0: Stmt_Echo( - exprs: array( - 0: Expr_Variable( - name: msg - ) - 1: Scalar_String( - value: - - ) - ) - ) - ) - name: printLine - ) - 1: Expr_FuncCall( - name: Name( - parts: array( - 0: printLine - ) - ) - args: array( - 0: Arg( - value: Scalar_String( - value: Hello World!!! - ) - byRef: false - ) - ) - ) -) -``` - -JSON encoding -------------- - -See [JSON representation](component/JSON_representation.markdown) section. \ No newline at end of file diff --git a/doc/README.md b/doc/README.md index 0c3c81c0..2662457e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -6,7 +6,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) Component documentation -----------------------