NAME
    Operator::Util - A selection of array and hash functions that extend
    operators

VERSION
    This document describes Operator::Util version 0.01.

SYNOPSIS
        use Operator::Util qw(
            reduce reducewith
            zip zipwith
            cross crosswith
            hyper hyperwith
            applyop reverseop
        );

WARNING
    This is an early release of Operator::Util. The interface and
    functionality may change in the future based on user feedback. Please
    make suggestions by creating an issue at
    <http://github.com/patch/operator-util-pm5/issues>.

    The documentation is in the process of being thoroughly expanded.

DESCRIPTION
    A pragmatic approach at providing the functionality of many of Perl 6's
    meta operators in Perl 5.

    The terms "operator string" or "opstring" are used to describe a string
    that represents an operator, such as the string '+' for the addition
    operator or the string '.' for the concatenation operator. Except where
    noted, opstrings default to binary infix operators and the short form
    may be used, e.g., '*' instead of 'infix:*'. All other operator types
    (prefix, postfix, circumfix, and postcircumfix) must have the type
    prepended in the opstrings, e.g., "prefix:++" and "postcircumfix:{}".

    When a list is passed as an argument for any of the functions, it must
    be either an array reference or a scalar value that will be used as a
    single-element list.

    The following functions are provided but are not exported by default.

    reduce OPSTRING, LIST [, triangle => 1 ]
        "reducewith" is an alias for "reduce". It may be desirable to use
        "reducewith" to avoid naming conflicts or confusion with "reduce" in
        List::Util.

    zip OPSTRING, LIST1, LIST2
    zip LIST1, LIST2
        "zipwith" is an alias for "reduce".

    cross OPSTRING, LIST1, LIST2
    cross LIST1, LIST2
        "crosswith" is an alias for "reduce".

    hyper OPSTRING, LIST1, LIST2 [, dwim_left => 1, dwim_right => 1 ]
    hyper OPSTRING, LIST
        "hyperwith" is an alias for "reduce".

    applyop OPSTRING, OPERAND1, OPERAND2
    applyop OPSTRING, OPERAND
        If three arguments are provided to "applyop", apply the binary
        operator OPSTRING to the operands OPERAND1 and OPERAND2. If two
        arguments are provided, apply the unary operator OPSTRING to the
        operand OPERAND. The unary form defaults to using prefix operators,
        so 'prefix:' may be omitted, e.g., '++' instead of 'prefix:++';

            applyop '.', 'foo', 'bar'  # foobar
            applyop '++', 5            # 6

    reverseop OPSTRING, OPERAND1, OPERAND2
        "reverseop" provides the same functionality as "applyop" except that
        OPERAND1 and OPERAND2 are reversed.

            reverseop '.', 'foo', 'bar'  # barfoo

        If an unary opstring is used, "reverseop" has the same functionality
        as "applyop".

    The optional named-argument "flat" can be passed to "reduce", "zip",
    "cross", and "hyper". It defaults to 1, which causes the function to
    return a flat list. When set to 0, it causes the return value from each
    operator to be stored in an array ref, resulting in a "list of lists"
    being returned from the function.

        zip [1..3], ['a'..'c']             # 1, 'a', 2, 'b', 3, 'c'
        zip [1..3], ['a'..'c'], flat => 0  # [1, 'a'], [2, 'b'], [3, 'c']

TODO
    *   Add "warn"ings on errors instead of simply "return"ing

    *   Add named unary operators such as "uc" and "lc"

    *   Allow unlimited arrayrefs passed to "zip", "cross", and "hyper"
        instead of just two

    *   Support meta-operator literals such as "Z" and "X"

    *   Should the first argument optionally be a subroutine ref instead of
        an operator string?

    *   Should the "flat => 0" option be changed to "lol => 1"?

    *   Convert tests to TestML

SEE ALSO
    *   perlop

    *   "pairwise" in List::MoreUtils is similar to "zip" except that its
        first argument is a block instead of an operator string and the
        remaining arguments are arrays instead of array refs:

            pairwise { $a + $b }, @array1, @array2  # List::MoreUtils
            zip '+', \@array1, \@array2             # Operator::Util

    *   "mesh" a.k.a. "zip" in List::MoreUtils is similar to "zip" when
        using the default operator ',' except that the arguments are arrays
        instead of array refs:

            mesh @array1, @array2   # List::MoreUtils
            zip \@array1, \@array2  # Operator::Util

    *   Set::CrossProduct is an object-oriented alternative to "cross" when
        using the default operator ","

    *   The "Meta operators" section of Synopsis 3: Perl 6 Operators
        (<http://perlcabal.org/syn/S03.html#Meta_operators>) is the
        inspiration for this module

AUTHOR
    Nick Patch <patch@cpan.org>

ACKNOWLEDGEMENTS
    *   This module is loosely based on the Perl 6 specification, as
        described in the Synopsis and implemented in Rakudo

    *   Much of the documentation is based on Synopsis 3: Perl 6 Operators
        (<http://perlcabal.org/syn/S03.html>)

    *   Most of the tests were forked from the Official Perl 6 Test Suite
        (<https://github.com/perl6/roast>)

COPYRIGHT AND LICENSE
    Copyright 2010, 2011 Nick Patch

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

