NAME

Lazy::Util - Perl utilities for lazy evaluation

VERSION

version 0.002

SYNOPSIS

use Lazy::Util qw/ l_grep l_map /;

my $lazy = l_map { $_ * 2 } l_grep { /^[0-9]+$/ } 3, 4, 5, sub {
  print "Enter a number: ";
  return scalar readline(STDIN);
};

while (defined(my $answer = $lazy->get())) { 
  print "Double your number: $answer\n";
}

DESCRIPTION

Perl utility functions for lazy evalutation.

FUNCTIONS

This module has two sets of functions, the l_* functions and the g_* functions. The l_* functions are designed to return a Lazy::Util::OO object which you can get values from, the g_* functions are designed to get a value out of a Lazy::Util::OO object. Some of the g_* functions may never return if the source of values is infinite, but they are for the most part designed to not eat up all of your memory at least ;).

All these functions can be exported, but none are exported by default. You can use the :all export tag to export all of them.

`l_*` functions

The l_* functions are:

`l_concat(@sources)`

my $lazy = l_concat @sources;

l_concat returns a Lazy::Util::OO object which will simply return each subsequent value from the list of sources it's given.

`l_first($n, @sources)`

my $lazy = l_first $n, @sources;

l_first will return a Lazy::Util::OO object which will only get the first $n values from the subsequent arguments. This can be used the 'break' an otherwise infinite list to only return a certain number of results.

`l_grep($code, @sources)`

my $lazy = l_grep { ... } @sources;

l_grep will return a Lazy::Util::OO object which will filter out any value which doesn't return true from the $code block in the first argument.

`l_map($code, @sources)`

my $lazy = l_map { ... } @sources;

l_map will return a Lazy::Util::OO object which will transform any value using the $code block in the first argument.

`l_nuniq(@sources)`

my $lazy = l_nuniq @sources;

l_nuniq will return a Lazy::Util::OO object which will only return numerically unique values from the sources. This has the potential to consume all of your memory if the @sources are infinite.

`l_uniq(@sources)`

my $lazy = l_uniq @sources;

l_uniq will return a Lazy::Util::OO object which will only return unique values from the sources. This has the potential to consume all of your memory if the @sources are infinite.

`l_until($code, @sources)`

my $lazy = l_until { ... } @sources;

l_until will return a Lazy::Util::OO object which will return values from the @sources until the $code block returns true, after which it will be exhausted.

`g_*` functions

The g_* functions are:

`g_count(@sources)`

my $count = g_count @sources;

g_count counts the number of values from the @sources and returns how many there were. This has the potential to never return if given a source of infinite values.

`g_first(@sources)`

my $val = g_first @sources;

g_first returns the first value from the list of arguments, lazily evaluating them. Equivalent to l_concat(...)->get();. If @sources is empty, it will return undef.

`g_join($sep, @sources)`

my $lines = g_join $str, @sources;

g_join evaluates all the values it's given and returns them joined into a string. This has the potential to never return as well as running out of memory if given a source of infinite values. If @sources is empty, it will return undef.

`g_last(@sources)`

my $val = g_last @sources;

g_last evaluates all the values it's given and returns the last value. This has the potential to never return if given a source of infinite values. If @sources is empty, it will return undef.

`g_max(@sources)`

my $val = g_max @sources;

g_max evaluates all the values it's given and returns the highest one. This has the potential to never return if given a source of infinite values. If @sources is empty, it will return undef.

`g_min(@sources)`

my $val = g_min @sources;

g_min evaluates all the values it's given and returns the lowest one. This has the potential to never return if given a source of infinite values. If @sources is empty, it will return undef.

`g_prod(@sources)`

my $val = g_prod @sources;

g_prod evaluates all the values it's given and returns the product of all of them. This has the potential to never return if given a source of infinite values. Unless one of them is 0. If so, it will short-circuit and return 0. If @sources is empty, it will return 1.

`g_sum(@sources)`

my $val = g_sum @sources;

g_sum evaluates all the values it's given and returns the sum of all of them. This has the potential to never return if given a source of infinite values. If @sources is empty, it will return 0.

`@sources`

The @sources array that most (all?) of these functions take can be any combination of regular scalar values, Lazy::Util::OO objects, Scalar::Defer variables (see "NOTES"), or subroutine references. Each of these will be iterated through from start to finish, and if one of them returns undef, the next one will be used instead, until the last one returns undef.

For instance, in the following scenario:

my @values = qw/ a b c /;
my $source = sub { shift @values };
my $lazy = l_concat $source, 1;

my @results = ($lazy->get(), $lazy->get(), $lazy->get(), $lazy->get());

What happens when you run $lazy->get() the first time is that the subroutine in $source will be executed, and so @values will change to only contain qw/ b c /, and a will be returned. The next time @values will be changed to only contain qw/ c /, and b will be returned. The third $lazy->get() will change @values to qw// (an empty array), and return the c.

So far so good.

What happens with the next $lazy->get() is that the subroutine in $source will be executed one last time, and it will run shift @values, but @values is empty, so it will return undef, which will signal that $source is exhausted, and so it will be discarded. The next value will be taken from the next element in @sources, which is the single scalar 1.

This means that at the end, @results will contain qw/ a b c 1 /, and any subsequent call to $lazy->get() will return undef.

NOTES

If Scalar::Defer is installed, it will assume that any variable of type 0 is a Scalar::Defer variable and will treat it as a source of values.

Not to be confused with Lazy::Utils.

AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The MIT (X11) License

To install Lazy::Util, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Lazy::Util

CPAN shell

perl -MCPAN -e shell
install Lazy::Util

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

FUNCTIONS

l_* functions

l_concat(@sources)

l_first($n, @sources)

l_grep($code, @sources)

l_map($code, @sources)

l_nuniq(@sources)

l_uniq(@sources)

l_until($code, @sources)

g_* functions

g_count(@sources)

g_first(@sources)

g_join($sep, @sources)

g_last(@sources)

g_max(@sources)

g_min(@sources)

g_prod(@sources)

g_sum(@sources)

@sources