vendor/wikimedia/remex-html/RemexHtml/TreeBuilder/TreeHandler.php

   1 <?php
   2
   3 namespace RemexHtml\TreeBuilder;
   4 use RemexHtml\Tokenizer\Attributes;
   5
   6 interface TreeHandler {
   7         /**
   8          * Called when parsing starts.
   9          *
  10          * @param string|null $fragmentNamespace The fragment namespace, or null
  11          *   to run in document mode.
  12          * @param string|null $fragmentName The fragment tag name, or null to run
  13          *   in document mode.
  14          */
  15         function startDocument( $fragmentNamespace, $fragmentName );
  16
  17         /**
  18          * Called when parsing stops.
  19          *
  20          * @param integer $pos The input string length, i.e. the past-the-end position.
  21          */
  22         function endDocument( $pos );
  23
  24         /**
  25          * Insert characters.
  26          *
  27          * @param integer $preposition The placement of the new node with respect
  28          *   to $ref. May be TreeBuilder::
  29          *    - BEFORE: insert as a sibling before the reference element
  30          *    - UNDER: append as the last child of the reference element
  31          *    - ROOT: append as the last child of the document node
  32          * @param Element|null $ref Insert before/below this element, or null if
  33          *   $preposition is ROOT.
  34          * @param string $text The text to insert is a substring of this string,
  35          *   with the start and length of the substring given by $start and
  36          *   $length. We do it this way to avoid unnecessary copying.
  37          * @param integer $start The start of the substring
  38          * @param integer $length The length of the substring
  39          * @param integer $sourceStart The input position. This is not necessarily
  40          *   accurate, particularly when the tokenizer is run without ignoreEntities,
  41          *   or in CDATA sections.
  42          * @param integer $sourceLength The length of the input which is consumed.
  43          *   The same caveats apply as for $sourceStart.
  44          */
  45         function characters( $preposition, $ref, $text, $start, $length, $sourceStart, $sourceLength );
  46
  47         /**
  48          * Insert an element. The element name and attributes are given in the
  49          * supplied Element object. Handlers for this event typically attach an
  50          * identifier to the userData property of the Element object, to identify
  51          * the element when it is used again in subsequent tree mutations.
  52          *
  53          * @param integer $preposition The placement of the new node with respect
  54          *   to $ref. May be TreeBuilder::
  55          *    - BEFORE: insert as a sibling before the reference element
  56          *    - UNDER: append as the last child of the reference element
  57          *    - ROOT: append as the last child of the document node
  58          * @param Element|null $ref Insert before/below this element, or null if
  59          *   $preposition is ROOT.
  60          * @param Element $element An object containing information about the new
  61          *   element. The same object will be used for $parent and $refNode in
  62          *   other calls as appropriate. The handler can set $element->userData to
  63          *   attach a suitable DOM object to identify the mutation target in
  64          *   subsequent calls.
  65          * @param bool $void True if this is a void element which cannot
  66          *   have any children appended to it. This is usually true if the element
  67          *   is closed by the same token that opened it. No endTag() event will be
  68          *   sent for such an element. This is only true if self-closing tags are
  69          *   acknowledged for this tag name, so it is a hint to the serializer that
  70          *   a self-closing tag is acceptable.
  71          * @param integer $sourceStart The input position
  72          * @param integer $sourceLength The length of the input which is consumed
  73          */
  74         function insertElement( $preposition, $ref, Element $element, $void,
  75                 $sourceStart, $sourceLength );
  76
  77         /**
  78          * A hint that an element was closed and was removed from the stack
  79          * of open elements. It probably won't be mutated again.
  80          *
  81          * @param Element $element The element being ended
  82          * @param integer $sourceStart The input position
  83          * @param integer $sourceLength The length of the input which is consumed
  84          */
  85         function endTag( Element $element, $sourceStart, $sourceLength );
  86
  87         /**
  88          * A valid DOCTYPE token was found.
  89          *
  90          * @param string $name The doctype name, usually "html"
  91          * @param string $public The PUBLIC identifier
  92          * @param string $system The SYSTEM identifier
  93          * @param integer $quirks The quirks mode implied from the doctype. One of:
  94          *   - TreeBuilder::NO_QUIRKS : no quirks
  95          *   - TreeBuilder::LIMITED_QUIRKS : limited quirks
  96          *   - TreeBuilder::QUIRKS : full quirks
  97          * @param integer $sourceStart The input position
  98          * @param integer $sourceLength The length of the input which is consumed
  99          */
 100         function doctype( $name, $public, $system, $quirks, $sourceStart, $sourceLength );
 101
 102         /**
 103          * Insert a comment
 104          *
 105          * @param integer $preposition The placement of the new node with respect
 106          *   to $ref. May be TreeBuilder::
 107          *    - BEFORE: insert as a sibling before the reference element
 108          *    - UNDER: append as the last child of the reference element
 109          *    - ROOT: append as the last child of the document node
 110          * @param Element|null $ref Insert before/below this element, or null if
 111          *   $preposition is ROOT.
 112          * @param string $text The text of the comment
 113          * @param integer $sourceStart The input position
 114          * @param integer $sourceLength The length of the input which is consumed
 115          */
 116         function comment( $preposition, $ref, $text, $sourceStart, $sourceLength );
 117
 118         /**
 119          * A parse error
 120          *
 121          * @param string $text An error message explaining in English what the
 122          *   author did wrong, and what the parser intends to do about the
 123          *   situation.
 124          * @param integer $pos The input position at which the error occurred
 125          */
 126         function error( $text, $pos );
 127
 128         /**
 129          * Add attributes to an existing element. This is used to update the
 130          * attributes of the <html> or <body> elements. The event receiver
 131          * should add only those attributes which the original element does not
 132          * already have. It should not overwrite existing attributes.
 133          *
 134          * @param Element $element The element to update
 135          * @param Attributes $attrs The new attributes to add
 136          * @param integer $sourceStart The input position
 137          */
 138         function mergeAttributes( Element $element, Attributes $attrs, $sourceStart );
 139
 140         /**
 141          * Remove a node from the tree, and all its children. This is only done
 142          * when a <frameset> element is found, which triggers removal of the
 143          * partially-constructed body element.
 144          *
 145          * @param Element $element The element to remove
 146          * @param integer $sourceStart The location in the source at which this
 147          *   action was triggered.
 148          */
 149         function removeNode( Element $element, $sourceStart );
 150
 151         /**
 152          * Take all children of a given parent $element, and insert them as
 153          * children of $newParent, removing them from their original parent in the
 154          * process. Insert $newParent as now the only child of $element.
 155          *
 156          * @param Element $element The old parent element
 157          * @param Element $newParent The new parent element
 158          * @param integer $sourceStart The location in the source at which this
 159          *   action was triggered.
 160          */
 161         function reparentChildren( Element $element, Element $newParent, $sourceStart );
 162
 163 }