root/trunk/lib/geshi.php

<?php
/**
 * GeSHi - Generic Syntax Highlighter
 * 
 * The GeSHi class for Generic Syntax Highlighting. Please refer to the documentation
 * at http://qbnz.com/highlighter/documentation.php for more information about how to
 * use this class.
 *
 * For changes, release notes, TODOs etc, see the relevant files in the docs/ directory
 *
 *   This file is part of GeSHi.
 *
 *  GeSHi is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  GeSHi is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with GeSHi; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * @package   core
 * @author    Nigel McNie <nigel@geshi.org>
 * @copyright Copyright &copy; 2004, 2005, Nigel McNie
 * @license   http://gnu.org/copyleft/gpl.html GNU GPL
 * @version   $Id$
 *
 */

//
// GeSHi Constants
// You should use these constant names in your programs instead of
// their values - you never know when a value may change in a future
// version
//

/** The version of this GeSHi file */
define('GESHI_VERSION', '1.0.7.5');

/** For the future (though this may never be realised) */
define('GESHI_OUTPUT_HTML', 0);

/** Set the correct directory separator */
define('GESHI_DIR_SEPARATOR', ('WIN' != substr(PHP_OS, 0, 3)) ? '/' : '\\');

// Define the root directory for the GeSHi code tree
if (!defined('GESHI_ROOT')) {
    /** The root directory for GeSHi */
    define('GESHI_ROOT', dirname(__FILE__) . GESHI_DIR_SEPARATOR);
}
/** The language file directory for GeSHi
    @access private */
define('GESHI_LANG_ROOT', GESHI_ROOT . 'geshi' . GESHI_DIR_SEPARATOR);


// Line numbers - use with enable_line_numbers()
/** Use no line numbers when building the result */
define('GESHI_NO_LINE_NUMBERS', 0);
/** Use normal line numbers when building the result */
define('GESHI_NORMAL_LINE_NUMBERS', 1);
/** Use fancy line numbers when building the result */
define('GESHI_FANCY_LINE_NUMBERS', 2);

// Container HTML type
/** Use nothing to surround the source */
define('GESHI_HEADER_NONE', 0);
/** Use a "div" to surround the source */
define('GESHI_HEADER_DIV', 1);
/** Use a "pre" to surround the source */
define('GESHI_HEADER_PRE', 2);

// Capatalisation constants
/** Lowercase keywords found */
define('GESHI_CAPS_NO_CHANGE', 0);
/** Uppercase keywords found */
define('GESHI_CAPS_UPPER', 1);
/** Leave keywords found as the case that they are */
define('GESHI_CAPS_LOWER', 2);

// Link style constants
/** Links in the source in the :link state */
define('GESHI_LINK', 0);
/** Links in the source in the :hover state */
define('GESHI_HOVER', 1);
/** Links in the source in the :active state */
define('GESHI_ACTIVE', 2);
/** Links in the source in the :visited state */
define('GESHI_VISITED', 3);

// Important string starter/finisher
// Note that if you change these, they should be as-is: i.e., don't
// write them as if they had been run through htmlentities()
/** The starter for important parts of the source */
define('GESHI_START_IMPORTANT', '<BEGIN GeSHi>');
/** The ender for important parts of the source */
define('GESHI_END_IMPORTANT', '<END GeSHi>');

/**#@+
 *  @access private
 */
// When strict mode applies for a language
/** Strict mode never applies (this is the most common) */
define('GESHI_NEVER', 0);
/** Strict mode *might* apply, and can be enabled or
    disabled by {@link GeSHi::enable_strict_mode()} */
define('GESHI_MAYBE', 1);
/** Strict mode always applies */
define('GESHI_ALWAYS', 2);

// Advanced regexp handling constants, used in language files
/** The key of the regex array defining what to search for */
define('GESHI_SEARCH', 0);
/** The key of the regex array defining what bracket group in a
    matched search to use as a replacement */
define('GESHI_REPLACE', 1);
/** The key of the regex array defining any modifiers to the regular expression */
define('GESHI_MODIFIERS', 2);
/** The key of the regex array defining what bracket group in a
    matched search to put before the replacement */ 
define('GESHI_BEFORE', 3);
/** The key of the regex array defining what bracket group in a
    matched search to put after the replacement */ 
define('GESHI_AFTER', 4);

/** Used in language files to mark comments */
define('GESHI_COMMENTS', 0);

// Error detection - use these to analyse faults
/** No sourcecode to highlight was specified */
define('GESHI_ERROR_NO_INPUT', 1);
/** The language specified does not exist */
define('GESHI_ERROR_NO_SUCH_LANG', 2);
/** GeSHi could not open a file for reading (generally a language file) */
define('GESHI_ERROR_FILE_NOT_READABLE', 3);
/** The header type passed to {@link GeSHi::set_header_type()} was invalid */
define('GESHI_ERROR_INVALID_HEADER_TYPE', 4);
/** The line number type passed to {@link GeSHi::enable_line_numbers()} was invalid */
define('GESHI_ERROR_INVALID_LINE_NUMBER_TYPE', 5);
/**#@-*/


/**
 * The GeSHi Class.
 *
 * Please refer to the documentation for GeSHi 1.0.X that is available
 * at http://qbnz.com/highlighter/documentation.php for more information
 * about how to use this class.
 * 
 * @package   core
 * @author    Nigel McNie <nigel@geshi.org>
 * @copyright Copyright &copy; 2004, 2005 Nigel McNie
 */
class GeSHi
{
    /**#@+
     * @access private
     */
    /**
     * The source code to highlight
     * @var string
     */
    var $source = '';
    
    /**
     * The language to use when highlighting
     * @var string
     */
    var $language = '';
    
    /**
     * The data for the language used
     * @var array
     */
    var $language_data = array();
    
    /**
     * The path to the language files
     * @var string
     */
    var $language_path = GESHI_LANG_ROOT;
    
    /**
     * The error message associated with an error
     * @var string
     * @todo check err reporting works
     */
    var $error = false;
    
    /**
     * Possible error messages
     * @var array
     */
    var $error_messages = array(
        GESHI_ERROR_NO_INPUT => 'No source code inputted',
        GESHI_ERROR_NO_SUCH_LANG => 'GeSHi could not find the language {LANGUAGE} (using path {PATH})',
        GESHI_ERROR_FILE_NOT_READABLE => 'The file specified for load_from_file was not readable',
        GESHI_ERROR_INVALID_HEADER_TYPE => 'The header type specified is invalid',
        GESHI_ERROR_INVALID_LINE_NUMBER_TYPE => 'The line number type specified is invalid'
    );
    
    /**
     * Whether highlighting is strict or not
     * @var boolean
     */
    var $strict_mode = false;
    
    /**
     * Whether to use CSS classes in output
     * @var boolean
     */
    var $use_classes = false;
    
    /**
     * The type of header to use. Can be one of the following
     * values:
     * 
     * <ul>
     *   <li><b>GESHI_HEADER_PRE</b>: Source is outputted in
     *   a &lt;pre&gt; HTML element.</li>
     *   <li><b>GESHI_HEADER_DIV</b>: Source is outputted in
     *   a &lt;div&gt; HTML element.</li>
     * </ul>
     * 
     * @var int
     */
    var $header_type = GESHI_HEADER_PRE;
    
    /**
     * Array of permissions for which lexics should be highlighted
     * @var array
     */
    var $lexic_permissions = array(
        'KEYWORDS' =>    array(),
        'COMMENTS' =>    array('MULTI' => true),
        'REGEXPS' =>     array(),
        'ESCAPE_CHAR' => true,
        'BRACKETS' =>    true,
        'SYMBOLS' =>     true,
        'STRINGS' =>     true,
        'NUMBERS' =>     true,
        'METHODS' =>     true,
        'SCRIPT' =>      true
    );

    /**
     * The time it took to parse the code
     * @var double
     */
    var $time = 0;
    
    /**
     * The content of the header block
     * @var string
     */
    var $header_content = '';
    
    /**
     * The content of the footer block
     * @var string
     */
    var $footer_content = '';
    
    /**
     * The style of the header block
     * @var string
     */
    var $header_content_style = '';
    
    /**
     * The style of the footer block
     * @var string
     */
    var $footer_content_style = '';
    
    /**
     * The styles for hyperlinks in the code
     * @var array
     */
    var $link_styles = array();
    
    /**
     * Whether important blocks should be recognised or not
     * @var boolean
     * @deprecated
     * @todo REMOVE THIS FUNCTIONALITY!
     */
    var $enable_important_blocks = false;
    
    /**
     * Styles for important parts of the code
     * @var string
     * @deprecated
     * @todo As above - rethink the whole idea of important blocks as it is buggy and
     * will be hard to implement in 1.2
     */
    var $important_styles = 'font-weight: bold; color: red;'; // Styles for important parts of the code
    
    /**
     * Whether CSS IDs should be added to the code
     * @var boolean
     */
    var $add_ids = false;
    
    /**
     * Lines that should be highlighted extra
     * @var array
     */
    var $highlight_extra_lines = array();
    
    /**
     * Styles of extra-highlighted lines
     * @var string
     */
    var $highlight_extra_lines_style = 'color: #cc0; background-color: #ffc;';
    
    /**
     * Number at which line numbers should start at
     * @var int
     * @todo Warning documentation about XHTML compliance
     */
    var $line_numbers_start = 1;

    /**
     * The overall style for this code block
     * @var string
     */
    var $overall_style = '';
    
    /**
     *  The style for the actual code
     * @var string
     */
    var $code_style = 'font-family: \'Courier New\', Courier, monospace; font-weight: normal;';
    
    /**
     * The overall class for this code block
     * @var string
     */
    var $overall_class = '';
    
    /**
     * The overall ID for this code block
     * @var string
     */
    var $overall_id = '';
    
    /**
     * Line number styles
     * @var string
     */
    var $line_style1 = 'font-family: \'Courier New\', Courier, monospace; color: black; font-weight: normal; font-style: normal;';
    
    /**
     * Line number styles for fancy lines
     * @var string
     */
    var $line_style2 = 'font-weight: bold;';
    
    /**
     * Flag for how line nubmers are displayed
     * @var boolean
     */
    var $line_numbers = GESHI_NO_LINE_NUMBERS;
    
    /**
     * The "nth" value for fancy line highlighting
     * @var int
     */
    var $line_nth_row = 0;

    /**
     * The size of tab stops
     * @var int
     */
    var $tab_width = 8;
        
    /**
     * Default target for keyword links
     * @var string
     */
    var $link_target = '';
    
    /**
     * The encoding to use for entity encoding
     * @var string
     */
    var $encoding = 'ISO-8859-1';

    /**
     * Unused (planned for future)
     * @var int
     */
    var $output_format = GESHI_OUTPUT_HTML;

    /**#@-*/

    /**
     * Creates a new GeSHi object, with source and language
     * 
     * @param string The source code to highlight
     * @param string The language to highlight the source with
     * @param string The path to the language file directory. <b>This
     *               is deprecated!</b> I've backported the auto path
     *               detection from the 1.1.X dev branch, so now it
     *               should be automatically set correctly. If you have
     *               renamed the language directory however, you will
     *               still need to set the path using this parameter or
     *               {@link GeSHi::set_language_path()}
     * @since 1.0.0
     */
    function GeSHi ($source, $language, $path = '')
    {
        $this->set_source($source);
        $this->set_language_path($path);
        $this->set_language($language);
    }

    /**
     * Returns an error message associated with the last GeSHi operation,
     * or false if no error has occured
     * 
     * @return string|false An error message if there has been an error, else false
     * @since  1.0.0
     */
    function error ()
    {
        if ($this->error) {
            $msg = $this->error_messages[$this->error];
            $debug_tpl_vars = array(
                '{LANGUAGE}' => $this->language,
                '{PATH}' => $this->language_path
            );
            foreach ($debug_tpl_vars as $tpl => $var) {
                $msg = str_replace($tpl, $var, $msg);
            }
            return "<br /><strong>GeSHi Error:</strong> $msg (code $this->error)<br />";
        }
        return false;
    }

    /**
     * Gets a human-readable language name (thanks to Simon Patterson
     * for the idea :))
     * 
     * @return string The name for the current language
     * @since  1.0.2
     */
    function get_language_name ()
    {
        if (GESHI_ERROR_NO_SUCH_LANG == $this->_error) {
            return $this->language_data['LANG_NAME'] . ' (Unknown Language)';
        }
        return $this->language_data['LANG_NAME'];
    }

    /**
     * Sets the source code for this object
     * 
     * @param string The source code to highlight
     * @since 1.0.0
     */
    function set_source ($source)
    {
        if ('' == trim($source)) {
            $this->error = GESHI_ERROR_NO_INPUT;
        }
        $this->source = $source;
    }

    /**
     * Sets the language for this object
     * 
     * @param string The name of the language to use
     * @since 1.0.0
     */
    function set_language ($language)
    {
        $this->error = false;
        $this->strict_mode = GESHI_NEVER;
        
        $language = preg_replace('#[^a-zA-Z0-9\-_]#', '', $language);
        $this->language = strtolower($language);
        
        $file_name = $this->language_path . $this->language . '.php';
        if (!is_readable($file_name)) {
            $this->error = GESHI_ERROR_NO_SUCH_LANG;
            return;
        }
        // Load the language for parsing
        $this->load_language($file_name);
    }

    /**
     * Sets the path to the directory containing the language files. Note
     * that this path is relative to the directory of the script that included
     * geshi.php, NOT geshi.php itself.
     * 
     * @param string The path to the language directory
     * @since 1.0.0
     * @deprecated The path to the language files should now be automatically
     *             detected, so this method should no longer be needed. The
     *             1.1.X branch handles manual setting of the path differently
     *             so this method will disappear in 1.2.0.
     */
    function set_language_path ($path)
    {
        if ($path) {
          $this->language_path = ('/' == substr($path, strlen($path) - 1, 1)) ? $path : $path . '/';
        }
    }

    /**
     * Sets the type of header to be used.
     * 
     * If GESHI_HEADER_DIV is used, the code is surrounded in a "div".This
     * means more source code but more control over tab width and line-wrapping.
     * GESHI_HEADER_PRE means that a "pre" is used - less source, but less
     * control. Default is GESHI_HEADER_PRE.
     * 
     * From 1.0.7.2, you can use GESHI_HEADER_NONE to specify that no header code
     * should be outputted.
     * 
     * @param int The type of header to be used
     * @since 1.0.0
     */
    function set_header_type ($type)
    {
        if (GESHI_HEADER_DIV != $type && GESHI_HEADER_PRE != $type && GESHI_HEADER_NONE != $type) {
            $this->error = GESHI_ERROR_INVALID_HEADER_TYPE;
            return;
        }
        $this->header_type = $type;
    }

    /**
     * Sets the styles for the code that will be outputted
     * when this object is parsed. The style should be a
     * string of valid stylesheet declarations
     * 
     * @param string  The overall style for the outputted code block
     * @param boolean Whether to merge the styles with the current styles or not
     * @since 1.0.0
     */
    function set_overall_style ($style, $preserve_defaults = false)
    {
        if (!$preserve_defaults) {
            $this->overall_style = $style;
        } else {
            $this->overall_style .= $style;
        }
    }

    /**
     * Sets the overall classname for this block of code. This
     * class can then be used in a stylesheet to style this object's
     * output
     * 
     * @param string The class name to use for this block of code
     * @since 1.0.0
     */
    function set_overall_class ($class)
    {
        $this->overall_class = $class;
    }

    /**
     * Sets the overall id for this block of code. This id can then
     * be used in a stylesheet to style this object's output
     * 
     * @param string The ID to use for this block of code
     * @since 1.0.0
     */
    function set_overall_id ($id)
    {
        $this->overall_id = $id;
    }

    /**
     * Sets whether CSS classes should be used to highlight the source. Default
     * is off, calling this method with no arguments will turn it on
     * 
     * @param boolean Whether to turn classes on or not
     * @since 1.0.0
     */
    function enable_classes ($flag = true)
    {
        $this->use_classes = ($flag) ? true : false;
    }

    /**
     * Sets the style for the actual code. This should be a string
     * containing valid stylesheet declarations. If $preserve_defaults is
     * true, then styles are merged with the default styles, with the
     * user defined styles having priority
     *
     * Note: Use this method to override any style changes you made to
     * the line numbers if you are using line numbers, else the line of
     * code will have the same style as the line number! Consult the
     * GeSHi documentation for more information about this.
     * 
     * @param string  The style to use for actual code
     * @param boolean Whether to merge the current styles with the new styles
     */
    function set_code_style ($style, $preserve_defaults = false)
    {
        if (!$preserve_defaults) {
            $this->code_style = $style;
        } else {
            $this->code_style .= $style;
        }
    }

    /**
     * Sets the styles for the line numbers.
     * 
     * @param string The style for the line numbers that are "normal"
     * @param string|boolean If a string, this is the style of the line
     *        numbers that are "fancy", otherwise if boolean then this
     *        defines whether the normal styles should be merged with the
     *        new normal styles or not
     * @param boolean If set, is the flag for whether to merge the "fancy"
     *        styles with the current styles or not
     * @since 1.0.2
     */
    function set_line_style ($style1, $style2 = '', $preserve_defaults = false)
    {
        if (is_bool($style2)) {
            $preserve_defaults = $style2;
            $style2 = '';
        }
        if (!$preserve_defaults) {
            $this->line_style1 = $style1;
            $this->line_style2 = $style2;
        } else {
            $this->line_style1 .= $style1;
            $this->line_style2 .= $style2;
        }
    }

    /**
     * Sets whether line numbers should be displayed.
     * 
     * Valid values for the first parameter are:
     * 
     * <ul>
     *   <li><b>GESHI_NO_LINE_NUMBERS</b>: Line numbers will not be displayed</li>
     *   <li><b>GESHI_NORMAL_LINE_NUMBERS</b>: Line numbers will be displayed</li>
     *   <li><b>GESHI_FANCY_LINE_NUMBERS</b>: Fancy line numbers will be displayed</li>
     * </ul>
     * 
     * For fancy line numbers, the second parameter is used to signal which lines
     * are to be fancy. For example, if the value of this parameter is 5 then every
     * 5th line will be fancy.
     * 
     * @param int How line numbers should be displayed
     * @param int Defines which lines are fancy
     * @since 1.0.0
     */
    function enable_line_numbers ($flag, $nth_row = 5)
    {
        if (GESHI_NO_LINE_NUMBERS != $flag && GESHI_NORMAL_LINE_NUMBERS != $flag
            && GESHI_FANCY_LINE_NUMBERS != $flag) {
            $this->error = GESHI_ERROR_INVALID_LINE_NUMBER_TYPE;
        }
        $this->line_numbers = $flag;
        $this->line_nth_row = $nth_row;
    }

    /**
     * Sets the style for a keyword group. If $preserve_defaults is
     * true, then styles are merged with the default styles, with the
     * user defined styles having priority
     * 
     * @param int     The key of the keyword group to change the styles of
     * @param string  The style to make the keywords
     * @param boolean Whether to merge the new styles with the old or just
     *                to overwrite them
     * @since 1.0.0
     */
    function set_keyword_group_style ($key, $style, $preserve_defaults = false)
    {
        if (!$preserve_defaults) {
            $this->language_data['STYLES']['KEYWORDS'][$key] = $style;
        } else {
            $this->language_data['STYLES']['KEYWORDS'][