/ 
Syntax-Kamelon-0.14
River stage one • 3 direct dependents • 4 total dependents
/ Syntax::Kamelon::Format::Base

NAME

Syntax::Kamelon::Format::Base

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

If you use the HighlightAndFormat method, every attribute tag expects a reference of a list with two values. The first one is parsed before the matched text. The second one is parsed after the matched text.

If you know which attributes are used by the syntax definition files you are using you do not have to specify all. If you want to play it safe, specify all available attribute tags.

If you do not specify this option, Kamelon will return the attribute tag name.

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.

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 < hansjeuken at xs4all dot nl>

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

Published under the GPLV3 license

SEE ALSO

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