/ 
Syntax-Highlight-Universal
River stage zero No dependents
/ Syntax::Highlight::Universal

NAME

Syntax::Highlight::Universal - Syntax highlighting module based on the Colorer library

SYNOPSIS

use Syntax::Highlight::Universal;
my $highlighter = Syntax::Highlight::Universal->new;

$highlighter->addConfig("hrc/proto.hrc");
$highlighter->setPrecompiledConfig("precompiled.hrcc");
$highlighter->setCacheDir("/tmp/highlighter");
$highlighter->setCachePrefixLen(2);

my $result = $highlighter->highlight("perl", "printf 'Hello, World!'");

my $callbacks = {
	initParsing => \&myInitHandler,
	addRegion => \&myRegionHandler,
	enterScheme => \&mySchemeStartHandler,
	leaveScheme => \&mySchemeEndHandler,
	finalizeParsing => \&myFinalizeHandler,
};
$highlighter->highlight("perl", "printf 'Hello, World!'", $callbacks);

$highlighter->precompile("precompiled.hrcc");

ABSTRACT

This module can process text of any format and produce a syntax highlighted version of it. The default output format is (X)HTML, custom formats are also possible. It uses parts of the Colorer library and supports its HRC configuration files. Configuration files for about 100 file formats are included.

DESCRIPTION

Syntax::Highlight::Universal doesn't export any functions. You can call its methods either statically or through an object. The result will be the same but we will use the latter here as it is the more convenient of the two.

Creating a new object

my $highlighter = Syntax::Highlight::Universal->new;

This will create a new object and bind it to the Syntax::Highlight::Universal namespace. It can be used to call the methods of this module in a more convenient way. However, this object has no other meaning, any configuration changes performed through it will have global effect.

Processing text

my $result = $highlighter->highlight(FORMAT, TEXT, [CALLBACKS]);

This will process the text and produce its syntax highlighted variant, by default in (X)HTML format.

FORMAT

This must be one of the formats defined in the configuration file. Usually it will be one of the following:

c, cpp, asm, perl, java, idl, pascal, csharp, jsnet,
vbnet, forth, fortran, vbasic, html, css, html-css,
svg-css, jsp, php, php-body, xhtml-trans, xhtml-strict,
xhtml-frameset, asp.vb, asp.js, asp.ps, svg, coldfusion,
jScript, actionscript, vbScript, xml, dtd, xslt,
xmlschema, relaxng, xlink, clarion, Clipper, foxpro,
sqlj, paradox, sql, mysql, Batch, shell, apache, config,
hrc, hrd, delphiform, javacc, javaProperties, lex, yacc,
makefile, regedit, resources, TeX, dcl, vrml, rarscript,
nsi, iss, isScripts, c1c, ada, abap4, AutoIt, awk, dssp,
adsp, Baan, cobol, cache, eiffel, icon, lisp, matlab,
modula2, picasm, python, rexx, ruby, sml, ocaml, tcltk,
sicstusProlog, turboProlog, verilog, vhdl, z80, asm80,
filesbbs, diff, messages, text, default
TEXT

The text to be processed, either as a string or as a reference to a list of lines (without the newline symbols)

CALLBACKS

Optional parameter, a hash reference defining the functions to be called during parsing of the text (all hash entries are optional). If this parameter is omitted it will be set to:

{
	initParsing => \&Syntax::Highlight::Universal::initParsing,
	addRegion => \&Syntax::Highlight::Universal::addRegion,
	enterScheme => \&Syntax::Highlight::Universal::enterScheme,
	leaveScheme => \&Syntax::Highlight::Universal::leaveScheme,
	finalizeParsing => \&Syntax::Highlight::Universal::finalizeParsing,
}

The callbacks are explained in detail below.

Return value

If the callbacks parameter is omitted, the return value is the syntax highlighted version of the text in (X)HTML. The regions are translated into <span> elements, the class attribute is set to the region's name. The resulting code can be formatted via CSS.

If the default callback functions are overridden, either the return value of the initParsing or finalizeParsing callback will be returned, depending on whether initParsing returns a value.

Importing configuration files

$highlighter->addConfig(FILE, ...);

This method imports a list of configuration files. They replace hrc/proto.hrc that is used by default.

FILE

The file containing a list of file format definitions. If this file can't be found in the current directory, the module will look for it in its library directory as well. For information on the format of the file, see HRC reference (http://colorer.sf.net/hrc-ref/).

Precompiling configuration files

$highlighter->precompile(FILE);

Parsing HRC files takes a while, resulting in a high time demand for processing of the first text. In order to speed it up, configuration files can be preprocessed into a binary file. The time to load the configuration will be reduced by a factor 5-10, memory usage also decreases. However, the binary file can't be changed and has to be rebuilt every time changes are made on the HRC files. Furthermore it isn't platform independent and should be always rebuilt when moving to another server/another operating system.

This method will process the current configuration and write it into a file in a binary format. It might take some time, the whole configuration needs to be loaded into memory.

make test will create a precompiled configuration file precompiled.hrcc. It can be copied into the library directory of the module and used instead of the HRC configuration.

FILE

Name of the file to be written

Loading a precompiled configuration

$highlighter->setPrecompiledConfig([FILE]);

This method will load a precompiled configuration file. It can only be called once, combining several files isn't yet supported. addConfig can't be used either when using a precompiled configuration.

FILE

The precompiled configuration file. If this file can't be found in the current directory, the module will look for it in its library directory as well. You can omit this parameter, the file precompiled.hrcc will be loaded then.

Setting a cache directory

$highlighter->setCacheDir(DIR);

This method will enable caching of the results and define a cache directory. Then, a text will only go through the complete processing if there is no file for it in the cache directory. Syntax highlighting takes time, therefore caching is generally a good idea. However, it won't be of much use if the texts processed are always different. Other problem is the cleaning of the cache directory. The cache files are never removed, this has to be done separately, e.g. with a cron script emptying the cache directory every two days.

Caching only works if the default callback functions are used.

DIR

The cache directory. The module might create subdirectories, depending on the prefix length setting (see setCachePrefixLen).

Setting cache prefix length

$highlighter->setCachePrefixLen(LENGTH);

This method defines how many characters should be used for subdirectories of the cache directory.

LENGTH

If this parameter is zero, the files will be put directly into the cache directory. Otherwise subdirectories with names of specified length (the first characters of the file name) will be created to allow faster access to large amounts of files. The file name will contain the remaining of the 32 characters. Default value is 2, meaning that there can be up to 256 subdirectories.

Callbacks

All callback functions get a reference to the list of text lines as their first parameter. The other parameters differ:

initParsing(LINES, FORMAT)

finalizeParsing(LINES, FORMAT)

These functions are called before/after the parsing of the text. If initParsing returns a value, parsing will be aborted and highlight will return this value. This can be used for caching to return cached results before even starting parsing. Otherwise parsing will proceed normally and the return value of finalizeParsing will be returned.

FORMAT

The text format, same as the parameter to highlight

addRegion(LINES, LINENO, START, END, REGIONS)

Called whenever a new region inside a line is identified.

LINENO

Line number, zero-based. This parameter can only increase, Colorer never goes back to a previous line.

START

The position of region start within the line

END

The position of region end (the first character not belonging to the region) within the line

REGIONS

Reference to a list of region names. First in the list is the name of the actual region found, the names of its parent regions (more generally defined regions whose meaning includes the currently found) are following.

enterScheme(LINES, LINENO, START, END, SCHEME, REGIONS)

leaveScheme(LINES, LINENO, START, END, SCHEME, REGIONS)

Called whenever the start/end of a scheme is found. The parameters are all the same as for addRegion, except:

SCHEME

Name of the scheme found

SEE ALSO

Colorer homepage

http://colorer.sf.net/

HRC reference

http://colorer.sf.net/hrc-ref/

AUTHOR

Wladimir Palant, <palant@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Wladimir Palant

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 661:

=back without =over