[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * HTML API: WP_HTML_Active_Formatting_Elements class
   4   *
   5   * @package WordPress
   6   * @subpackage HTML-API
   7   * @since 6.4.0
   8   */
   9  
  10  /**
  11   * Core class used by the HTML processor during HTML parsing
  12   * for managing the stack of active formatting elements.
  13   *
  14   * This class is designed for internal use by the HTML processor.
  15   *
  16   * > Initially, the list of active formatting elements is empty.
  17   * > It is used to handle mis-nested formatting element tags.
  18   * >
  19   * > The list contains elements in the formatting category, and markers.
  20   * > The markers are inserted when entering applet, object, marquee,
  21   * > template, td, th, and caption elements, and are used to prevent
  22   * > formatting from "leaking" into applet, object, marquee, template,
  23   * > td, th, and caption elements.
  24   * >
  25   * > In addition, each element in the list of active formatting elements
  26   * > is associated with the token for which it was created, so that
  27   * > further elements can be created for that token if necessary.
  28   *
  29   * @since 6.4.0
  30   *
  31   * @access private
  32   *
  33   * @see https://html.spec.whatwg.org/#list-of-active-formatting-elements
  34   * @see WP_HTML_Processor
  35   */
  36  class WP_HTML_Active_Formatting_Elements {
  37      /**
  38       * Holds the stack of active formatting element references.
  39       *
  40       * @since 6.4.0
  41       *
  42       * @var WP_HTML_Token[]
  43       */
  44      private $stack = array();
  45  
  46      /**
  47       * Reports if a specific node is in the stack of active formatting elements.
  48       *
  49       * @since 6.4.0
  50       *
  51       * @param WP_HTML_Token $token Look for this node in the stack.
  52       * @return bool Whether the referenced node is in the stack of active formatting elements.
  53       */
  54  	public function contains_node( WP_HTML_Token $token ) {
  55          foreach ( $this->walk_up() as $item ) {
  56              if ( $token->bookmark_name === $item->bookmark_name ) {
  57                  return true;
  58              }
  59          }
  60  
  61          return false;
  62      }
  63  
  64      /**
  65       * Returns how many nodes are currently in the stack of active formatting elements.
  66       *
  67       * @since 6.4.0
  68       *
  69       * @return int How many node are in the stack of active formatting elements.
  70       */
  71  	public function count() {
  72          return count( $this->stack );
  73      }
  74  
  75      /**
  76       * Returns the node at the end of the stack of active formatting elements,
  77       * if one exists. If the stack is empty, returns null.
  78       *
  79       * @since 6.4.0
  80       *
  81       * @return WP_HTML_Token|null Last node in the stack of active formatting elements, if one exists, otherwise null.
  82       */
  83  	public function current_node() {
  84          $current_node = end( $this->stack );
  85  
  86          return $current_node ? $current_node : null;
  87      }
  88  
  89      /**
  90       * Inserts a "marker" at the end of the list of active formatting elements.
  91       *
  92       * > The markers are inserted when entering applet, object, marquee,
  93       * > template, td, th, and caption elements, and are used to prevent
  94       * > formatting from "leaking" into applet, object, marquee, template,
  95       * > td, th, and caption elements.
  96       *
  97       * @see https://html.spec.whatwg.org/#concept-parser-marker
  98       *
  99       * @since 6.7.0
 100       */
 101  	public function insert_marker(): void {
 102          $this->push( new WP_HTML_Token( null, 'marker', false ) );
 103      }
 104  
 105      /**
 106       * Pushes a node onto the stack of active formatting elements.
 107       *
 108       * @since 6.4.0
 109       *
 110       * @see https://html.spec.whatwg.org/#push-onto-the-list-of-active-formatting-elements
 111       *
 112       * @param WP_HTML_Token $token Push this node onto the stack.
 113       */
 114  	public function push( WP_HTML_Token $token ) {
 115          /*
 116           * > If there are already three elements in the list of active formatting elements after the last marker,
 117           * > if any, or anywhere in the list if there are no markers, that have the same tag name, namespace, and
 118           * > attributes as element, then remove the earliest such element from the list of active formatting
 119           * > elements. For these purposes, the attributes must be compared as they were when the elements were
 120           * > created by the parser; two elements have the same attributes if all their parsed attributes can be
 121           * > paired such that the two attributes in each pair have identical names, namespaces, and values
 122           * > (the order of the attributes does not matter).
 123           *
 124           * @todo Implement the "Noah's Ark clause" to only add up to three of any given kind of formatting elements to the stack.
 125           */
 126          // > Add element to the list of active formatting elements.
 127          $this->stack[] = $token;
 128      }
 129  
 130      /**
 131       * Removes a node from the stack of active formatting elements.
 132       *
 133       * @since 6.4.0
 134       *
 135       * @param WP_HTML_Token $token Remove this node from the stack, if it's there already.
 136       * @return bool Whether the node was found and removed from the stack of active formatting elements.
 137       */
 138  	public function remove_node( WP_HTML_Token $token ) {
 139          foreach ( $this->walk_up() as $position_from_end => $item ) {
 140              if ( $token->bookmark_name !== $item->bookmark_name ) {
 141                  continue;
 142              }
 143  
 144              $position_from_start = $this->count() - $position_from_end - 1;
 145              array_splice( $this->stack, $position_from_start, 1 );
 146              return true;
 147          }
 148  
 149          return false;
 150      }
 151  
 152      /**
 153       * Steps through the stack of active formatting elements, starting with the
 154       * top element (added first) and walking downwards to the one added last.
 155       *
 156       * This generator function is designed to be used inside a "foreach" loop.
 157       *
 158       * Example:
 159       *
 160       *     $html = '<em><strong><a>We are here';
 161       *     foreach ( $stack->walk_down() as $node ) {
 162       *         echo "{$node->node_name} -> ";
 163       *     }
 164       *     > EM -> STRONG -> A ->
 165       *
 166       * To start with the most-recently added element and walk towards the top,
 167       * see WP_HTML_Active_Formatting_Elements::walk_up().
 168       *
 169       * @since 6.4.0
 170       */
 171  	public function walk_down() {
 172          $count = count( $this->stack );
 173  
 174          for ( $i = 0; $i < $count; $i++ ) {
 175              yield $this->stack[ $i ];
 176          }
 177      }
 178  
 179      /**
 180       * Steps through the stack of active formatting elements, starting with the
 181       * bottom element (added last) and walking upwards to the one added first.
 182       *
 183       * This generator function is designed to be used inside a "foreach" loop.
 184       *
 185       * Example:
 186       *
 187       *     $html = '<em><strong><a>We are here';
 188       *     foreach ( $stack->walk_up() as $node ) {
 189       *         echo "{$node->node_name} -> ";
 190       *     }
 191       *     > A -> STRONG -> EM ->
 192       *
 193       * To start with the first added element and walk towards the bottom,
 194       * see WP_HTML_Active_Formatting_Elements::walk_down().
 195       *
 196       * @since 6.4.0
 197       */
 198  	public function walk_up() {
 199          for ( $i = count( $this->stack ) - 1; $i >= 0; $i-- ) {
 200              yield $this->stack[ $i ];
 201          }
 202      }
 203  
 204      /**
 205       * Clears the list of active formatting elements up to the last marker.
 206       *
 207       * > When the steps below require the UA to clear the list of active formatting elements up to
 208       * > the last marker, the UA must perform the following steps:
 209       * >
 210       * > 1. Let entry be the last (most recently added) entry in the list of active
 211       * >    formatting elements.
 212       * > 2. Remove entry from the list of active formatting elements.
 213       * > 3. If entry was a marker, then stop the algorithm at this point.
 214       * >    The list has been cleared up to the last marker.
 215       * > 4. Go to step 1.
 216       *
 217       * @see https://html.spec.whatwg.org/multipage/parsing.html#clear-the-list-of-active-formatting-elements-up-to-the-last-marker
 218       *
 219       * @since 6.7.0
 220       */
 221  	public function clear_up_to_last_marker(): void {
 222          foreach ( $this->walk_up() as $item ) {
 223              array_pop( $this->stack );
 224              if ( 'marker' === $item->node_name ) {
 225                  break;
 226              }
 227          }
 228      }
 229  }