aleph1.co.uk Git - yaffs-website/blob - vendor/masterminds/html5/src/HTML5/Parser/EventHandler.php

   1 <?php
   2 namespace Masterminds\HTML5\Parser;
   3
   4 /**
   5  * Standard events for HTML5.
   6  *
   7  * This is roughly analogous to a SAX2 or expat-style interface.
   8  * However, it is tuned specifically for HTML5, according to section 8
   9  * of the HTML5 specification.
  10  *
  11  * An event handler receives parser events. For a concrete
  12  * implementation, see DOMTreeBuilder.
  13  *
  14  * Quirks support in the parser is limited to close-in syntax (malformed
  15  * tags or attributes). Higher order syntax and semantic issues with a
  16  * document (e.g. mismatched tags, illegal nesting, etc.) are the
  17  * responsibility of the event handler implementation.
  18  *
  19  * See HTML5 spec section 8.2.4
  20  */
  21 interface EventHandler
  22 {
  23
  24     const DOCTYPE_NONE = 0;
  25
  26     const DOCTYPE_PUBLIC = 1;
  27
  28     const DOCTYPE_SYSTEM = 2;
  29
  30     /**
  31      * A doctype declaration.
  32      *
  33      * @param string $name
  34      *            The name of the root element.
  35      * @param int $idType
  36      *            One of DOCTYPE_NONE, DOCTYPE_PUBLIC, or DOCTYPE_SYSTEM.
  37      * @param string $id
  38      *            The identifier. For DOCTYPE_PUBLIC, this is the public ID. If DOCTYPE_SYSTEM,
  39      *            then this is a system ID.
  40      * @param boolean $quirks
  41      *            Indicates whether the builder should enter quirks mode.
  42      */
  43     public function doctype($name, $idType = 0, $id = null, $quirks = false);
  44
  45     /**
  46      * A start tag.
  47      *
  48      * IMPORTANT: The parser watches the return value of this event. If this returns
  49      * an integer, the parser will switch TEXTMODE patters according to the int.
  50      *
  51      * This is how the Tree Builder can tell the Tokenizer when a certain tag should
  52      * cause the parser to go into RAW text mode.
  53      *
  54      * The HTML5 standard requires that the builder is the one that initiates this
  55      * step, and this is the only way short of a circular reference that we can
  56      * do that.
  57      *
  58      * Example: if a startTag even for a `script` name is fired, and the startTag()
  59      * implementation returns Tokenizer::TEXTMODE_RAW, then the tokenizer will
  60      * switch into RAW text mode and consume data until it reaches a closing
  61      * `script` tag.
  62      *
  63      * The textmode is automatically reset to Tokenizer::TEXTMODE_NORMAL when the
  64      * closing tag is encounter. **This behavior may change.**
  65      *
  66      * @param string $name
  67      *            The tag name.
  68      * @param array $attributes
  69      *            An array with all of the tag's attributes.
  70      * @param boolean $selfClosing
  71      *            An indicator of whether or not this tag is self-closing (<foo/>)
  72      * @return int One of the Tokenizer::TEXTMODE_* constants.
  73      */
  74     public function startTag($name, $attributes = array(), $selfClosing = false);
  75
  76     /**
  77      * An end-tag.
  78      */
  79     public function endTag($name);
  80
  81     /**
  82      * A comment section (unparsed character data).
  83      */
  84     public function comment($cdata);
  85
  86     /**
  87      * A unit of parsed character data.
  88      *
  89      * Entities in this text are *already decoded*.
  90      */
  91     public function text($cdata);
  92
  93     /**
  94      * Indicates that the document has been entirely processed.
  95      */
  96     public function eof();
  97
  98     /**
  99      * Emitted when the parser encounters an error condition.
 100      */
 101     public function parseError($msg, $line, $col);
 102
 103     /**
 104      * A CDATA section.
 105      *
 106      * @param string $data
 107      *            The unparsed character data.
 108      */
 109     public function cdata($data);
 110
 111     /**
 112      * This is a holdover from the XML spec.
 113      *
 114      * While user agents don't get PIs, server-side does.
 115      *
 116      * @param string $name
 117      *            The name of the processor (e.g. 'php').
 118      * @param string $data
 119      *            The unparsed data.
 120      */
 121     public function processingInstruction($name, $data = null);
 122 }