NAME
    ControlBreak - Compare values during iteration to detect changes

SYNOPSIS
        use v5.18;

        use ControlBreak;

        # set up two levels, in minor to major order
        my $cb = ControlBreak->new( qw( District Country ) );

        my $country_total = 0;
        my $district_total = 0;

        while (my $line = <DATA>) {
            chomp $line;

            my ($country, $district, $city, $population) = split ',', $line;

            # test the values (minor to major order)
            $cb->test($district, $country);

            # break on District (or Country) detected
            if ($cb->break('District')) {
                printf "%s,%s,%d%s\n", $cb->last('Country'), $cb->last('District'), $district_total, '*';
                $district_total = 0;
            }

            # break on Country detected
            if ($cb->break('Country')) {
                printf "%s total,%s,%d%s\n", $cb->last('Country'), '', $country_total, '**';
                $country_total = 0;
            }

            $country_total  += $population;
            $district_total += $population;
        }
        continue {
            # save the current values (as received by ->test) as the new
            # 'last' values on the next iteration.
            $cb->continue();
        }

        # simulate break at end of data, if we iterated at least once
        if ($cb->iteration > 0) {
            printf "%s,%s,%d%s\n", $cb->last('Country'), $cb->last('District'), $district_total, '*';
            printf "%s total,%s,%d%s\n", $cb->last('Country'), '', $country_total, '**';
        }

        __DATA__
        Canada,Alberta,Calgary,1019942
        Canada,Ontario,Ottawa,812129
        Canada,Ontario,Toronto,2600000
        Canada,Quebec,Montreal,1704694
        Canada,Quebec,Quebec City,531902
        Canada,Quebec,Sherbrooke,161323
        USA,Arizona,Phoenix,1640641
        USA,California,Los Angeles,3919973
        USA,California,San Jose,1026700
        USA,Illinois,Chicago,2756546
        USA,New York,New York City,8930002
        USA,New York,Buffalo,281757
        USA,Pennsylvania,Philadelphia,1619355
        USA,Texas,Houston,2345606

DESCRIPTION
    The ControlBreak module provides a class that is used to detect control
    breaks; i.e. when a value changes.

    Typically, the data being retrieved or iterated over is ordered and
    there may be more than one value that is of interest. For example
    consider a table of population data with columns for country, district
    and city, sorted by country and district. With this module you can
    create an object that will detect changes in the district or country,
    considered level 1 and level 2 respectively. The calling program can
    take action, such as printing subtotals, whenever level changes are
    detected.

    Ordered data is not a requirement. An example using unordered data would
    be counting consecutive numbers within a data stream; e.g. 0 0 1 1 1 1 0
    1 1. Using ControlBreak you can detect each change and count the
    consecutive values, yielding two zeros, four 1's, one zero, and two 1's.

    Note that ControlBreak cannot detect the end of your data stream. The
    test() method is normally called within a loop to detect changes in
    control variables, but once the last iteration is processed there are no
    further calls to test() as the loop ends. It may be necessary,
    therefore, to do additional processing after the loop in order to handle
    the very last data group; e.g. to print a final set of subtotals.

    To simplify this situation, method test_and_do()) can be used in place
    of test() and continue().

FIELDS
  iteration
    A readonly field that provides the current iteration number.

    This can be useful if you are doing an final processing after an
    iteration loop has ended. In the event that the data stream is empty and
    there were no iterations, then you can condition your final processing
    on iteration > 0.

    Note that interation is incremented by test (or <test_and_do>).
    Therefore, when called wihtin a loop it is effectively zero-based if
    referenced within the iteration block before test is invoked, and then
    one-based after test.

  level_names
    A readonly field that provides a list of the level names that were
    provided as arguments to new().

METHODS
  new ( <level_name> [, <level_name> ]... )
    Create a new ControlBreak object.

    Arguments are user-defined names for each level, in minor to major
    order. The set of names must be unique, and they must each start with a
    letter or underscore, followed by any number of letters, numbers or
    underscores.

    A level name can also begin with a '+', which denotes that a numeric
    comparison will be used for the values processed at this level.

    The number of arguments to new() determines the number of control levels
    that will be monitored. The variables provided to method test() must
    match in number and datatype to these operators.

    The order of the arguments corresponds to a hierachical level of
    control, from lowest to highest; i.e. the first argument corresponds to
    level 1, the second to level 2, etc. This also corresponds to sort
    order, from minor to major, when iterating through a data stream.

  break ( [ <level_name> ] )
    The break method provides a convenient way to check whether the last
    invocation of the test method resulted in a control break, or a control
    break greater than or equal to the <level_name> optionally provided as
    an argument.

    For example, if you have levels 'City', 'State' and 'Country', and
    there's a control break on level 1 (City), then invoking break() will
    return 1 and therefore be treated as true within a condition. If there
    was no control break, then 0 (false) is returned.

    When invoked with a level name argument, break will map the level name
    to a level number and compare it to the control break level determined
    by the last invocation of test(). If the tested control break level
    number is equal or higher than the argument level, then that level
    number is returned and, since it will be non-zero, treated as a true
    value within a condition. Otherwise, zero (false) is returned.

    Ultimately the point of this is that you can use it to write a series of
    actions, like printing subtotals and clearing subtotal variables, such
    that a higher level control break will trigger actions associated with
    lower level control breaks. For example:

        my $cb = ControlBreak( qw/City State Country/ );

        if ( $cb->break() ) {
            say '=== control break detected at level: ' . $cb->levelname;
        }
        if ( $cb->break('City') ) {
            say "City total: $city";
            $city = 0;
        }
        if ( $cb->break('State') ) {
            say "State total: $state";
            $state = 0;
        }
        if ( $cb->break('Country') ) {
            say "Country total: $country";
            $country = 0;
        }

    In this example, when a Country control break is detected all three
    subtotals will be printed. When a State control break is detected, only
    State and City will print.

  comparison ( level_name => [ 'eq' | '==' | sub ] ... )
    The comparison method accepts a hash which sets the comparison
    operations for the designated levels. Keywords must match the level
    names provide in new(). Values can be '==' for numeric comparison, 'eq'
    for alpha comparison, or anonymous subroutines.

    Anonymous subroutines must take two arguments, compare them in some
    fashion, and return a boolean. The first argument to the comparison
    routine will be the value passed to the test() method. The second
    argument will be the corresponding value from the last iteration.

    All levels are provided with default comparison functions as determined
    by new(). This method is provided so you can change one or more of those
    defaults. Any level name not referenced by keys in the argument list
    will be left unchanged.

    Some handy comparison functions are:

        # case-insensitive match
        sub { lc $_[0] eq lc $_[1] }

        # strings coerced to numbers (so 07 and 7 are equal)
        sub { ($_[0] + 0) == ($_[1] + 0) }

        # blank values treated as matched
        sub { $_[0] eq '' ? 1 : $_[0] eq $_[1] }

  continue ()
    Saves the values most recently provided to the test() method so they can
    be compared to new values on the next iteration.

    On the next iteration these values will be accessible via the last()
    method.

    continue is best invoked within the continue block of a loop, to make
    sure it isn't missed.

    continue cannot be used in conjunction with test_and_do, which
    internally calls test and continue for you.

  last ($level)
    Returns the value (of the corresponding level) that was given to the
    test() method called prior to the most recent one.

    The argument can be a level name or a level number.

    Normally this is used while iterating through a data stream. When a
    level change (i.e. control break) is detected, the current data value
    has changed relative to the preceding iteration. At this point it may be
    necessary to take some action, such a printing a subtotal. But, the
    subtotal will be for the preceding group of data and the current value
    belongs to the next group. The last() method allows you to access the
    value for the group that was just processed so, for example, the group
    name can be included on the subtotal line.

    For example, if control levels were named 'X' and 'Y' and you are
    iterating through data and invoking test($x, $y) at each iteration, then
    invoking $cb->last('Y') on iteration 9 will returns the value of $y on
    iteration 8.

    Note that continue() should not be invoked before last() within the
    scope of an iteration loop; i.e. continue() should be the last thing
    done before the next turn of the loop.

  levelname
    Return the level name for the most recent invocation of the test method.

  levelnum
    Return the level number for the most recent invocation of the test
    method.

  level_numbers
    Return a list of level numbers corresponding to the levels defined in
    new(). This can be useful, for example, when you want to set up some
    lexical variables for use as indexes into a list you might use to
    accumulate subtotals.

        my $cb = ControlBreak->new( qw( L1 L2 EOD ) );
        my @totals;
        my ($L1, $L2, $EOD) = $cb->level_numbers;

        foreach my $sublist (@list_of_lists) {
            my ($control1, $control2, $number) = $sublist->@*;
            ...
            my $sub_totals = sub {
                if ($cb->break('L1')) {
                    # report the L1 subtotal here
                    $totals[$L1] = 0; # clear the subtotal
                }
                ...
                # accumulate subtotals
                map { $totals[$_] += $number } $cb->level_numbers;
            };

            $cb->test_and_do(
                $control1,
                $control2,
                $cb->iteration == $list_of_lists - 1,
                $sub_totals
            );
        }

  reset
    Resets the state of the object so it can be used again for another set
    of iterations using the same number and type of controls establish when
    the object was instantiated with new(). Any comparisons that were
    subsequently modified are retained.

  test ( $var1 [, $var2 ]... )
    Submits the control variables for testing against the values from the
    previous iteration.

    Testing is done in reverse order, from highest to lowest (major to
    minor) and stops once a change is detected. Where it stops determines
    the control break level. For example, if $var2 changed, method levelnum
    will return 2. If $var2 did not change, but $var1 did, then method
    levelnum will return 1. If nothing changes, then levelnum will return 0.

    Note that the level numbers set by test(...) are true if there was a
    level change, and false if there wasn't. So, they can be used as a
    simple boolean test of whether there was a change. Or you can use the
    break method to determine whether any control break has occured.

    Because level numbers correspond to the hierachy of data order, they can
    be use to trigger multiple actions; e.g. levelnum >= 1 could be used to
    print subtotals for levels 1 whenever a control break occured for level
    1, 2 or 3. It is usually the case that higher control breaks are meant
    to cascade to lower control levels and this can be achieved in this
    fashion. The break method simplifies this.

    Note that method continue() must be called at the end of each iteration
    in order to save the values of the iteration for the next iteration. If
    not, the next test(...) invocation will croak.

  test_and_do ( $var1 [, $var2 ]... $var_end, $coderef )
    The test_and_do() method is similar to test(). It takes the same
    arguments as test(), plus one additional argument that is an anonymous
    code reference. Internally, it calls test() and then, if there is a
    control break, calls the anonymous subroutine provided in the last
    argument. Typically, that code will perform work related to subtotals or
    other actions necessary when a control break occurs.

    But test_and_do does one other thing. It expects the last control
    variable ($var_end) to be an end of data indicator, such as the perl
    builtin operator eof. This indicator should return false on each
    iteration over the data until the very last iteration -- when it should
    change to true, thereby triggering a major control break.

    What test_and_do does then is to add an extra loop. This simulates a
    final record and will trigger test() to signal control breaks at all
    levels. Thus, the code provided will be executed between every change of
    data AND after all data has been iterated over.

    This avoids the necessity of repeating the control break actions you've
    put inside the data loop immediately after the loop's closing bracket.
    When you just use test and continue, an end-of-data control break won't
    occur and the simplist workaround is to just duplicate your control
    break code after the loops closing bracket.

    Here's a typical use case involving end of file processing. Note the
    extra control level, named 'EOF', and the use of the eof builtin
    function as the second last argument of test_and_do:

        my $cb = ControlBreak->new( qw( L1 L2 EOF ) );

        my $lev1_subtotal = 0;
        my $lev2_subtotal = 0;
        my $grand_total = 0;

        while (my $line = <>) {
            chomp $line;

            my ($lev1, $lev2, $data) = split "\t", $line;

            my $subtotal_coderef = sub {
                if ($cb->break('L1')) {
                    say $cb->last('L1'), $cb->last('L2'), $lev1_subtotal . '*';
                    $lev1_subtotal = 0;
                }
                ...
                if ($cb->break('EOF')) {
                    say 'Grand total,,', $grand_total, '***';
                }

                $lev1_subtotal  += $data;
                $lev2_subtotal  += $data;
                $gran_total     += $data;
            }

            $cb->test_and_do($lev1, $lev2, eof, $subtotal_coderef);
        }

    Also note that if your subroutine needs to reference variables defined
    outside the scope of the loop (as in this case with the totalling
    variables) then it needs to be defined within the loop so it can be a
    closure over the variables in the enclosing scope.

    Another typical use case involves iterating over a list of values. Here,
    we have no built in function to tell us when we've reached the final
    value, but if we have a fixed list of values we can use the length of
    the list and test it against the value returned by the ControlBreak
    iterator method. For example:

        my $cb = ControlBreak->new( qw( L1 L2 EOD ) );

        my $lev1_subtotal = 0;
        my $lev2_subtotal = 0;
        my $grand_total = 0;

        my $last_iter = @data - 1;

        foreach my $line (@data {
            chomp $line;
            my ($lev1, $lev2, $data) = split "\t", $line;

            my $subtotal_coderef = sub {
                if ($cb->break('L1')) {
                    say $cb->last('L1'), $cb->last('L2'), $lev1_subtotal . '*';
                    $lev1_subtotal = 0;
                }
                ...
                if ($cb->break('EOD')) {
                    say 'Grand total,,', $grand_total, '***';
                }

                $lev1_subtotal  += $data;
                $lev2_subtotal  += $data;
                $gran_total     += $data;
            }

            $cb->test_and_do($lev1, $lev2, $cb->iteration == $last_iter, $subtotal_coderef);
        }

AUTHOR
    Gary Puckering <jgpuckering@rogers.com>

LICENSE AND COPYRIGHT
    Copyright 2022, Gary Puckering

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

    See <https://dev.perl.org/licenses/artistic.html>

