NAME
    Tie::Reduce - a scalar that reduces its old and new values to a single
    value

SYNOPSIS
      use Tie::Reduce;
  
      tie my $sum, "Tie::Reduce", sub { $a + $b }, 0;
  
      $sum = 1;
      $sum = 2;
      $sum = 3;
      $sum = 4;
  
      say $sum;  # 10

    This is similar in spirit to:

      use List::Util qw(reduce);
  
      my $sum = reduce { $a + $b } 0, 1, 2, 3, 4;
  
      say $sum;  # 10

DESCRIPTION
    Tie::Reduce allows you to create a scalar which when assigned a new value,
    passes its old value and assigned value to a coderef, and uses the result
    as its new value.

  Tie API
    `tie($scalar, "Tie::Reduce", \&reduction, $initial_value)`
        Ties the scalar using the given coderef for reducing values.

        The initial value is optional and will default to undef. This value is
        set to the scalar immediately without being passed through the
        reduction coderef.

    $scalar (FETCH)
        Returns the current value of the scalar.

    $scalar (STORE)
        Sets the current value to the result of passing the old value and the
        stored value into the coderef.

        Within the coderef, the old and new values are available as the
        special package variables $a and $b (like `reduce` from List::Util and
        the Perl built-in `sort` function).

  Object API
    The object API is not generally useful for end users of Tie::Reduce, with
    the possible exception of `set_value`. It is mostly documented for people
    wishing to subclass this module.

    `Tie::Reduce->new($coderef, $initial_value)`
        Constructor.

    `tied($scalar)->get_value`
        Returns the current value of the scalar variable.

        This is called by

    `tied($scalar)->set_value($value)`
        Sets the scalar variable *without* passing it through the coderef.

    `tied($scalar)->assign_value($value)`
        Sets the scalar variable, passing it through the coderef.

        Subclassers should be aware that this method uses `caller` to find the
        name of the calling package and access package variables $a and $b.

    `tied($scalar)->get_coderef`
        Returns the coderef being used to reduce values.

    `tied($scalar)->_set_coderef($coderef)`
        Sets the coderef used to reduce values. This is only documented for
        people subclassing Tie::Reduce. Variables tied with Tie::Reduce are
        confusing enough without changing the coderef part-way through the
        variable's lifetime!

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=Tie-Reduce>.

SEE ALSO
    "tie" in perlfunc, perltie, Tie::Scalar.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2018 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.