root/trunk/patXMLPretty.php

<?php
/**
 * File containing the patXMLPretty class.
 *
 * @package        patXMLPretty
 * @author        Sebastian 'The Argh' Mordziol <argh@php-tools.net>
 * @see         patXMLPretty
 */

/**
 * Error: Invalid configuration reader object
 */
 define( 'PATXMLPRETTY_ERROR_INVALID_CONFIG_READER', 'patXMLPretty:01' );

/**
 * Error: Missing a vital component
 */
 define( 'PATXMLPRETTY_ERROR_COMPONENT_MISSING', 'patXMLPretty:02' );

/**
 * Error: Internal file not found
 */
 define( 'PATXMLPRETTY_ERROR_FILE_NOT_FOUND', 'patXMLPretty:03' );

/**
 * Error: Internal file class not found
 */
 define( 'PATXMLPRETTY_ERROR_CLASS_NOT_FOUND', 'patXMLPretty:04' );

/**
 * Error: File could not be included
 */
 define( 'PATXMLPRETTY_ERROR_COULD_NOT_INCLUDE_FILE', 'patXMLPretty:05' );

/**
 * Error: XML parsing process failed
 */
 define( 'PATXMLPRETTY_ERROR_XML_PARSING_FAILED', 'patXMLPretty:06' );

/**
 * Error: XML could not be read from target file
 */
 define( 'PATXMLPRETTY_ERROR_COULD_NOT_READ_XML_FROM_FILE', 'patXMLPretty:07' );

/**
 * The base directory from which patXMLPretty operates
 */
 define( 'PATXMLPRETTY_BASE_DIR', dirname( __FILE__ ) );

/**
 * Lightweight and fast XML syntax highlighting package with
 * inline source documentation capabilities.
 *
 * @package        patXMLPretty
 * @author        Sebastian 'The Argh' Mordziol <argh@php-tools.net>
 * @author        Stephan Schmidt <schst@php.net>
 * @version        0.1.0
 * @license        LGPL
 * @link        http://www.php-tools.net
 */
class patXMLPretty
{
   /**
    * Stores the configuration reader object used to load
    * and access tag syntax definitions.
    *
    * @access    private
    * @var        patXMLReader_ConfigReader
    * @see         setConfigReader()
    * @see         createConfigReader()
    */
    var $configReader = null;

   /**
    * Stores the renderer object used to render the highlighted
    * syntax.
    *
    * @access    private
    * @var        patXMLPretty_Renderer
    * @see         setRenderer()
    * @see         createRenderer()
    */
    var $renderer = null;

   /**
    * Stores the parsing engine object used to parse the XML to highlight
    *
    * @access    private
    * @var        patXMLPretty_Engine
    * @see         setEngine()
    * @see         createEngine()
    */
    var $engine = null;

   /**
    * Stores a list of folders in which patXMLPretty will look
    * for modules like renderers and config readers to allow
    * external repositories.
    *
    * @access    private
    * @var        array
    * @see         addClassRepository()
    * @see         getClassRepositories()
    */
    var $classRepositories = array();

   /**
    * Sets the configuration reader to use to load and access the tag
    * coloring and syntax definitions.
    *
    * @access    public
    * @param    patXMLPretty_ConfigReader
    * @return    bool true|patError
    * @see         createConfigReader()
    * @see         $configReader
    */
    function setConfigReader( &$configReader )
    {
        if( !is_a( $configReader, 'patXMLPretty_ConfigReader' ) ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_INVALID_CONFIG_READER,
                'Invalid configuration reader object',
                'The config reader you set is not a valid patXMLPretty configuration reader. '.
                'For reference, the argument given is a ['.gettype( $configReader ).'].'
            );

            return $error;
        }

        $this->configReader =& $configReader;
        $result = true;
        return $result;
    }

   /**
    * Sets the renderer to use to render the highlighted content
    *
    * @access    public
    * @param    patXMLPretty_Renderer
    * @return    bool true|patError
    * @see         createRenderer()
    * @see         $renderer
    */
    function setRenderer( &$renderer )
    {
        if( !is_a( $renderer, 'patXMLPretty_Renderer' ) ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_INVALID_RENDERER,
                'Invalid renderer object',
                'The reader you set is not a valid patXMLPretty renderer. '.
                'For reference, the argument given is a ['.gettype( $renderer ).'].'
            );

            return $error;
        }

        $this->renderer =& $renderer;
        $result = true;
        return $result;
    }

   /**
    * Sets the engine to use to parse the XML to highlight
    *
    * @access    public
    * @param    patXMLPretty_Engine
    * @return    bool true|patError
    * @see         createEngine()
    * @see         $engine
    */
    function setEngine( &$engine )
    {
        if( !is_a( $engine, 'patXMLPretty_Engine' ) ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_INVALID_ENGINE,
                'Invalid engine object',
                'The engine you set is not a valid patXMLPretty parsing engine. '.
                'For reference, the argument given is a ['.gettype( $engine ).'].'
            );

            return $error;
        }

        $this->engine =& $engine;
        $result = true;
        return $result;
    }

   /**
    * Creates a configuration reader object. patXMLPretty uses configuration
    * reader objects to access tag syntax information. With this factory method
    * you can create the reader object that best fits your needs and set it via
    * the {@link setConfigReader()} method.
    *
    * Note: this is not mandatory, as patXMLPretty will use the default config
    * reader automatically if no reader has been specifically set.
    *
    * @access    public
    * @param    string
    * @param     array
    * @return    patXMLPretty_ConfigReader|patError
    */
    function &createConfigReader( $type, $options = array() )
    {
        $configReader =& $this->_createModule( 'ConfigReader', $type, $options );
        return $configReader;
    }

   /**
    * Creates a renderer object. patXMLPretty uses renderer objects to create
    * the highlighted content. With this factory method you can create a renderer
    * object that best fits your needs and set it via the {@link setRenderer()} method.
    *
    * Note: this is not mandatory, as patXMLPretty will use a default renderer
    * automatically if no renderer has been specifically set.
    *
    * @access    private
    * @param    string
    * @param     array
    * @return    patXMLPretty_Renderer|patError
    */
    function &createRenderer( $type, $options = array() )
    {
        $renderer =& $this->_createModule( 'Renderer', $type, $options );
        return $renderer;
    }

   /**
    * Creates a parsing engine object. patXMLPretty uses parser objects to parse the
    * XML data to highlight. With this factory method you can create a parsing engine
    * object that best fits your needs and set it via the {@link setEngine()} method.
    *
    * Note: this is not mandatory, as patXMLPretty will use a default engine
    * automatically if no engine has been specifically set.
    *
    * @access    private
    * @param    string
    * @param     array
    * @return    patXMLPretty_Engine|patError
    */
    function &createEngine( $type, $options = array() )
    {
        $engine =& $this->_createModule( 'Engine', $type );
        return $engine;
    }

   /**
    * Generic method to create a patXMLPretty module object, like
    * a renderer or config reader.
    *
    * @access    private
    * @param    string
    * @param     string
    * @param     array
    * @return    object
    */
    function &_createModule( $type, $name, $options = array() )
    {
        // include the base module file
        $moduleBase = PATXMLPRETTY_BASE_DIR.'/patXMLPretty/Module.php';
        if( !@include_once $moduleBase ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_COMPONENT_MISSING,
                'Missing vital component',
                'Could not find the base module component in path ['.$moduleBase.']. '.
                'Please check your patXMLPretty installation.'
            );

            return $error;
        }

        // include the base reader file
        $baseFile = PATXMLPRETTY_BASE_DIR.'/patXMLPretty/'.$type.'.php';
        if( !@include_once $baseFile ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_COMPONENT_MISSING,
                'Missing vital component',
                'Could not find the base config reader component in path ['.$baseFile.']. '.
                'Please check your patXMLPretty installation.'
            );

            return $error;
        }

        $class = 'patXMLPretty_'.str_replace( '/', '_', $type ).'_'.str_replace( '/', '_', $name );
        $file = $type.'/'.$name.'.php';

        $success = $this->_includeFile( $file, $class );
        if( patErrorManager::isError( $success ) ) {
            return $success;
        }

        $module =& new $class;
        $module->setOptions( $options );
        $module->setPretty( $this );

        return $module;
    }

   /**
    * Finds a file in the available class repositories
    *
    * @access    private
    * @param    string
    * @return    string|bool false
    */
    function _findFile( $file )
    {
        // now search for the requested file in all
        // available class repositories.
        $repositories = $this->getClassRepositories();
        foreach( $repositories as $repository ) {
            $file = $repository.'/patXMLPretty/'.$file;
            if( file_exists( $file ) ) {
                return $file;
            }
        }

        $result = false;
        return $result;
    }

   /**
    * Includes an internal patXMLPretty file, like a configuration
    * reader or such, from any of the available class repositories.
    *
    * @access    private
    * @param    string
    * @param     string
    * @return    bool true|patError
    */
    function _includeFile( $file, $class = null )
    {
        // find the file in the available repositories
        $fullPath = $this->_findFile( $file );
        if( !$fullPath ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_FILE_NOT_FOUND,
                'File not found',
                'Could not find the file ['.$file.'] in any of the available class '.
                'repository folders.'
            );

            return $error;
        }

        // try to include the file
        if( !include_once $fullPath ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_COULD_NOT_INCLUDE_FILE,
                'Cannot include file',
                'The file ['.$file.'] exists, but cannot be included. Please make sure that '.
                'sufficient access rights are set so that I may include this file.'
            );

            return $error;
        }

        // if a class is required to be present in the file, check that too
        if( !is_null( $class ) && !class_exists( $class ) ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_CLASS_NOT_FOUND,
                'Required class does not exist',
                'The file ['.$file.'] could be included, but the required class ['.$class.'] '.
                'could not be found. There is either a mismatch between the file name and the '.
                'containing class, or it is the wrong file.'
            );

            return $error;
        }

        $result = true;
        return $result;
    }

   /**
    * Adds a directory to the list of class repositories in which
    * patXMLPretty will look for configuration readers and other
    * assets. You can use this to use your own classes without
    * copying them to the patXMLPretty directory tree.
    *
    * The folder structure has to follow that of the patXMLPretty
    * package for the files to be found.
    *
    * @access    public
    * @param    string
    * @see         getClassRepositories()
    * @see         $classRepositories
    */
    function addClassRepository( $dir )
    {
        $this->classRepositories[] = $dir;
    }

   /**
    * Returns the current list of folders in which patXMLPretty
    * searches for subclasses.
    *
    * @access    public
    * @return    array
    * @see         addClassRepository()
    * @see         $classRepositories
    */
    function getClassRepositories()
    {
        $repositories = $this->classRepositories;
        array_unshift( $repositories, PATXMLPRETTY_BASE_DIR );
        return $repositories;
    }

   /**
    * Retrieves a reference to the engine object
    * that is currently used.
    *
    * @access    public
    * @return    object|null
    * @see        setEngine()
    * @see         $engine
    */
    function &getEngine()
    {
        return $this->engine;
    }

   /**
    * Initializes the parsing process by setting up all needed
    * data and checking everything required is present.
    *
    * @access    private
    * @return    bool true|patError
    */
    function _init()
    {
        // if no config reader is present, we create and use the default one.
        if( is_null( $this->configReader ) ) {
            $reader =& $this->createConfigReader( 'Default' );
            if( patErrorManager::isError( $reader ) ) {
                return $reader;
            }

            $this->setConfigReader( $reader );
        }

        $success = $this->configReader->read();
        if( patErrorManager::isError( $success ) ) {
            return $success;
        }

        // if no renderer is present, we create and use the default one.
        if( is_null( $this->renderer ) ) {
            $renderer =& $this->createRenderer( 'HTML/Simple' );
            if( patErrorManager::isError( $renderer ) ) {
                return $renderer;
            }

            $this->setRenderer( $renderer );
        }

        // if no engine has been set, create and use the default one.
        if( is_null( $this->engine ) ) {
            $engine =& $this->createEngine( 'Automatic' );
            if( patErrorManager::isError( $engine ) ) {
                return $engine;
            }

            $this->setEngine( $engine );
        }

        $result = true;
        return $result;
    }

   /**
    * Parses an XML file, syntax-highlights it and returns
    * the rendered content.
    *
    * @access    public
    * @param    string
    * @return    string|patError
    * @see         parseString()
    */
    function parseFile( $file )
    {
        $xmlSource = @file_get_contents( $file );
        if( !$xmlSource ) {
            $error = patErrorManager::raiseError(
                PATXMLPRETTY_ERROR_COULD_NOT_READ_XML_FROM_FILE,
                'Could not open XML file',
                'Contents of target XML file ['.$file.'] could not be read.'
            );

            return $error;
        }

        $result = $this->parseString( $xmlSource );
        return $result;
    }

   /**
    * Parses and XML string, syntax-highlights it and returns
    * the rendered content.
    *
    * @access    public
    * @param    string
    * @return    string|patError
    * @see         parseFile()
    */
    function parseString( $xmlSource )
    {
        $success = $this->_init();
        if( patErrorManager::isError( $success ) ) {
            return $success;
        }

        // tell everyone who is whom :)
        $this->renderer->setConfigReader( $this->configReader );
        $this->engine->setRenderer( $this->renderer );
        $this->engine->setConfigReader( $this->configReader );

        $structure = $this->engine->parse( $xmlSource );
        if( patErrorManager::isError( $structure ) ) {
            return $structure;
        }

        $rendered = $this->renderer->render( $structure['document'], $structure['elements'], $structure['doctype'] );
        return $rendered;
    }
}
?>