ActiveState::Scineplex(3)

NAME
ActiveState::Scineplex - Perl extension to access Scineplex code lexer.

SYNOPSIS
  use ActiveState::Scineplex qw(Annotate);
  $color_info = Annotate($code, $lang, %options);

DESCRIPTION
Scineplex is a C library for heuristic parsing of source code in various languages. Scineplex is based on the Scintilla sources. The "ActiveState::Scineplex" module provide a Perl interface to this library.

Currently this module implements an interface consisting of one function, Annotate, which returns a scineplex-driven colorization for one or more lines of source code. It either returns a string giving the colorization or throws an exception.

    $color_info = Annotate($code, $lang, %options);

The $code is one or more lines of source-code to be analyzed passed as a single string. The lines are separated by any newline sequence.

The $lang argument can be one of 'perl', 'python', 'ruby', 'vbscript', or 'xslt'. The default is 'perl'.

Additional %options can be passed as key/value pairs. The following options are supported (defaults in parentheses):

    outputFormat => 'html' | 'json' | 'line' | 'classic' ('line')
    parsingStartState => number (0)
    DumpSource => 0 | 1 (0)
    DumpEndState => 0 | 1 (0)
    DumpFoldLevels => 0 | 1 (0)
    StopAfterDataSectionLine1 => 0 | 1 (0)

The "outputFormat" is the most important option. In "classic" mode, "Annotate" echos back each character on the start of a line, followed by separating white-space and its style value:

    $res = Annotate('$abc = 3;', 'perl', outputFormat => 'classic');
    print $res;

    $       12
    a       12
    b       12
    c       12
    chr(32) 0
    =       10
    chr(32) 0
    3       4
    ;       10
    chr(10) 0

Symbolic names for the numeric style values can be looked up in the %SCE_TOKEN hash (exportable). For example $SCE_TOKEN{perl}{12} is the string "SCE_PL_SCALAR".

Setting "outputFormat" to "line" gives a terser output, and represents each numeric style with the character corresponding to the style added to the ASCII value of character '0':

    $res = Annotate('$abc = 3;', 'perl', outputFormat => 'line');
    print $res;

    <<<<0:04:

Setting "outputFormat" to "html" returns an HTML-encoded string containing the original code wrapped in "span" tags with generic classes with names like "variable", "operator", etc. This kind of output is designed to be wrapped in "pre" tags, and styled with a CSS file of that contains rules like

    pre span.comments {
      color: 0x696969;
      font-style: italic;
    }

Default text is not placed in a span tag.

Setting "outputFormat" to "json" returns a JSON array of arrays. Each one of the inner arrays contains a generic style label together with the span in positions; [$tag, $line, $col, $len]. The returned JSON array will also be valid Perl code and can be converted to a Perl array using Perl's builtin "eval" function.

Example:

    $res = Annotate('$abc = 3;', 'perl', outputFormat => 'json');
    print $res;
    $array = eval $res;

    [
     ["variable",1,0,4],
     ["operator",1,5,1],
     ["number",1,7,1],
     ["operator",1,8,1]
    ]

The "parsingStartState" setting should be used only when you know that the code starts with a given style, such as lines 3-5 of a multi-line string.

The "DumpSource" flag is used only with "line" output. It is intended mostly for human consumption, and produces output like the following:

    $res = Annotate('$abc = 3;', 'perl', DumpSource=>1);
    print $res;

    $abc = 3;
    <<<<0:04:

The "DumpEndState" is used only in "line" mode, and gives the styles for whichever characters constitute the line-end sequence:

    $res = Annotate(qq($abc = 3;\r\n), 'perl', DumpSource=>1, DumpEndState=>1);
    print $res;

    $abc = 3;
    <<<<0:04:00

The "DumpFoldLevels" is used only in "line" mode, and gives the fold levels as a 4-hex-digit sequence in a leading column.

    $res = Annotate(qq(if(1) {\n$abc = 3;\n}\n), 'perl', DumpSource=>1, DumpEndState=>1);
    print $res;

    2400 if(1) {
         55:4:0:
    0401 $abc = 3
         <<<<0:04
    0401 }
         :

The "StopAfterDataSectionLine1" is used only for Perl code in "line" mode.

SEE ALSO
Info on scintilla available at http://www.scintilla.org.

COPYRIGHT
Copyright (C) 2005 by ActiveState Software Inc.