NAME

Syntax::Kamelon::Format::Base - Basic formatting module

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(
    formatter => ['Base',
       textfilter => \$textfilter,
       format_table => \%formtab,
       newline => "</br>\n",
       tagend => '</font>',
    ],
);

DESCRIPTION

Syntax::Kamelon::Format::Base provides a basic formatting interface to Syntax::Kamelon. You do not have to create an instance of Base yourself. Kamelon will do that for you. During the parsing process it collects all the parsing information from Kamelon through the Parse method. When all information is collected you can start the formatting through the Format method. It is based on and inherits Template toolkit.

OPTIONS

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

data => ref to hash

Set a user defined hash that is used by the process method. Parsing data is added to this hash.

foldingdepth => integer

This option specifies if the code folding mechanism in Kamelon should be activated and to which nesting depth you want code folding to be detected. If you set it to 0 the codefolding routines are not loaded. With any other value they are and parsing speed will be lower. If you set it to 1 only the top folds will be passed on to the formatter, making it ideal to create an indexed document. If you want all code folding points detected, set it to a high value, like 999 or so. The default value is 0.

format_table => ref to hash

Here you specify what Kamelon should return for each attribute tag. For instance if you are formatting to HTML You might want to make it look like:

 format_table => {
        Alert => '<font class="Alert">'
        Annotation => '<font class="Annotation">'
 },

If you do not specify this option, all attribute tags revert to their name, as in Alert => 'Alert', Annotation => 'Annotation' etc.

The following attribute tags are available:

 Alert              Annotation          Attribute           BaseN
 BuiltIn            Char                Comment             CommentVar
 Constant           ControlFlow         DataType            DecVal
 Documentation      Error               Extension           Float
 Function           Import              Information         Keyword
 Normal             Operator            Others              Preprocessor
 RegionMarker       SpecialChar         SpecialString       String
 Variable           VerbatimString      Warning

The syntax definition XML files have them specified with 'ds' in front of them. When loading the XML file, these are removed.

minfoldsize => integer

Specifies the minimum size, in lines, of a fold. Default is 1 line.

newline => string

Specifies what a newline looks like. By default it is set to "\n". If you are, for example, parsing to HTML you might want to set it to "</br>\n".

lineoffset => integer

Specifies the start line number in the output. If you do not specify this option no line numbers are shown.

outmethod => various

This option is passed on to the process method of the Template Toolkit. It can be a reference to a scalar, a reference to a output file handle, or a filename. You can also set it to 'returnscalar', which is also the default value. If this case the Format method returns the formatted document in a scalar variable.

tagend => string

Specifies the end of a highlight tag. By default it is an empty string.

template => various

This option is passed on to the process method of the Template Toolkit. It can be a reference to a scalar, a reference to a input file handle, or a file name.

textfilter => various

This otion allows you to run every line through a user defined template. A sort of pre-formatting. This means you do not have to rewrite the core template.

ttconfig ref to hash

This is the config hash that is used in Template Tookits constructor. By default it is set to {}.

PUBLIC METHODS

Foldingdepth

Corresponds with the folding option. You can set and get the folding depth here. If the folding depth changes from 0 to something else or vice versa, all the loaded lexers in Kamelon are removed and need to be reloaded.

Folds

Returns a reference to the folds hash.

Format

Usually called through Kamelon. It turns the parsing and folding information into a textstring and returns it.

FormatTable($tagname);

Returns the format data belonging to $tagname. Used by the Builder module. The data is set through the format_table option.

GetData

Use this method if you want to use your own instance of Template Tooolkit instead of TT's internal one. It returns a data structure that looks like this:

 {
    folds => { #the keys of this hash are line numbers
            4 => {
          end => $endline,
                    depth => $folddepth,
                    line => $text,
                    region => $regionname,
            },
            ...
    },
    content => [
       [{ text => $snippet, tag => $tagname}, ...], #this is one line
       ...
    ],
 }

Lines

Returns a reference to the lines array.

OutMethod($various)

Corresponds with the outmethod option. Sets and returns the output method.

Reset

Clears all parser data.

Template($various)

Corresponds with the template option. Sets and returns the template that will be processed by Format.

TextFilter($template)

Corresponds with the textfilter option. Sets and returns the template that is used for preprocessing a line of text.

Toolkit ref to Template Toolkit instance

Corresponds with the toolkit option. Sets and returns the Template Toolkit instance that is used for formatting.

PRIVATE METHODS

FindINC

FoldBegin($regionname)

Called By Kamelon when it encounters a beginRegion attribute in a rule. It collects the line number, the current line that is parsed, and pushes all that to the fold stack in a hash.

FoldEnd($regionname)

Called By Kamelon when it encounters an endRegion attribute in a rule. Pulls the top item from the foldhash. It checks if the fold end occurred in a different line then where it started. If so it passes a valid fold record to the folds hash with the starting line number as key. This hash looks like: $linenumber => { end => $endline, depth => $folddepth, line => $text, region => $regionname, }

FoldStackLevel

Returns the nesting depth of folds.

FoldStackPull

Returns the top item on the foldstack and removes it from the stack.

FoldStackPush($reftohash)

Pushes $reftohash to the fold stack.

FoldStackTop

Returns top item from the fold stack.

Parse(@out)

Called by Kamelon to send the line it just parsed to the formatter.

PreProcessOff($line)

Called when no textfilter is defined. Actually only returns $line.

PreProcessOn($line)

Called when a textfilter is defined. Pre-formats $line using the template defined in TextFilter.

Process

Convenience method. Does the same as process in Template::Toolkit. Adds error reporting and always retuns the processed input as a scalar.

AUTHOR AND COPYRIGHT

This module is written and maintained by:

Hans Jeuken < hanje at cpan dot org >

Copyright (c) 2017 - 2023 by Hans Jeuken, all rights reserved.

Published under the same license as Perl.

SEE ALSO

Syntax::Kamelon, Syntax::Kamelon::Builder, Syntax::Kamelon::Debugger, Syntax::Kamelon::Diagnostics, Syntax::Kamelon::Indexer, Syntax::Kamelon::XMLData, Syntax::Kamelon::Format::ANSI, Syntax::Kamelon::Format::HTML4