/ 
Params-Lazy-0.001
River stage one • 1 direct dependent • 1 total dependent
/ Params::Lazy

NAME

Params::Lazy - Transparent lazy arguments for subroutines.

VERSION

Version 0.001

SYNOPSIS

sub delay {
    say "One";
    force($_[0]);
    say "Three";
}
use Params::Lazy delay => '^';

delay say "Two"; # Will output One, Two, Three

sub fakemap {
   my $delayed = shift;
   my @retvals;
   push @retvals, force($delayed) for @_;
   return @retvals;
}
use Params::Lazy fakemap => '^@';

my @goodies = fakemap "<$_>", 1..10; # same as map "<$_>", 1..10;
...

sub fakegrep (&@) {
    my $delayed = shift;
    my $coderef = ref($delayed) eq 'CODE';
    my @retvals;
    for (@_) {
        if ($coderef ? $delayed->() : force($delayed)) {
            push @retvals, $_;
        }
    }
    return @retvals;
}
use Params::Lazy fakegrep => ':@';

say fakegrep { $_ % 2 } 9, 16, 25, 36;
say fakegrep   $_ % 2,  9, 16, 25, 36;

DESCRIPTION

The Params::Lazy module provides a way to transparently create lazy arguments for a function, without the callers being aware that anything unusual is happening under the hood.

You can enable a lazy argument by defining a function normally, then use the module, followed by the function name, and a prototype-looking string. Besides the normal characters allowed in a prototype, that string takes two new options: A caret (^) which means "make this argument lazy", and a colon (:), which will be explained later. After that, when the function is called, instead of receiving the result of whatever expression the caller put there, the delayed arguments will instead be a simple scalar reference. Only if you pass that variable to force() will the delayed expression be run.

The colon (:) is special cased to work with the & prototype. The gist of it is that, if the expression is something that the & prototype would allow, it stays out of the way and gives you that. Otherwise, it gives you a delayed argument you can use with force().

EXPORT

force($delayed)

Runs the delayed code.

LIMITATIONS

  • When using the : prototype, these two cases are indistinguishable:

    myfunction { ... }
myfunction sub { ... }

    Which means that mymap sub { ... }, 1..10 will work differently than the default map.

  • Strange things will happen if you goto LABEL out of a lazy argument.

  • It's also important to note that delayed arguments are *not* closures, so storing them for later use will likely lead to crashes, segfaults, and a general feeling of malignancy to descend upon you, your family, and your cat. Passing them to other functions should work fine, but returning them to the place where they were delayed is generally a bad idea.

  • Throwing an exception within a delayed eval might not work properly on older Perls (particularly, the 5.8 series). Similarly, there's a bug in Perls 5.10.1 through 5.12.5 that makes delaying a regular expression likely to crash the program.

  • Finally, delayed arguments, although intended to be faster & more light weight than coderefs, are currently about twice as slow as passing a coderef and dereferencing it, so beware!

AUTHOR, LICENSE AND COPYRIGHT

Copyright 2013 Brian Fraser, <fraserbn at gmail.com>

This program is free software; you may redistribute it and/or modify it under the same terms as perl.

ACKNOWLEDGEMENTS

To Scala for the inspiration, to #p5p in general for holding my hand as I stumbled through the callchecker, and to Zefram for Devel::CallChecker and spotting a leak.