Rename WP_Parser_Tree to WP_Parser_Node and document it

tests/bootstrap.php

@@ -5,7 +5,7 @@
 require_once __DIR__ . '/../wp-includes/mysql/class-wp-mysql-lexer.php';
 require_once __DIR__ . '/../wp-includes/parser/class-wp-parser-grammar.php';
 require_once __DIR__ . '/../wp-includes/parser/class-wp-parser.php';
-require_once __DIR__ . '/../wp-includes/parser/class-wp-parser-tree.php';
+require_once __DIR__ . '/../wp-includes/parser/class-wp-parser-node.php';
 require_once __DIR__ . '/../wp-includes/mysql/class-wp-mysql-parser.php';
 require_once __DIR__ . '/../wp-includes/sqlite/class-wp-sqlite-query-rewriter.php';
 require_once __DIR__ . '/../wp-includes/sqlite/class-wp-sqlite-lexer.php';

tests/tools/run-parser-benchmark.php

@@ -16,7 +16,7 @@ function ( $severity, $message, $file, $line ) {
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-token.php';
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-lexer.php';
 require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-grammar.php';
-require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-tree.php';
+require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-node.php';
 require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser.php';
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-parser.php';
 

tests/tools/run-parser-test.php

@@ -16,7 +16,7 @@ function ( $severity, $message, $file, $line ) {
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-lexer.php';
 require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser.php';
 require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-grammar.php';
-require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-tree.php';
+require_once __DIR__ . '/../../wp-includes/parser/class-wp-parser-node.php';
 require_once __DIR__ . '/../../wp-includes/mysql/class-wp-mysql-parser.php';
 
 $grammar_data = include __DIR__ . '/../../wp-includes/mysql/mysql-grammar.php';

wip/run-mysql-driver.php

@@ -150,7 +150,7 @@ private function translate_query( $parse_tree ) {
 			}
 		}
 
-		if ( ! ( $parse_tree instanceof WP_Parser_Tree ) ) {
+		if ( ! ( $parse_tree instanceof WP_Parser_Node ) ) {
 			throw new Exception( 'translateQuery only accepts MySQLToken and ParseTree instances' );
 		}
 

wp-includes/parser/class-wp-parser-tree.php → wp-includes/parser/class-wp-parser-node.php

@@ -1,6 +1,18 @@
 <?php
 
-class WP_Parser_Tree {
+/**
+ * A node in parse tree.
+ *
+ * This class represents a node in the parse tree that is produced by WP_Parser.
+ * A node corresponds to the related grammar rule that was matched by the parser.
+ * Each node can contain children, consisting of other nodes and grammar tokens.
+ * In this way, a parser node constitutes a recursive structure that represents
+ * a parse (sub)tree at each level of the full grammar tree.
+ */
+class WP_Parser_Node {
+	/**
+	 * @TODO: Review and document these properties and their visibility.
+	 */
 	public $rule_id;
 	public $rule_name;
 	public $children = array();
@@ -92,7 +104,7 @@ public function merge_fragment( $node ) {
 
 	public function has_child( $rule_name ) {
 		foreach ( $this->children as $child ) {
-			if ( ( $child instanceof WP_Parser_Tree && $child->rule_name === $rule_name ) ) {
+			if ( ( $child instanceof WP_Parser_Node && $child->rule_name === $rule_name ) ) {
 				return true;
 			}
 		}
@@ -125,7 +137,7 @@ public function get_token( $token_id = null ) {
 
 	public function get_child( $rule_name = null ) {
 		foreach ( $this->children as $child ) {
-			if ( $child instanceof WP_Parser_Tree && (
+			if ( $child instanceof WP_Parser_Node && (
 				$child->rule_name === $rule_name ||
 				null === $rule_name
 			) ) {
@@ -160,7 +172,7 @@ public function get_descendants( $rule_name ) {
 	public function get_children( $rule_name = null ) {
 		$matches = array();
 		foreach ( $this->children as $child ) {
-			if ( $child instanceof WP_Parser_Tree && (
+			if ( $child instanceof WP_Parser_Node && (
 				null === $rule_name ||
 				$child->rule_name === $rule_name
 			) ) {

wp-includes/parser/class-wp-parser.php

@@ -64,7 +64,7 @@ private function parse_recursive( $rule_id ) {
 		$starting_position = $this->position;
 		foreach ( $rule as $branch ) {
 			$this->position = $starting_position;
-			$node           = new WP_Parser_Tree( $rule_id, $rule_name );
+			$node           = new WP_Parser_Node( $rule_id, $rule_name );
 			$branch_matches = true;
 			foreach ( $branch as $subrule_id ) {
 				$subnode = $this->parse_recursive( $subrule_id );