1	<?php
2
3	namespace Wikimedia\RemexHtml\Tokenizer;
4
5	/**
6	* This is the interface for handlers receiving events from the Tokenizer.
7	* All events which consume characters give a source offset and length,
8	* allowing for input stream patching. The offset and length are relative to
9	* the preprocessed input, see Tokenizer::getPreprocessd
10	*/
11	interface TokenHandler {
12	/**
13	* Called once at the start of the document (STATE_START)
14	*
15	* @param Tokenizer $tokenizer The Tokenizer which generated the event
16	* @param string|null $fragmentNamespace The fragment namespace, or null
17	*   to run in document mode.
18	* @param string|null $fragmentName The fragment tag name, or null to run
19	*   in document mode.
20	*/
21	public function startDocument( Tokenizer $tokenizer, $fragmentNamespace, $fragmentName );
22
23	/**
24	* Called when the end of the input string is consumed
25	* @param int $pos The input position (past the end)
26	*/
27	public function endDocument( $pos );
28
29	/**
30	* This is called for "parse errors" (as defined by the spec). The spec
31	* does not define names for error messages, so we just use some English
32	* text for now. The imagined audience is a developer reading validator
33	* output.
34	*
35	* @param string $text The error message
36	* @param int $pos The input position
37	*/
38	public function error( $text, $pos );
39
40	/**
41	* A merged sequence of character tokens. We use the SAX-like convention of
42	* requiring the handler to do the substring operation, i.e. the actual
43	* text is substr( $text, $start, $length ), since this allows us to avoid
44	* some copying, at least if ignoreCharRefs and ignoreNulls are enabled.
45	*
46	* @param string $text The string which contains the emitted characters
47	* @param int $start The start of the range within $text to use
48	* @param int $length The length of the range within $text to use
49	* @param int $sourceStart The input position
50	* @param int $sourceLength The input length
51	*/
52	public function characters( $text, $start, $length, $sourceStart, $sourceLength );
53
54	/**
55	* A start tag event. We call it a tag rather than an element since the
56	* start/end events are not balanced, so the relationship between tags
57	* and elements is complex. Errors emitted by attribute parsing will be
58	* not be received until $attrs is accessed by the handler.
59	*
60	* @param string $name The tag name
61	* @param Attributes $attrs The tag attributes
62	* @param bool $selfClose Whether there is a self-closing slash
63	* @param int $sourceStart The input position
64	* @param int $sourceLength The input length
65	*/
66	public function startTag( $name, Attributes $attrs, $selfClose, $sourceStart, $sourceLength );
67
68	/**
69	* An end tag event.
70	*
71	* @param string $name The tag name
72	* @param int $sourceStart The input position
73	* @param int $sourceLength The input length
74	*/
75	public function endTag( $name, $sourceStart, $sourceLength );
76
77	/**
78	* A DOCTYPE declaration
79	*
80	* @param string|null $name The DOCTYPE name, or null if none was found
81	* @param string|null $public The public identifier, or null if none was found
82	* @param string|null $system The system identifier, or null if none was found
83	* @param bool $quirks What the spec calls the "force-quirks flag"
84	* @param int $sourceStart The input position
85	* @param int $sourceLength The input length
86	*/
87	public function doctype( $name, $public, $system, $quirks, $sourceStart, $sourceLength );
88
89	/**
90	* A comment.
91	*
92	* @param string $text The inner text of the comment
93	* @param int $sourceStart The input position
94	* @param int $sourceLength The input length
95	*/
96	public function comment( $text, $sourceStart, $sourceLength );
97	}