NAME
PTools::Counter - Maintain counters; format syntactically correct results.
VERSION
This document describes version 0.08, released April, 2005.
SYNOPSIS
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');
DEPENDENCIES
PTools::String, PTools::Date::Format and PTools::Time::Elapsed.
DESCRIPTION
Constructor
- new ( )
-
Create a new object used to manage various counter values.
use PTools::Counter; $countObj = new PTools::Counter;
Methods
- init ( CounterName "-internal-" )
- init ( CounterName [, Word, Plural [, Singular ] ] )
-
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.
- CounterName
-
The name used to access a particular counter value by other methods in this class.
- Word
-
The singular (or base) of a word used to describe a particular counter
- Plural
-
The plural ending for Word.
- Singular
-
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-");
- incr ( CounterName [, IncrValue ] )
- decr ( CounterName [, DecrValue ] )
-
Increment or decrement a CounterName. Default is to add or subtract one. Pass an additional integer value for a different increment or decrement.
- CounterName
-
The name used to access a particular counter value.
- IncrValue
- DecrValue
-
Value for an increment or decrement.
- del ( CounterName )
-
Delete the counter named CounterName from the counter object.
- reset ( CounterName [, NewValue ] )
-
Reset the counter named CounterName to zero.
- value ( CounterName )
-
Return the current value for the counter named CounterName.
- list
-
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;
- get ( CounterName [, Word, Plural [, Singular ] ] )
- result ( CounterName [, Word, Plural [, Singular ] ] )
-
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.
- head ( [ Text ] )
-
Set heading text used by the format method.
- foot ( [ Text ] )
-
Set footing text used by the format method.
- start ( [ Text ] [, Time ] )
-
Set "start time" text used by the format method.
- end ( [ Text ] [, Time ] )
-
Set "end time" text used by the format method.
- elapsed ( [ Text ] [, Time ] )
-
Set "end time" text used by the format method.
- tmFormat ( [ TimeFormat ] )
-
Return or set the TimeFormat string used to control the display of the ElapsedTime value, when used.
- TimeFormat
-
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.
- Header
-
Heading text used during formatting.
-
Footing text used during formatting.
- NonZeroOnly
-
Flag to indicate that any counters with a current value of zero should not be included in the resulting formatted text.
- TimeFormat
-
The TimeFormat string used to control the display of the ElapsedTime value, when used. See the tmFormat method, above, for examples.
- CounterList
-
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.
Examples:
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;
INHERITANCE
None currently.
AUTHOR
Chris Cobb [no dot spam at ccobb dot net]
COPYRIGHT
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.