.\" -*- 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 "Text::Xslate::Manual::Debugging 3pm"
.TH Text::Xslate::Manual::Debugging 3pm 2024-03-07 "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
Text::Xslate::Manual::Debugging \- Debugging techniques for Xslate templates
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This document describes techniques for debugging templates.
.ie n .SS "Setting ""verbose => 2"""
.el .SS "Setting \f(CWverbose => 2\fP"
.IX Subsection "Setting verbose => 2"
Try \f(CW\*(C`verbose => 2\*(C'\fR in the first step. This option enables full warnings, especially warnings related to \f(CW\*(C`undef\*(C'\fR.
.SS "File names and line numbers"
.IX Subsection "File names and line numbers"
Xslate messages include file names, line numbers, and, if possible, source
code lines which seems problems.
.PP
You can also access the file name and the line number in templates by
\&\f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR tokens just like as Perl.
.PP
If you want reports files and lines from your registered functions,
\&\f(CW\*(C`Text::Xslate\->current_file\*(C'\fR and \f(CW\*(C`Text::Xslate\->current_line\*(C'\fR
in callbacks are the same as \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_LINE_\|_\*(C'\fR in templates
respectively.
.PP
.Vb 2
\&    sub my_sqrt {
\&        my($n) = @_;
\&
\&        if($n < 1) {
\&            # return a message instead of warnings
\&            return sprintf "!!! Can\*(Aqt take sqrt of $n at %s line %d !!!",
\&                Text::Xslate\->current_file, Text::Xslate\->current_line;
\&        }
\&        return sqrt($n);
\&    }
\&
\&    my $tx = Text::Xslate\->new(
\&        function => { sqrt => \e&my_sqrt },
\&    );
.Ve
.SS "To dump values"
.IX Subsection "To dump values"
You can use any dumping modules via the \f(CW\*(C`function\*(C'\fR option, but
Xslate has a builtin \f(CW\*(C`dump\*(C'\fR filter to dump template values.
.PP
.Vb 1
\&    <: $value | dump # Dump $value with Data::Dumper :>
.Ve
.SS "Detection of missing variables (or typos or variable names)"
.IX Subsection "Detection of missing variables (or typos or variable names)"
Xslate itself has warning system for use of uninitialized values, but sometimes
it is not enough.
.PP
If you want fill in some string, e.g. \fBFILL ME\fR, for missing variables,
you can use the \f(CWhash_with_default()\fR utility. For example:
.PP
.Vb 2
\&    use Text::Xslate::Util qw(hash_with_default);
\&    $tx\->render($name, hash_with_default(\e%vars, sub { "FILL ME \*(Aq@_\*(Aq " }) );
.Ve
.PP
Note that this is really \fBslow\fR because it is a tied-hash wrapper.
.SS "Customization of error messages"
.IX Subsection "Customization of error messages"
You can customize error handlers by \f(CW\*(C`warn_handler\*(C'\fR and \f(CW\*(C`die_handler\*(C'\fR.
In these handlers, you can call \f(CW\*(C`Text::Xslate\->print()\*(C'\fR method in order to add your custom messages to the output buffer, which makes debugging easier.
.PP
.Vb 11
\&    #!perl \-w
\&    use strict;
\&    use Text::Xslate;
\&    my %vpath = (
\&        hello => \*(AqHello, <: $lang :> world!\*(Aq . "\en",
\&    );
\&    my $tx = Text::Xslate\->new(
\&        path         => \e%vpath,
\&        verbose      => 2,
\&        warn_handler => sub { Text::Xslate\->print(\*(Aq[[\*(Aq, @_, \*(Aq]]\*(Aq) },
\&    );
\&
\&    print $tx\->render(\*(Aqhello\*(Aq, { });
\&    # => Hello, [[use nil to print at ...]] world!
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Xslate
.PP
Text::Xslate::Manual