PEAR :: Manual :: Text

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
SQL
XML

There are diferent 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:

Przykład 60-5. Highlighting a SQL query


<?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:

Przykład 60-6. Using the console renderer


<?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:

Przykład 60-7. Options for the HTML renderer


<?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:

Tabela 60-1. Possible options for the renderer classes

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.
`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`.)