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

Text-Sprintf-Named documentation Contained in the Text-Sprintf-Named distribution.

Index

Code Index:

NAME

Top

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

VERSION

Top

Version 0.0301

SYNOPSIS

Top

    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"}});

DESCRIPTION

Top

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

Top

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.

AUTHOR

Top

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

BUGS

Top

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

Top

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

    perldoc Text::Sprintf::Named

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Text::Sprintf::Named

* CPAN Ratings

http://cpanratings.perl.org/d/Text::Sprintf::Named

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text::Sprintf::Named

* Search CPAN

http://search.cpan.org/dist/Text::Sprintf::Named

* Subversion Repository

http://svn.berlios.de/svnroot/repos/web-cpan/Text-Sprintf/trunk/

ACKNOWLEDGEMENTS

Top

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.

COPYRIGHT & LICENSE

Top

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

Text-Sprintf-Named documentation Contained in the Text-Sprintf-Named distribution. 
package Text::Sprintf::Named;

use warnings;
use strict;

use Carp;
use warnings::register;


our $VERSION = '0.0301';


sub new
{
    my $class = shift;

    my $self = {};
    bless $self, $class;

    $self->_init(@_);

    return $self;
}

sub _init
{
    my ($self, $args) = @_;

    my $fmt = $args->{fmt} or
        confess "The 'fmt format was not specified for Text::Sprintf::Named.";
    $self->_fmt($fmt);

    return 0;
}

sub _fmt
{
    my $self = shift;

    if (@_)
    {
        $self->{_fmt} = shift;
    }

    return $self->{_fmt};
}


sub format
{
    my $self = shift;

    my $args = shift || {};

    if ( (scalar keys %{$args}) > 0  && not exists $args->{args} ){
        warnings::warnif( $self, 'Format parameters were specified, but none of them were \'args\', this is probably a mistake.' );
    }

    my $named_params = $args->{args} || {};

    my $format = $self->_fmt;

    $format =~ s/%(%|\(([a-zA-Z_]\w*)\)([\+\-\.\d]*)([DEFGOUXbcdefgiopsux]))/
                $self->_conversion({
                        format_args => $args,
                        named_params => $named_params,
                        conv => $1,
                        name => $2,
                        conv_prefix => $3,
                        conv_letter => $4,
                })
                /ge;

    return $format;
}


sub calc_param
{
    my ($self, $args) = @_;
    if ( not exists $args->{named_params}->{$args->{name}} ){
        warnings::warnif($self, "Token '$args->{name}' specified in the format '$self->{_fmt}' was not found." );
        return '';
    }
    return $args->{named_params}->{$args->{name}};
}

sub _conversion
{
    my ($self, $args) = @_;

    if ($args->{conv} eq "%")
    {
        return "%";
    }
    else
    {
        return $self->_sprintf(
            ("%" . $args->{conv_prefix} . $args->{conv_letter}),
            $self->calc_param($args),
        );
    }
}

sub _sprintf
{
    my ($self, $format, @args) = @_;

    return sprintf($format, @args);
}


1; # End of Text::Sprintf::Named