Update docs to use new names

.travis.yml

@@ -1,7 +1,6 @@
 language: php
 
 php:
-  - 5.2
   - 5.3
   - 5.4
   - 5.5

README.md

@@ -4,7 +4,9 @@ PHP Parser
 This is a PHP 5.5 (and older) parser written in PHP. It's purpose is to simplify static code analysis and
 manipulation.
 
-Documentation can be found in the [`doc/`][1] directory.
+[**Documentation for version 0.9.x**][doc_0_9].
+
+[Documentation for version 1.0-dev]. (For >= PHP 5.3, using namespaced names, but compatible with old names.)
 
 ***Note: This project is experimental, so the API is subject to change.***
 
@@ -75,4 +77,5 @@ Additionally, you can convert a syntax tree back to PHP code. This allows you to
 
 So, that's it, in a nutshell. You can find everything else in the [docs][1].
 
- [1]: https://github.com/nikic/PHP-Parser/tree/master/doc
+ [doc_0_9]: https://github.com/nikic/PHP-Parser/tree/0.9/doc
+ [doc_master]: https://github.com/nikic/PHP-Parser/tree/master/doc

doc/1_Installation.markdown

@@ -15,7 +15,7 @@ Create a `composer.json` file in your project root and use it to define your dep
 
     {
         "require": {
-            "nikic/php-parser": "0.9.4"
+            "nikic/php-parser": "1.0-dev"
         }
     }
 
@@ -27,14 +27,6 @@ And finally ask Composer to install the dependencies:
 
     php composer.phar install
 
-Installing as a PEAR package
-----------------------------
-
-Run the following two commands:
-
-    pear channel-discover nikic.github.com/pear
-    pear install nikic/PHPParser-0.9.4
-
 Installing as a Git Submodule
 -----------------------------
 

doc/2_Usage_of_basic_components.markdown

@@ -26,20 +26,20 @@ This ensures that there will be no errors when traversing highly nested node tre
 Parsing
 -------
 
-In order to parse some source code you first have to create a `PHPParser_Parser` object (which
+In order to parse some source code you first have to create a `PhpParser\Parser` object (which
-needs to be passed a `PHPParser_Lexer` instance) and then pass the code (including `<?php` opening
+needs to be passed a `PhpParser\Lexer` instance) and then pass the code (including `<?php` opening
-tags) to the `parse` method. If a syntax error is encountered `PHPParser_Error` is thrown, so this
+tags) to the `parse` method. If a syntax error is encountered `PhpParser\Error` is thrown, so this
 exception should be `catch`ed.
 
 ```php
 <?php
 $code = '<?php // some code';
 
-$parser = new PHPParser_Parser(new PHPParser_Lexer);
+$parser = new PhpParser\Parser(new PhpParser\Lexer);
 
 try {
     $stmts = $parser->parse($code);
-} catch (PHPParser_Error $e) {
+} catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```
@@ -48,7 +48,7 @@ The `parse` method will return an array of statement nodes (`$stmts`).
 
 ### Emulative lexer
 
-Instead of `PHPParser_Lexer` one can also use `PHPParser_Lexer_Emulative`. This class will emulate tokens
+Instead of `PhpParser\Lexer` one can also use `PhpParser\Lexer\Emulative`. This class will emulate tokens
 of newer PHP versions and as such allow parsing PHP 5.5 on PHP 5.2, for example. So if you want to parse
 PHP code of newer versions than the one you are running, you should use the emulative lexer.
 
@@ -81,37 +81,41 @@ array(
 ```
 
 Thus `$stmts` will contain an array with only one node, with this node being an instance of
-`PHPParser_Node_Stmt_Echo`.
+`PhpParser\Node\Stmt\Echo_`.
 
 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:
 
- * `PHPParser_Node_Stmt`s are statement nodes, i.e. language constructs that do not return
+ * `PhpParser\Node\Stmt`s are statement nodes, i.e. language constructs that do not return
    a value and can not occur in an expression. For example a class definition is a statement.
    It doesn't return a value and you can't write something like `func(class A {});`.
- * `PHPParser_Node_Expr`s are expression nodes, i.e. language constructs that return a value
+ * `PhpParser\Node\Expr`s are expression nodes, i.e. language constructs that return a value
    and thus can occur in other expressions. Examples of expressions are `$var`
-   (`PHPParser_Node_Expr_Variable`) and `func()` (`PHPParser_Node_Expr_FuncCall`).
+   (`PhpParser\Node\Expr\Variable`) and `func()` (`PhpParser\Node\Expr\FuncCall`).
- * `PHPParser_Node_Scalar`s are nodes representing scalar values, like `'string'`
+ * `PhpParser\Node\Scalar`s are nodes representing scalar values, like `'string'`
-   (`PHPParser_Node_Scalar_String`), `0` (`PHPParser_Node_Scalar_LNumber`) or magic constants
+   (`PhpParser\Node\Scalar\String`), `0` (`PhpParser\Node\Scalar\LNumber`) or magic constants
-   like `__FILE__` (`PHPParser_Node_Scalar_FileConst`). All `PHPParser_Node_Scalar`s extend
+   like `__FILE__` (`PhpParser\Node\Scalar\MagicConst\File`). All `PhpParser\Node\Scalar`s extend
-   `PHPParser_Node_Expr`, as scalars are expressions, too.
+   `PhpParser\Node\Expr`, as scalars are expressions, too.
- * There are some nodes not in either of these groups, for example names (`PHPParser_Node_Name`)
+ * There are some nodes not in either of these groups, for example names (`PhpParser\Node\Name`)
-   and call arguments (`PHPParser_Node_Arg`).
+   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.
 
 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
+`$node->subNodeName`. The `Stmt\Echo_` node has only one subnode `exprs`. So in order to access it
 in the above example you would write `$stmts[0]->exprs`. If you wanted to access name of the function
 call, you would write `$stmts[0]->exprs[1]->name`.
 
-All nodes also define a `getType()` method that returns the node type (the type is the class name
+All nodes also define a `getType()` method that returns the node type. The type is the class name
-without the `PHPParser_Node_` prefix).
+without the `PHPParser\Node\` prefix and `\` replaced with `_`. It also does not contain a trailing
+`_` for reserved-keyword class names.
 
 It is possible to associate custom metadata with a node using the `setAttribute()` method. This data
 can then be retrieved using `hasAttribute()`, `getAttribute()` and `getAttributes()`.
 
 By default the lexer adds the `startLine`, `endLine` and `comments` attributes. `comments` is an array
-of `PHPParser_Comment[_Doc]` instances.
+of `PhpParser\Comment[\Doc]` instances.
 
 The start line can also be accessed using `getLine()`/`setLine()` (instead of `getAttribute('startLine')`).
 The last doc comment from the `comments` attribute can be obtained using `getDocComment()`.
@@ -121,14 +125,14 @@ Pretty printer
 
 The pretty printer component compiles the AST back to PHP code. As the parser does not retain formatting
 information the formatting is done using a specified scheme. Currently there is only one scheme available,
-namely `PHPParser_PrettyPrinter_Default`.
+namely `PhpParser\PrettyPrinter\Standard`.
 
 ```php
 <?php
 $code = "<?php echo 'Hi ', hi\\getTarget();";
 
-$parser        = new PHPParser_Parser(new PHPParser_Lexer);
+$parser        = new PhpParser\Parser(new PhpParser\Lexer);
-$prettyPrinter = new PHPParser_PrettyPrinter_Default;
+$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
 
 try {
     // parse
@@ -145,7 +149,7 @@ try {
     $code = '<?php ' . $prettyPrinter->prettyPrint($stmts);
 
     echo $code;
-} catch (PHPParser_Error $e) {
+} catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```
@@ -154,11 +158,11 @@ The above code will output:
 
     <?php echo 'Hallo ', hi\getTarget();
 
-As you can see the source code was first parsed using `PHPParser_Parser->parse`, then changed and then
+As you can see the source code was first parsed using `PhpParser\Parser->parse()`, then changed and then
-again converted to code using `PHPParser_PrettyPrinter_Default->prettyPrint`.
+again converted to code using `PhpParser\PrettyPrinter\Standard->prettyPrint()`.
 
-The `prettyPrint` method pretty prints a statements array. It is also possible to pretty print only a
+The `prettyPrint()` method pretty prints a statements array. It is also possible to pretty print only a
-single expression using `prettyPrintExpr`.
+single expression using `prettyPrintExpr()`.
 
 Node traversation
 -----------------
@@ -169,15 +173,15 @@ Usually you want to change / analyze code in a generic way, where you don't know
 going to look like.
 
 For this purpose the parser provides a component for traversing and visiting the node tree. The basic
-structure of a program using this `PHPParser_NodeTraverser` looks like this:
+structure of a program using this `PhpParser\NodeTraverser` looks like this:
 
 ```php
 <?php
 $code = "<?php // some code";
 
-$parser        = new PHPParser_Parser(new PHPParser_Lexer);
+$parser        = new PhpParser\Parser(new PhpParser\Lexer);
-$traverser     = new PHPParser_NodeTraverser;
+$traverser     = new PhpParser\NodeTraverser;
-$prettyPrinter = new PHPParser_PrettyPrinter_Default;
+$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
 
 // add your visitor
 $traverser->addVisitor(new MyNodeVisitor);
@@ -193,7 +197,7 @@ try {
     $code = '<?php ' . $prettyPrinter->prettyPrint($stmts);
 
     echo $code;
-} catch (PHPParser_Error $e) {
+} catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```
@@ -202,10 +206,10 @@ A same node visitor for this code might look like this:
 
 ```php
 <?php
-class MyNodeVisitor extends PHPParser_NodeVisitorAbstract
+class MyNodeVisitor extends PhpParser\NodeVisitorAbstract
 {
-    public function leaveNode(PHPParser_Node $node) {
+    public function leaveNode(PhpParser\Node $node) {
-        if ($node instanceof PHPParser_Node_Scalar_String) {
+        if ($node instanceof PhpParser\Node\Scalar\String) {
             $node->value = 'foo';
         }
     }
@@ -214,12 +218,12 @@ class MyNodeVisitor extends PHPParser_NodeVisitorAbstract
 
 The above node visitor would change all string literals in the program to `'foo'`.
 
-All visitors must implement the `PHPParser_NodeVisitor` interface, which defined the following four
+All visitors must implement the `PhpParser\NodeVisitor` interface, which defined the following four
 methods:
 
     public function beforeTraverse(array $nodes);
-    public function enterNode(PHPParser_Node $node);
+    public function enterNode(PhpParser\Node $node);
-    public function leaveNode(PHPParser_Node $node);
+    public function leaveNode(PhpParser\Node $node);
     public function afterTraverse(array $nodes);
 
 The `beforeTraverse` method is called once before the traversal begins and is passed the nodes the
@@ -245,7 +249,7 @@ class, which will define empty default implementations for all the above methods
 The NameResolver node visitor
 -----------------------------
 
-One visitor is already bundled with the package: `PHPParser_NodeVisitor_NameResolver`. This visitor
+One visitor is already bundled with the package: `PhpParser\NodeVisitor\NameResolver`. This visitor
 helps you work with namespaced code by trying to resolve most names to fully qualified ones.
 
 For example, consider the following code:
@@ -280,12 +284,12 @@ const IN_DIR  = '/some/path';
 const OUT_DIR = '/some/other/path';
 
 // use the emulative lexer here, as we are running PHP 5.2 but want to parse PHP 5.3
-$parser        = new PHPParser_Parser(new PHPParser_Lexer_Emulative);
+$parser        = new PhpParser\Parser(new PhpParser\Lexer\Emulative);
-$traverser     = new PHPParser_NodeTraverser;
+$traverser     = new PhpParser\NodeTraverser;
-$prettyPrinter = new PHPParser_PrettyPrinter_Default;
+$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
 
-$traverser->addVisitor(new PHPParser_NodeVisitor_NameResolver); // we will need resolved names
+$traverser->addVisitor(new PhpParser\NodeVisitor\NameResolver); // we will need resolved names
-$traverser->addVisitor(new NodeVisitor_NamespaceConverter);     // our own node visitor
+$traverser->addVisitor(new NodeVisitor\NamespaceConverter);     // our own node visitor
 
 // iterate over all .php files in the directory
 $files = new RecursiveIteratorIterator(new RecursiveDirectoryIterator(IN_DIR));
@@ -310,7 +314,7 @@ foreach ($files as $file) {
             substr_replace($file->getPathname(), OUT_DIR, 0, strlen(IN_DIR)),
             $code
         );
-    } catch (PHPParser_Error $e) {
+    } catch (PhpParser\Error $e) {
         echo 'Parse Error: ', $e->getMessage();
     }
 }
@@ -321,11 +325,12 @@ is convert `A\\B` style names to `A_B` style ones.
 
 ```php
 <?php
-class NodeVisitor_NamespaceConverter extends PHPParser_NodeVisitorAbstract
+use PhpParser\Node;
+class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
 {
-    public function leaveNode(PHPParser_Node $node) {
+    public function leaveNode(Node $node) {
-        if ($node instanceof PHPParser_Node_Name) {
+        if ($node instanceof Node\Name) {
-            return new PHPParser_Node_Name($node->toString('_'));
+            return new Node\Name($node->toString('_'));
         }
     }
 }
@@ -343,16 +348,18 @@ name:
 
 ```php
 <?php
-class NodeVisitor_NamespaceConverter extends PHPParser_NodeVisitorAbstract
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
 {
-    public function leaveNode(PHPParser_Node $node) {
+    public function leaveNode(Node $node) {
-        if ($node instanceof PHPParser_Node_Name) {
+        if ($node instanceof Node\Name) {
-            return new PHPParser_Node_Name($node->toString('_'));
+            return new Node\Name($node->toString('_'));
-        } elseif ($node instanceof PHPParser_Node_Stmt_Class
+        } elseif ($node instanceof Stmt\Class_
-                  || $node instanceof PHPParser_Node_Stmt_Interface
+                  || $node instanceof Stmt\Interface_
-                  || $node instanceof PHPParser_Node_Stmt_Function) {
+                  || $node instanceof Stmt\Function_) {
             $node->name = $node->namespacedName->toString('_');
-        } elseif ($node instanceof PHPParser_Node_Stmt_Const) {
+        } elseif ($node instanceof Stmt\Const_) {
             foreach ($node->consts as $const) {
                 $const->name = $const->namespacedName->toString('_');
             }
@@ -367,23 +374,25 @@ The last thing we need to do is remove the `namespace` and `use` statements:
 
 ```php
 <?php
-class NodeVisitor_NamespaceConverter extends PHPParser_NodeVisitorAbstract
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
 {
-    public function leaveNode(PHPParser_Node $node) {
+    public function leaveNode(Node $node) {
-        if ($node instanceof PHPParser_Node_Name) {
+        if ($node instanceof Node\Name) {
-            return new PHPParser_Node_Name($node->toString('_'));
+            return new Node\Name($node->toString('_'));
-        } elseif ($node instanceof PHPParser_Node_Stmt_Class
+        } elseif ($node instanceof Stmt\Class_
-                  || $node instanceof PHPParser_Node_Stmt_Interface
+                  || $node instanceof Stmt\Interface_
-                  || $node instanceof PHPParser_Node_Stmt_Function) {
+                  || $node instanceof Stmt\Function_) {
             $node->name = $node->namespacedName->toString('_');
-        } elseif ($node instanceof PHPParser_Node_Stmt_Const) {
+        } elseif ($node instanceof Stmt\Const_) {
             foreach ($node->consts as $const) {
                 $const->name = $const->namespacedName->toString('_');
             }
-        } elseif ($node instanceof PHPParser_Node_Stmt_Namespace) {
+        } elseif ($node instanceof Stmt\Namespace_) {
             // returning an array merges is into the parent array
             return $node->stmts;
-        } elseif ($node instanceof PHPParser_Node_Stmt_Use) {
+        } elseif ($node instanceof Stmt\Use_) {
             // returning false removed the node altogether
             return false;
         }

doc/3_Other_node_tree_representations.markdown

@@ -14,7 +14,7 @@ Human readable dumping
 ----------------------
 
 Furthermore it is possible to dump nodes into a human readable form using the `dump` method of
-`PHPParser_NodeDumper`. This can be used for debugging.
+`PhpParser\NodeDumper`. This can be used for debugging.
 
 ```php
 <?php
@@ -27,14 +27,14 @@ $code = <<<'CODE'
     printLine('Hallo World!!!');
 CODE;
 
-$parser     = new PHPParser_Parser(new PHPParser_Lexer);
+$parser     = new PhpParser\Parser(new PhpParser\Lexer);
-$nodeDumper = new PHPParser_NodeDumper;
+$nodeDumper = new PhpParser\NodeDumper;
 
 try {
     $stmts = $parser->parse($code);
 
     echo '<pre>' . htmlspecialchars($nodeDumper->dump($stmts)) . '</pre>';
-} catch (PHPParser_Error $e) {
+} catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```
@@ -89,8 +89,8 @@ array(
 Serialization to XML
 --------------------
 
-It is also possible to serialize the node tree to XML using `PHPParser_Serializer_XML->serialize()`
+It is also possible to serialize the node tree to XML using `PhpParser\Serializer\XML->serialize()`
-and to unserialize it using `PHPParser_Unserializer_XML->unserialize()`. This is useful for
+and to unserialize it using `PhpParser\Unserializer\XML->unserialize()`. This is useful for
 interfacing with other languages and applications or for doing transformation using XSLT.
 
 ```php
@@ -104,14 +104,14 @@ $code = <<<'CODE'
     printLine('Hallo World!!!');
 CODE;
 
-$parser     = new PHPParser_Parser(new PHPParser_Lexer);
+$parser     = new PhpParser\Parser(new PhpParser\Lexer);
-$serializer = new PHPParser_Serializer_XML;
+$serializer = new PhpParser\Serializer\XML;
 
 try {
     $stmts = $parser->parse($code);
 
     echo '<pre>' . htmlspecialchars($serializer->serialize($stmts)) . '</pre>';
-} catch (PHPParser_Error $e) {
+} catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```

doc/4_Code_generation.markdown

@@ -15,7 +15,7 @@ Here is an example:
 
 ```php
 <?php
-$factory = new PHPParser_BuilderFactory;
+$factory = new PhpParser\BuilderFactory;
 $node = $factory->class('SomeClass')
     ->extend('SomeOtherClass')
     ->implement('A\Few', 'Interfaces')
@@ -30,7 +30,7 @@ $node = $factory->class('SomeClass')
         ->makeProtected() // ->makePublic() [default], ->makePrivate()
         ->addParam($factory->param('someParam')->setDefault('test'))
         // it is possible to add manually created nodes
-        ->addStmt(new PHPParser_Node_Expr_Print(new PHPParser_Node_Expr_Variable('someParam')))
+        ->addStmt(new PhpParser\Node\Expr\Print_(new PhpParser\Node\Expr\Variable('someParam')))
     )
 
     // properties will be correctly reordered above the methods
@@ -104,7 +104,7 @@ Using this template we can easily create a class with multiple properties and th
 <?php
 
 // $templateString contains the above template
-$template = new PHPParser_Template($parser, $templateString);
+$template = new PhpParser\Template($parser, $templateString);
 
 // We only have to specify the __name__ placeholder, as the
 // capitalized __Name__ placeholder is automatically created
@@ -246,7 +246,7 @@ When using multiple templates it is easier to manage them on the filesystem. The
 <?php
 
 // We'll store our templates in ./templates and give them a .php suffix
-$loader = new PHPParser_TemplateLoader($parser, './templates', '.php');
+$loader = new PhpParser\TemplateLoader($parser, './templates', '.php');
 
 // loads ./templates/GetterSetter.php
 $getterSetterTemplate = $loader->load('GetterSetter');
@@ -255,7 +255,7 @@ $getterSetterTemplate = $loader->load('GetterSetter');
 $collectionTemplate = $loader->load('Collection');
 
 // The use of a suffix is optional. The following code for example is equivalent:
-$loader = new PHPParser_TemplateLoader($parser, './templates');
+$loader = new PhpParser\TemplateLoader($parser, './templates');
 
 // loads ./templates/GetterSetter.php
 $getterSetterTemplate = $loader->load('GetterSetter.php');

doc/component/Lexer.markdown

@@ -1,8 +1,8 @@
 Lexer component documentation
 =============================
 
-The lexer is responsible for providing tokens to the parser. The project comes with two lexers: `PHPParser_Lexer` and
+The lexer is responsible for providing tokens to the parser. The project comes with two lexers: `PhpParser\Lexer` and
-`PHPParser_Lexer_Emulative`. The latter is an extension of the former, which adds the ability to emulate tokens of
+`PhpParser\Lexer\Emulative`. The latter is an extension of the former, which adds the ability to emulate tokens of
 newer PHP versions and thus allows parsing of new code on older versions.
 
 A lexer has to define the following public interface:
@@ -22,7 +22,7 @@ Even though `startLexing` is meant to accept a source code string, you could for
 ```php
 <?php
 
-class FileLexer extends PHPParser_Lexer {
+class FileLexer extends PhpParser\Lexer {
     public function startLexing($fileName) {
         if (!file_exists($fileName)) {
             throw new InvalidArgumentException(sprintf('File "%s" does not exist', $fileName));
@@ -32,7 +32,7 @@ class FileLexer extends PHPParser_Lexer {
     }
 }
 
-$parser = new PHPParser_Parser(new FileLexer);
+$parser = new PhpParser\Parser(new FileLexer);
 
 var_dump($parser->parse('someFile.php'));
 var_dump($parser->parse('someOtherFile.php'));
@@ -63,7 +63,7 @@ overriding the method:
 ```php
 <?php
 
-class LessAttributesLexer extends PHPParser_Lexer {
+class LessAttributesLexer extends PhpParser\Lexer {
     public function getNextToken(&$value = null, &$startAttributes = null, &$endAttributes = null) {
         $tokenId = parent::getNextToken($value, $startAttributes, $endAttributes);
 
@@ -82,7 +82,7 @@ a `fileName` attribute to all nodes:
 ```php
 <?php
 
-class FileLexer extends PHPParser_Lexer {
+class FileLexer extends PhpParser\Lexer {
     protected $fileName;
 
     public function startLexing($fileName) {