NAME

Params::Lazy - Transparent lazy arguments for subroutines.

VERSION

Version 0.003

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.

• It's 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, while delayed arguments are intended to be faster & more lightweight than passing coderefs, are at best just as fast, and generally anywhere between 5% and 100% slower than 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.