NAME

    String::Template - Fills in string templates from hash of fields

VERSION

    version 0.23

SYNOPSIS

     use String::Template;
     
     my %fields = ( num => 2, str => 'this', date => 'Feb 27, 2008' );
     
     my $template = "...<num%04d>...<str>...<date:%Y/%m/%d>...\n";
     
     print expand_string($template, \%fields);
     #prints: "...0002...this...2008/02/27..."

DESCRIPTION

    Generate strings based on a template.

 template language

    Replacement tokens are denoted with angle brackets. That is <fieldname>
    is replaced by the values in the \%fields hash reference provided.

    Some special characters can be used after the field name to impose
    formatting on the fields:

    %

      Treat like a sprintf format, example: <int%02d>.

    :

      Treat like a "strftime" in POSIX format, example <date:%Y-%m-%d>.

      The field is parsed by Date::Parse, so it can handle any format that
      it can handle.

    !

      [version 0.05]

      Same as :, but with gmtime instead of localtime.

    #

      Treat like args to substr; example <str#0,2> or <str#4>.

    { and }

      [version 0.20]

      The { character is specially special, since it allows fields to
      contain additional characters that are not intended for formatting.
      This is specially useful for specifying additional content inside a
      field that may not exist in the hash, and which should be entirely
      replaced with the empty string.

      This makes it possible to have templates like this:

       my $template = '<name><nick{ "%s"}><surname{ %s}>';
       
       my $mack = { name => 'Mack', nick    => 'The Knife' };
       my $jack = { name => 'Jack', surname => 'Sheppard'  };
       
       expand_string( $template, $mack ); # Returns 'Mack "The Knife"'
       expand_string( $template, $jack ); # Returns 'Jack Sheppard'

FUNCTIONS

    All functions are exported by default, or by request, except for
    "expand_hash"

 expand_string

     my $str = expand_string($template, \%fields);
     my $str = expand_string($template, \%fields, $undef_flag);

    Fills in a simple template with values from a hash, replacing tokens
    with the value from the hash $fields{fieldname}.

    Handling of undefined fields can be controlled with $undef_flag. If it
    is false (default), undefined fields are simply replaced with an empty
    string. If set to true, the field is kept verbatim. This can be useful
    for multiple expansion passes.

 expand_stringi

    [version 0.08]

     my $str = expand_stringi($template, \%fields);
     my $str = expand_stringi($template, \%fields, $undef_flag);

    expand_stringi works just like "expand_string", except that tokens and
    hash keys are treated case insensitively.

 missing_values

    [version 0.06]

     my @missing = missing_values($template, \%fields);
     my @missing = missing_values($template, \%fields, $dont_allow_undefs);

    Checks to see if the template variables in a string template exist in a
    hash. Set $dont_allow_undefs to 1 to also check to see if the values
    for all such keys are defined.

    Returns a list of missing keys or an empty list if no keys were
    missing.

 expand_hash

    [version 0.07]

     my $status = expand_hash($hash);
     my $status = expand_hash($hash, $maxdepth);

    Expand a hash of templates/values. This function will repeatedly
    replace templates in the values of the hash with the values of the hash
    they reference, until either all <fieldname> templates are gone, or it
    has iterated $maxdepth times (default 10).

    Returns undef if there are unexpanded templates left, otherwise true.

    This function must be explicitly exported.

SEE ALSO

    String::Format performs a similar function, with a different syntax.

AUTHOR

    Original author: Brian Duggan

    Current maintainer: Graham Ollis <plicease@cpan.org>

    Contributors:

    Curt Tilmes

    Jeremy Mates (thirg, JMATES)

    José Joaquín Atria

COPYRIGHT AND LICENSE

    This software is copyright (c) 2015 by Brian Duggan.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

