Rename WP_Parser_Tree to WP_Parser_Node and document it

Author: JanJakes

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 renamed to 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();
@@ -20,7 +32,7 @@ public function append_child( $node ) {
 	 *
 	 * What are rule fragments?
 	 *
-	 * When we initially parse the BNF grammar file, it has compound rules such
+	 * When we initially parse the grammar file, it has compound rules such
 	 * as this one:
 	 *
 	 *      query ::= EOF | ((simpleStatement | beginWork) ((SEMICOLON_SYMBOL EOF?) | EOF))
@@ -35,7 +47,7 @@ public function append_child( $node ) {
 	 *      %%query02 ::= SEMICOLON_SYMBOL EOF_zero_or_one | EOF
 	 *      EOF_zero_or_one ::= EOF | ε
 	 *
-	 * This factorization happens in 1-ebnf-to-json.js.
+	 * This factorization happens in "convert-grammar.php".
 	 *
 	 * "Fragments" are intermediate artifacts whose names are not in the original grammar.
 	 * They are extremely useful for the parser, but the API consumer should never have to
@@ -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 );