String::Expando - expand %(foo) codes in strings


    $e = String::Expando->new;
    print $e->expand('%(foo) %(bar)', { foo => 'Hello', bar => 'world!' }), "\n";
    print $e->expand(
        '### %04d(year)-%02d(month)-%02d(day)
        { year => 2011, month => 3, day => 9 }
    ), "\n";
    ### 2011-03-09


    $e = String::Expando->new;
    $e = String::Expando->new(
        # "[% foo %]" -> $stash->{foo}
        'expando' => qr/\[%\s*([^%]+?)\s*%\]/,
        # "%%" -> "%"
        'escaped_literal' => qr/%(%)/,
        # etc.
        'literal' => qr/(.)/,
    $e = String::Expando->new(
        # "%[.2f]L" => sprintf('%.2f', $stash->{L})
        'expando' => qr{
                # Optional format string
                # Stash key
                ( [A-Za-z0-9] )
        'stash' => { A => 1, B => 2, ... },

Create a new expando object. Arguments allowed are as follows.


The hash from which expando values are obtained. An expando %(xyz) expanded using stash $h will yield the value of $h-{'xyz'}> (or the empty string, if the value of $h-{'xyz'}> is undefined).


The regexp (or simple scalar) to use to identify expando codes when parsing the input. It must contain a capture group for what will become the key into the stash. If it contains two capture groups and $2 is defined (and not empty) after matching, the value of $1 will be used with sprintf to produce the final output.

The default is:


In other words, %(...) with an optional format string between % and (.

    $h = $e->stash;

Get or set the stash from which expando values will be obtained.


A reference to a function with the signature ($expando, $k, $stash) that is called to obtain a value from $stash using code $k.

The default is to call $expando-decode($code, $stash)>, which returns:

  • The empty string if $stash is scalar value.

  • $stash-{$code}> if $stash is a hash reference and $stash-{$k}> is a scalar.

  • $stash-[$code]> if $stash is an array reference and $stash-[$k]> is a scalar; $stash->{$code}->() if $stash is a hash reference and $stash-{$k}> is a code reference; or $stash->[$code]->() if $stash is an array reference and $stash-[$k]> is a code reference.

dot_separator STRING|REGEXP

A separator to use in expando codes in order to access values not at the top level of the stash. Decoding happens

For example, if dot_separator is set to . or qr/\./ then the expando expanded using stash $h will yield the same value as the expando baz expanded using stash $h-{foo}{bar}> (or the empty string, if said value is undefined). This may or may not be the same value as $h-{foo}{bar}{baz}>, depending on the decoder.

For example, if $h is this:

        'foo' => {
            'bar' => sub { return { 'baz' => 123 } },

Then will expand to 123.

By default, no dot separator is defined.

consume_escaped_literal =item consume_expando =item consume_literal =item default_hash_keys

When expanding, the result of the expansion

escaped_literal =item functions =item literal =item stash =item stringify

A coderef that will be used to stringify an expanded value. The code will be called with two arguments: the String::Expando object and the datum to stringify:

    $stringify->($expando, $val);