.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::Hogan::Compiler 3pm"
.TH Text::Hogan::Compiler 3pm "2022-06-30" "perl v5.34.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::Hogan::Compiler \- parse templates and output Perl code
.SH "VERSION"
.IX Header "VERSION"
version 2.03
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Text::Hogan::Compiler;
\&
\&    my $compiler = Text::Hogan::Compiler\->new;
\&
\&    my $text = "Hello, {{name}}!";
\&
\&    my $tokens   = $compiler\->scan($text);
\&    my $tree     = $compiler\->parse($tokens, $text);
\&    my $template = $compiler\->generate($tree, $text);
\&
\&    say $template\->render({ name => "Alex" });
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Takes nothing, returns a Compiler object.
.PP
.Vb 1
\&    my $compiler = Text::Hogan::Compiler\->new;
.Ve
.SS "scan"
.IX Subsection "scan"
Takes template text and returns an arrayref which is a list of tokens.
.PP
.Vb 1
\&    my $tokens = $compiler\->scan("Hello, {{name}}!");
.Ve
.PP
Optionally takes a hashref with options. 'delimiters' is a string which
represents different delimiters, split by white-space. You should never
need to pass this directly, it it used to implement the in-template
delimiter-switching functionality.
.PP
.Vb 2
\&    # equivalent to the above call with mustaches
\&    my $tokens = Text::Hogan::Compiler\->new\->scan("Hello, <% name %>!", { delimiters => "<% %>" });
.Ve
.PP
\&'allow_whitespace_before_hashmark' is a boolean. If true,tags are allowed
to have space(s) between the delimiters and the opening sigil ('#', '/', '^', '<', etc.).
.PP
.Vb 1
\&    my $tokens = Text::Hogan::Compiler\->new\->scan("Hello{{ # foo }}, again{{ / foo }}.", { allow_whitespace_before_hashmark => 1 });
.Ve
.SS "parse"
.IX Subsection "parse"
Takes the tokens returned by scan, along with the original text, and returns a
tree structure ready to be turned into Perl code.
.PP
.Vb 1
\&    my $tree = $compiler\->parse($tokens, $text);
.Ve
.PP
Optionally takes a hashref that can have a key called \*(L"section_tags\*(R" which
should be an arrayref. I don't know what it does. Probably something internal
related to recursive calls that you don't need to worry about.
.PP
Note that a lot of error checking on your input gets done in this method, and
it is pretty much the only place exceptions might be thrown. Exceptions which
may be thrown include: \*(L"Closing tag without opener\*(R", \*(L"Missing closing tag\*(R",
\&\*(L"Nesting error\*(R" and \*(L"Illegal content in < super tag\*(R".
.SS "generate"
.IX Subsection "generate"
Takes the parsed tree and the original text and returns a Text::Hogan::Template
object that you can call render on.
.PP
.Vb 1
\&    my $template = $compiler\->generate($tree, $text);
.Ve
.PP
Optionally takes a hashref that can have
.PP
\&\- a key \*(L"as_string\*(R". If that is passed then instead of getting a template object
back you get some stringified Perl code that you can cache somewhere on
disk as part of your build process.
.PP
.Vb 1
\&    my $perl_code_as_string = $compiler\->generate($tree, $text, { \*(Aqas_string\*(Aq => 1 });
.Ve
.PP
\&\- a key \*(L"numeric_string_as_string\*(R". If that is passed output that looks like a number
is \s-1NOT\s0 converted into a number (ie \*(L"01234\*(R" is \s-1NOT\s0 converted to \*(L"1234\*(R")
.PP
.Vb 1
\&    my $perl_code_as_string = $compiler\->generate($tree, $text, { \*(Aqnumeric_string_as_string\*(Aq => 1 });
.Ve
.PP
The options hashref can have other keys which will be passed to
Text::Hogan::Template::new among other places.
.SS "compile"
.IX Subsection "compile"
Takes a template string and calls scan, parse and generate on it and returns
you the Text::Hogan::Template object.
.PP
.Vb 1
\&    my $template = $compiler\->compile("Hello, {{name}}!");
.Ve
.PP
Also caches templates by a sensible cache key, which can be useful if you're
not stringifying and storing on disk or in memory anyway.
.PP
Optionally takes a hashref that will be passed on to scan, parse, and generate.
.PP
.Vb 8
\&    my $perl_code_as_string = $compiler\->compile(
\&        $text,
\&        {
\&            delimiters => "<% %>",
\&            as_string => 1,
\&            allow_whitespace_before_hashmark => 1,
\&        },
\&    );
.Ve
.SH "ENCODING"
.IX Header "ENCODING"
As long as you are consistent with your use of encoding in your template
variables and your context variables, everything should just work. You can use
byte strings or character strings and you'll get what you expect.
.PP
The only danger would be if you use byte strings of a multi-byte encoding and
you happen to get a clash with your delimiters, eg. if your 4 byte kanji
character happens to contain the \s-1ASCII\s0 '<' and '%' characters next to each
other. I have no idea what the likelihood of that is, but hopefully if you're
working with non-ASCII character sets you're also using Perl's unicode
character strings features.
.PP
Compiling long character string inputs with Text::Hogan used to be extremely
slow but an optimisation added in version 2.00 has made the overhead much more
manageable.
.SH "AUTHORS"
.IX Header "AUTHORS"
Started out statement-for-statement copied from hogan.js by Twitter!
.PP
Initial translation by Alex Balhatchet (alex@balhatchet.net)
.PP
Further improvements from:
.PP
Ed Freyfogle
Mohammad S Anwar
Ricky Morse
Jerrad Pierce
Tom Hukins
Tony Finch
Yanick Champoux