Syntax::Highlight::Perl::Improved - Highlighting of Perl Syntactical Structures

FORMAT TYPES
PROCEDURAL vs. OBJECT ORIENTED
KNOWN ISSUES or LIMITATIONS
BUGS
AUTHOR
TO DO
REVISIONS

05-03-2004 David C.Y. Liu (Version 1.01)
04-04-2001 Cory Johns
03-30-2001 Cory Johns
03-29-2001 Cory Johns
03-27-2001 Cory Johns
03-20-2001 Cory Johns

VERSION

This file documents Syntax::Highlight::Perl::Improved version 1.0.

SYNOPSIS

    # simple procedural
    use Syntax::Highlight::Perl::Improved ':BASIC';  # or ':FULL'

    print format_string($my_string);


    # OO
    use Syntax::Highlight::Perl::Improved;

    my $formatter = new Syntax::Highlight::Perl::Improved;
    print $formatter->format_string($my_string);

DESCRIPTION

This module provides syntax highlighting for Perl code. The design bias is roughly line-oriented and streamed (ie, processing a file line-by-line in a single pass). Provisions may be made in the future for tasks related to ``back-tracking'' (ie, re-doing a single line in the middle of a stream) such as speeding up state copying.

Constructors

The only constructor provided is new(). When called on an existing object, new() will create a new copy of that object. Otherwise, new() creates a new copy of the (internal) Default Object. Note that the use of the procedural syntax modifies the Default Object and that those changes will be reflected in any subsequent new() calls.

Formatting

Formatting is done using the format_string() method. Call format_string() with one or more strings to format, or it will default to using $_.

Setting and Getting Formats

You can set the text used for formatting a syntax element using set_format() (or set the start and end format individually using set_start_format() and set_end_format(), respectively).

You can also retrieve the text used for formatting for an element via get_start_format() or get_end_format. Bulk retrieval of the names or values of defined formats is possible via get_format_names_list() (names), get_start_format_values_list() and get_end_format_values_list().

See FORMAT TYPES later in this document for information on what format elements can be used.

Checking and Setting the State

You can check certain aspects of the state of the formatter via the methods: in_heredoc(), in_string(), in_pod(), was_pod(), in_data(), and line_count().

You can reset all of the above states (and a few other internal ones) using reset().

Stable and Unstable Formatting Modes

You can set or check the stability of formatting via unstable().

In unstable (TRUE) mode, formatting is not considered to be persistent with nested formats. Or, put another way, when unstable, the formatter can only ``remember'' one format at a time and must reinstate formatting for each token. An example of unstable formatting is using ANSI color escape sequences in a terminal.

In stable (FALSE) mode (the default), formatting is considered persistent within arbitrarily nested formats. Even in stable mode, however, formatting is never allowed to span multiple lines; it is always fully closed at the end of the line and reinstated at the beginning of a new line, if necessary. This is to ensure properly balanced tags when only formatting a partial code snippet. An example of stable formatting is HTML.

Substitutions

Using define_substitution(), you can have the formatter substitute certain strings with others, after the original string has been parsed (but before formatting is applied). This is useful for escaping characters special to the output mode (eg, > and < in HTML) without them affecting the way the code is parsed.

You can retrieve the current substitutions (as a hash-ref) via substitutions().

FORMAT TYPES

The Syntax::Highlight::Perl::Improved formatter recognizes and differentiates between many Perl syntactical elements. Each type of syntactical element has a Format Type associated with it. There is also a 'DEFAULT' type that is applied to any element who's Format Type does not have a value.

Several of the Format Types have underscores in their name. This underscore is special, and indicates that the Format Type can be ``generalized.'' This means that you can assign a value to just the first part of the Format Type name (the part before the underscore) and that value will be applied to all Format Types with the same first part. For example, the Format Types for all types of variables begin with ``Variable_''. Thus, if you assign a value to the Format Type ``Variable'', it will be applied to any type of variable. Generalized Format Types take precedence over non-generalized Format Types. So the value assigned to ``Variable'' would be applied to ``Variable_Scalar'', even if ``Variable_Scalar'' had a value explicitly assigned to it.

You can also define a ``short-cut'' name for each Format Type that can be generalized. The short-cut name would be the part of the Format Type name after the underscore. For example, the short-cut for ``Variable_Scalar'' would be ``Scalar''. Short-cut names have the least precedence and are only assigned if neither the generalized Type name, nor the full Type name have values.

Following is a list of all the syntactical elements that Syntax::Highlight::Perl::Improved currently recognizes, along with a short description of what each would be applied to.

Comment_Normal: A normal Perl comment. Starts with '#' and goes until the end of the line.
Comment_POD: Inline documentation. Starts with a line beginning with an equal sign ('=') followed by a word (eg: '=pod') and continuing until a line beginning with '=cut'.
Directive: Either the ``she-bang'' line at the beginning of the file, or a line directive altering what the compiler thinks the current line and file is.
Label: A loop or statement label (to be the target of a goto, next, last or redo).
Quote: Any string or character that begins or ends a String. Including, but not necessarily limited to: quote-like regular expression operators (m//, s///, tr///, etc), a Here-Document terminating line, the lone period terminating a format, and, of course, normal quotes (', ", `, q{}, qq{}, qr{}, qx{}).
String: Any text within quotes, formats, Here-Documents, Regular Expressions, and the like.
Subroutine: The identifier used to define, identify, or call a subroutine (or method). Note that Syntax::Highlight::Perl::Improved cannot recognize a subroutine if it is called without using parentheses or an ampersand, or methods called using the indirect object syntax. It formats those as barewords.
Variable_Scalar: A scalar variable.; Note that (theoretically) this format is not applied to non-scalar variables that are being used as scalars (ie: array or hash lookups, nor references to anything other than scalars). Syntax::Highlight::Perl::Improved figures out (or at least tries to) the actual type of the variable being used (by looking at how you're subscripting it) and formats it accordingly. The first character of the variable (ie, the $, @, %, or *) tells you the type of value being used, and the color (hopefully) tells you the type of variable being used to get that value.; (See KNOWN ISSUES for information about when this doesn't work quite right.)
Variable_Array: An array variable (but not usually a slice; see above).
Variable_Hash: A hash variable.
Variable_Typeglob: A typeglob. Note that typeglobs not beginning with an asterisk (*) (eg: filehandles) are formatted as barewords. This is because, well, they are.
Whitespace: Whitespace. Not usually formatted but it can be.
Character: A special, or backslash-escaped, character. For example: \n (newline), or \d (digits).; Only occurs within strings or regular expressions.
Keyword: A Perl keyword. Some examples include: my, local, sub, next.; Note that Perl does not make any distinction between keywords and built-in functions (at least not in the documentation). Thus I had to make a subjective call as to what would be considered keywords and what would be built-in functions.; The list of keywords can be found (and overloaded) in the variable $Syntax::Highlight::Perl::Improved::keyword_list_re as a pre-compiled regular expression.
Builtin_Function: A Perl built-in function, called as a function (ie, using parentheses).; The list of built-in functions can be found (and overloaded) in the variable $Syntax::Highlight::Perl::Improved::builtin_list_re as a pre-compiled regular expression.
Builtin_Operator: A Perl built-in function, called as a list or unary operator (ie, without using parentheses).; The list of built-in functions can be found (and overloaded) in the variable $Syntax::Highlight::Perl::Improved::builtin_list_re as a pre-compiled regular expression.
Operator: A Perl operator.; The list of operators can be found (and overloaded) in the variable $Syntax::Highlight::Perl::Improved::operator_list_re as a pre-compiled regular expression.
Bareword: A bareword. This can be user-defined subroutine called without parentheses, a typeglob used without an asterisk (*), or just a plain old bareword.
Package: The name of a package or pragmatic module.; Note that this does not apply to the package portion of a fully qualified variable name.
Number: A numeric literal.
Symbol: A symbol (ie, non-operator punctuation).
CodeTerm: The special tokens that signal the end of executable code and the begining of the DATA section. Specifically, '__END__' and '__DATA__'.
DATA: Anything in the DATA section (see CodeTerm).

PROCEDURAL vs. OBJECT ORIENTED

Syntax::Highlight::Perl::Improved uses OO method-calls internally (and actually defines a Default Object that is used when the functions are invoked procedurally) so you will not gain anything (efficiency-wise) by using the procedural interface. It is just a matter of style.

It is actually recommended that you use the OO interface, as this allows you to instantiate multiple, concurrent-yet-separate formatters. Though I cannot think of why you would need multiple formatters instantiated. :-)

One point to note: the new() method uses the Default Object to initialize new objects. This means that any changes to the state of the Default Object (including Format definitions) made by using the procedural interface will be reflected in any subsequently created objects. This can be useful in some cases (eg, call set_format() procedurally just before creating a batch of new objects to define default Formats for them all) but will most likely lead to trouble.

new PACKAGE
new OBJECT: Creates a new object. If called on an existing object, creates a new copy of that object (which is thenceforth totally separate from the original).
unstable: Returns true if the formatter is in unstable mode.; If called with a non-zero number, puts the formatter into unstable formatting mode.; In unstable mode, it is assumed that formatting is not persistent one token to the next and that each token must be explicitly formatted.
define_substitution LIST: Allows user to define certain characters that will be substituted before formatting is done (but after they have been processed for meaning).; If the first parameter is a reference to a hash, the formatter will replace it's own hash with the given one, and subsequent changes to the hash outside the formatter will be reflected.; Otherwise, it will copy the arguments passed into it's own hash, and any substitutions already defined (but not in the parameter list) will be preserved. (ie, the new substitutions will be added, without destroying what was there already.)
set_start_format LIST: Given either a list of keys/values, or a reference to a hash of keys/values, copy them into the object's Formats list.
set_end_format LIST: Given either a list of keys/values, or a reference to a hash of keys/values, copy them into the object's Formats list.