WIP: Add comment types

Author: dmsnell

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

@@ -327,7 +327,7 @@
  *      until the next `>` becomes a bogus HTML comment, meaning there can be no CDATA
  *      section in an HTML document containing `>`. The Tag Processor will first find
  *      all valid and bogus HTML comments, and then if the comment _would_ have been a
- *      CDATA section _were they to exist_, it will re-classify the bogus comment as such.
+ *      CDATA section _were they to exist_, it will indicate this as the type of comment.
  *
  * [2]: XML allows a broader range of characters in a processing instruction's target name
  *      and disallows "xml" as a name, since it's special. The Tag Processor only recognizes
@@ -494,7 +494,6 @@ class WP_HTML_Tag_Processor {
 	 * | *Matched tag*   | Found an HTML tag; it's possible to modify its attributes.           |
 	 * | *Text node*     | Found a #text node; this is plaintext and modifiable.                |
 	 * | *CDATA node*    | Found a CDATA section; this is modifiable.                           |
-	 * | *PI node*       | Found a Processing Instruction; this is modifiable.                  |
 	 * | *Comment*       | Found a comment or bogus comment; this is modifiable.                |
 	 * | *Presumptuous*  | Found an empty tag closer: `</>`.                                    |
 	 * | *Funky comment* | Found a tag closer with an invalid tag name; this is modifiable.     |
@@ -507,7 +506,6 @@ class WP_HTML_Tag_Processor {
 	 * @see WP_HTML_Tag_Processor::STATE_MATCHED_TAG
 	 * @see WP_HTML_Tag_Processor::STATE_TEXT_NODE
 	 * @see WP_HTML_Tag_Processor::STATE_CDATA_NODE
-	 * @see WP_HTML_Tag_Processor::STATE_PI_NODE
 	 * @see WP_HTML_Tag_Processor::STATE_COMMENT
 	 * @see WP_HTML_Tag_Processor::STATE_DOCTYPE
 	 * @see WP_HTML_Tag_Processor::STATE_PRESUMPTUOUS_TAG
@@ -517,6 +515,19 @@ class WP_HTML_Tag_Processor {
 	 */
 	protected $parser_state = self::STATE_READY;
 
+	/**
+	 * What kind of syntax token became an HTML comment.
+	 *
+	 * Since there are many ways in which HTML syntax can create an HTML comment,
+	 * this indicates which of those caused it. This allows the Tag Processor to
+	 * represent more from the original input document than would appear in the DOM.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @var string|null
+	 */
+	protected $comment_type = null;
+
 	/**
 	 * How many bytes from the original HTML document have been read and parsed.
 	 *
@@ -1602,10 +1613,12 @@ private function parse_next_tag() {
 						 *       involves inserting an additional `-` into the token after the modifiable text.
 						 */
 						$this->parser_state = self::STATE_COMMENT;
+						$this->comment_type = self::COMMENT_AS_ABRUPTLY_CLOSED_COMMENT;
 						$this->token_length = $closer_at + $span_of_dashes + 1 - $this->token_starts_at;
 
 						// Only provide modifiable text if the token is long enough to contain it.
 						if ( $span_of_dashes >= 2 ) {
+							$this->comment_type   = self::COMMENT_AS_HTML_COMMENT;
 							$this->text_starts_at = $this->token_starts_at + 4;
 							$this->text_length    = $span_of_dashes - 2;
 						}
@@ -1631,6 +1644,7 @@ private function parse_next_tag() {
 
 						if ( $closer_at + 2 < $doc_length && '>' === $html[ $closer_at + 2 ] ) {
 							$this->parser_state         = self::STATE_COMMENT;
+							$this->comment_type         = self::COMMENT_AS_HTML_COMMENT;
 							$this->token_length         = $closer_at + 3 - $this->token_starts_at;
 							$this->text_starts_at       = $this->token_starts_at + 4;
 							$this->text_length          = $closer_at - $this->text_starts_at;
@@ -1644,6 +1658,7 @@ private function parse_next_tag() {
 							'>' === $html[ $closer_at + 3 ]
 						) {
 							$this->parser_state         = self::STATE_COMMENT;
+							$this->comment_type         = self::COMMENT_AS_HTML_COMMENT;
 							$this->token_length         = $closer_at + 4 - $this->token_starts_at;
 							$this->text_starts_at       = $this->token_starts_at + 4;
 							$this->text_length          = $closer_at - $this->text_starts_at;
@@ -1696,6 +1711,7 @@ private function parse_next_tag() {
 				}
 
 				$this->parser_state         = self::STATE_COMMENT;
+				$this->comment_type         = self::COMMENT_AS_INVALID_HTML;
 				$this->token_length         = $closer_at + 1 - $this->token_starts_at;
 				$this->text_starts_at       = $this->token_starts_at + 2;
 				$this->text_length          = $closer_at - $this->text_starts_at;
@@ -1727,7 +1743,8 @@ private function parse_next_tag() {
 					'[' === $html[ $this->token_starts_at + 8 ] &&
 					']' === $html[ $closer_at - 1 ]
 				) {
-					$this->parser_state    = self::STATE_CDATA_NODE;
+					$this->parser_state    = self::STATE_COMMENT;
+					$this->comment_type    = self::COMMENT_AS_CDATA_LOOKALIKE;
 					$this->text_starts_at += 7;
 					$this->text_length    -= 9;
 				}
@@ -1764,6 +1781,7 @@ private function parse_next_tag() {
 				}
 
 				$this->parser_state         = self::STATE_COMMENT;
+				$this->comment_type         = self::COMMENT_AS_INVALID_HTML;
 				$this->token_length         = $closer_at + 1 - $this->token_starts_at;
 				$this->text_starts_at       = $this->token_starts_at + 2;
 				$this->text_length          = $closer_at - $this->text_starts_at;
@@ -1800,7 +1818,8 @@ private function parse_next_tag() {
 					if ( 0 < $pi_target_length ) {
 						$pi_target_length += strspn( $comment_text, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789:_-.', $pi_target_length );
 
-						$this->parser_state       = self::STATE_PI_NODE;
+						$this->parser_state       = self::STATE_COMMENT;
+						$this->comment_type       = self::COMMENT_AS_PI_NODE_LOOKALIKE;
 						$this->tag_name_starts_at = $this->token_starts_at + 2;
 						$this->tag_name_length    = $pi_target_length;
 						$this->text_starts_at    += $pi_target_length;
@@ -2003,6 +2022,7 @@ private function after_tag() {
 		$this->text_length          = 0;
 		$this->is_closing_tag       = null;
 		$this->attributes           = array();
+		$this->comment_type         = null;
 		$this->duplicate_attributes = null;
 	}
 
@@ -2621,9 +2641,6 @@ public function get_token_type() {
 			case self::STATE_DOCTYPE:
 				return '#doctype';
 
-			case self::STATE_PI_NODE:
-				return '#processing-instruction';
-
 			default:
 				return $this->get_token_name();
 		}
@@ -2661,9 +2678,6 @@ public function get_token_name() {
 			case self::STATE_CDATA_NODE:
 				return '#cdata-section';
 
-			case self::STATE_PI_NODE:
-				return substr( $this->html, $this->tag_name_starts_at, $this->tag_name_length );
-
 			case self::STATE_COMMENT:
 				return '#comment';
 
@@ -2678,6 +2692,27 @@ public function get_token_name() {
 		}
 	}
 
+	/**
+	 * Indicates what kind of comment produced the comment node.
+	 *
+	 * Because there are different kinds of HTML syntax which produce
+	 * comments, the Tag Processor tracks the source in order to expose
+	 * it to callers.
+	 *
+	 * @todo finish this comment!
+	 *
+	 * @since 6.5.0
+	 *
+	 * @return string|null
+	 */
+	public function get_comment_type() {
+		if ( self::STATE_COMMENT !== $this->parser_state ) {
+			return null;
+		}
+
+		return $this->comment_type;
+	}
+
 	/**
 	 * Returns the modifiable text for a matched token, or an empty string.
 	 *
@@ -2708,7 +2743,6 @@ public function get_modifiable_text() {
 			self::STATE_CDATA_NODE === $this->parser_state ||
 			self::STATE_COMMENT === $this->parser_state ||
 			self::STATE_DOCTYPE === $this->parser_state ||
-			self::STATE_PI_NODE === $this->parser_state ||
 			self::STATE_FUNKY_COMMENT === $this->parser_state
 		) {
 			return $text;
@@ -3290,32 +3324,14 @@ private function matches() {
 	 * Indicates that the parser has found a CDADA node and it's possible
 	 * to read and modify its modifiable text. Note that in HTML there are
 	 * no CDATA nodes outside foreign elements (SVG and MathML). Outside
-	 * of foreign elements, they are treated as HTML comments. Nonetheless,
-	 * the Tag Processor still recognizes them as they appear in the HTML
-	 * stream and exposes them for inspection and modification.
+	 * of foreign elements, they are treated as HTML comments.
 	 *
 	 * @since 6.5.0
 	 *
 	 * @access private
 	 */
 	const STATE_CDATA_NODE = 'STATE_CDATA_NODE';
 
-	/**
-	 * Parser Processing Instruction State.
-	 *
-	 * Indicates that the parser has found a Processing Instruction and
-	 * it's possible to read and modify its modifiable text. Note that in
-	 * HTML there are no Processing Instruction nodes and they are treated
-	 * as HTML comments. Nonetheless, the Tag Processor still recognizes
-	 * them as they appear in the HTML stream and exposes them for
-	 * inspection and modification.
-	 *
-	 * @since 6.5.0
-	 *
-	 * @access private
-	 */
-	const STATE_PI_NODE = 'STATE_PI_NODE';
-
 	/**
 	 * Indicates that the parser has found an HTML comment and it's
 	 * possible to read and modify its modifiable text.
@@ -3373,4 +3389,70 @@ private function matches() {
 	 * @access private
 	 */
 	const STATE_FUNKY_COMMENT = 'STATE_WP_FUNKY';
+
+	/**
+	 * Indicates that a comment was created when encountering abruptly-closed HTML comment.
+	 *
+	 * Example:
+	 *
+	 *     <!-->
+	 *     <!--->
+	 *     <!---->
+	 *
+	 * @since 6.5.0
+	 */
+	const COMMENT_AS_ABRUPTLY_CLOSED_COMMENT = 'COMMENT_AS_ABRUPTLY_CLOSED_COMMENT';
+
+	/**
+	 * Indicates that a comment would be parsed as a CDATA node,
+	 * were HTML to allow CDATA nodes outside of foreign elements.
+	 *
+	 * Example:
+	 *
+	 *     <![CDATA[This is a CDATA node.]]>
+	 *
+	 * This is an HTML comment, but it looks like a CDATA node.
+	 *
+	 * @since 6.5.0
+	 */
+	const COMMENT_AS_CDATA_LOOKALIKE = 'COMMENT_AS_CDATA_LOOKALIKE';
+
+	/**
+	 * Indicates that a comment was created when encountering
+	 * normative HTML comment syntax.
+	 *
+	 * Example:
+	 *
+	 *     <!-- this is a comment -->
+	 *
+	 * @since 6.5.0
+	 */
+	const COMMENT_AS_HTML_COMMENT = 'COMMENT_AS_HTML_COMMENT';
+
+	/**
+	 * Indicates that a comment would be parsed as a Processing
+	 * Instruction node, were they to exist within HTML.
+	 *
+	 * Example:
+	 *
+	 *     <?wp __( 'Like' ) ?>
+	 *
+	 * This is an HTML comment, but it looks like a CDATA node.
+	 *
+	 * @since 6.5.0
+	 */
+	const COMMENT_AS_PI_NODE_LOOKALIKE = 'COMMENT_AS_PI_NODE_LOOKALIKE';
+
+	/**
+	 * Indicates that a comment was created when encountering invalid
+	 * HTML input, a so-called "bogus comment."
+	 *
+	 * Example:
+	 *
+	 *     <?nothing special>
+	 *     <!{nothing special}>
+	 *
+	 * @since 6.5.0
+	 */
+	const COMMENT_AS_INVALID_HTML = 'COMMENT_AS_INVALID_HTML';
 }