NAME

String::ExpandEscapes - Expand printf-style %-escapes in a string.

SYNOPSIS

    use String::ExpandEscapes qw(expand);
        
    my %escapes = (
        a => 'Tori Amos',
        t => 'Silent All These Years'
    )
                                      
    my ($result, $error) = expand('%.1a/%a/%t.mp3', \%escapes);

    die "Illegal escape sequence $error\n" if $error;
                                      

ABSTRACT

This module contains functions for parsing and doing substitutions in format strings similar to those used by printf. The %-escapes to be replaced can either be given using a hash, or, for maximum flexibility, using a callback function.

DESCRIPTION

The expand() function can be called in two different ways, differing in the type and number of expected arguments.

expand(string, hashref)

The first one, as described in the SYNOPSIS section, expects two arguments: A string that possibly contains escape sequences and a reference to a hash. The hash acts as a conversation table between valid escape sequences and replacement strings. In this mode, a default handler is used which is very close in behaviour to perl's builtin sprintf(). Here is another example:

 my %table = (
        a => 'Hello World',
        b => 'Test'
 );

 my ($mystr, $err) = expand('[%.5a] [%-10b] [%10b]', \%table);

 # content of $mystr: "[Hello] [Test      ] [      Test]"

expand(string, coderef, [data])

The second method is more flexible. Instead of merely passing a conversation table, you can give a code reference to expand() that is used as a callback each time an escape sequence is detected in the string. Your handler is called with four or five arguments, depending on how you called expand():

• flags: an arbitrary set of '-', '+', '0' and '#'

• width: integer value

• precision: integer value

• format: a single letter

• data: the data you passed to expand()

In case of error (such as an unexpected format character), your handler should return undef. That causes expand() to return undef as well.

Have a look at the default handler expand_handler of this module for an example.

EXPORT

Nothing by default.

AUTHOR

Matthias Friedrich, <matt@mafr.de>

COPYRIGHT AND LICENSE

Copyright (c) 2003 by Matthias Friedrich <matt@mafr.de>.

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