PTools::Counter - Maintain counters; format syntactically correct results.
This document describes version 0.08, released April, 2005.
use PTools::Counter; $counter = new PTools::Counter;
Initialize some counters
$counter->init("error", " Errors: "); $counter->init("warn", " Warnings: ");
Increment a counter
$counter->incr("warn");
Display some results
# The following will generate output that resembles: # Warnings: 1 # Errors: 0 foreach my $counterName ("warn","error") { print $counter->result( $counterName ) ."\n"; } # The following will generate output that resembles: # Errors: 0 Warnings: 1 print $counter->result('error'), " ", $counter->result('warn'), "\n"; # Note: using "dot" to concatenate strings invokes # method in "scalar" context, while using a comma # to concatenate invokes method in "array" context. # There may be some differences in the results.
Initialize counters such that results are syntactically correct
$counter->init("error", "Descrepenc","ies","y"); $counter->init("warn", "Warning","s");
Obtain results that are suitable for additional formatting
# The following will generate output that resembles: # Found 0 Descrepencies # Found 1 Warning foreach my $counterName ("error","warn") { ($text,$value) = $counter->result( $counterName ); print "Found $value $text\n"; }
Initialize counter such that results are NOT included in formatting and use it for tracking some event.
$counter->init("nextSequence", "-internal-"); $nextSequence = $counter->incr('nextSequence');
PTools::String, PTools::Date::Format and PTools::Time::Elapsed.
Create a new object used to manage various counter values.
use PTools::Counter; $countObj = new PTools::Counter;
Initialize a counter variable named by CounterName. Optionally can add text that will be used via the format method to create syntactically correct results.
Use the special Word "-internal-" to prevent the counter from being included in any text returned by the format method.
The name used to access a particular counter value by other methods in this class.
The singular (or base) of a word used to describe a particular counter
The plural ending for Word.
Any additional characters required for a singular instance of Word.
Examples:
$counter->init("error", "Descrepenc","ies","y"); $counter->init("warn", "Warning","s"); $counter->init("nextSequence", "-internal-");
Increment or decrement a CounterName. Default is to add or subtract one. Pass an additional integer value for a different increment or decrement.
The name used to access a particular counter value.
Value for an increment or decrement.
Delete the counter named CounterName from the counter object.
Reset the counter named CounterName to zero.
Return the current value for the counter named CounterName.
Return an array (in list context) or a colon-separated string (in scalar context) of the currently defined CounterNames.
(@counterList) = $countObj->list; $counterList = $countObj->list;
Create a formatted result for the counter named CounterName using the current value of the counter.
Parameters are indentical as described in the init method, above.
Also see the format method, below, for a discussion of a more flexible way to display counter results.
Set heading text used by the format method.
Set footing text used by the format method.
Set "start time" text used by the format method.
Set "end time" text used by the format method.
Return or set the TimeFormat string used to control the display of the ElapsedTime value, when used.
Specify a date(1) format string as supported by the Time::Format class.
Default: "%C" # Wed Nov 22 21:05:57 2000 Example: "%a, %d-%b-%Y %I:%M:%S %p" # Wed, 22-Nov-2000 09:05:39 pm Example: "%d-%b-%Y.%I:%M:%S" # 22-Nov-2000.09:05:39
The format method is used to create text from the current state of the current object.
Heading text used during formatting.
Footing text used during formatting.
Flag to indicate that any counters with a current value of zero should not be included in the resulting formatted text.
The TimeFormat string used to control the display of the ElapsedTime value, when used. See the tmFormat method, above, for examples.
Pass an array (list) of CounterNames to be included in the resulting formatted text. By default all counters are included except internal counters. Also see the NonZeroOnly flag, above.
ToDo: Document the "format" method, and include some examples of using with the "init","start","end" methods (etc) that are able to create some interesting results. $counter->start (" Script Started: ", $starttime); $counter->end (" Script Ended: "); $counter->cumulate(" Cumulative Time: "); # is optional $counter->elapsed (" Elapsed Time: "); ... $counter->incr('warn'); $counter->accumulate( $seconds ); ... print $counter->format;
None currently.
Chris Cobb [no dot spam at ccobb dot net]
Copyright (c) 2002-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install PTools, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PTools
CPAN shell
perl -MCPAN -e shell install PTools
For more information on module installation, please visit the detailed CPAN module installation guide.