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(['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