Changeset 58970 for trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

Timestamp:

09/02/2024 11:19:08 PM (17 months ago)

Author:

dmsnell

Message:

HTML API: Allow subdividing text nodes by meaningful prefixes.

HTML parsing rules at times differentiate character tokens that are all null bytes, all whitespace, or other content. This patch introduces a new function which may be used to classify text node sub-regions and lead to more efficient application of these parsing rules.

Further, when classified in this way, application code may skip some rules and decoding entirely, improving performance. For example, this can be used to ease the implementation of skipping inter-element whitespace, which is usually not rendered.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/7236
Discussed in https://core.trac.wordpress.org/ticket/61974

Props dmsnell, jonsurrell.
Fixes #61974.

File:

• trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php (modified) (4 diffs)

trunk/src/wp-includes/html-api/class-wp-html-tag-processor.php

@@ -541 +541 @@
      */
     protected $comment_type = null;
+
+    /**
+     * What kind of text the matched text node represents, if it was subdivided.
+     *
+     * @see self::TEXT_IS_NULL_SEQUENCE
+     * @see self::TEXT_IS_WHITESPACE
+     * @see self::TEXT_IS_GENERIC
+     * @see self::subdivide_text_appropriately
+     *
+     * @since 6.7.0
+     *
+     * @var string
+     */
+    protected $text_node_classification = self::TEXT_IS_GENERIC;
 
     /**
@@ -2200 +2214 @@
         }
 
-        $this->token_starts_at      = null;
-        $this->token_length         = null;
-        $this->tag_name_starts_at   = null;
-        $this->tag_name_length      = null;
-        $this->text_starts_at       = 0;
-        $this->text_length          = 0;
-        $this->is_closing_tag       = null;
-        $this->attributes           = array();
-        $this->comment_type         = null;
-        $this->duplicate_attributes = null;
+        $this->token_starts_at          = null;
+        $this->token_length             = null;
+        $this->tag_name_starts_at       = null;
+        $this->tag_name_length          = null;
+        $this->text_starts_at           = 0;
+        $this->text_length              = 0;
+        $this->is_closing_tag           = null;
+        $this->attributes               = array();
+        $this->comment_type             = null;
+        $this->text_node_classification = self::TEXT_IS_GENERIC;
+        $this->duplicate_attributes     = null;
     }
 
@@ -3320 +3335 @@
 
         return $this->comment_type;
+    }
+
+    /**
+     * Subdivides a matched text node or CDATA text node, splitting NULL byte sequences
+     * and decoded whitespace as distinct prefixes.
+     *
+     * Note that once anything that's neither a NULL byte nor decoded whitespace is
+     * encountered, then the remainder of the text node is left intact as generic text.
+     *
+     *  - The HTML Processor uses this to apply distinct rules for different kinds of text.
+     *  - Inter-element whitespace can be detected and skipped with this method.
+     *
+     * Text nodes aren't eagerly subdivided because there's no need to split them unless
+     * decisions are being made on NULL byte sequences or whitespace-only text.
+     *
+     * Example:
+     *
+     *     $processor = new WP_HTML_Tag_Processor( "\x00Apples & Oranges" );
+     *     true  === $processor->next_token();                   // Text is "Apples & Oranges".
+     *     true  === $processor->subdivide_text_appropriately(); // Text is "".
+     *     true  === $processor->next_token();                   // Text is "Apples & Oranges".
+     *     false === $processor->subdivide_text_appropriately();
+     *
+     *     $processor = new WP_HTML_Tag_Processor( " \r\n\tMore" );
+     *     true  === $processor->next_token();                   // Text is "␤ ␤␉More".
+     *     true  === $processor->subdivide_text_appropriately(); // Text is "␤ ␤␉".
+     *     true  === $processor->next_token();                   // Text is "More".
+     *     false === $processor->subdivide_text_appropriately();
+     *
+     * @since 6.7.0
+     *
+     * @return bool Whether the text node was subdivided.
+     */
+    public function subdivide_text_appropriately(): bool {
+        $this->text_node_classification = self::TEXT_IS_GENERIC;
+
+        if ( self::STATE_TEXT_NODE === $this->parser_state ) {
+            /*
+             * NULL bytes are treated categorically different than numeric character
+             * references whose number is zero. `�` is not the same as `"\x00"`.
+             */
+            $leading_nulls = strspn( $this->html, "\x00", $this->text_starts_at, $this->text_length );
+            if ( $leading_nulls > 0 ) {
+                $this->token_length             = $leading_nulls;
+                $this->text_length              = $leading_nulls;
+                $this->bytes_already_parsed     = $this->token_starts_at + $leading_nulls;
+                $this->text_node_classification = self::TEXT_IS_NULL_SEQUENCE;
+                return true;
+            }
+
+            /*
+             * Start a decoding loop to determine the point at which the
+             * text subdivides. This entails raw whitespace bytes and any
+             * character reference that decodes to the same.
+             */
+            $at  = $this->text_starts_at;
+            $end = $this->text_starts_at + $this->text_length;
+            while ( $at < $end ) {
+                $skipped = strspn( $this->html, " \t\f\r\n", $at, $end - $at );
+                $at     += $skipped;
+
+                if ( $at < $end && '&' === $this->html[ $at ] ) {
+                    $matched_byte_length = null;
+                    $replacement         = WP_HTML_Decoder::read_character_reference( 'data', $this->html, $at, $matched_byte_length );
+                    if ( isset( $replacement ) && 1 === strspn( $replacement, " \t\f\r\n" ) ) {
+                        $at += $matched_byte_length;
+                        continue;
+                    }
+                }
+
+                break;
+            }
+
+            if ( $at > $this->text_starts_at ) {
+                $new_length                     = $at - $this->text_starts_at;
+                $this->text_length              = $new_length;
+                $this->token_length             = $new_length;
+                $this->bytes_already_parsed     = $at;
+                $this->text_node_classification = self::TEXT_IS_WHITESPACE;
+                return true;
+            }
+
+            return false;
+        }
+
+        // Unlike text nodes, there are no character references within CDATA sections.
+        if ( self::STATE_CDATA_NODE === $this->parser_state ) {
+            $leading_nulls = strspn( $this->html, "\x00", $this->text_starts_at, $this->text_length );
+            if ( $leading_nulls === $this->text_length ) {
+                $this->text_node_classification = self::TEXT_IS_NULL_SEQUENCE;
+                return true;
+            }
+
+            $leading_ws = strspn( $this->html, " \t\f\r\n", $this->text_starts_at, $this->text_length );
+            if ( $leading_ws === $this->text_length ) {
+                $this->text_node_classification = self::TEXT_IS_WHITESPACE;
+                return true;
+            }
+        }
+
+        return false;
     }
 
@@ -4249 +4365 @@
      */
     const COMMENT_AS_INVALID_HTML = 'COMMENT_AS_INVALID_HTML';
+
+    /**
+     * Indicates that a span of text may contain any combination of significant
+     * kinds of characters: NULL bytes, whitespace, and others.
+     *
+     * @see self::$text_node_classification
+     * @see self::subdivide_text_appropriately
+     *
+     * @since 6.7.0
+     */
+    const TEXT_IS_GENERIC = 'TEXT_IS_GENERIC';
+
+    /**
+     * Indicates that a span of text comprises a sequence only of NULL bytes.
+     *
+     * @see self::$text_node_classification
+     * @see self::subdivide_text_appropriately
+     *
+     * @since 6.7.0
+     */
+    const TEXT_IS_NULL_SEQUENCE = 'TEXT_IS_NULL_SEQUENCE';
+
+    /**
+     * Indicates that a span of decoded text comprises only whitespace.
+     *
+     * @see self::$text_node_classification
+     * @see self::subdivide_text_appropriately
+     *
+     * @since 6.7.0
+     */
+    const TEXT_IS_WHITESPACE = 'TEXT_IS_WHITESPACE';
 }