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 ACCESSORS OF Syntax::SourceHighlight::SourceHighlight

$hl->setDataDir($data_directory_name)

Path for several configuration files.

$hl->setStyleFile($style_file_name)

The style file.

$hl->setStyleCssFile($style_file_name)

The css style file.

$hl->setStyleDefaultFile($style_file_name)

The style defaults file.

$hl->setTitle($title)

The title of the output document. Defaults to the source file name.

$hl->setCss($css)

The value for the css.

$hl->setHeaderFileName($header_file_name)

The file name of the header.

$hl->setFooterFileName($footer_file_name)

The file name of the footer.

$hl->setOutputDir($output_directory_name)

The directory for output files.

$hl->setOptimize([$flag])

Whether to optmize output. For example adiacent text parts belonging to the same element will be buffered and generated as a single text part.

$hl->setGenerateLineNumbers([$flag])

Whether to generate line numbers.

$hl->setGenerateLineNumberRefs([$flag])

Whether to generate line numbers with references.

$hl->setLineNumberPad($character)

The line number padding char. Defaults to "0".

$hl->setLineNumberAnchorPrefix($prefix)

The prefix for the line number anchors.

$hl->setGenerateEntireDoc([$flag])

Whether to generate an entire document. Defaults to false.

$hl->setGenerateVersion([$flag])

Whether to generate the program version in the output file. Defaults to true.

$hl->setCanUseStdOut([$flag])

Whether we can use stdout for generating the output. Defaults to true.

$hl->setBinaryOutput([$flag])

Whether to open output files in binary mode. Defaults to false.

$hl->setRangeSeparator($separator)

The separator for ranges.

$hl->setTabSpaces($number)

If greater than 0 it means that tabs will be replaced by that many blank characters.

$hl->setHighlightEventListener($sub_name | $sub_ref)

A callback to be invoked on each highlighting event. Highlighting events are objects of the class Syntax::SourceHighlight::HighlightEvent.

The highlighting event objects passed to the callback are roots of object graphs valid only during the dynamic scope of the callback execution.

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

PROPERTY ACCESSORS OF Syntax::SourceHighlight::LangMap

$lm->langNames()

An array reference containing all known human readable language names known to the language map.

$lm->mappedFileNames()

An array reference containing all known file names of language definitions known to the language map.

PROPERTY ACCESSORS OF Syntax::SourceHighlight::HighlightEvent

$evt->type()

The type of event. The value is == to one of the following constants:

$Syntax::SourceHighlight::HighlightEvent::FORMAT

A standard formatting event.

$Syntax::SourceHighlight::HighlightEvent::FORMATDEFAULT

Formatting something as normal.

$Syntax::SourceHighlight::HighlightEvent::ENTERSTATE

Entering a new formatting state.

$Syntax::SourceHighlight::HighlightEvent::EXITSTATE

Exiting a formatting state.

$evt->token()

The token of source text corresponding to the event, represented by an object of the class Syntax::SourceHighlight::HighlightToken.

PROPERTY ACCESSORS OF Syntax::SourceHighlight::HighlightToken

$tok->prefix()

An possible part of source text before the matched string.

$tok->isPrefixOnlySpaces()

True value iff the prefix is empty or consists only of whitespace characters.

$tok->suffix()

A possible part of source text after the matched string.

$tok->matchedSize()

The size of the whole match.

$tok->matched()

An array reference containing strings of the form "$element_name:$source_text". The $element_name part depends on the source language definition and usually classifies the type of source text, for example whether it is a variable name or a keyword.

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.