View source for Text Highlighter

Provides functionality to perform syntax highlighting for different file formats. 

{{toc numerate=1}}

===Introduction===

With Text_Highlighter it is possible to create syntax highlighted versions of different file formats.

Currently, the following formats are supported:

  * ABAP
  * C++
  * CSS
  * output of diff(1)
  * DTD
  * HTML
  * Java
  * Javascript
  * MySQL
  * Perl
  * PHP
  * Python
  * Ruby
  * sh
  * SQL
  * VBScript
  * XML

There are different options for getting the results of the highlighting, through the use of renderers. The list of renderers is as follows.

  * Array
  * Console
  * HTML - using span-tags containing a CSS class name, this is the default renderer
  * HTMLTags - using simple set of tags, only B, I and U, useful for devices that support only a subset of HTML (example is an iPod)
  * JSON
  * XML

===Usage===

The class Text_Highlighter contains all necessary functionality to perform the syntax highlighting except for the actual highlighting rules for the different formats. These rules are defined in subclasses of Text_Highlighter, but one must not directly instantiate these subclasses. Instead the object-oriented factory pattern is used to create a highlighter object depending on the format:

**Highlighting a SQL query**
%%(hl php)
<?php
require_once "Text/Highlighter.php";

$hlSQL =& Text_Highlighter::factory("SQL");
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
?>
%%

This code generates a highlighted version of the SQL SELECT-query that is passed to ##Text_Highlighter::highlight## in HTML. It is possible to customize the output to e.g. instead generate output suitable for usage on a console. This is described in the section Output Customization.

In order to produce syntax highlighting for other formats, one must replace the argument value SQL of ##Text_Highlighter::factory## with one of ##ABAP##, ##CPP##, ##CSS##, ##DIFF##, ##DTD##, ##HTML##, ##JAVA##, ##JAVASCRIPT##, ##MYSQL##, ##PERL##, ##PHP##, ##PYTHON##, ##RUBY##, ##SQL##, or ##XML##.

===Output Customization===

The default behaviour of Text_Highlighter is to generate a syntax highlighted HTML version of the input.

It is possible to instead generate output that is suitable for being displayed on color-capable terminals such as **xterm** or through **less(1)** by telling Text_Highlighter to use another renderer:

**Using the console renderer**
%%(hl php)
<?php
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Console.php";

$hlSQL =& Text_Highlighter::factory("SQL");
$hlSQL->setRenderer(new Text_Highlighter_Renderer_Console);
echo $hlSQL->highlight("SELECT * FROM some_table WHERE id = 12");
?>
%%

Also it is possible to further customize the output of both the HTML- and the console-renderer by passing an associative array of options to the constructor:

**Options for the HTML renderer**
%%(hl php)
<?php
require_once "Text/Highlighter.php";
require_once "Text/Highlighter/Renderer/Html.php";

$renderer = new Text_Highlighter_Renderer_Html(array("numbers" => HL_NUMBERS_LI, "tabsize" => 4));

$hlJava =& Text_Highlighter::factory("JAVA");
$hlJava->setRenderer($renderer);

echo $hlJava->highlight('class JavaProgram {
    public static void main(String args[]) {
        System.out.println("Hello World!");
    }
}');
?>
%%

The above example configures a HTML renderer with two options: The first one tells it to number the lines in the output using the ##<ol/>## HTML tag and the second one instructs the renderer to use a tab width of 4 spaces for indentation.

The following options are applicable:


#|
*| Name | Description | Available in HTML renderer | Available in console renderer | Hints |*
|| ##numbers## | Line numbering style | yes | yes | In the console renderer, this option takes just **TRUE** or **FALSE** in order to denote if line numbers should be displayed or not. The HTML rendered accepts three different values: **HL_NUMBERS_LI** instructs the class to number the lines using the ##<ol/>## HTML tag, while **HL_NUMBERS_TABLE** uses a two-column table with the line numbers in the first and the source code in the second column. Setting the value to **FALSE** turns line numbering off in the HTML renderer. ||
|| ##numbers_start## | Set a start number | yes | yes | Make the line numbers start at any number, rather than just 1. ||
|| ##tabsize## | Tab width | yes | yes | ||
|| ##colors## | Additional colors | no | yes | An associate array of additional colors for color-enabled consoles. The key of each array entry must be the name of the color and the corresponding value must be the escape sequence for it. (Example: ##\033[1;31mRed.##) ||
|#
Possible options for the renderer classes

----
original is located at: ((/Dev/Components/Lib/TextHighlighter))