Merge branch 'html-api/add-select-api' into html-api/work-on-select-api

Author: sirreal

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

@@ -635,6 +635,44 @@ public function get_unsupported_exception() {
 		return $this->unsupported_exception;
 	}
 
+	/**
+	 * Use a selector to advance.
+	 *
+	 * @param string $selectors
+	 * @return Generator<void>|null
+	 */
+	public function select_all( string $selectors ): ?Generator {
+		$select = WP_CSS_Selector_List::from_selectors( $selectors );
+		if ( null === $select ) {
+			return null;
+		}
+
+		while ( $this->next_tag() ) {
+			if ( $select->matches( $this ) ) {
+				yield;
+			}
+		}
+	}
+
+	/**
+	 * Select the next matching element.
+	 *
+	 * If iterating through matching elements, use `select_all` instead.
+	 *
+	 * @param string $selectors
+	 * @return bool|null
+	 */
+	public function select( string $selectors ) {
+		$selection = $this->select_all( $selectors );
+		if ( null === $selection ) {
+			return null;
+		}
+		foreach ( $selection as $_ ) {
+			return true;
+		}
+		return false;
+	}
+
 	/**
 	 * Finds the next tag matching the $query.
 	 *