.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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" ''
.    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 "Text::MicroMason::LineNumbers 3pm"
.TH Text::MicroMason::LineNumbers 3pm "2023-08-10" "perl v5.36.0" "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"
Text::MicroMason::LineNumbers \- Report errors at correct source code line numbers
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This mixin class associates each token in a template with the line
number on which it was found, and then inserts special comments in the
generated Perl code that preserve that original source file and line
number information.
.PP
This should facilitate debugging, by making it easier to match up run\-
time errors with the template code that produced them.
.PP
To turn this behavior on, just add \*(L"\-LineNumbers\*(R" to your MicroMason
creation call:
.PP
.Vb 1
\&  my $mason = Text::MicroMason\->new( qw( \-LineNumbers ) );
.Ve
.SS "Public Methods"
.IX Subsection "Public Methods"
These methods are called from within the normal flow of MicroMason
functionality, and you do not need to invoke them directly.
.IP "\fBread()\fR" 4
.IX Item "read()"
Clears the variables used to store the file name and first line of a
template, so that they can be set by the methods below.
.IP "\fBread_file()\fR" 4
.IX Item "read_file()"
Saves the source file name before invoking the standard behavior for this method.
.Sp
.Vb 1
\&  $mason\->compile( file => $filename );
.Ve
.IP "\fBread_handle()\fR" 4
.IX Item "read_handle()"
Saves the caller's file name before invoking the standard behavior for this method.
.Sp
.Vb 1
\&  $mason\->compile( handle => $filename );
.Ve
.IP "\fBread_text()\fR" 4
.IX Item "read_text()"
Saves the caller's file name before invoking the standard behavior for this method.
.Sp
.Vb 1
\&  $mason\->compile( text => $filename );
.Ve
.IP "\fBread_inline()\fR" 4
.IX Item "read_inline()"
This is similar to read_text, except it adjusts the line numbering to
reflect a template that's embdded as a literal text in the Perl code.
.Sp
.Vb 3
\&  $mason\->compile( inline => q{
\&          My template text goes here.
\&  } );
.Ve
.IP "\fBlex()\fR" 4
.IX Item "lex()"
Identical to the \fBlex()\fR method provided by the Base class, except that it
also inserts a stream of line-number-setting comments into the to\-be\-
compiled Perl code that attempt to re-synchronize the
.IP "\fBassembler_rules()\fR" 4
.IX Item "assembler_rules()"
Maps the \*(L"line_num\*(R" token to a perl line number comment.
.SS "Private Methods"
.IX Subsection "Private Methods"
.IP "\fB_get_external_caller()\fR" 4
.IX Item "_get_external_caller()"
Returns the source file and line number of the first item in the
function call stack that is not a Text::MicroMason package.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For an overview of this templating framework, see Text::MicroMason.
.PP
This is a mixin class intended for use with Text::MicroMason::Base.
.PP
For distribution, installation, support, copyright and license
information, see Text::MicroMason::Docs::ReadMe.