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,2345606DESCRIPTION
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 the interation field is incremented by test() (or test_and_do()). Therefore, when called within 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 hierarchical 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_name_or_number> )
For the corresponding level, returns the value 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 occurred.
Because level numbers correspond to the hierarchical 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 occurred 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 simplest 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.