From 14a6d2b15abe169e945e1cfaa2b8a2da3c805026 Mon Sep 17 00:00:00 2001
From: nikic <+@ni-po.com>
Date: Tue, 31 May 2011 18:01:00 +0200
Subject: [PATCH] Rewrite README

---
 README    |  23 ---------
 README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 test.php  |  23 ---------
 3 files changed, 149 insertions(+), 46 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md
 delete mode 100644 test.php

diff --git a/README b/README
deleted file mode 100644
index 47d2c9f..0000000
--- a/README
+++ /dev/null
@@ -1,23 +0,0 @@
-This is a PHP parser written in PHP.
-
-This project is work in progress, but it basically works and was tested on a large code base.
-
-Usage:
-
-    $parser = new Parser();
-    $stmts = $parser->yyparse(
-        new Lexer('<?php // some code'),
-        function($msg) {
-            // this is the error callback, which is fired in case of
-            // a parse error. It is passed the error message.
-            echo $msg, "\n";
-        }
-    );
-
-    // the return value of Parser->yyparse will either be false (which
-    // signifies that an error occured) or an array of statements (Nodes)
-    if (false !== $stmts) {
-        // dump nodes
-        $nodeDumper = new NodeDumper();
-        echo $nodeDumper->dump($stmts);
-    }
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1cee738
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+PHP Parser
+==========
+
+This is a PHP parser written in PHP. It's purpose is to simplify static code analysis and
+manipulation.
+
+***Note: This project is work in progress. It is known to not function perfectly correct yet.***
+
+Components
+==========
+
+This package currently bundles several components:
+
+    * The `Parser` itself
+    * A `NodeDumper` to dump the nodes to a human readable string representation
+    * A `PrettyPrinter` to translate the node tree back to PHP
+
+Parser and ParserDebug
+----------------------
+
+Parsing is performed using `Parser->parse()`. This method accepts a `Lexer` as the first parameter
+and a error callback, i.e. a function that will be passed a message in case of an error, as
+second parameter. The parser returns an array of statement nodes. If an error occurs the parser
+instead returns `false` and sends an error message to the error callback.
+
+    $code = '<?php // some code';
+
+    $parser = new Parser;
+    $stmts = $parser->parse(
+        new Lexer($code),
+        function ($msg) {
+            echo $msg;
+        }
+    );
+
+The `ParserDebug` class also parses a PHP code, but outputs a debug trace while doing so.
+
+Node Tree
+---------
+
+The output of the parser is an array of statement nodes. All nodes are instances of `NodeAbstract`.
+Furthermore nodes are divided into three categories:
+
+    * `Node_Stmt`: A statement
+    * `Node_Expr`: An expression
+    * `Node_Scalar`: A scalar (which is a string, a number, aso.)
+      `Node_Scalar` inherits from `Node_Expr`.
+
+Each node may have subnodes. For example `Node_Expr_Plus` has two subnodes, namely `left` and
+`right`, which represend the left hand side and right hand side expressions of the plus operation.
+Subnodes are accessed as normal properties:
+
+    $node->left
+
+The subnodes which a certain node can have are documented as `@property` doccomments in the
+respective files.
+
+NodeDumper
+----------
+
+Nodes can be dumped into a string representation using the `NodeDumper->dump` method:
+
+    $code = <<<'CODE'
+<?php
+    function printLine($msg) {
+        echo $msg, "\n";
+    }
+
+    printLine('Hallo World!!!');
+CODE;
+
+    $parser = new Parser;
+    $stmts = $parser->parse(
+        new Lexer($code),
+        function ($msg) {
+            echo $msg;
+        }
+    );
+
+    if (false !== $stmts) {
+        $nodeDumper = new NodeDumper;
+        echo '<pre>' . htmlspecialchars($nodeDumper->dump($stmts)) . '</pre>';
+    }
+
+This script will have an output similar to the following:
+
+    array(
+        0: Stmt_Func(
+            byRef: false
+            name: printLine
+            params: array(
+                0: Stmt_FuncParam(
+                    type: null
+                    name: msg
+                    byRef: false
+                    default: null
+                )
+            )
+            stmts: array(
+                0: Stmt_Echo(
+                    exprs: array(
+                        0: Variable(
+                            name: msg
+                        )
+                        1: Scalar_String(
+                            value:
+
+                            isBinary: false
+                            type: 1
+                        )
+                    )
+                )
+            )
+        )
+        1: Expr_FuncCall(
+            func: Name(
+                parts: array(
+                    0: printLine
+                )
+            )
+            args: array(
+                0: Expr_FuncCallArg(
+                    value: Scalar_String(
+                        value: Hallo World!!!
+                        isBinary: false
+                        type: 0
+                    )
+                    byRef: false
+                )
+            )
+        )
+    )
+
+PrettyPrinter
+-------------
+
+The pretty printer compiles nodes back to PHP code. "Pretty printing" here is just the formal
+name of the process and does not mean that the output is in any way pretty.
+
+    $prettyPrinter = new PrettyPrinter_Zend;
+    echo '<pre>' . htmlspecialchars($prettyPrinter->pStmts($stmts)) . '</pre>';
+
+For the code mentioned in the above section this should create the output:
+
+    function printLine($msg)
+    {
+        echo $msg, "\n";
+    }
+    printLine('Hallo World!!!');
\ No newline at end of file
diff --git a/test.php b/test.php
deleted file mode 100644
index d868d1c..0000000
--- a/test.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php
-
-function __autoload($class) {
-    is_file($file = './lib/' . strtr($class, '_', '/') . '.php') && require_once $file;
-}
-
-echo '<pre>';
-
-$parser        = new Parser;
-$prettyPrinter = new PrettyPrinter_Zend;
-
-$code = $prettyPrinter->pStmts(
-    $parser->parse(
-        new Lexer(file_get_contents(
-            '../symfonySandbox\src\vendor\symfony\src\Symfony\Components\Console\Input\InputDefinition.php'
-        )),
-        function ($msg) {
-            echo $msg;
-        }
-    )
-);
-
-echo htmlspecialchars($code);
\ No newline at end of file