Syntax...t::Perl(3pm)

✨ Syntax::Highlight::Perl 💖

okay bestie, gather round, because this little page right here is Syntax...t::Perl(3pm) from the User Contributed Perl Documentation, and it is the lore drop for Syntax::Highlight::Perl. if you've ever wanted Perl code to look cute and colorful instead of looking like a wall of sad gray text, this is your girl. no cap. 👑

---

💅 NAME

Syntax::Highlight::Perl — Highlighting of Perl Syntactical Structures. literally what it says on the tin, she highlights your Perl's syntactic structures. iconic behavior.

---

🌸 VERSION

this file documents Syntax::Highlight::Perl version 1.0. so like, the whole entire documented vibe is 1.0. ✨

---

🦋 SYNOPSIS

here's the tea, two ways to do the exact same thing:

the simple procedural way (no objects, just vibes):

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

print format_string($my_string);

the OO way (main character energy):

# OO
use Syntax::Highlight::Perl;

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

both slay. pick your fighter. 🫶

---

🎀 DESCRIPTION

so, this module provides syntax highlighting for Perl code. the whole design bias is roughly line-oriented and streamed — meaning it thinks about processing a file line-by-line in a single pass, which is lowkey the most efficient way to do it.

provisions may be made in the future for stuff related to "back-tracking" (that's re-doing a single line right in the middle of a stream, which would speed up state copying). future plans, not current facts, bestie. don't come for me. 🙈

🧵 Constructors

the only constructor provided is new(). that's it, that's the whole list.

when you call new() on an existing object, it makes a brand new copy of that object. otherwise, new() creates a fresh new copy of the (internal) Default Object.

⚠️ okay important: using the procedural syntax modifies the Default Object, and those changes will be reflected in any subsequent new() calls. so your procedural shenanigans have consequences. remember that. 💀

💖 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 $_. yes, the classic. she loves $_.

🔤 Setting and Getting Formats

you can set the text used for formatting a syntax element using set_format() — or, if you're feeling granular, 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. and for bulk retrieval of the names or values of defined formats, you've got:

• get_format_names_list() — for the names
• get_start_format_values_list() — for the start values
• get_end_format_values_list() — for the end values

see FORMAT TYPES later in this document for info on what format elements you can actually use. ✨

🔍 Checking and Setting the State

you can check certain aspects of the formatter's state via these methods:

• in_heredoc()
• in_string()
• in_pod()
• was_pod()
• in_data()
• line_count()

and you can reset all of the above states (plus a few other internal ones) using reset(). clean slate, fresh start, new era. 🧚

🌈 Stable and Unstable Formatting Modes

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

in unstable (TRUE) mode, formatting is not considered 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.

⚠️ but even in stable mode, 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 that are special to the output mode (like > and < in HTML) without them messing with the way the code gets parsed. 🫶

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

---

👑 FORMAT TYPES

the Syntax::Highlight::Perl formatter recognizes and differentiates between many Perl syntactical elements. each type of syntactical element has a Format Type associated with it. there's also a 'DEFAULT' type that gets applied to any element whose Format Type doesn't have a value.

several of the Format Types have underscores in their name. this underscore is special, and it means the Format Type can be "generalized." that means you can assign a value to just the first part of the Format Type name (everything before the underscore) and that value gets applied to all Format Types with the same first part. for example: the Format Types for all types of variables begin with Variable_. so if you assign a value to the Format Type Variable, it'll 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. wild, right?

you can also define a "short-cut" name for each Format Type that can be generalized. the short-cut name is 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 currently recognizes, plus a short description of what each would be applied to. let's go, one by one, no skipping. 💖

• 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, "format"s, 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 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 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 info 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 the author 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::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::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::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::operator_list_re as a pre-compiled regular expression.

• Bareword — a bareword. this can be a 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 beginning of the DATA section. specifically, '"__END__"' and '"__DATA__"'.
• DATA — anything in the DATA section (see "CodeTerm").

---

🌈 PROCEDURAL vs. OBJECT ORIENTED

Syntax::Highlight::Perl uses OO method-calls internally (and actually defines a Default Object that gets used when the functions are invoked procedurally), so you will not gain anything efficiency-wise by using the procedural interface. it's just a matter of style, bestie. pick whichever one feels right in your soul. ✨

it is actually recommended that you use the OO interface, because that lets you instantiate multiple, concurrent-yet-separate formatters. though, honestly, the author cannot think of why you would need multiple formatters instantiated. :-) 😭

one point to note, and this one matters: the new() method uses the Default Object to initialize new objects. that means any changes to the state of the Default Object (including Format definitions) that you make using the procedural interface will be reflected in any subsequently created objects.

this can be useful in some cases (eg, call set_format() procedurally right before creating a batch of new objects to define default Formats for them all) — but it will most likely lead to trouble. 🙈 proceed with intention, queen.

✨ METHODS ✨

okay bestie, this is the part where we actually get our hands on the object 💅 every method, every form, all of it.

---

new PACKAGE

new OBJECT

Makes you a brand-new object 🌱 and if you call it on an object that already exists? It makes a copy of that object — and from that point on the copy is totally separate from the original. No shared vibes, no crossed wires.

reset

Wipes the object's internal state back to defaults. This breaks out of strings and here-docs, ends PODs, resets the line-count, and generally gets the object back into a "normal" state so it can start processing a fresh stream 🧼

heads up bestie — this does not reset any user options. That includes formats and format stability. Those stay exactly where you left them 👑

unstable EXPR

unstable

Returns true if the formatter is currently in unstable mode.

Call it with a non-zero number and it flips the formatter into unstable formatting mode 🔥

In unstable mode, the assumption is that formatting is not persistent from one token to the next, and that every token has to be explicitly formatted. no shortcuts, no carrying over.

in_heredoc

Returns true if the next string to be formatted will be inside a Here-Document.

in_string

Returns true if the next string to be formatted will be inside a multi-line string.

in_pod

Returns true if the formatter would consider the next string passed to it as beginning inside a POD structure. Here's the tea on the exact timing 🍵 this is false immediately before any POD instigators ("=pod", "=head1", "=item", etc), true immediately after an instigator, throughout the POD and immediately before the POD terminator ("=cut"), and false immediately after the POD terminator. the timing is the whole point, iykyk.

was_pod

Returns true if the last line of the string you just formatted was part of a POD structure. This includes the /^=\w+/ POD instigators and terminators.

in_data

Returns true if the next string to be formatted will be inside the DATA section — aka it follows a __DATA__ or __END__ tag.

line_count

Returns the number of lines processed by the formatter 🔢

substitutions

Returns a reference to the substitution table being used 🫶 that table is a hash whose keys are the strings to be replaced, and whose values are what to replace them with.

define_substitution HASH_REF

define_substitution LIST

Lets you (the user) define certain characters that get substituted before formatting is done — but after they've been processed for meaning. Order matters, periodt.

If the first parameter is a reference to a hash, the formatter replaces its own hash with the one you gave it, and any later changes to that hash made outside the formatter will be reflected ✨

Otherwise, it copies the arguments you passed into its own hash, and any substitutions that were already defined (but aren't in your parameter list) get preserved. So basically: the new substitutions are added, without destroying what was already there 💖

set_start_format HASH_REF

set_start_format LIST

Hand it either a list of keys/values, or a reference to a hash of keys/values, and it copies them into the object's Formats list.

set_end_format HASH_REF

set_end_format LIST

Same deal 🎀 give it either a list of keys/values, or a reference to a hash of keys/values, and it copies them into the object's Formats list.

set_format LIST

Sets the formatting string for one or more formats.

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. order is not a suggestion bestie.

get_start_format LIST

Grabs the string that gets inserted to begin a given format type (the starting format string).

The names are looked for in this order:

First: it prefers the names joined by underscore, going from most general to least. For example, given ("Variable", "Scalar"): "Variable" then "Variable_Scalar".

Second: then it tries each name singly, in reverse order. For example, "Scalar" then "Variable".

See "FORMAT TYPES" for more information 👀

get_end_format LIST

Grabs the string that gets inserted to end a given format type (the ending format string).

get_format_names_list

Returns a list of the names of all the Formats defined.

get_start_format_values_list

Returns a list of the values of all the start Formats defined, in the same order as the names returned by get_format_names_list().

get_end_format_values_list

Returns a list of the values of all the end Formats defined, in the same order as the names returned by get_format_names_list().

format_string LIST

Formats one or more strings of Perl code 🪄 If you don't specify any strings, it defaults to $_. It returns the list of formatted strings (or just the first string formatted, if you call it in scalar context).

Note: the end of the string is treated as the end of a line, regardless of whether or not there's a trailing line-break — but trailing line-breaks will not cause an extra, empty line. we love a considerate formatter.

Another Note: the function actually uses $/ to determine line-breaks, unless $/ is set to "\n" (newline). If $/ is "\n", then it looks for the first match of m/\r?\n|\n?\r/ in the string and uses that to determine line-breaks. The point of all this is to make it easy to handle non-unix text 💻 and whatever characters it ends up using as line-breaks are preserved.

format_token TOKEN, LIST

Returns TOKEN wrapped in the start and end Formats corresponding to LIST — exactly as they'd come back from get_start_format( LIST ) and get_end_format( LIST ), respectively.

No syntax checking is done on TOKEN, but substitutions defined with define_substitution() are performed.

---

😭 KNOWN ISSUES or LIMITATIONS 😭

bestie, we're being honest here. the receipts:

• 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.
• This version does not handle formats (see perlform(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. So 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. The plan is to get to the comment lines and non-interpolating picture lines first. If/When that gets fixed, a format type of 'Format' (or something) will most likely be added, so they can be formatted differently, if so desired.
• This version does not handle Regular Expression significant characters. It simply treats Regular Expressions as interpolated strings.
• 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 that would require going as far as perl does when doing the -c check (ie, executing BEGIN and END blocks and the like). That's not going to happen. periodt.
• If you are indexing (subscripting) an array or hash, the formatter tries to figure out the "real" 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 gets confused and treats 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 "correct" class 🙈
• If you put a line-break between your variable identifier and its indexing character (see above), which is also legal in Perl, the formatter will never find it and will treat your variable as a scalar.
• If you put a line-break between a bareword hash-subscript and the hash variable, or between a bareword and its associated => operator, the bareword will not be formatted correctly (as a string). (Noticing a pattern here? 💀)

---

🫶 AUTHOR 🫶

Cory Johns darkness@yossman.net

Copyright (c) 2001 Cory Johns. This library is free software; you can redistribute and/or modify it under the same conditions as Perl itself.

---

⭐ TO DO ⭐

1. Improve handling of regular expressions. Add support for regexp-special characters. Recognize the /e option to the substitution operator (maybe).
2. Improve handling of formats. Don't treat format definitions as interpolating. Handle format-comments. Possibly format value lines as normal Perl code.
3. Create in-memory deep-copy routine to replace eval(Data::Dumper) deep-copy.
4. Generalize state transitions (reset() and, in the future, copy_state()) 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.
5. Create a method to save or copy states between objects (copy_state()). Would be useful for using this module in an editor.
6. Add support for greater-than-one length special characters. Specifically, octal, hexidecimal, and control character codes. For example, "\644", "\x1a4" or "\c[".

---

🌈 REVISIONS 🌈

04-04-2001 Cory Johns

• Fixed problem with special characters not formatting inside of Here-Documents.
• Fixed bug causing hash variables to format inside of Here-Documents.

03-30-2001 Cory Johns

• Fixed bug where quote-terminators were checked for inside of Here-Documents.

03-29-2001 Cory Johns

• Moved token processing tests from _format_line() into _process_token() (where they should've been all along), generally making _format_line() more logical. Contemplating extrapolating the tokenizing and token loop into its own subroutine to avoid all the recursive calls.
• Fixed bug that caused special characters to be recognized outside of strings.
• Added $VERSION variable.
• Added support for different types of literal numbers: floating point, exponential notation (eg: 1.3e10), hexidecimal, and underscore-separated.
• Added the "CodeTerm" and "DATA" Formats.

03-27-2001 Cory Johns

• Added was_pod() and updated the documentation for in_pod().

03-20-2001 Cory Johns

• Added support for Perl formats (ie, "format = ...").

---

and that's the whole page bestie 💖 you made it all the way through. this is from perl v5.40.1, dated 2025-05-04 — go forth and format, you absolute icon 👑✨