NAME

String::Interpolate::Delayed - delay string interpolation until you really want it

SYNOPSIS

   use strict;
   use warnings;
   use String::Interpolate::Delayed;
   
   my $str   = delayed "$role of the $thing";
   my $role  = "Lord";
   my $thing = [qw( Rings Flies Dance )]->[rand 3];
   
   print "$str\n";

DESCRIPTION

This module allows you to create strings which are interpolated, but not immediately.

Running the code in the SYNPOSIS will print the name of one of my favourite lords, even though at the time $str was declared, the variables $role and $thing had still not been declared!

Discussion

How does this pass strictures? You might expect that the line which declares $str would trigger a compile-time error, as it refers to two variables which don't exist. Fear not! delayed is technically a quote-like operator, not a function; the string following it is parsed by Perl as an uninterpolated string, even if it appears in double quotes. We could equally have written:

   my $str = delayed/$role of the $thing/;

I prefer the double-quoted style because it fares better with syntax highlighting.

What is $str? It's actually a blessed object, but it uses UNIVERSAL::ref to conceal this fact. (blessed from Scalar::Util knows the truth though.)

And it overloads stringification, right? By George! You've got it! Yes, it overloads stringification and plays silly games with PadWalker and String::Interpolate.

Methods

As mentioned above, strings with delayed interpolation are blessed objects. As such, they have methods:

new($text)

Object-oriented way to create a string with delayed interpretation, bypassing the delayed quote-like operator.

   my $str = "String::Interpolate::Delayed"->new('$foo');

interpolated

Retrieve the text as a Perl scalar string, performing interpolation.

The object overloads stringification to call this method. Passing a hashref as a parameter, allows you to define additional variables:

   my $str   = delayed "The $thing in $place @description.\n";
   my $thing = "rain";
   
   print $str->interpolated({
      place       => \"Spain",
      description => [qw/ stays mainly on the plain /],
   });

uninterpolated

Retrieve the text as a Perl scalar string, without performing interpolation.

ref

Just returns undef. This is for the benefit of UNIVERSAL::ref.

CAVEATS

Limitations on interpolation

Most variables, including lexical variables and "magic" variables (such as $1, $_, etc) will work. There's one significant exception: @_. This limitation is inherited from String::Interpolate.

Danger, Will Robinson!!

Interpolated Perl strings can execute arbitrary code:

   my $str = "I think I might @{[ unlink '/etc/passwd' ]}";

This is a caveat with interpolated strings in Perl in general, however String::Interpolate::Delayed makes it easier to fall into this trap, because you might be tempted to load strings with delayed interpolation from an untrusted external source and throw them at the OO constructor.

String::Interpolate

This module includes a workaround for a bug in String::Interpolate. If the bug is fixed, the workaround may stop working. The workaround can be disabled by setting

   $String::Interpolate::Delayed::WORKAROUND = 0;

BUGS

forkprove

Test suite fails when run using App::ForkProve, but runs fine using App::Prove. I don't know what all that's about...

Bug tracker

Please report any other bugs to http://rt.cpan.org/Dist/Display.html?Queue=String-Interpolate-Delayed.

SEE ALSO

String::Interpolate, PerlX::QuoteOperator.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2013 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

cpanm String::Interpolate::Delayed

perl -MCPAN -e shell
install String::Interpolate::Delayed