danog/PHP-Parser
1
0
Fork 0
mirror of https://github.com/danog/PHP-Parser.git synced 2024-11-30 04:19:30 +01:00
Code Issues Projects Releases Wiki Activity

Proofreading the docs - very minor changes!

Browse Source
This commit is contained in:
Ryan Weaver 2018-02-28 10:40:30 -05:00 committed by Nikita Popov
parent 8d1e86b47f
commit de3470190c
6 changed files with 15 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/0_Introduction.markdown
View File

@ -14,7 +14,7 @@ There are other ways of processing source code. One that PHP supports natively i
token stream generated by [`token_get_all`][2]. The token stream is much more low level than token stream generated by [`token_get_all`][2]. The token stream is much more low level than
the AST and thus has different applications: It allows to also analyze the exact formatting of the AST and thus has different applications: It allows to also analyze the exact formatting of
a file. On the other hand the token stream is much harder to deal with for more complex analysis. a file. On the other hand the token stream is much harder to deal with for more complex analysis.
For example an AST abstracts away the fact that in PHP variables can be written as `$foo`, but also For example, an AST abstracts away the fact that, in PHP, variables can be written as `$foo`, but also
as `$$bar`, `${'foobar'}` or even `${!${''}=barfoo()}`. You don't have to worry about recognizing as `$$bar`, `${'foobar'}` or even `${!${''}=barfoo()}`. You don't have to worry about recognizing
all the different syntaxes from a stream of tokens. all the different syntaxes from a stream of tokens.
@ -36,7 +36,7 @@ hacky and not perfect, but it should work well on any sane code.
What output does it produce? What output does it produce?
---------------------------- ----------------------------
The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks like The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks
can best be seen in an example. The program `<?php echo 'Hi', 'World';` will give you a node tree can best be seen in an example. The program `<?php echo 'Hi', 'World';` will give you a node tree
roughly looking like this: roughly looking like this:

10
doc/2_Usage_of_basic_components.markdown
View File

@ -41,7 +41,7 @@ Kind | Behavior
`ParserFactory::ONLY_PHP7` | Parse code as PHP 7. `ParserFactory::ONLY_PHP7` | Parse code as PHP 7.
`ParserFactory::ONLY_PHP5` | Parse code as PHP 5. `ParserFactory::ONLY_PHP5` | Parse code as PHP 5.
Unless you have strong reason to use something else, `PREFER_PHP7` is a reasonable default. Unless you have a strong reason to use something else, `PREFER_PHP7` is a reasonable default.
The `create()` method optionally accepts a `Lexer` instance as the second argument. Some use cases The `create()` method optionally accepts a `Lexer` instance as the second argument. Some use cases
that require customized lexers are discussed in the [lexer documentation](component/Lexer.markdown). that require customized lexers are discussed in the [lexer documentation](component/Lexer.markdown).
@ -166,7 +166,7 @@ The additional `_` at the end of the first class name is necessary, because `Fun
reserved keyword. Many node class names in this library have a trailing `_` to avoid clashing with reserved keyword. Many node class names in this library have a trailing `_` to avoid clashing with
a keyword. a keyword.
As PHP is a large language there are approximately 140 different nodes. In order to make work As PHP is a large language there are approximately 140 different nodes. In order to make working
with them easier they are grouped into three categories: 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
@ -243,7 +243,7 @@ try {
The above code will output: The above code will output:
<?php echo 'Hello ', hi\getTarget(); echo 'Hello ', 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\Standard->prettyPrint()`. again converted to code using `PhpParser\PrettyPrinter\Standard->prettyPrint()`.
@ -351,7 +351,7 @@ class, which will define empty default implementations for all the above methods
The NameResolver node visitor The NameResolver node visitor
----------------------------- -----------------------------
One visitor is already bundled with the package: `PhpParser\NodeVisitor\NameResolver`. This visitor One visitor that is already bundled with the package is `PhpParser\NodeVisitor\NameResolver`. This visitor
helps you work with namespaced code by trying to resolve most names to fully qualified ones. helps you work with namespaced code by trying to resolve most names to fully qualified ones.
For example, consider the following code: For example, consider the following code:
@ -362,7 +362,7 @@ For example, consider the following code:
In order to know that `B\C` really is `A\C` you would need to track aliases and namespaces yourself. In order to know that `B\C` really is `A\C` you would need to track aliases and namespaces yourself.
The `NameResolver` takes care of that and resolves names as far as possible. The `NameResolver` takes care of that and resolves names as far as possible.
After running it most names will be fully qualified. The only names that will stay unqualified are After running it, most names will be fully qualified. The only names that will stay unqualified are
unqualified function and constant names. These are resolved at runtime and thus the visitor can't unqualified function and constant names. These are resolved at runtime and thus the visitor can't
know which function they are referring to. In most cases this is a non-issue as the global functions know which function they are referring to. In most cases this is a non-issue as the global functions
are meant. are meant.

2
doc/component/AST_builders.markdown
View File

@ -1,7 +1,7 @@
AST builders AST builders
============ ============
When PHP-Parser is used to generate (or modify) code, by first creating an Abstract Syntax Tree and 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 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 be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
the construction of common AST nodes. the construction of common AST nodes.

2
doc/component/Error_handling.markdown
View File

@ -27,7 +27,7 @@ try {
} }
``` ```
Before using column information its availability needs to be checked with `$e->hasColumnInfo()`, as the precise Before using column information, its availability needs to be checked with `$e->hasColumnInfo()`, as the precise
location of an error cannot always be determined. The methods for retrieving column information also have to be passed location of an error cannot always be determined. The methods for retrieving column information also have to be passed
the source code of the parsed file. An example for printing an error: the source code of the parsed file. An example for printing an error:

6
doc/component/Lexer.markdown
View File

@ -107,9 +107,9 @@ function handleHaltCompiler(): string;
function getNextToken(string &$value = null, array &$startAttributes = null, array &$endAttributes = null): int; function getNextToken(string &$value = null, array &$startAttributes = null, array &$endAttributes = null): int;
``` ```
The `startLexing()` method is invoked with the source code that is to be lexed (including the opening tag) whenever the The `startLexing()` method is invoked whenever the `parse()` method of the parser is called and is passed the source
`parse()` method of the parser is called. It can be used to reset state or preprocess the source code or tokens. The code that is to be lexed (including the opening tag). It can be used to reset state or preprocess the source code or tokens. The
passes `ErrorHandler` should be used to report lexing errors. passed `ErrorHandler` should be used to report lexing errors.
The `getTokens()` method returns the current token array, in the usual `token_get_all()` format. This method is not The `getTokens()` method returns the current token array, in the usual `token_get_all()` format. This method is not
used by the parser (which uses `getNextToken()`), but is useful in combination with the token position attributes. used by the parser (which uses `getNextToken()`), but is useful in combination with the token position attributes.

6
doc/component/Pretty_printing.markdown
View File

@ -52,8 +52,8 @@ For automated code refactoring, migration and similar, you will usually only wan
portion of the code and leave the remainder alone. The basic pretty printer is not suitable for portion of the code and leave the remainder alone. The basic pretty printer is not suitable for
this, because it will also reformat parts of the code which have not been modified. this, because it will also reformat parts of the code which have not been modified.
Since PHP-Parser 4.0 an experimental formatting-preserving pretty-printing mode is available, which Since PHP-Parser 4.0, an experimental formatting-preserving pretty-printing mode is available, which
attempts to preserve the formatting of code, those AST nodes have not changed, and only reformat attempts to preserve the formatting of code (those AST nodes that have not changed) and only reformat
code which has been modified or newly inserted. code which has been modified or newly inserted.
Use of the formatting-preservation functionality requires some additional preparatory steps: Use of the formatting-preservation functionality requires some additional preparatory steps:
@ -86,7 +86,7 @@ $newCode = $printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens);
``` ```
If you make use of the name resolution functionality, you will likely want to disable the If you make use of the name resolution functionality, you will likely want to disable the
`replaceNames` option. This will add resolved names as attributes, instead of directlying modifying `replaceNodes` option. This will add resolved names as attributes, instead of directlying modifying
the AST and causing spurious changes to the pretty printed code. For more information, see the the AST and causing spurious changes to the pretty printed code. For more information, see the
[name resolution documentation](Name_resolution.markdown). [name resolution documentation](Name_resolution.markdown).