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

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

       Initial translation by Alex Balhatchet (alex@balhatchet.net)

       Further improvements from:

       Ed Freyfogle Mohammad S Anwar Ricky Morse Jerrad Pierce Tom Hukins Tony Finch Yanick Champoux

perl v5.34.0                                       2022-06-30                         Text::Hogan::Compiler(3pm)

       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.

       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 ASCII '<' 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.

       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.

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

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

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

       version 2.03