$Id: Readme,v 1.4 2004/06/02 14:33:38 hfuecks Exp $
++Introduction
XML_HTMLSax3 is a SAX based XML parser for badly formed XML documents,
such as HTML.

The original code base was developed by Alexander Zhukov and published at
http://sourceforge.net/projects/phpshelve/. Alexander kindly gave permission
to modify the code and license for inclusion in PEAR.

PEAR::XML_HTMLSax3 provides an API very similar to the native PHP SAX
extension (http://www.php.net/xml), allowing handlers using one to be
easily adapted to the other. The key difference is HTMLSax will not
break on badly formed XML, allowing it to be used for parsing HTML
documents. Otherwise HTMLSax supports all the handlers available from
Expat except namespace and external entity handlers. Provides methods
for handling XML escapes as well as JSP/ASP opening and close tags.

Version 1.x introduced an API similar to the native SAX extension but
used a slow character by character approach to parsing.

Version 2.x has had it's internals completely overhauled to use a Lexer,
delivering performance *approaching* that of the native XML extension,
as well as a radically improved, modular design that makes adding
further functionality easy.

Version 3.x is about fine tuning the API, behaviour and providing a
mechanism to distinguish HTML "quirks" from badly formed HTML


A big thanks to Jeff Moore (lead developer of WACT:
http://wact.sourceforge.net) who's largely responsible for new design, as well
input from members at Sitepoint's Advanced PHP forums:
http://www.sitepointforums.com/showthread.php?threadid=121246.

Thanks also to Marcus Baker (lead developer of SimpleTest:
http://www.lastcraft.com/simple_test.php) for sorting out the unit tests.

++Uses
Some particular situations where XML_HTMLSax3 can be useful include;
- Template Engines (see WACT for example: http://wact.sf.net)
- Parsing XML documents (such as those online) where the source is
  out of your control and Expat is choking because it's badly formed.
- Converting HTML to XHTML
- Reading HTML based content from a database and converting to PDF (with
  help from a PDF generation library and probably PEAR::XML_SaxFilters as
  well)
- Parsing ASP(.NET) and JSP pages.
- Creating a PHP-GTK based web browser? A PHP CSS Parser exists:
  http://www.phpclasses.org/browse.html/package/1081.html

++Features
- Won't "break" on badly formed XML. May in some instances get it "wrong"
  (see Limitations) but will continue parsing.

- Provides an API similar to the native PHP XML extension so switching code
  from one to the other is typically minimal effort.

- Can be instructed to behave in more or less the same manner as SAX,
  when dealing with linefeeds, tabs and XML entities

- In addition to handling basic XML elements attributes and data also
  capable of dealing with; 
   - Processing instructions e.g. <?php ?> / <?xml ?> etc. Within PI's
     XML entities are not parsed (i.e. ignore < and > )
   - XML Escape markup such as <! >, <!-- --> and <![CDATA[ ]]>. Within
     this XML entities are not parsed (useful for JavaScript, for example)
   - JSP / ASP (JASP) marked up with <% %>. Note: You will need to
     deal with <%@ %> and <%= %> yourself. With JASP markup XML entities
     are not parsed

++Usage Notes

- Performance-wise, it runs faster on PHP 4.3.0 thanks to strspn() and
  strcspn() supporting position arguments. For older PHP versions while
  loops are used to achieve the same effect, meaning a slightly higher
  overhead. Note also that setting XML options with XML_HTMLSax3::set_option()
  also slows down the parser, the options being handled by "decorators"
  which perform some further formatting on XML events which have already
  been parsed.

- By default, no parser options are set

- Regarding the XML_OPTION_ENTITIES_PARSED, this uses the html_entity_decode()
  function which is only available in PHP 4.3.0+. To get round this, HTMLSax
  checks your PHP version and for the function name html_entity_decode. If not
  found, it defines a function which mirrors the behavior of the native PHP
  html_entity_decode().
  Both XML_OPTION_ENTITIES_PARSED and XML_OPTION_ENTITIES_UNPARSED can be used
  down to PHP version 4.0.5, due to the regular expression used to find entities.

- For attributes which have just a name but no value e.g.
  <option value="bar" selected>

  HTMLSax will return a NULL value for that attribute name, when
  calling the opening tag handler;

  function myOpenHandler($parser,$name,$attrs) {
      print_r ( $attrs );
  }

  This would produce;

  Array
  (
      [value] => bar
      [selected] => NULL
  )

- JASP directives like <%@ and <%= will be not be regarded as special.
  I.e. you will get back the @ or % from the contents of the JASP block
  and have to deal with these yourself.

++ Limitations
- XML_HTMLSax3 only supports use of PHP classes as callback handlers;
  there is no support for using PHP functions as handlers.

- The only weird behaviour is for attributes which only have a left quote
  or apostrophe e.g. <tag foo="bar>Some Text</tag> will give you an
  attribute like $attrs['foo']="bar>Some Text"; This is a trade off against
  allowing XML entities like < and > to appear inside attributes.

- Although the package name might suggest otherwise, XML_HTMLSax3 currently
  has no special knowledge of HTML (i.e. there is no understanding of whether
  a given HTML document is well formed or not, according to HTML's rules).
  XML_HTMLSax3 is primarily intended as a SAX based parser that will not
  complain about structure of a document it is asked to parse. It even does
  a fair job of parsing http://static.php.net/www.php.net/images/php.gif ...
  Version 3.x will introduce some basic knowledge of HTML grammar to help with
  identifying HTML "quirks".

- <script /> elements containing < or > characters; these will be treated as new
  elements triggering the listeners. Make sure that any JavaScript inside is marked
  either with an XML comment <!-- --> or a CDATA block <[CDATA[ ]]>
  </script>
  Alternatively define open / close handlers which watch for <script /> elements
  as a special case, so that any further events triggered within them are handled
  as part of the <script /> element.

- If you change the handlers once parsing has started, you will need to re-set
  and parser options you have defined

++ Example Use
Further examples are available in the examples directory of this package.

<?php
// Include HTMLSax
require_once('XML/HTMLSax3.php');

// Define a customer handler class
class MyHandler {
    function MyHandler(){}

    // Opening tags
    function openHandler(& $parser,$name,$attrs) {
        echo ( 'Open Tag Handler: '.$name );
        echo ( 'Attrs:' );
        print_r($attrs);
    }

    // Closing tags
    function closeHandler(& $parser,$name) {
        echo ( 'Close Tag Handler: '.$name );
    }

    // Text node handler
    function dataHandler(& $parser,$data) {
        echo ( 'Data Handler: '.$data );
    }

    // XML escape handler (e.g. HTML comments)
    function escapeHandler(& $parser,$data) {
        echo ( 'Escape Handler: '.$data );
    }

    // Processing instruction handler
    function piHandler(& $parser,$target,$data) {
        echo ( 'PI Handler: '.$target.' - '.$data );
    }

    // JSP / ASP markup handler
    function jaspHandler(& $parser,$data) {
        echo ( 'Jasp Handler: '.$data );
    }
}

// Get some HTML document
$doc = file_get_contents('http://www.php.net');

// Instantiate the handler
$handler=new MyHandler();

// Instantiate the parser
$parser=& new XML_HTMLSax3();

// Register the handler with the parser
$parser->set_object($handler);

// Set a parser option
$parser->set_option('XML_OPTION_TRIM_DATA_NODES');

// Set the callback handlers (MyHandler methods)
$parser->set_element_handler('openHandler','closeHandler');
$parser->set_data_handler('dataHandler');
$parser->set_escape_handler('escapeHandler');
$parser->set_pi_handler('piHandler');
$parser->set_jasp_handler('jaspHandler');

// Parse the document
$parser->parse($doc);
?>