<?php
/**
 * Interface
 * 
 * $Id$
 *
 * @author gERD Schaufelberger <gerd@php-tools.net>
 * @license PHP License
 * @package wb
 * @subpackage Markup
 */

/**
 * Interface for a scanner client
 *
 * If you want to programm a Client for the Scanner Class
 * following functions have to be implemented. All these functions
 * gonna be called by the Scanner Class
 *
 * @version 1.0.0
 * @package wb
 * @subpackage Markup
 */
interface WBMarkup_Handler
{
   /**
    * Handler to be called right before scan starts
    *
    * Use this function if you want to influence the content
    * before the Scanner starts his work. After that function
    * was called you don't have any chances manipulating the content
    * of the scanner
    *
    * @param string $content
    * @return bool usually true, false to stop the scanner
    */
    public function onScanStart( &$content );
    
   /**
    * Handler to be called for each opening tag
    *
    * Gonna be callled if the Scanner finds a StartElement
    *
    * @param string $ns            = The used Namespace, if set. Otherwise null
    * @param string $tag           = The tag itself
    * @param array  $attributes    = the Attributes of the found Element
    * @param bool   $isEmpty       = true if it is a Start- and Closing-Element (e.g. <br />)
    * @return bool usually true, false to stop the scanner
    */
    public function onStartElement( $ns, $tag, $attributes, $isEmpty );
    
   /**
    * Handler to be called if character data comes in
    *
    * Gonna be called if the Scanner find cData
    *
    * @param string $cData = the cData
    * @return bool usually true, false to stop the scanner
    * @return bool usually true, false to stop the scanner
    */
    public function onCharacterData( $cData );
    
   /**
    * Handler to be called for each closing tag
    *
    * Gonna be called if the Scanner finds a EndElement
    *
    * @param string $ns    = The NameSpace
    * @param string $tag   = The Tag itself
    * @param bool $empty   = Defines if the tag is empty
    * @return bool usually true, false to stop the scanner
    */
    public function onEndElement( $ns, $tag, $empty );
        
   /**
    * Handler to be called when scanner reaches the end of input stream
    *
    * This function gonna be called when the Scanner was'nt
    * distrubed by the client and has finished scanning the
    * whole content string.
    *
    * @return bool usually true, false to stop the scanner
    */
    public function onScanComplete();

   /**
    * Occurs if a entity element will be found inside cdata
    *
    * This function gonna be called if the scanner finds a entity element
    * like e.g. &nbsp; The Client may then decided want he wants to do with it
    *
    * @param $entity		= the entity without the surrounding & and ;, e.g. nbsp
    * @param $isUnicode	= true if it is a unicode string, false if not
    *
    * @return bool usually true, false to stop the scanner
    */
    public function onEntityElement( $entity, $isUnicode );
    
   /**
    * Receive result
    *
    * This function is meant to be called after scan has completed and
    * everything went alright. getParsedContent() gives you access to
    * whatever this handler build up.
    *
    * @return mixed contente
    */
    public function getParsedContent();
}
?>