PEAR Manual
PrevChapter 61. TextNext

Text_Highlighter

Provides functionality to perform syntax highlighting for different file formats.

Introduction

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

Currently, the following formats are supported:

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

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:

Example 61-7. Highlighting a SQL query

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:

Example 61-8. Using the console renderer

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:

Example 61-9. Options for the HTML renderer

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:

Table 61-1. Possible options for the renderer classes

NameDescriptionAvailable in HTML rendererAvailable in console rendererHints
numbersLine numbering styleyesyes 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.
tabsizeTab widthyesyes 
colorsAdditional colorsnoyes 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.)
PrevHomeNext
Text_FigletUpText_LanguageDetect