1<?php
  2/**
  3 * HTML API: WP_HTML_Unsupported_Exception 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 indicating that a given operation is unsupported.
 13 *
 14 * This class is designed for internal use by the HTML processor.
 15 *
 16 * The HTML API aims to operate in compliance with the HTML5
 17 * specification, but does not implement the full specification.
 18 * In cases where it lacks support it should not cause breakage
 19 * or unexpected behavior. In the cases where it recognizes that
 20 * it cannot proceed, this class is used to abort from any
 21 * operation and signify that the given HTML cannot be processed.
 22 *
 23 * @since 6.4.0
 24 * @since 6.7.0 Gained contextual information for use in debugging parse failures.
 25 *
 26 * @access private
 27 *
 28 * @see WP_HTML_Processor
 29 */
 30class WP_HTML_Unsupported_Exception extends Exception {
 31	/**
 32	 * Name of the matched token when the exception was raised,
 33	 * if matched on a token.
 34	 *
 35	 * This does not imply that the token itself was unsupported, but it
 36	 * may have been the case that the token triggered part of the HTML
 37	 * parsing that isn't supported, such as the adoption agency algorithm.
 38	 *
 39	 * @since 6.7.0
 40	 *
 41	 * @var string
 42	 */
 43	public $token_name;
 44
 45	/**
 46	 * Number of bytes into the input HTML document where the parser was
 47	 * parsing when the exception was raised.
 48	 *
 49	 * Use this to reconstruct context for the failure.
 50	 *
 51	 * @since 6.7.0
 52	 *
 53	 * @var int
 54	 */
 55	public $token_at;
 56
 57	/**
 58	 * Full raw text of the matched token when the exception was raised,
 59	 * if matched on a token.
 60	 *
 61	 * Whereas the `$token_name` will be normalized, this contains the full
 62	 * raw text of the token, including original casing, duplicated attributes,
 63	 * and other syntactic variations that are normally abstracted in the HTML API.
 64	 *
 65	 * @since 6.7.0
 66	 *
 67	 * @var string
 68	 */
 69	public $token;
 70
 71	/**
 72	 * Stack of open elements when the exception was raised.
 73	 *
 74	 * Use this to trace the parsing circumstances which led to the exception.
 75	 *
 76	 * @since 6.7.0
 77	 *
 78	 * @var string[]
 79	 */
 80	public $stack_of_open_elements = array();
 81
 82	/**
 83	 * List of active formatting elements when the exception was raised.
 84	 *
 85	 * Use this to trace the parsing circumstances which led to the exception.
 86	 *
 87	 * @since 6.7.0
 88	 *
 89	 * @var string[]
 90	 */
 91	public $active_formatting_elements = array();
 92
 93	/**
 94	 * Constructor function.
 95	 *
 96	 * @since 6.7.0
 97	 *
 98	 * @param string   $message                    Brief message explaining what is unsupported, the reason this exception was raised.
 99	 * @param string   $token_name                 Normalized name of matched token when this exception was raised.
100	 * @param int      $token_at                   Number of bytes into source HTML document where matched token starts.
101	 * @param string   $token                      Full raw text of matched token when this exception was raised.
102	 * @param string[] $stack_of_open_elements     Stack of open elements when this exception was raised.
103	 * @param string[] $active_formatting_elements List of active formatting elements when this exception was raised.
104	 */
105	public function __construct( string $message, string $token_name, int $token_at, string $token, array $stack_of_open_elements, array $active_formatting_elements ) {
106		parent::__construct( $message );
107
108		$this->token_name = $token_name;
109		$this->token_at   = $token_at;
110		$this->token      = $token;
111
112		$this->stack_of_open_elements     = $stack_of_open_elements;
113		$this->active_formatting_elements = $active_formatting_elements;
114	}
115}
116