NAME

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

SYNOPSIS

    $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

METHODS

new
    $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{
            (?x)
            %
                # Optional format string
                (?:
                    \[
                        ([^\]]+)
                    \]
                )?
                # Stash key
                ( [A-Za-z0-9] )
        },
        'stash' => { A => 1, B => 2, ... },
    );

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

stash

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).

expando

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:

    qr/
        (?x)
        \%
        ([^%()]*j
        \(
            ([^\s()]+)
        \)
    /

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

stash
    $h = $e->stash;
    $e->stash(\%hash);

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