NAME

Syntax::SourceHighlight - Perl Binding to GNU Source Highlight

SYNOPSIS

use Syntax::SourceHighlight;

my $hl = Syntax::SourceHighlight::SourceHighlight->new();
my $lm = Syntax::SourceHighlight::LangMap->new();

print $hl->highlightString(
  'my $_ = 42;',
  $lm->getMappedFileName('perl')
);

DESCRIPTION

Source Highlight is a library to format code written in a number of programming languages as text in a number of markup languages.

This binding to the underlying C++ library is very basic, supporting only the essential functionality.

Note that any exceptions thrown by the underlying C++ library are caught by the Perl binding and rethrown using the equivalent of a die statement.

CONSTRUCTORS

Syntax::SourceHighlight::SourceHighlight->new([$output_language])

Creates a new source highlighting control object that formats code using the specified output language.

The output language is a file name resolved relative to the data directory of the control object. The default output language is 'html.outlang'. The default data directory depends on the compilation time setup of the underlying C++ library.

Syntax::SourceHighlight::LangMap->new([[$data_directory], $language_map])

Creates a new language map using the given name and data directory. A language map can be used to determine the correct input language file name for a source file name or a language name.

The language map name is a file name resolved relative to the data directory. The default language map is 'lang.map'. The default data directory depends on the compilation time setup of the underlying C++ library.

METHODS OF Syntax::SourceHighlight::SourceHighlight

$hl->highlightFile($input_file_name, $output_file_name, $input_language)

Highlights the contents of the input file into the output file, using the specified input language definition.

If the input or output file names are the empty string, standard input or output will be used respectively.

$hl->highlightString($input, $input_language, [$input_file_name])

Highlights the contents of the input string using the specified input language definition. The output is again returned as a string.

Optionally, the input may be given a name that can be used by output templates.

$hl->checkLangDef($input_language)

Only check the validity of the language definition file.

If the language definition is valid it simply returns, otherwise, it throws an exception.

$hl->checkOutLangDef($output_language)

Only check the validity of the out language definition file.

If the language definition is valid it simply returns, otherwise, it throws an exception.

$hl->createOutputFileName($input_file_name)

Given the input file name creates an output file name.

PROPERTY SETTERS OF Syntax::SourceHighlight::SourceHighlight

$hl->setDataDir($data_directory_name)

$hl->setStyleFile($style_file_name)

$hl->setStyleCssFile($style_file_name)

$hl->setStyleDefaultFile($style_file_name)

$hl->setTitle($title)

$hl->setCss($css)

$hl->setHeaderFileName($header_file_name)

$hl->setFooterFileName($footer_file_name)

$hl->setOutputDir($output_directory_name)

$hl->setOptimize([$flag])

$hl->setGenerateLineNumbers([$flag])

$hl->setGenerateLineNumberRefs([$flag])

$hl->setLineNumberPad($character)

$hl->setLineNumberAnchorPrefix($prefix)

$hl->setGenerateEntireDoc([$flag])

$hl->setGenerateVersion([$flag])

$hl->setCanUseStdOut([$flag])

$hl->setBinaryOutput([$flag])

$hl->setRangeSeparator($separator)

$hl->setTabSpaces($number)

METHODS OF Syntax::SourceHighlight::LangMap

$lm->getMappedFileName($language)

Determines a suitable input language name for the given human readable language name. If no known input language definition is found, the method returns the empty string.

$lm->getMappedFileNameFromFileName($file_name)

Determines a suitable input language name for the given source file name. If no known input language definition is found, the method returns the empty string.

Note that the default language map shipped with recent versions of the Source Highlight library maps the file name extension '.pl' to Prolog, not Perl :-(

SEE ALSO

The homepage of the original library is at http://www.gnu.org/software/src-highlite/.

The most recent source code for the binding can be found at https://code.launchpad.net/~chust/+junk/SourceHighlight.

AUTHOR

Thomas Chust, <chust@web.de>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Thomas Chust

This binding is in the public domain.