mirror of
https://github.com/phabelio/PHP-Parser.git
synced 2024-11-26 20:14:46 +01:00
Proofreading the docs - very minor changes!
This commit is contained in:
parent
8d1e86b47f
commit
de3470190c
@ -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
|
||||
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.
|
||||
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
|
||||
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?
|
||||
----------------------------
|
||||
|
||||
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
|
||||
roughly looking like this:
|
||||
|
||||
|
@ -41,7 +41,7 @@ Kind | Behavior
|
||||
`ParserFactory::ONLY_PHP7` | Parse code as PHP 7.
|
||||
`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
|
||||
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
|
||||
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:
|
||||
|
||||
* `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:
|
||||
|
||||
<?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
|
||||
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
|
||||
-----------------------------
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
know which function they are referring to. In most cases this is a non-issue as the global functions
|
||||
are meant.
|
||||
|
@ -1,7 +1,7 @@
|
||||
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
|
||||
be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
|
||||
the construction of common AST nodes.
|
||||
|
@ -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
|
||||
the source code of the parsed file. An example for printing an error:
|
||||
|
||||
|
@ -107,9 +107,9 @@ function handleHaltCompiler(): string;
|
||||
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
|
||||
`parse()` method of the parser is called. It can be used to reset state or preprocess the source code or tokens. The
|
||||
passes `ErrorHandler` should be used to report lexing errors.
|
||||
The `startLexing()` method is invoked whenever the `parse()` method of the parser is called and is passed the source
|
||||
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
|
||||
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
|
||||
used by the parser (which uses `getNextToken()`), but is useful in combination with the token position attributes.
|
||||
|
@ -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
|
||||
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
|
||||
attempts to preserve the formatting of code, those AST nodes have not changed, and only reformat
|
||||
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 that have not changed) and only reformat
|
||||
code which has been modified or newly inserted.
|
||||
|
||||
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
|
||||
`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
|
||||
[name resolution documentation](Name_resolution.markdown).
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user