NAME

       Text::Hogan::Compiler - parse templates and output Perl code

VERSION

       version 1.04

SYNOPSIS

           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" });

METHODS

   new
       Takes nothing, returns a Compiler object.

           my $compiler = Text::Hogan::Compiler->new;

   scan
       Takes template text and returns an arrayref which is a list of tokens.

           my $tokens = $compiler->scan("Hello, {{name}}!");

       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.

           # equivalent to the above call with mustaches
           my $tokens = Text::Hogan::Compiler->new->scan("Hello, <% name %>!", { delimiters => "<% %>" });

       'allow_whitespace_before_hashmark' is a boolean. If true,tags are allowed to have space(s)
       between the delimiters and the opening sigil ('#', '/', '^', '<', etc.).

               my $tokens = Text::Hogan::Compiler->new->scan("Hello{{ # foo }}, again{{ / foo }}.", { allow_whitespace_before_hashmark => 1 });

   parse
       Takes the tokens returned by scan, along with the original text, and returns a tree
       structure ready to be turned into Perl code.

           my $tree = $compiler->parse($tokens, $text);

       Optionally takes a hashref that can have a key called "section_tags" 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.

       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:
       "Closing tag without opener", "Missing closing tag", "Nesting error" and "Illegal content
       in < super tag".

   generate
       Takes the parsed tree and the original text and returns a Text::Hogan::Template object
       that you can call render on.

           my $template = $compiler->generate($tree, $text);

       Optionally takes a hashref that can have

       - a key "as_string". 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.

           my $perl_code_as_string = $compiler->generate($tree, $text, { 'as_string' => 1 });

       - a key "numeric_string_as_string". If that is passed output that looks like a number is
       NOT converted into a number (ie "01234" is NOT converted to "1234")

           my $perl_code_as_string = $compiler->generate($tree, $text, { 'numeric_string_as_string' => 1 });

       The options hashref can have other keys which will be passed to Text::Hogan::Template::new
       among other places.

   compile
       Takes a template string and calls scan, parse and generate on it and returns you the
       Text::Hogan::Template object.

           my $template = $compiler->compile("Hello, {{name}}!");

       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.

       Optionally takes a hashref that will be passed on to scan, parse, and generate.

           my $perl_code_as_string = $compiler->compile(
               $text,
               {
                   delimiters => "<% %>",
                   as_string => 1,
                   allow_whitespace_before_hashmark => 1,
               },
           );

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.

       However be aware that compilation is much slower when using character strings!  The
       tokenization does a lot of character-by-character operations using substr(), length(),
       etc. which are much slower when operating on character strings than byte strings.

       I would still recommend you use character strings for your own sanity of course! Just be
       aware that you will gain a lot of performance by pre-compiling your templates, either
       using the as_string option of compile or just using a compile-once render-lots pattern in
       your code.

AUTHOR

       Started out statement-for-statement copied from hogan.js by Twitter!

       Alex Balhatchet (alex@balhatchet.net)