/ 
String-Template-0.23
River stage one • 1 direct dependent • 1 total dependent
/ String::Template

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.