HOI-Comprehensions version 0.02
===============================

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

    Alias >= 2.32

NAME

HOI::Comprehensions - Higher-Order Imperative "Re"features in Perl: List Comprehensions

SYNOPSIS

  use HOI::Comprehensions;

  my $list = HOI::Comprehensions::comp( sub { $x + $y + $z + $w }, x => [ 1, 2, 3 ], y => [ 4, 5, 6 ], w => HOI::Comprehensions::comp( sub { $u }, u => [ 1, 2, 3 ] )->(), z => sub { (2, 1) } )->( sub { $x > 1 } );

  my ($elt, $done);
  do {
      ($elt, $done) = @{<$list>};
      print "$elt ";
  } while (not $done);
  print "\n";

DESCRIPTION

HOI::Comprehensions offers lazy-evaluated list comprehensions with limited support to 
generators of an infinite list. It works as if evaluating multi-level loops lazily.

Currently, the generators are handled in sequence of the argument list offered by the user.
As a result of such implementation, a list
    { (x, y) | x belongs to { 0, 1 }, y belongs to natural number set }
may be trapped in the inner infinite loop. To avoid such situation, make sure finite generators 
are subsequent to all the infinite ones.

FUNCTIONS

comp($@)->(@)

For creating a list comprehension object. The formula for computing the elements of
the list is given as a subroutine, following by the generators, in form of name => arrayref, 
name => subroutine or name => comprehension. Comp returns a function which takes all guards 
in form of subroutines. Guard parameters can be left empty if there is no guard.

The variable names for naming the ganerators could be used directly in the computation sub and
all guard subs without strict vars enabled. They have local scope as if they were declared with
keyword 'local' in Perl.

A hashref which holds generator variables as its keys and value of those variables as
its values is passed to the formula subroutine. However, it is recommended to use such
variables directly instead of dereference the hashref.

Generators can be arrayrefs or subroutines or list comprehensions. A subroutine generator 
should return a pair ( elt, done ), where elt is the next element and done is a flag telling 
whether the iteration is over.

It is possible that some generator A is dependent on another generator B. In that case, B
must be subsequent to A. See test cases for details.

The subroutine comp is in EXPORT_OK, but it is not exported by default

METHODS

get_list

Get the list member of a list comprehension object. It returns a arrayref which holds
the actual list evaluated so far.

is_over

Returns a boolean which tells if the evaluation of the list is over.

get_member($)

Get a member of a list comprehension object by name.
A list comprehension object is actually a blessed hashref.

force

Eval the comprehension eagerly. Beware - it will be trapped forever in an infinite 
comprehension.
The method returns the evaluated list reference.

OPERATORS

<>

List evaluation iterator. Returns the "next" element generated in the sequence in the 
situation of eager evaluation, and a flag telling whether the evaluation is done, together
in a arrayref.

+

List indexing operator. Takes an integer as the index and a list comprehension object.
The operator returns an arrayref [ $elt, $done ], where $elt is the element at the given
index and $done is a flag telling whether the evaluation is done.

COPYRIGHT AND LICENCE

Copyright (C) 2014 by withering

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.20.0 or,
at your option, any later version of Perl 5 you may have available.