The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Sprintf-Named-0.0402
River stage two • 6 direct dependents • 22 total dependents
2 ++
/ Text::Sprintf::Named

NAME

Text::Sprintf::Named - sprintf-like function with named conversions

VERSION

Version 0.0402

SYNOPSIS

    use Text::Sprintf::Named;

    my $formatter =
        Text::Sprintf::Named->new(
            {fmt => "Hello %(name)s! Today is %(day)s!"}
        );

    # Returns "Hello Ayeleth! Today is Sunday!"
    $formatter->format({args => {'name' => "Ayeleth", 'day' => "Sunday"}});

    # Returns "Hello John! Today is Thursday!"
    $formatter->format({args => {'name' => "John", 'day' => "Thursday"}});

    # Or alternatively using the non-OOP interface:

    use Text::Sprintf::Named qw(named_sprintf);

    # Prints "Hello Sophie!" (and a newline).
    print named_sprintf("Hello %(name)s!\n", { name => 'Sophie' });

    # Same, but with a flattened parameter list (not inside a hash reference)
    print named_sprintf("Hello %(name)s!\n", name => 'Sophie');

DESCRIPTION

Text::Sprintf::Named provides a sprintf equivalent with named conversions. Named conversions are sprintf field specifiers (like "%s" or "%4d") only they are associated with the key of an associative array of parameters. So for example "%(name)s" will emit the 'name' parameter as a string, and "%(num)4d" will emit the 'num' parameter as a variable with a width of 4.

FUNCTIONS

my $formatter = Text::Sprintf::Named->new({fmt => $format})

Creates a new object which formats according to the $format format.

$formatter->format({args => \%bindings})

Returns the formatting string as formatted using the named parameters pointed to by the args parameter.

$self->calc_param({%args})

This method is used to calculate the parameter for the conversion. It can be over-rided by subclasses so it will behave differently. An example can be found in t/02-override-param-retrieval.t where it is used to call the accessors of an object for values.

%args contains:

  • named_params

    The named paramters.

  • name

    The name of the conversion.

named_sprintf($format, {%parameters})

named_sprintf($format, %parameters)

This is a convenience function to directly format a string with the named parameters, which can be specified inside a (non-blessed) hash reference or as a flattened hash. See the synopsis for an example.

AUTHOR

Shlomi Fish, shlomif@cpan.org , http://www.shlomifish.org/

BUGS

Please report any bugs or feature requests to bug-text-sprintf-named at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text::Sprintf::Named. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::Sprintf::Named

You can also look for information at:

ACKNOWLEDGEMENTS

The (possibly ad-hoc) regex for matching the optional digits+symbols parameters' prefix of the sprintf conversion was originally written by Bart Lateur (BARTL on CPAN) for his String::Sprintf module.

The syntax was borrowed directly from Python’s "%" operator when used with its dictionaries as the right-hand argument. A quick web search did not yield good documentation about it (and I came with the idea of a named sprintf without knowing that Python had it, only ran into the fact that Python had it by web-searching).

SIMILAR MODULES

Text::sprintfn is a newer module which only provides a procedural interface that allows one to mix positional and named arguments, with some other interesting features.

String::Formatter is a comprehensive module that allows one to define custom sprintf-like functions (I’m not sure whether it has named conversions). Its license is the GNU General Public Licence version 2 (GPLv2), which is both restrictive and incompatible with version 3 of the GPL and with many other open-source licenses.

String::Sprintf appears to allow one to provide custom sprintf/printf formats (without providing named conversions).

For the lighter side, there is Acme::StringFormat, which provides a "%" operator to format a string.

COPYRIGHT & LICENSE

Copyright 2006 Shlomi Fish, all rights reserved.

This program is released under the following license: MIT/X11:

http://www.opensource.org/licenses/mit-license.php