.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Syntax::Highlight::Perl::Improved 3pm"
.TH Syntax::Highlight::Perl::Improved 3pm "2008-03-12" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Syntax::Highlight::Perl::Improved \- Highlighting of Perl Syntactical Structures
.SH "VERSION"
.IX Header "VERSION"
This file documents Syntax::Highlight::Perl::Improved version \fB1.0\fR.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # simple procedural
\&    use Syntax::Highlight::Perl::Improved \(aq:BASIC\(aq;  # or \(aq:FULL\(aq
.Ve
.PP
.Vb 1
\&    print format_string($my_string);
.Ve
.PP
.Vb 2
\&    # OO
\&    use Syntax::Highlight::Perl::Improved;
.Ve
.PP
.Vb 2
\&    my $formatter = new Syntax::Highlight::Perl::Improved;
\&    print $formatter\->format_string($my_string);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \fImay\fR be made
in the future for tasks related to \*(L"back\-tracking\*(R" (ie, re-doing a single line in the middle of
a stream) such as speeding up state copying.
.Sh "Constructors"
.IX Subsection "Constructors"
.RS 4
The only constructor provided is \f(CW\*(C`new()\*(C'\fR.  When called on an existing object, \f(CW\*(C`new()\*(C'\fR will
create a new \fI\f(BIcopy\fI\fR of that object.  Otherwise, \f(CW\*(C`new()\*(C'\fR creates a new copy of the (internal)
\&\fIDefault Object\fR.  Note that the use of the procedural syntax modifies the \fIDefault Object\fR
and that those changes \fIwill\fR be reflected in any subsequent \f(CW\*(C`new()\*(C'\fR calls.
.Sh "Formatting"
.IX Subsection "Formatting"
Formatting is done using the \f(CW\*(C`format_string()\*(C'\fR method.  Call \f(CW\*(C`format_string()\*(C'\fR with one or more
strings to format, or it will default to using \f(CW$_\fR.
.Sh "Setting and Getting Formats"
.IX Subsection "Setting and Getting Formats"
You can set the text used for formatting a syntax element using \f(CW\*(C`set_format()\*(C'\fR (or set
the start and end format individually using \f(CW\*(C`set_start_format()\*(C'\fR and \f(CW\*(C`set_end_format()\*(C'\fR,
respectively).
.Sp
You can also retrieve the text used for formatting for an element via \f(CW\*(C`get_start_format()\*(C'\fR
or \f(CW\*(C`get_end_format\*(C'\fR.  Bulk retrieval of the names or values of defined formats is possible
via \f(CW\*(C`get_format_names_list()\*(C'\fR (names), \f(CW\*(C`get_start_format_values_list()\*(C'\fR and \f(CW\*(C`get_end_format_values_list()\*(C'\fR.
.Sp
See \*(L"\s-1FORMAT\s0 \s-1TYPES\s0\*(R" later in this document for information on what format elements can be used.
.Sh "Checking and Setting the State"
.IX Subsection "Checking and Setting the State"
You can check certain aspects of the state of the formatter via the methods: \f(CW\*(C`in_heredoc()\*(C'\fR,
\&\f(CW\*(C`in_string()\*(C'\fR, \f(CW\*(C`in_pod()\*(C'\fR, \f(CW\*(C`was_pod()\*(C'\fR, \f(CW\*(C`in_data()\*(C'\fR, and \f(CW\*(C`line_count()\*(C'\fR.
.Sp
You can reset all of the above states (and a few other internal ones) using \f(CW\*(C`reset()\*(C'\fR.
.Sh "Stable and Unstable Formatting Modes"
.IX Subsection "Stable and Unstable Formatting Modes"
You can set or check the stability of formatting via \f(CW\*(C`unstable()\*(C'\fR.
.Sp
In unstable (\s-1TRUE\s0) mode, formatting is not considered to be persistent with nested formats.
Or, put another way, when unstable, the formatter can only \*(L"remember\*(R" one format at a time
and must reinstate formatting for each token.  An example of unstable formatting is using
\&\s-1ANSI\s0 color escape sequences in a terminal.
.Sp
In stable (\s-1FALSE\s0) 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 \s-1HTML\s0.
.Sh "Substitutions"
.IX Subsection "Substitutions"
Using \f(CW\*(C`define_substitution()\*(C'\fR, 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 \s-1HTML\s0) without them
affecting the way the code is parsed.
.Sp
You can retrieve the current substitutions (as a hash\-ref) via \f(CW\*(C`substitutions()\*(C'\fR.
.RE
.SH "FORMAT TYPES"
.IX Header "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
\&'\s-1DEFAULT\s0' type that is applied to any element who's Format Type does not have a value.
.PP
Several of the Format Types have underscores in their name.  This underscore is special, and
indicates that the Format Type can be \*(L"generalized.\*(R"  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 \*(L"Variable_\*(R".  Thus, if you assign a value to the Format Type \*(L"Variable\*(R",
it will be applied to any type of variable.  Generalized Format Types take precedence over
non-generalized Format Types.  So the value assigned to \*(L"Variable\*(R" would be applied to
\&\*(L"Variable_Scalar\*(R", even if \*(L"Variable_Scalar\*(R" had a value explicitly assigned to it.
.PP
You can also define a \*(L"short\-cut\*(R" 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 \*(L"Variable_Scalar\*(R" would be \*(L"Scalar\*(R".  Short-cut names have the least precedence and are only
assigned if neither the generalized Type name, nor the full Type name have values.
.PP
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.
.IP "Comment_Normal" 4
.IX Item "Comment_Normal"
A normal Perl comment.  Starts with '#' and goes until the end of the line.
.IP "Comment_POD" 4
.IX Item "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'.
.IP "Directive" 4
.IX Item "Directive"
Either the \*(L"she\-bang\*(R" line at the beginning of the file, or a line directive altering what
the compiler thinks the current line and file is.
.IP "Label" 4
.IX Item "Label"
A loop or statement label (to be the target of a goto, next, last or redo).
.IP "Quote" 4
.IX Item "Quote"
Any string or character that begins or ends a String.  Including, but not necessarily limited to:
quote-like regular expression operators (\f(CW\*(C`m//\*(C'\fR, \f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`tr///\*(C'\fR, etc), a Here-Document terminating
line, the lone period terminating a format, and, of course, normal quotes (\f(CW\*(C`'\*(C'\fR, \f(CW\*(C`"\*(C'\fR, \f(CW\*(C``\*(C'\fR, \f(CW\*(C`q{}\*(C'\fR,
\&\f(CW\*(C`qq{}\*(C'\fR, \f(CW\*(C`qr{}\*(C'\fR, \f(CW\*(C`qx{}\*(C'\fR).
.IP "String" 4
.IX Item "String"
Any text within quotes, \f(CW\*(C`format\*(C'\fRs, Here\-Documents, Regular Expressions, and the like.
.IP "Subroutine" 4
.IX Item "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.
.IP "Variable_Scalar" 4
.IX Item "Variable_Scalar"
A scalar variable.
.Sp
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 \fItype\fR 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 \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`%\*(C'\fR, or \f(CW\*(C`*\*(C'\fR) tells you the type of value being
used, and the color (hopefully) tells you the type of variable being used to get that value.
.Sp
(See \*(L"\s-1KNOWN\s0 \s-1ISSUES\s0\*(R" for information about when this doesn't work quite right.)
.IP "Variable_Array" 4
.IX Item "Variable_Array"
An array variable (but not usually a slice; see above).
.IP "Variable_Hash" 4
.IX Item "Variable_Hash"
A hash variable.
.IP "Variable_Typeglob" 4
.IX Item "Variable_Typeglob"
A typeglob.  Note that typeglobs not beginning with an asterisk (*) (eg: filehandles) are formatted
as barewords.  This is because, well, they are.
.IP "Whitespace" 4
.IX Item "Whitespace"
Whitespace.  Not usually formatted but it can be.
.IP "Character" 4
.IX Item "Character"
A special, or backslash\-escaped, character.  For example: \f(CW\*(C`\en\*(C'\fR (newline), or \f(CW\*(C`\ed\*(C'\fR (digits).
.Sp
Only occurs within strings or regular expressions.
.IP "Keyword" 4
.IX Item "Keyword"
A Perl keyword.  Some examples include: my, local, sub, next.
.Sp
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.
.Sp
The list of keywords can be found (and overloaded) in the variable
\&\f(CW$Syntax::Highlight::Perl::Improved::keyword_list_re\fR as a pre-compiled regular expression.
.IP "Builtin_Function" 4
.IX Item "Builtin_Function"
A Perl built-in function, called as a function (ie, using parentheses).
.Sp
The list of built-in functions can be found (and overloaded) in the variable
\&\f(CW$Syntax::Highlight::Perl::Improved::builtin_list_re\fR as a pre-compiled regular expression.
.IP "Builtin_Operator" 4
.IX Item "Builtin_Operator"
A Perl built-in function, called as a list or unary operator (ie, without using parentheses).
.Sp
The list of built-in functions can be found (and overloaded) in the variable
\&\f(CW$Syntax::Highlight::Perl::Improved::builtin_list_re\fR as a pre-compiled regular expression.
.IP "Operator" 4
.IX Item "Operator"
A Perl operator.
.Sp
The list of operators can be found (and overloaded) in the variable
\&\f(CW$Syntax::Highlight::Perl::Improved::operator_list_re\fR as a pre-compiled regular expression.
.IP "Bareword" 4
.IX Item "Bareword"
A bareword.  This can be user-defined subroutine called without parentheses, a typeglob used
without an asterisk (*), or just a plain old bareword.
.IP "Package" 4
.IX Item "Package"
The name of a package or pragmatic module.
.Sp
Note that this does not apply to the package portion of a fully qualified variable name.
.IP "Number" 4
.IX Item "Number"
A numeric literal.
.IP "Symbol" 4
.IX Item "Symbol"
A symbol (ie, non-operator punctuation).
.IP "CodeTerm" 4
.IX Item "CodeTerm"
The special tokens that signal the end of executable code and the begining of the
\&\s-1DATA\s0 section.  Specifically, '\f(CW\*(C`_\|_END_\|_\*(C'\fR' and '\f(CW\*(C`_\|_DATA_\|_\*(C'\fR'.
.IP "\s-1DATA\s0" 4
.IX Item "DATA"
Anything in the \s-1DATA\s0 section (see \f(CW\*(C`CodeTerm\*(C'\fR).
.SH "PROCEDURAL vs. OBJECT ORIENTED"
.IX Header "PROCEDURAL vs. OBJECT ORIENTED"
Syntax::Highlight::Perl::Improved uses \s-1OO\s0 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.
.PP
It is actually recommended that you use the \s-1OO\s0 interface, as this allows you to instantiate
multiple, concurrent-yet-separate formatters.  Though I cannot think of \fIwhy\fR you would \fIneed\fR
multiple formatters instantiated. :\-)
.PP
One point to note: the \f(CW\*(C`new()\*(C'\fR 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 \f(CW\*(C`set_format()\*(C'\fR procedurally just before creating a batch of new
objects to define default Formats for them all) but will most likely lead to trouble.
.SH "METHODS"
.IX Header "METHODS"
.IP "new \s-1PACKAGE\s0" 4
.IX Item "new PACKAGE"
.PD 0
.IP "new \s-1OBJECT\s0" 4
.IX Item "new OBJECT"
.PD
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).
.IP "reset" 4
.IX Item "reset"
Resets the object's internal state.  This breaks out of strings and here\-docs, ends PODs,
resets the line\-count, and otherwise gets the object back into a \*(L"normal\*(R" state to begin
processing a new stream.
.Sp
Note that this does \fB\f(BInot\fB\fR reset any user options (including formats and format stability).
.IP "unstable \s-1EXPR\s0" 4
.IX Item "unstable EXPR"
.PD 0
.IP "unstable" 4
.IX Item "unstable"
.PD
Returns true if the formatter is in unstable mode.
.Sp
If called with a non-zero number, puts the formatter into unstable formatting mode.
.Sp
In unstable mode, it is assumed that formatting is not persistent one token to the
next and that each token must be explicitly formatted.
.IP "in_heredoc" 4
.IX Item "in_heredoc"
Returns true if the next string to be formatted will be inside a Here\-Document.
.IP "in_string" 4
.IX Item "in_string"
Returns true if the next string to be formatted will be inside a multi-line string.
.IP "in_pod" 4
.IX Item "in_pod"
Returns true if the formatter would consider the next string passed to it as begin within
a \s-1POD\s0 structure.  This is false immediately before any \s-1POD\s0 instigators
(\f(CW\*(C`=pod\*(C'\fR, \f(CW\*(C`=head1\*(C'\fR, \f(CW\*(C`=item\*(C'\fR, etc), true immediately after an instigator, throughout the \s-1POD\s0 and
immediately before the \s-1POD\s0 terminator (\f(CW\*(C`=cut\*(C'\fR), and false immediately after the \s-1POD\s0 terminator.
.IP "was_pod" 4
.IX Item "was_pod"
Returns true if the last line of the string just formatted was part of a \s-1POD\s0 structure.
This includes the \f(CW\*(C`/^=\ew+/\*(C'\fR \s-1POD\s0 instigators and terminators.
.IP "in_data" 4
.IX Item "in_data"
Returns true if the next string to be formatted will be inside
the \s-1DATA\s0 section (ie, follows a \f(CW\*(C`_\|_DATA_\|_\*(C'\fR or \f(CW\*(C`_\|_END_\|_\*(C'\fR tag).
.IP "line_count" 4
.IX Item "line_count"
Returns the number of lines processed by the formatter.
.IP "substitutions" 4
.IX Item "substitutions"
Returns a reference to the substitution table used.  The substitution
table is a hash whose keys are the strings to be replaced, and whose values
are what to replace them with.
.IP "define_substitution \s-1HASH_REF\s0" 4
.IX Item "define_substitution HASH_REF"
.PD 0
.IP "define_substitution \s-1LIST\s0" 4
.IX Item "define_substitution LIST"
.PD
Allows user to define certain characters that will be substituted
before formatting is done (but after they have been processed for
meaning).
.Sp
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.
.Sp
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.)
.IP "set_start_format \s-1HASH_REF\s0" 4
.IX Item "set_start_format HASH_REF"
.PD 0
.IP "set_start_format \s-1LIST\s0" 4
.IX Item "set_start_format LIST"
.PD
Given either a list of keys/values, or a reference to a hash of keys/values,
copy them into the object's Formats list.
.IP "set_end_format \s-1HASH_REF\s0" 4
.IX Item "set_end_format HASH_REF"
.PD 0
.IP "set_end_format \s-1LIST\s0" 4
.IX Item "set_end_format LIST"
.PD
Given either a list of keys/values, or a reference to a hash of keys/values,
copy them into the object's Formats list.
.IP "set_format \s-1LIST\s0" 4
.IX Item "set_format LIST"
Sets the formatting string for one or more formats.
.Sp
You should pass a list of keys/values where the keys are the format names and the values
are references to arrays containing the starting and ending formatting strings (in that order)
for that format.
.IP "get_start_format \s-1LIST\s0" 4
.IX Item "get_start_format LIST"
Retrieve the string that is inserted to begin a given format type (starting format string).
.Sp
The names are looked for in the following order:
.Sp
\&\fBFirst:\fR Prefer the names joined by underscore, from most general to least.  For example, given
(\*(L"Variable\*(R", \*(L"Scalar\*(R"): \*(L"Variable\*(R" then \*(L"Variable_Scalar\*(R".
.Sp
\&\fBSecond:\fR Then try each name singly, in reverse order.  For example,
\&\*(L"Scalar\*(R" then \*(L"Variable\*(R".
.Sp
See \*(L"\s-1FORMAT\s0 \s-1TYPES\s0\*(R" for more information.
.IP "get_end_format \s-1LIST\s0" 4
.IX Item "get_end_format LIST"
Retrieve the string that is inserted to end a given format type (ending format string).
.IP "get_format_names_list" 4
.IX Item "get_format_names_list"
Returns a list of the \fInames\fR of all the Formats defined.
.IP "get_start_format_values_list" 4
.IX Item "get_start_format_values_list"
Returns a list of the \fIvalues\fR of all the start Formats defined (in the same order
as the names returned by \f(CW\*(C`get_format_names_list()\*(C'\fR).
.IP "get_end_format_values_list" 4
.IX Item "get_end_format_values_list"
Returns a list of the \fIvalues\fR of all the end Formats defined (in the same order
as the names returned by \f(CW\*(C`get_format_names_list()\*(C'\fR).
.IP "format_string \s-1LIST\s0" 4
.IX Item "format_string LIST"
Formats one or more strings of Perl code.  If no strings are specified, defaults to \f(CW$_\fR.
Returns the list of formatted strings (or the first string formatted if called in scalar context).
.Sp
\&\fBNote:\fR  The end of the string is considered to be the end of a line, regardless of whether
or not there is a trailing line-break (but trailing line-breaks will \fInot\fR cause an extra, empty
line).
.Sp
\&\fBAnother Note:\fR  The function actually uses \f(CW$/\fR to determine line\-breaks, unless \f(CW$/\fR is
set to \f(CW\*(C`\en\*(C'\fR (newline).  If \f(CW$/\fR \fIis\fR \f(CW\*(C`\en\*(C'\fR, then it looks for the first match
of \f(CW\*(C`m/\er?\en|\en?\er/\*(C'\fR in the string and uses that to determine line\-breaks.  This is to make
it easy to handle non-unix text.  Whatever characters it ends up using as line-breaks are
preserved.
.IP "format_token \s-1TOKEN\s0, \s-1LIST\s0" 4
.IX Item "format_token TOKEN, LIST"
Returns \s-1TOKEN\s0 wrapped in the start and end Formats corresponding to \s-1LIST\s0
(as would be returned by \f(CW\*(C`get_start_format( LIST )\*(C'\fR and \f(CW\*(C`get_end_format( LIST )\*(C'\fR,
respectively).
.Sp
No syntax checking is done on \s-1TOKEN\s0 but substitutions defined with \f(CW\*(C`define_substitution()\*(C'\fR
are performed.
.SH "KNOWN ISSUES or LIMITATIONS"
.IX Header "KNOWN ISSUES or LIMITATIONS"
.IP "\(bu" 4
Barewords used as keys to a hash are formatted as strings.  This is Good.  They should
not be, however, if they are not the only thing within the curly braces.  That can be
fixed.
.IP "\(bu" 4
This version does not handle formats (see \fIperlform\fR\|(1)) very well.  It treats them as
Here-Documents and ignores the rules for comment lines, as well as the fact that picture
lines are not supposed to be interpolated.  Thus, your picture lines will look strange
with the '@'s being formatted as array variables (albeit, invalid ones).
Ideally, it would also treat value lines as normal Perl code and format accordingly.
I think I'll get to the comment lines and non-interpolating picture lines first.
If/When I do get this fixed, I will most likely add a format type of 'Format' or something,
so that they can be formatted differently, if so desired.
.IP "\(bu" 4
This version does not handle Regular Expression significant characters.  It simply treats
Regular Expressions as interpolated strings.
.IP "\(bu" 4
User-defined subroutines, called without parentheses, are formatted as barewords.
This is because there is no way to tell them apart from barewords without parsing
the code, and would require us to go as far as perl does when doing the \f(CW\*(C`\-c\*(C'\fR check
(ie, executing \s-1BEGIN\s0 and \s-1END\s0 blocks and the like).  That's not going to happen.
.IP "\(bu" 4
If you are indexing (subscripting) an array or hash, the formatter tries to figure
out the \*(L"real\*(R" variable class by looking at how you index the variable.  However, if
you do something funky (but legal in Perl) and put line-breaks or comments between
the variable class character ($) and your identifier, the formatter will get confused
and treat your variable as a scalar.  Until it finds the index character.  Then it
will format the scalar class character ($) as a scalar and your identifier as
the \*(L"correct\*(R" class.
.IP "\(bu" 4
If you put a line-break between your variable identifier and it's indexing character (see
above), which is also legal in Perl, the formatter will never find it and treat your
variable as a scalar.
.IP "\(bu" 4
If you put a line-break between a bareword hash-subscript and the hash variable, or between
a bareword and its associated \f(CW\*(C`=>\*(C'\fR operator, the bareword will not be formatted correctly
(as a string).  \fI(Noticing a pattern here?)\fR
.SH "BUGS"
.IX Header "BUGS"
Bug reports are always welcome. Email me at b<davidcyl@cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
David C.Y. Liu b<davidcyl@cpan.org>
.PP
based on code by
Cory Johns \fBdarkness@yossman.net\fR
.PP
Copyright (c) 2004 David C.Y. Liu.  This library is free software; you can
redistribute and/or modify it under the same conditions as Perl itself.
.SH "TO DO"
.IX Header "TO DO"
\&\fINote:\fR This is Cory John's todo list, not mine. Currently none of these features are
planned for the near future.
.IP "1" 4
.IX Item "1"
Improve handling of regular expressions.  Add support for regexp-special characters.
Recognize the /e option to the substitution operator (maybe).
.IP "2" 4
.IX Item "2"
Improve handling of formats.  Don't treat format definitions as interpolating.  Handle
format\-comments.  Possibly format value lines as normal Perl code.
.IP "3" 4
.IX Item "3"
Create in-memory deep-copy routine to replace \f(CW\*(C`eval(Data::Dumper)\*(C'\fR deep\-copy.
.IP "4" 4
.IX Item "4"
Generalize state transitions (\f(CW\*(C`reset()\*(C'\fR and, in the future, \f(CW\*(C`copy_state()\*(C'\fR) to use
non-hard-coded keys and values for state variables.  Probably will extrapolate them into an
overloadable hash, and use the aforementioned deep-copy to assign them.
.IP "5" 4
.IX Item "5"
Create a method to save or copy states between objects (\f(CW\*(C`copy_state()\*(C'\fR).  Would be useful for
using this module in an editor.
.IP "6" 4
.IX Item "6"
Add support for greater-than-one length special characters.  Specifically, octal,
hexidecimal, and control character codes.  For example, \f(CW\*(C`\e644\*(C'\fR, \f(CW\*(C`\ex1a4\*(C'\fR or \f(CW\*(C`\ec[\*(C'\fR.
.SH "REVISIONS"
.IX Header "REVISIONS"
.Sh "05\-03\-2004  David C.Y. Liu (Version 1.01)"
.IX Subsection "05-03-2004  David C.Y. Liu (Version 1.01)"
.IP "\(bu" 4
Added 'our' to the keywords list.
.IP "\(bu" 4
Fixed bug that prevented interpolation inside \fIqq()\fR quotes.
.IP "\(bu" 4
Renamed to Syntax::Highlight::Perl::Improved.
.Sh "04\-04\-2001  Cory Johns"
.IX Subsection "04-04-2001  Cory Johns"
.IP "\(bu" 4
Fixed problem with special characters not formatting inside of Here\-Documents.
.IP "\(bu" 4
Fixed bug causing hash variables to format inside of Here\-Documents.
.Sh "03\-30\-2001  Cory Johns"
.IX Subsection "03-30-2001  Cory Johns"
.IP "\(bu" 4
Fixed bug where quote-terminators were checked for inside of Here\-Documents.
.Sh "03\-29\-2001  Cory Johns"
.IX Subsection "03-29-2001  Cory Johns"
.IP "\(bu" 4
Moved token processing tests from \fI_format_line()\fR into \fI_process_token()\fR
(where they should've been all along), generally making \fI_format_line()\fR
more logical.  Contemplating extrapolating the tokenizing and token
loop into its own subroutine to avoid all the recursive calls.
.IP "\(bu" 4
Fixed bug that caused special characters to be recognized outside of
strings.
.IP "\(bu" 4
Added \f(CW$VERSION\fR variable.
.IP "\(bu" 4
Added support for different types of literal numbers: floating point,
exponential notation (eg: 1.3e10), hexidecimal, and underscore\-separated.
.IP "\(bu" 4
Added the \f(CW\*(C`CodeTerm\*(C'\fR and \f(CW\*(C`DATA\*(C'\fR Formats.
.Sh "03\-27\-2001  Cory Johns"
.IX Subsection "03-27-2001  Cory Johns"
.IP "\(bu" 4
Added \fIwas_pod()\fR and updated the documentation for \fIin_pod()\fR.
.Sh "03\-20\-2001  Cory Johns"
.IX Subsection "03-20-2001  Cory Johns"
.IP "\(bu" 4
Added support for Perl formats (ie, `\f(CW\*(C`format = ...\*(C'\fR').