HTML API: Add matches_breadcrumbs() to HTML Processor for better querying

[dmsnell]

Inside a next_tag() loop it can be challenging to use breadcrumbs because they are only exposed inside the call to next_tag() via the $query arg.

<?php
while ( $processor->next_tag( array( 'breadcrumbs' => array( 'figure', 'img' ) ) ) ) {
        …
}

In this patch a new method, matches_breadcrumbs() is exposed which allows for querying within the next_tag() loop for more complicated queries.

<?php
while ( $processor->next_tag() ) {
        if ($processor->matches_breadcrumbs( array( 'figure', 'img' ) ) ) {
                …
        }
}

This method exposes a wildcard * operator to allow matching any HTML tag that the currently-matched tag is a child or descendant of. It also exposes a ** operator to allow matching from zero to any number of non-specific tags in the stack of open elements between the current breadcrumb and the next.

<?php
while ( $processor->next_tag() ) {
        // Detect A descendants of NAV elements.
        if ( $processor->matches_breadcrumbs( array( 'nav', '**', a' ) ) ) {
                …
        }
}

Trac ticket: #59400

Inside a next_tag() loop it can be challenging to use breadcrumbs because they are only exposed inside the call to next_tag() via the $query arg.

In this patch a new method, matches_breadcrumbs() is exposed which allows for querying within the next_tag() loop for more complicated queries.

This method exposes a wildcard * operator to allow matching _any HTML tag_ that the currently-matched tag is a child or descendant of.

Trac ticket:

[dmsnell]

Probably I won't add the ** because it not only is much more complicated than * but it also opens up the opportunity for some gnarly performance cases, whereas I think it has to incorporate backtracking to make sure it works the way people expect.

Rebased.

[Bernhard Reiter]

In 56702:

HTML API: Add matches_breadcrumbs() method for better querying.

Inside a next_tag() loop it can be challenging to use breadcrumbs because they are only exposed inside the call to next_tag() via the $query arg.

In this patch a new method, matches_breadcrumbs(), is exposed which allows for querying within the next_tag() loop for more complicated queries.

This method exposes a wildcard * operator to allow matching any HTML tag that the currently-matched tag is a child or descendant of.

Props dmsnell, westonruter, mukesh27.
Fixes #59400.

Committed to Core in https://core.trac.wordpress.org/changeset/56702.