Move multi-query parsing to WP_MySQL_Parser, improve naming and docs

Author: JanJakes

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

@@ -1,4 +1,55 @@
 <?php
 
 class WP_MySQL_Parser extends WP_Parser {
+	/**
+	 * The current query AST.
+	 *
+	 * @var WP_Parser_Node|null
+	 */
+	private $current_ast;
+
+	/**
+	 * Parse the next query from the input SQL string.
+	 *
+	 * This method reads tokens until a query is parsed, or the parsing fails.
+	 * It returns a boolean indicating whether a query was successfully parsed.
+	 *
+	 * Example:
+	 *
+	 *     // Parse all queries in the input SQL string.
+	 *     $parser = new WP_MySQL_Parser( $sql );
+	 *     while ( $parser->next_query() ) {
+	 *         $ast = $parser->get_query_ast();
+	 *         if ( ! $ast ) {
+	 *             // The parsing failed.
+	 *         }
+	 *         // The query was successfully parsed.
+	 *     }
+	 *
+	 * @return bool Whether a query was successfully parsed.
+	 */
+	public function next_query(): bool {
+		if ( $this->position >= count( $this->tokens ) ) {
+			return false;
+		}
+		$this->current_ast = $this->parse();
+		if ( ! $this->current_ast ) {
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Get the current query AST.
+	 *
+	 * When no query has been parsed yet, the parsing failed, or the end of the
+	 * input was reached, this method returns null.
+	 *
+	 * @see WP_MySQL_Parser::next_query() for usage example.
+	 *
+	 * @return WP_Parser_Node|null The current query AST, or null if no query was parsed.
+	 */
+	public function get_query_ast(): ?WP_Parser_Node {
+		return $this->current_ast;
+	}
 }

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

@@ -264,7 +264,7 @@ public function get_descendant_tokens( ?int $token_id = null ): array {
 	}
 
 	/**
-	 * Get the byte offset in the input where the node begins.
+	 * Get the byte offset in the input SQL string where this node begins.
 	 *
 	 * @return int
 	 */
@@ -273,7 +273,7 @@ public function get_start(): int {
 	}
 
 	/**
-	 * Get the byte length of the node in the input.
+	 * Get the byte length of this node in the input SQL string.
 	 *
 	 * @return int
 	 */

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

@@ -9,16 +9,9 @@
  *        satisfy in order to be supported by this parser (e.g., no left recursion).
  */
 class WP_Parser {
-	private $grammar;
-	private $tokens;
-	private $position;
-
-	/**
-	 * The current AST.
-	 *
-	 * @var WP_Parser_Node|null
-	 */
-	private $current_ast;
+	protected $grammar;
+	protected $tokens;
+	protected $position;
 
 	public function __construct( WP_Parser_Grammar $grammar, array $tokens ) {
 		$this->grammar  = $grammar;
@@ -33,37 +26,6 @@ public function parse() {
 		return false === $ast ? null : $ast;
 	}
 
-	/**
-	 * Parse the next AST from the input tokens.
-	 *
-	 * This method reads tokens from the input until an AST is successfully parsed.
-	 * It starts from "$this->tokens[ $this->position ]", advances the number of
-	 * tokens read, and returns a boolean indicating whether an AST was successfully
-	 * parsed. When the end of the input is reached or a query could not be parsed,
-	 * the method returns false.
-	 *
-	 * @return bool Whether an AST was successfully parsed.
-	 */
-	public function next_ast(): bool {
-		if ( $this->position >= count( $this->tokens ) ) {
-			return false;
-		}
-		$this->current_ast = $this->parse();
-		return true;
-	}
-
-	/**
-	 * Get the current AST.
-	 *
-	 * When no AST has been parsed yet, the parsing failed, or the end of the
-	 * input was reached, this method returns null.
-	 *
-	 * @return WP_Parser_Node|null The current AST, or null if no AST was parsed.
-	 */
-	public function get_ast(): ?WP_Parser_Node {
-		return $this->current_ast;
-	}
-
 	private function parse_recursive( $rule_id ) {
 		$is_terminal = $rule_id <= $this->grammar->highest_terminal_id;
 		if ( $is_terminal ) {

wp-includes/sqlite-ast/class-wp-sqlite-driver.php

@@ -739,8 +739,8 @@ public function parse_query( string $query ): Generator {
 		$tokens = $lexer->remaining_tokens();
 
 		$parser = new WP_MySQL_Parser( self::$mysql_grammar, $tokens );
-		while ( $parser->next_ast() ) {
-			$ast = $parser->get_ast();
+		while ( $parser->next_query() ) {
+			$ast = $parser->get_query_ast();
 			if ( null === $ast ) {
 				throw $this->new_driver_exception( 'Failed to parse the MySQL query.' );
 			}