view release on metacpan or  search on metacpan

lib/Syntax/Kamelon.pod  view on Meta::CPAN

=head1 NAME

Syntax::Kamelon - A versatile and fully programmable textual content parser that is extremely well suited for syntax highlighting and code folding 

=head1 SYNOPSIS

 use Syntax::Kamelon;
 
 my @attributes = Syntax::Kamelon->AvailableAttributes;
 my %formtab = ();
 for (@attributes) {
    $formtab{$_} = "<font class=\"$_\">"
 }
 
 my $textfilter = "[%~ text FILTER html FILTER replace('\\040', '&nbsp;') FILTER replace('\\t', '&nbsp;&nbsp;&nbsp;') ~%]";
 my $hl = new Syntax::Kamelon(
    xmlfolder => $xmldir,
    noindex => 1,
    formatter => ['Base',
       textfilter => \$textfilter,
       format_table => \%formtab,
       newline => "</br>\n",
       tagend => '</font>',
    ],
 );
 while (my $in = <IFILE>) {
   $hl->Parse($in);
 }
 print $hl->Format;

=head1 DESCRIPTION

Kamelon is based on the syntax highlighting and code folding algorithms used in the Kate texteditor
of the KDE desktop. It replaces and supercedes Syntax::Highlight::Engine::Kate.

B<This is a rewrite> and not backwards compatible with Syntax::Highlight::Engine::Kate.

Instead of using plugin modules it loads Kate's syntax
highlight definition xml files directly. That makes development and testing a lot easier. It
also opens up a new field of applications like creating your own highlight definitions to 
neatly format your reports. Tons of bugs have been removed. Testing has been redesigned. 
It runs about four times faster than version 0.10 and is up to spec with the latest Kate 
highlight definitions.

=head1 OPTIONS

Kamelons' constructor is called with a paired list of options as parameters. You can use
the following options.

=over 4

=item B<commands> => ref to hash

Specify commands to execute upon a specific match. Example:

 mycommand => sub { my $match = shift; return '' }

You can specify the command in the rules of your own syntax xml file.
Kamelon will give the matched text to your sub as parameter and will parse whatever
your sub returns. Make it always return at least an empty string.

=item B<formatter> => ['Name', @options],

A formatter can be any object that inherits B<Syntax::Kamelon::Format::Base> and 
lives in B<Syntax::Kamelon::Format::Name>. By default 'Base' without options is loaded.
This is convenient if you only use B<ParseRaw>.

See also B<Syntax::Kamelon::Format::Base>, B<Syntax::Kamelon::Format::ANSI>, B<Syntax::Kamelon::Format::HTML4>.

=item B<indexfile> => filename

Specifies the filename where Kamelon stores information about available syntax definitions.

By default it points to 'indexrc' in the B<xmlfolder>. If the file does not exist Kamelon will 
load all xml files in the B<xmlfolder> and attempt to create the indexfile.

Once the indexfile has been created it becomes static. If you add a syntax definition 
XML file to the B<xmlfolder> it will no longer be recognized. Delete the indexfile and reload
Kamelon to fix that. 

See also B<Syntax::Kamelon::Indexer>

=item B<logcall> => ref to sub

By default Kamelon writes all errors to STERR. 

=item B<noindex> => boolean

By default 0. If you set this option Kamelon will ignore the existence of an indexfile
and manually build the index, without saving it. But it gives
you the liberty of adding and removing syntax highlight definition files.

This option comes with a considerable startup penalty.