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