NAME
List::Gen::Haskell  the haskell prelude in perl5
SYNOPSIS
this module provides most of the functions in the haskell prelude that pertain to working with lists.
# haskell: fibs = 0 : 1 : zipWith (+) fibs (tail fibs)
use List::Gen::Haskell;
$fibs = lazy 0, 1, zipWith {&sum} $fibs, tail $fibs;
print "@$fibs[0 .. 10]\n"; # prints '0 1 1 2 3 5 8 13 21 34 55'
lazy
provides the generic behavior of haskell's lazy list concatenation (the :
and ++
operators). none of its elements are touched until they are needed. in general, all the functions in this package defer their execution until something is required of them. they also only touch their arguments at the latest possible time, which is how the corecursion above works.
the functions in this module are a bit more flexible (perlish) than those in haskell. in most cases where a function expects a single generator, a list of values and/or generators can be provided, which will be preprocessed by lazy
into a single generator.
when loaded, most of the functions in this package become methods for all generators. if a method of the same name already exists, the method from this package will be prefixed with hs_
. so filter
is a method named >hs_filter(...)
this library currently does not have the best performance due to overcaching of many internal generators. a future update will address this by replacing those generators with cacheless generator streams.
FUNCTIONS
all of these functions are available with a ucfirst name, since many clash with perl builtin names.
Utility Operations
 x_xs
[GENERATOR]

x_xs
is a convenience function that returns the head and tail of a passed in generator.x_xs
uses$_
without an argument.  seq
LIST

forces immediate evaluation of the elements in
LIST
and returns the list  flip
{CODE}

flip
convertsCODE
into a function that takes it's arguments reversedmy $idx = \&head . flip \&drop; $idx>($gen, 5) == $gen>$idx(5) == $gen>get(5)
List operations
 Map
{CODE} LIST

Map f xs is the list obtained by applying f to each element of xs, i.e.,
map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn] map f [x1, x2, ...] == [f x1, f x2, ...] $x = &map(sub {$_**2}, $gen); $x = Map {$_**2} $gen;
that usage is the same as
List::Gen::gen
, but this is something thatgen
can't do:my $pow_2 = Map {$_**2}; # partial application, needs at least 1 more # argument to evaluate, but can be passed a list my $ints = <0..>; my $squares = $ints>$pow_2; say "@$squares[0 .. 10]"; # 0 1 4 9 16 25 36 49 64 81 100
and this:
my $src; my $square_of_src = Map {$_ ** 2} $src; $src = <1.. by 2>; say "@$square_of_src[0 .. 4]"; # 1 9 25 49 81
 filter
{CODE} LIST

filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; i.e.,
filter p xs = [ x  x < xs, p x]
 head
GENERATOR

Extract the first element of a list, which must be nonempty.
 Last
GENERATOR

Extract the last element of a list, which must be finite and nonempty.
 tail
GENERATOR

Extract the elements after the head of a list, which must be nonempty.
 init
GENERATOR

Return all the elements of a list except the last one. The list must be nonempty.
 null
GENERATOR

Test whether a list is empty.
 Length
GENERATOR
 Reverse
LIST

reverse xs returns the elements of xs in reverse order. xs must be finite.
Reducing lists (folds)
 foldl
{CODE} ITEM LIST

foldl, applied to a binary operator, a starting value (typically the leftidentity of the operator), and a list, reduces the list using the binary operator, from left to right:
foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
The list must be finite.
 foldl1
{CODE} LIST

foldl1
is a variant offoldl
that has no starting value argument, and thus must be applied to nonempty lists.  foldr
{CODE} ITEM LIST

foldr, applied to a binary operator, a starting value (typically the rightidentity of the operator), and a list, reduces the list using the binary operator, from right to left:
foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
 foldr1
{CODE} LIST

foldr1
is a variant offoldr
that has no starting value argument, and thus must be applied to nonempty lists.
Special folds
 And
LIST

and returns the conjunction of a Boolean list. For the result to be True, the list must be finite; False, however, results from a False value at a finite index of a finite or infinite list.
 Or
LIST

or returns the disjunction of a Boolean list. For the result to be False, the list must be finite; True, however, results from a True value at a finite index of a finite or infinite list.
 any
{CODE} LIST

Applied to a predicate and a list, any determines if any element of the list satisfies the predicate.
 all
{CODE} LIST

Applied to a predicate and a list, all determines if all elements of the list satisfy the predicate.
 sum
LIST

The sum function computes the sum of a finite list of numbers.
 product
LIST

The product function computes the product of a finite list of numbers.
 concat
GENERATOR

Concatenate a list of lists.
 concatMap
{CODE} LIST

Map a function over a list and concatenate the results.
 maximum
LIST

maximum returns the maximum value from a list, which must be nonempty, finite, and of an ordered type. It is a special case of maximumBy, which allows the programmer to supply their own comparison function.
 minimum
LIST

minimum returns the minimum value from a list, which must be nonempty, finite, and of an ordered type. It is a special case of minimumBy, which allows the programmer to supply their own comparison function.
Building lists
Scans
 scanl
{CODE} LIST

scanl is similar to foldl, but returns a list of successive reduced values from the left:
scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
Note that
last (scanl f z xs) == foldl f z xs.
 scanr
{CODE} LIST

scanr is the righttoleft dual of scanl. Note that
head (scanr f z xs) == foldr f z xs.
Infinite lists
 iterate
{CODE} ITEM

iterate f x returns an infinite list of repeated applications of f to x:
iterate f x == [x, f x, f (f x), ...]
 repeat
ITEM

repeat x is an infinite list, with x the value of every element.
 hs_repeat
ITEM

my $repeat; $repeat = lazy $x, $repeat;
 replicate
NUM ITEM

replicate n x is a list of length n with x the value of every element.
 cycle
LIST

cycle ties a finite list into a circular one, or equivalently, the infinite repetition of the original list. It is the identity on infinite lists.
 hs_cycle
LIST

hs_cycle ties a finite list into a circular one, or equivalently, the infinite repetition of the original list. It is the identity on infinite lists.
it is defined in perl as:
my $cycle; $cycle = lazy $xs, $cycle;
Sublists
 take
NUM LIST

take n, applied to a list xs, returns the prefix of xs of length n, or xs itself if n > length xs:
take 3 [1,2,3,4,5] == [1,2,3] take 3 [1,2] == [1,2] take 3 [] == [] take (1) [1,2] == [] take 0 [1,2] == []
 drop
NUM LIST

drop n xs returns the suffix of xs after the first n elements, or [] if n > length xs:
drop 3 [1,2,3,4,5] == [4,5] drop 3 [1,2] == [] drop 3 [] == [] drop (1) [1,2] == [1,2] drop 0 [1,2] == [1,2]
 splitAt
NUM LIST

splitAt n xs returns a tuple where first element is xs prefix of length n and second element is the remainder of the list:
splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5]) splitAt 1 [1,2,3] == ([1],[2,3]) splitAt 3 [1,2,3] == ([1,2,3],[]) splitAt 4 [1,2,3] == ([1,2,3],[]) splitAt 0 [1,2,3] == ([],[1,2,3]) splitAt (1) [1,2,3] == ([],[1,2,3])
It is equivalent to (take n xs, drop n xs).
 takeWhile
{CODE} LIST

takeWhile, applied to a predicate p and a list xs, returns the longest prefix (possibly empty) of xs of elements that satisfy p:
take_while (< 3) [1,2,3,4,1,2,3,4] == [1,2] take_while (< 9) [1,2,3] == [1,2,3] take_while (< 0) [1,2,3] == []
 dropWhile
{CODE} LIST

dropWhile p xs returns the suffix remaining after take_while p xs:
dropWhile (< 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3] dropWhile (< 9) [1,2,3] == [] dropWhile (< 0) [1,2,3] == [1,2,3]
 span
{CODE} LIST

span, applied to a predicate p and a list xs, returns a tuple where first element is longest prefix (possibly empty) of xs of elements that satisfy p and second element is the remainder of the list:
span (< 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4]) span (< 9) [1,2,3] == ([1,2,3],[]) span (< 0) [1,2,3] == ([],[1,2,3])
span p xs is equivalent to (takeWhile p xs, dropWhile p xs)
 break
{CODE} LIST

break, applied to a predicate p and a list xs, returns a tuple where first element is longest prefix (possibly empty) of xs of elements that do not satisfy p and second element is the remainder of the list:
break (> 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4]) break (< 9) [1,2,3] == ([],[1,2,3]) break (> 9) [1,2,3] == ([1,2,3],[])
break p is equivalent to span (not . p)
Searching lists
 elem
ITEM LIST

elem is the list membership predicate, usually written in infix form, e.g., x `elem` xs.
 notElem
ITEM LIST

notElem is the negation of elem.
Zipping and unzipping lists
 zip
LIST

zip takes 2+ lists and returns a single interleaved list. If one input list is short, excess elements of the longer lists are discarded. unlike the haskell version, the zip returns a flat generator.
zip
is the same aszipWith {\@_}
 zipWith
{CODE} LIST

zipWith generalizes zip by zipping with the function given as the first argument, instead of a tupling function. For example, zipWith (+) is applied to two lists to produce the list of corresponding sums.
 zipWithAB
{$a * $b} $gen1, $gen2

The zipWithAB function takes a function which uses
$a
and$b
, as well as two lists and returns a list analogous to zipWith.  unzip
GENERATOR

unzip transforms a list into two lists of the even and odd elements.
zs = zip xs, ys (xs, ys) == unzip zs
 unzipn
NUM GENERATOR

The unzipn function is the ndimentional precursor to
unzip
unzip xs = unzipn 2, xs
Functions on strings
 lines
STRING

lines breaks a string up into a list of strings at newline characters. The resulting strings do not contain newlines. the newline sequence is taken from the value of the input record separator
$/
 words
STRING

words breaks a string up into a list of words, which were delimited by white space.
 unlines
LIST

unlines is an inverse operation to lines. It joins lines, after appending a terminating newline to each. the newline sequence is taken from the value of the input record separator
$/
 unwords
LIST

unwords is an inverse operation to words. It joins words with separating spaces.
ACKNOWLEGEMENTS
most of the documentation here started out at http://www.haskell.org/ghc/docs/6.12.2/html/libraries/base4.2.0.1/Prelude.html and was subsequently edited to account for implementation differences.
AUTHOR
Eric Strom, <asg at cpan.org>
BUGS
there are certainly bugs in code this complex. send in reports, tests, patches.
report any bugs / feature requests to buglistgen at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ListGen.
COPYRIGHT & LICENSE
copyright 20092011 Eric Strom.
this program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
see http://dev.perl.org/licenses/ for more information.