Chris@0: <?php
Chris@17: 
Chris@0: namespace Masterminds\HTML5\Parser;
Chris@0: 
Chris@0: /**
Chris@0:  * Standard events for HTML5.
Chris@0:  *
Chris@0:  * This is roughly analogous to a SAX2 or expat-style interface.
Chris@0:  * However, it is tuned specifically for HTML5, according to section 8
Chris@0:  * of the HTML5 specification.
Chris@0:  *
Chris@0:  * An event handler receives parser events. For a concrete
Chris@0:  * implementation, see DOMTreeBuilder.
Chris@0:  *
Chris@0:  * Quirks support in the parser is limited to close-in syntax (malformed
Chris@0:  * tags or attributes). Higher order syntax and semantic issues with a
Chris@0:  * document (e.g. mismatched tags, illegal nesting, etc.) are the
Chris@0:  * responsibility of the event handler implementation.
Chris@0:  *
Chris@0:  * See HTML5 spec section 8.2.4
Chris@0:  */
Chris@0: interface EventHandler
Chris@0: {
Chris@0:     const DOCTYPE_NONE = 0;
Chris@0: 
Chris@0:     const DOCTYPE_PUBLIC = 1;
Chris@0: 
Chris@0:     const DOCTYPE_SYSTEM = 2;
Chris@0: 
Chris@0:     /**
Chris@0:      * A doctype declaration.
Chris@0:      *
Chris@17:      * @param string $name   The name of the root element.
Chris@17:      * @param int    $idType One of DOCTYPE_NONE, DOCTYPE_PUBLIC, or DOCTYPE_SYSTEM
Chris@17:      * @param string $id     The identifier. For DOCTYPE_PUBLIC, this is the public ID. If DOCTYPE_SYSTEM,
Chris@17:      *                       then this is a system ID.
Chris@17:      * @param bool   $quirks Indicates whether the builder should enter quirks mode.
Chris@0:      */
Chris@0:     public function doctype($name, $idType = 0, $id = null, $quirks = false);
Chris@0: 
Chris@0:     /**
Chris@0:      * A start tag.
Chris@0:      *
Chris@0:      * IMPORTANT: The parser watches the return value of this event. If this returns
Chris@0:      * an integer, the parser will switch TEXTMODE patters according to the int.
Chris@0:      *
Chris@0:      * This is how the Tree Builder can tell the Tokenizer when a certain tag should
Chris@0:      * cause the parser to go into RAW text mode.
Chris@0:      *
Chris@0:      * The HTML5 standard requires that the builder is the one that initiates this
Chris@0:      * step, and this is the only way short of a circular reference that we can
Chris@0:      * do that.
Chris@0:      *
Chris@0:      * Example: if a startTag even for a `script` name is fired, and the startTag()
Chris@0:      * implementation returns Tokenizer::TEXTMODE_RAW, then the tokenizer will
Chris@0:      * switch into RAW text mode and consume data until it reaches a closing
Chris@0:      * `script` tag.
Chris@0:      *
Chris@0:      * The textmode is automatically reset to Tokenizer::TEXTMODE_NORMAL when the
Chris@0:      * closing tag is encounter. **This behavior may change.**
Chris@0:      *
Chris@17:      * @param string $name        The tag name.
Chris@17:      * @param array  $attributes  An array with all of the tag's attributes.
Chris@17:      * @param bool   $selfClosing An indicator of whether or not this tag is self-closing (<foo/>).
Chris@17:      *
Chris@17:      * @return int one of the Tokenizer::TEXTMODE_* constants
Chris@0:      */
Chris@0:     public function startTag($name, $attributes = array(), $selfClosing = false);
Chris@0: 
Chris@0:     /**
Chris@0:      * An end-tag.
Chris@0:      */
Chris@0:     public function endTag($name);
Chris@0: 
Chris@0:     /**
Chris@0:      * A comment section (unparsed character data).
Chris@0:      */
Chris@0:     public function comment($cdata);
Chris@0: 
Chris@0:     /**
Chris@0:      * A unit of parsed character data.
Chris@0:      *
Chris@0:      * Entities in this text are *already decoded*.
Chris@0:      */
Chris@0:     public function text($cdata);
Chris@0: 
Chris@0:     /**
Chris@0:      * Indicates that the document has been entirely processed.
Chris@0:      */
Chris@0:     public function eof();
Chris@0: 
Chris@0:     /**
Chris@0:      * Emitted when the parser encounters an error condition.
Chris@0:      */
Chris@0:     public function parseError($msg, $line, $col);
Chris@0: 
Chris@0:     /**
Chris@0:      * A CDATA section.
Chris@0:      *
Chris@0:      * @param string $data
Chris@17:      *                     The unparsed character data
Chris@0:      */
Chris@0:     public function cdata($data);
Chris@0: 
Chris@0:     /**
Chris@0:      * This is a holdover from the XML spec.
Chris@0:      *
Chris@0:      * While user agents don't get PIs, server-side does.
Chris@0:      *
Chris@17:      * @param string $name The name of the processor (e.g. 'php').
Chris@17:      * @param string $data The unparsed data.
Chris@0:      */
Chris@0:     public function processingInstruction($name, $data = null);
Chris@0: }