.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::Mason::Lexer 3pm"
.TH HTML::Mason::Lexer 3pm 2024-03-05 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
HTML::Mason::Lexer \- Generates events based on component source lexing
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  my $lexer = HTML::Mason::Lexer\->new;
\&
\&  $lexer\->lex( comp_source => $source, name => $comp_name, compiler => $compiler );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The Lexer works in tandem with the Compiler to turn Mason component
source into something else, generally Perl code.
.PP
As the lexer finds component elements, like a tag or block, it calls
the appropriate event methods in the compiler object it was given.
.PP
It has only a few public methods.
.PP
You can replace this lexer with one of your own simply by telling the
Compiler to use a different lexer class.  Your lexer class simply
needs to call the appropriate methods in the Component Class's API as
it scans the source.
.SH METHODS
.IX Header "METHODS"
The lexer has very few public methods.
.IP new 4
.IX Item "new"
This method creates a new Lexer object.  This methods takes no
parameters.
.IP "lex ( comp_source => ..., name => ..., compiler => ... )" 4
.IX Item "lex ( comp_source => ..., name => ..., compiler => ... )"
This method tells the lexer to start scanning the given component
source.  All of these parameters are required.  The \f(CW\*(C`name\*(C'\fR parameter
will be used in any error messages generated during lexing.  The
\&\f(CW\*(C`compiler\*(C'\fR object must be an object that implements the Mason
Component API.
.IP line_number 4
.IX Item "line_number"
The current line number that the lexer has reached.
.IP name 4
.IX Item "name"
The name of the component currently being lexed.
.IP "throw_syntax_error ($error)" 4
.IX Item "throw_syntax_error ($error)"
This throws an \f(CW\*(C`HTML::Mason::Exception::Syntax\*(C'\fR error with the given
error message as well as additional information about the component
source.
.Sp
This method is used by both the Lexer and the Compiler.
.SH SUBCLASSING
.IX Header "SUBCLASSING"
Any subclass of the lexer should declare itself to be a subclass of
\&\f(CW\*(C`HTML::Mason::Lexer\*(C'\fR, even if it plans to override all of its public
methods.
.PP
If you want your subclass to work with the existing Compiler classes
in Mason, you must implement the methods listed above.  If you plan to
use a custom Compiler class that you're writing, you can do whatever
you want.
.PP
We recommend that any parameters you add to Lexer be read-only,
because the compiler object_id is only computed once on creation
and would not reflect any changes to Lexer parameters.