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

NAME

Params::Lazy - Transparent lazy arguments for subroutines.

VERSION

Version 0.004

SYNOPSIS

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

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

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

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

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

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 lazy arguments using this module and specifying the function name and a prototype-looking string as the functions to "export".

That pseudo-prototype allows all the characters normally present in a prototype, plus two new options: A caret (^), which means "make this argument lazy", and a colon (:), which will be explained later.

When a function with lazy magic is called, instead of receiving the result of whatever expression the caller specified, the delayed argument will instead show up as a simple scalar reference in @_. Only after you pass that reference to force() will the delayed expression be run.

By default, delayed arguments will see the @_ of the context they were delayed in. While this is generally the most desirable behavior, it makes delayed arguments slightly slower, so you can switch to using the current @_ by defining the delaying function under the scope of no Params::Lazy 'caller_args'; that is, you must do this:

{
    no Params::Lazy 'caller_args';
    use Params::Lazy foo => q(^^);
    ...
}

For the sake of sanity, it's not recommended that you define a function under no-caller-args, but then enable those again inside the function and then use &force (note the &).

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 AND CAVEATS

  • 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.

  • On Perl 5.8, throwing an exception within a delayed eval does not generally work properly, and, if running with $ENV{PERL_DESTRUCT_LEVEL} set to anything but 0, causes Segfaults during global destruction.

  • There's a bug in Perls older than 5.14 that makes delaying a regular expression likely to crash the program.

  • Threading support is experimental. It should behave slightly better on Perls 5.18 and newer.

  • In 5.16 and older, using delay caller outside of a sub will not get the proper values. Unfortunately for those versions, this is a tradeoff to implement delay sub { $lex }, so it's unlikely to be fixed.

  • As of version 0.004, the 'caller arguments' feature doesn't work if you're passing a delayed argument to another delayed function:

    use Params::Lazy qw( delay_1 ^$ delay_2 ^$ );
sub delay_1 { my $delayed = shift; delay_2 expr(), $delayed }
sub delay_2 { my ($d1, $d2) = @_; force $d2 }

sub {
    delay_1(
        warn("I should see the original \@_: <@_>"),
        "delay_2 should see this"
    );
}->('delay_1 should see this');

    This is because currently, the 'delayed argument' magic is attached to the delaying function, rather than the delayed argument. This will be fixed in future releases.

  • 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!

PREREQUISITES

Perl 5.14.0 or higher, although 5.18.0 is recommended to get the most stable behavior. The module will build and test fine as far back as 5.8.8, but some operations are either unstable or plain dangerous; for example, delaying a regular expression might cause the program to crash in 5.10, and trying to goto LABEL out of a delayed expression in 5.8 will cause all sorts of unexpected behavior.

Devel::CallChecker 0.005 or higher, for perl versions earlier than 5.14.

Exporter 5.58 or higher.

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.