| 1 |
package Biblio::COUNTER; |
| 2 |
|
| 3 |
use Biblio::COUNTER::Report; |
| 4 |
|
| 5 |
use warnings; |
| 6 |
use strict; |
| 7 |
|
| 8 |
use vars qw($VERSION); |
| 9 |
|
| 10 |
$VERSION = '0.11'; |
| 11 |
|
| 12 |
sub report { |
| 13 |
my ($cls, $how, %args) = @_; |
| 14 |
if (ref($how) eq 'ARRAY') { |
| 15 |
die "Instantiating a report from an array not yet implemented"; |
| 16 |
} |
| 17 |
elsif (ref($how)) { |
| 18 |
# Read report from a filehandle |
| 19 |
my $fh = $how; |
| 20 |
my $callbacks = delete($args{'callback'}) || {}; |
| 21 |
my $report = Biblio::COUNTER::Report->new( |
| 22 |
%args, |
| 23 |
'fh' => $fh, |
| 24 |
'callback' => { |
| 25 |
'output' => sub { |
| 26 |
my ($self, $output) = @_; |
| 27 |
print $output, "\n"; |
| 28 |
}, |
| 29 |
%$callbacks, |
| 30 |
}, |
| 31 |
'rows' => [], |
| 32 |
'errors' => 0, |
| 33 |
'warnings' => 0, |
| 34 |
# Current position within the report |
| 35 |
'r' => 0, |
| 36 |
'c' => '', |
| 37 |
# Current scope (REPORT, HEADER, or RECORD) |
| 38 |
'scope' => undef, |
| 39 |
# Current field (NAME, DESCRIPTION, etc. or TITLE, PUBLISHER, etc.) |
| 40 |
'field' => undef, |
| 41 |
# Containers |
| 42 |
'report' => undef, |
| 43 |
'header' => undef, |
| 44 |
'record' => undef, |
| 45 |
'container' => undef, # Current container |
| 46 |
); |
| 47 |
} |
| 48 |
else { |
| 49 |
# Instantiate a named report, e.g., "Journal Report 1 (R2)" |
| 50 |
my $name = $how; |
| 51 |
my ($genre, $number, $release) = $cls->_parse_report_name($name); |
| 52 |
die "Unrecognized report type: $name" |
| 53 |
unless defined $genre; |
| 54 |
# Create the "model" object |
| 55 |
$cls = "Biblio::COUNTER::Report::Release${release}::${genre}Report${number}"; |
| 56 |
die "Unimplemented report type: $name" |
| 57 |
unless eval "use $cls; 1"; |
| 58 |
return $cls->new(%args); |
| 59 |
} |
| 60 |
} |
| 61 |
|
| 62 |
sub _parse_report_name { |
| 63 |
my ($cls, $name) = @_; |
| 64 |
my ($genre, $number, $release); |
| 65 |
if ($name =~ s/^\s*(Journal|Database|Book)\s+Report\s+(\w+)\s*//) { |
| 66 |
($genre, $number) = ($1, $2); |
| 67 |
} |
| 68 |
else { |
| 69 |
return; |
| 70 |
} |
| 71 |
if ($name =~ /^\(R?(\d+[a-z]?)\)/) { |
| 72 |
$release = $1; |
| 73 |
} |
| 74 |
else { |
| 75 |
$release = 2; # XXX Safe to default? |
| 76 |
} |
| 77 |
return ($genre, $number, $release); |
| 78 |
} |
| 79 |
|
| 80 |
|
| 81 |
1; |
| 82 |
|
| 83 |
|
| 84 |
=pod |
| 85 |
|
| 86 |
=head1 NAME |
| 87 |
|
| 88 |
Biblio::COUNTER - COUNTER Codes of Practice report processing |
| 89 |
|
| 90 |
=head1 SYNOPSIS |
| 91 |
|
| 92 |
# --- Process a report |
| 93 |
|
| 94 |
# (1) Using Biblio::COUNTER |
| 95 |
$report = Biblio::COUNTER->report(\*STDIN)->process; |
| 96 |
$report = Biblio::COUNTER->report($file)->process; |
| 97 |
|
| 98 |
# (2) Using Biblio::COUNTER::Processor or a subclass |
| 99 |
$processor = Biblio::COUNTER::Processor::Default->new;\ |
| 100 |
$report = $processor->run(\*STDIN); |
| 101 |
$report = $processor->run($file); |
| 102 |
$report = $processor->run(Biblio::COUNTER->new(\*STDIN)); |
| 103 |
|
| 104 |
# --- Access information in a processed report |
| 105 |
|
| 106 |
warn "Invalid report" unless $report->is_valid; |
| 107 |
|
| 108 |
# Access data in the report |
| 109 |
$name = $report->name; |
| 110 |
# e.g., "Database Report 2 (R2)" |
| 111 |
$descrip = $report->description; |
| 112 |
# e.g., "Turnaways by Month and Database" |
| 113 |
$date_run = $report->date_run; |
| 114 |
# e.g., "2008-04-11" |
| 115 |
$criteria = $report->criteria; |
| 116 |
$publisher = $report->publisher; |
| 117 |
$platform = $report->platform; |
| 118 |
$periods = $report->periods; |
| 119 |
# e.g., [ "2008-01", "2008-02", "2008-03" ] |
| 120 |
|
| 121 |
foreach $rec ($report->records) { |
| 122 |
$title = $rec->{title}; |
| 123 |
$publisher = $rec->{publisher}; |
| 124 |
$platform = $rec->{platform}; |
| 125 |
$count = $rec->{count}; |
| 126 |
foreach $period (@periods) { |
| 127 |
$period_count = $count->{$period}; |
| 128 |
while (($metric, $n) = each %$period_count) { |
| 129 |
# e.g., ("turnaways", 3) |
| 130 |
} |
| 131 |
} |
| 132 |
} |
| 133 |
|
| 134 |
=head1 NOTE |
| 135 |
|
| 136 |
Because the COUNTER Codes of Practice are so poorly written and |
| 137 |
documented, with incomplete specifications and inconsistent |
| 138 |
terminology, it has been necessary to make certain assumptions and |
| 139 |
normalizations in the code and documentation of this module. |
| 140 |
|
| 141 |
First, all reports must be in plain text, tab- or comma-delimited |
| 142 |
format; Excel spreadsheets are not allowed. (To convert an Excel |
| 143 |
spreadsheet to tab-delimited text, consider using |
| 144 |
L<Spreadsheet::ParseExcel::Simple|Spreadsheet::ParseExcel::Simple>. |
| 145 |
|
| 146 |
(XML formats may be handled in a future version of this module.) |
| 147 |
|
| 148 |
Some terminology notes are in order: |
| 149 |
|
| 150 |
=over 4 |
| 151 |
|
| 152 |
=item B<name> |
| 153 |
|
| 154 |
The B<name> of a report fully denotes the report's type and the version |
| 155 |
of the COUNTER Codes of Practice that defines it. For example, |
| 156 |
C<Journal Report 1 (R2)>. COUNTER sometimes refers to this as the |
| 157 |
report I<title>. |
| 158 |
|
| 159 |
=item B<description> |
| 160 |
|
| 161 |
This is the phrase, also defined by the COUNTER Codes of Practice, that |
| 162 |
describes the contents of a report. For example, B<Journal Report 1> |
| 163 |
is described as C<Number of Successful Full-Text Article Requests by |
| 164 |
Month and Journal>. |
| 165 |
|
| 166 |
=item B<code> |
| 167 |
|
| 168 |
This is the term I use for the short name that identifies the type, |
| 169 |
B<but not the version>, of a COUNTER report. For example, C<JR1> is the code |
| 170 |
for B<Journal Report 1> reports. |
| 171 |
|
| 172 |
=item B<metric> |
| 173 |
|
| 174 |
A metric is a particular measure of usage (or non-usage), including the |
| 175 |
number of searches or sessions in a database or the number of full-text |
| 176 |
articles in a journal downloaded successfully. |
| 177 |
|
| 178 |
=back |
| 179 |
|
| 180 |
=head1 METHODS |
| 181 |
|
| 182 |
=over 4 |
| 183 |
|
| 184 |
=item B<report>(I<$how>, [I<%args>]) |
| 185 |
|
| 186 |
Create a new report instance. |
| 187 |
|
| 188 |
Set I<$how> to a glob ref (e.g., C<\*STDIN>) to specify a filehandle |
| 189 |
from which an existing report will be read. |
| 190 |
|
| 191 |
Specify a report name in I<$how> (e.g., C<Database Report 2 (R2)>) to |
| 192 |
instantiate a new, empty report. (Report generation is not yet implemented.) |
| 193 |
|
| 194 |
I<%args> may contain any of the following: |
| 195 |
|
| 196 |
=over 4 |
| 197 |
|
| 198 |
=item B<treat_blank_counts_as_zero> |
| 199 |
|
| 200 |
If set to a true value, a blank cell where a count was expected is |
| 201 |
treated as if it contained a zero; otherwise, blank counts are silently |
| 202 |
ignored (the default). |
| 203 |
|
| 204 |
=item B<change_not_available_to_blank> |
| 205 |
|
| 206 |
If set to a true value (the default), the value C<n/a>) in a count |
| 207 |
field will be changed to the empty string. It will B<never> be treated |
| 208 |
as if it were zero, regardless of the B<treat_blank_counts_as_zero> |
| 209 |
setting. |
| 210 |
|
| 211 |
=item B<callback> |
| 212 |
|
| 213 |
Get or set a reference to a hash of (I<$event>, I<$code>) pairs |
| 214 |
specifying what to do for each of the events described under |
| 215 |
L<CALLBACKS>. |
| 216 |
|
| 217 |
Each I<$code> must be a coderef, not the name of a function or method. |
| 218 |
|
| 219 |
If an event is not specified in this hash, then the default action for the |
| 220 |
event will be taken. |
| 221 |
|
| 222 |
=back |
| 223 |
|
| 224 |
=item B<name> |
| 225 |
|
| 226 |
Get or set the report's name: this is the official name defined by the COUNTER |
| 227 |
codes of practice. See L<REPORTS SUPPORTED> for a complete list of the |
| 228 |
reports supported by this verison of L<Biblio::COUNTER|Biblio::COUNTER>. |
| 229 |
|
| 230 |
=item B<code> |
| 231 |
|
| 232 |
Get or set the report's code: this is the short string (e.g., C<JR1>) |
| 233 |
that identifies the type, B<but not the version>, of a COUNTER report. |
| 234 |
|
| 235 |
=item B<description> |
| 236 |
|
| 237 |
Get or set the report's description: this is the official description |
| 238 |
defined by the COUNTER codes of practice. For example, the C<Journal |
| 239 |
Report 1 (R2)> report has the description C<Number of Successful |
| 240 |
Full-Text Article Requests by Month and Journal>. |
| 241 |
|
| 242 |
=item B<date_run> |
| 243 |
|
| 244 |
Get or set the date on which the report was run. The date, if valid, is in |
| 245 |
the ISO8601 standard form C<YYYY-MM-DD>. |
| 246 |
|
| 247 |
=item B<criteria> |
| 248 |
|
| 249 |
Get or set the report criteria. This is a free text field. |
| 250 |
|
| 251 |
=item B<periods> |
| 252 |
|
| 253 |
Get or set the periods for which the report contains counts. To |
| 254 |
simplify things, periods are returned (and must be set) in the ISO 8601 |
| 255 |
standard form C<YYYY-MM>. |
| 256 |
|
| 257 |
=item B<publisher> |
| 258 |
|
| 259 |
Get or set the publisher common to all of the resources in the report. |
| 260 |
|
| 261 |
=item B<platform> |
| 262 |
|
| 263 |
Get or set the platform common to all of the resources in the report. |
| 264 |
|
| 265 |
=back |
| 266 |
|
| 267 |
=head1 CALLBACKS |
| 268 |
|
| 269 |
While processing a report, a number of different B<events> occur. For |
| 270 |
example, a B<fixed> event occurs when a field whose value is invalid |
| 271 |
is corrected. For event different kind of event, a B<callback> may be |
| 272 |
specified that is triggered each time the event occurs; see the B<report> |
| 273 |
method for how to specify a callback. |
| 274 |
|
| 275 |
Callbacks must be coderefs, not function or method names. |
| 276 |
|
| 277 |
For example, the following callbacks may be used to provide an indication of |
| 278 |
the progress in processing it: |
| 279 |
|
| 280 |
$record_number = 0; |
| 281 |
%callbacks = ( |
| 282 |
'begin_report' => sub { |
| 283 |
print STDERR "Beginning report: "; |
| 284 |
}, |
| 285 |
'end_header' => sub { |
| 286 |
my ($report, $header) = @_; |
| 287 |
print STDERR $report->name, "\n"; |
| 288 |
} |
| 289 |
'end_record' => sub { |
| 290 |
my ($report, $record) = @_; |
| 291 |
++$record_number; |
| 292 |
print STDERR "$record_number " |
| 293 |
if $record_number % 20 == 0; |
| 294 |
print STDERR "\n" |
| 295 |
if $record_number % 200 == 0; |
| 296 |
}, |
| 297 |
'end_report' => sub { |
| 298 |
my ($report) = @_; |
| 299 |
if ($report->is_valid) { |
| 300 |
print STDERR "OK\n"; |
| 301 |
} |
| 302 |
else { |
| 303 |
print STDERR "INVALID\n"; |
| 304 |
} |
| 305 |
}, |
| 306 |
); |
| 307 |
|
| 308 |
By default, the only callback defined is for B<output>; it prints each |
| 309 |
line of input (corrected, if there were correctable problems) to |
| 310 |
standard output. (Spurious blank lines are not printed.) |
| 311 |
|
| 312 |
Events fall into four broad categories: B<structure>, B<validation>, |
| 313 |
B<tracing>, and B<data>. |
| 314 |
|
| 315 |
=head2 Structure |
| 316 |
|
| 317 |
Logically, a COUNTER report has the following structure: |
| 318 |
|
| 319 |
report |
| 320 |
header |
| 321 |
body |
| 322 |
record |
| 323 |
record |
| 324 |
... |
| 325 |
|
| 326 |
=over 4 |
| 327 |
|
| 328 |
=item B<begin_file>(I<$report>, I<$file>) |
| 329 |
|
| 330 |
Parsing of the given file is beginning. This is always the first event |
| 331 |
triggered. At the time this callback is invoked, the report has not yet been |
| 332 |
identified. |
| 333 |
|
| 334 |
=item B<end_file>(I<$report>, I<$file>) |
| 335 |
|
| 336 |
Parsing of the given file has ended. This is always the last event |
| 337 |
triggered. |
| 338 |
|
| 339 |
=item B<begin_report>(I<$report>) |
| 340 |
|
| 341 |
Processing of the report is beginning. At the time this callback is invoked, |
| 342 |
the report has not yet been identified. |
| 343 |
|
| 344 |
=item B<end_report>(I<$report>) |
| 345 |
|
| 346 |
Processing of the report has ended. This is always the last event |
| 347 |
triggered. |
| 348 |
|
| 349 |
=item B<begin_header>(I<$report>, I<$header>) |
| 350 |
|
| 351 |
Processing of the report's header is beginning. The header is everything |
| 352 |
before the first data row. |
| 353 |
|
| 354 |
I<$header> is a reference to an empty hash; the callback code may, if it wishes, |
| 355 |
put something into this hash. |
| 356 |
|
| 357 |
=item B<end_header>(I<$report>, I<$header>) |
| 358 |
|
| 359 |
Processing of the report's header is complete. |
| 360 |
|
| 361 |
I<$header> is a reference to the same hash referenced in the B<begin_header> |
| 362 |
callback, but which now contains one or more of the elements listed below. |
| 363 |
(These elements are described under B<METHODS> above): |
| 364 |
|
| 365 |
=over 4 |
| 366 |
|
| 367 |
=item B<date_run> |
| 368 |
|
| 369 |
The date on which the report was run, in the ISO8601 standard form |
| 370 |
C<YYYY-MM-DD>. |
| 371 |
|
| 372 |
=item B<criteria> |
| 373 |
|
| 374 |
The report criteria. |
| 375 |
|
| 376 |
=item B<description> |
| 377 |
|
| 378 |
The report's description (e.g., C<Turnaways by Month and Database>). |
| 379 |
|
| 380 |
=item B<periods> |
| 381 |
|
| 382 |
The periods for which the report contains counts, in the ISO 8601 |
| 383 |
standard form C<YYYY-MM>. |
| 384 |
|
| 385 |
=item B<publisher> |
| 386 |
|
| 387 |
The publisher common to all of the resources in the report. |
| 388 |
|
| 389 |
=item B<platform> |
| 390 |
|
| 391 |
The platform common to all of the resources in the report. |
| 392 |
|
| 393 |
=back |
| 394 |
|
| 395 |
=item B<begin_body>(I<$report>) |
| 396 |
|
| 397 |
Processing of the report's body is beginning. The body is the part of the |
| 398 |
report that contains data rows. |
| 399 |
|
| 400 |
=item B<end_body>(I<$report>) |
| 401 |
|
| 402 |
Processing of the report's body is complete. |
| 403 |
|
| 404 |
=item B<begin_record>(I<$report>, I<$record>) |
| 405 |
|
| 406 |
Processing of a new record is beginning. (In some COUNTER reports, a record |
| 407 |
occupies more than one row.) |
| 408 |
|
| 409 |
I<$record> is a reference to a hash, which is empty at the time the |
| 410 |
event is triggered. |
| 411 |
|
| 412 |
=item B<end_record>(I<$report>, I<$record>) |
| 413 |
|
| 414 |
I<$record> is a reference to a hash that contains the data found in the |
| 415 |
record (title, publisher, counts, etc.). Fields that are invalid and |
| 416 |
uncorrectable will B<not> be represented in the hash -- e.g., if a title is |
| 417 |
blank then there will be no B<title> element in the hash. |
| 418 |
|
| 419 |
=back |
| 420 |
|
| 421 |
=head2 Validation |
| 422 |
|
| 423 |
Each of these events is triggered when a cell (or, in the case of |
| 424 |
B<skip_blank_row>, a row) is validated. |
| 425 |
|
| 426 |
The cell's row and column (e.g., C<D7>) may be retrieved by calling |
| 427 |
C<< $report-E<gt>current_position >>. |
| 428 |
|
| 429 |
Note that a single cell may trigger more than one validation event -- |
| 430 |
e.g., a cell may be trimmed and then deleted -- and there is no guarantee |
| 431 |
that these events will occur in any particular order. |
| 432 |
|
| 433 |
=over 4 |
| 434 |
|
| 435 |
=item B<ok>(I<$report>, I<$field_name>, I<$value>) |
| 436 |
|
| 437 |
A cell's value is valid. |
| 438 |
|
| 439 |
=item B<trimmed>(I<$report>, I<$field_name>, I<$value>) |
| 440 |
|
| 441 |
Whitespace has been trimmed from the beginning and/or end of a cell. |
| 442 |
|
| 443 |
=item B<fixed>(I<$report>, I<$field_name>, I<$old_value>, I<$new_value>) |
| 444 |
|
| 445 |
A cell's value was invalid but has been corrected. |
| 446 |
|
| 447 |
=item B<cant_fix>(I<$report>, I<$field_name>, I<$value>, I<$expected>) |
| 448 |
|
| 449 |
A cell's value is invalid and cannot be corrected. The expected value may |
| 450 |
be an exact string (e.g., C<EBSCOhost>) or merely a general hint (e.g., |
| 451 |
C<< E<lt>issnE<gt> >>). |
| 452 |
|
| 453 |
=item B<deleted>(I<$report>, I<$value>) |
| 454 |
|
| 455 |
A spurious cell has been deleted. (A this time, this only occurs for |
| 456 |
blank cells at the end of a row.) |
| 457 |
|
| 458 |
=item B<skip_blank_row>(I<$report>) |
| 459 |
|
| 460 |
A blank row that doesn't belong here has been skipped. |
| 461 |
|
| 462 |
=back |
| 463 |
|
| 464 |
=head2 Tracing |
| 465 |
|
| 466 |
=over 4 |
| 467 |
|
| 468 |
=item B<input>(I<$line>) |
| 469 |
|
| 470 |
A line of input has been read. |
| 471 |
|
| 472 |
=item B<line>(I<$line_number>) |
| 473 |
|
| 474 |
The report processor has moved to the next line of input. |
| 475 |
|
| 476 |
=item B<output>(I<$line>) |
| 477 |
|
| 478 |
A new line of output is ready. The default is to print the line to |
| 479 |
standard output. Both valid and invalid lines, including invalid lines |
| 480 |
that could not be corrected as well as those that could be corrected, |
| 481 |
trigger an output event. Blank lines that have been skipped do not. |
| 482 |
|
| 483 |
=back |
| 484 |
|
| 485 |
=head2 Data |
| 486 |
|
| 487 |
=over 4 |
| 488 |
|
| 489 |
=item B<count>(I<$report>, I<$scope>, I<$metric>, I<$period>, I<$value>) |
| 490 |
|
| 491 |
A valid count has been identified within the report. |
| 492 |
|
| 493 |
I<$scope> is either C<report> (for summary counts that appear at the |
| 494 |
top of the report) or C<record> (for counts that occur within the body |
| 495 |
of the report). |
| 496 |
|
| 497 |
I<$metric> is the type of event being counted, and is always one of the following: |
| 498 |
|
| 499 |
=over 4 |
| 500 |
|
| 501 |
=item C<requests> |
| 502 |
|
| 503 |
=item C<searches> |
| 504 |
|
| 505 |
=item C<sessions> |
| 506 |
|
| 507 |
=item C<turnaways> |
| 508 |
|
| 509 |
=back |
| 510 |
|
| 511 |
I<$period> is a year and month, in the ISO8601 form C<YYYY-MM>. |
| 512 |
|
| 513 |
I<$value> is the number of requests (or searches, or whatever). |
| 514 |
|
| 515 |
B<count> events are B<not> triggered for blank counts unless the |
| 516 |
B<treat_blank_counts_as_zero> option was set to a true value when the |
| 517 |
report was instantiated. |
| 518 |
|
| 519 |
=item B<count_ytd>(I<$report>, I<$scope>, I<$metric>, I<$value>) |
| 520 |
=item B<count_ytd_html>(I<$report>, I<$scope>, I<$metric>, I<$value>) |
| 521 |
=item B<count_ytd_pdf>(I<$report>, I<$scope>, I<$metric>, I<$value>) |
| 522 |
|
| 523 |
A valid YTD count has been identified. |
| 524 |
|
| 525 |
I<$scope> is either C<report> (for summary counts that appear at the |
| 526 |
top of the report) or C<record> (for counts that occur within the body |
| 527 |
of the report). |
| 528 |
|
| 529 |
=back |
| 530 |
|
| 531 |
=head1 REPORTS SUPPORTED |
| 532 |
|
| 533 |
Biblio::COUNTER implements processing of text-format (comma- or tab-delimited) |
| 534 |
COUNTER reports only. XML formats are not supported at this time. |
| 535 |
|
| 536 |
The following is a list of COUNTER reports, with full name and description, |
| 537 |
that are supported by this version of L<Biblio::COUNTER|Biblio::COUNTER>: |
| 538 |
|
| 539 |
=over 4 |
| 540 |
|
| 541 |
=item C<Journal Report 1 (R2)> |
| 542 |
|
| 543 |
Number of Successful Full-Text Article Requests by Month and Journal |
| 544 |
|
| 545 |
=item C<Journal Report 1a (R2)> |
| 546 |
|
| 547 |
Number of Successful Full-Text Article Requests from an Archive by Month and Journal |
| 548 |
|
| 549 |
=item C<Journal Report 2 (R2)> |
| 550 |
|
| 551 |
Turnaways by Month and Journal |
| 552 |
|
| 553 |
=item C<Database Report 1 (R2)> |
| 554 |
|
| 555 |
Total Searches and Sessions by Month and Database |
| 556 |
|
| 557 |
=item C<Database Report 2 (R2)> |
| 558 |
|
| 559 |
Turnaways by Month and Database |
| 560 |
|
| 561 |
=item C<Database Report 3 (R2)> |
| 562 |
|
| 563 |
Total Searches and Sessions by Month and Service |
| 564 |
|
| 565 |
=back |
| 566 |
|
| 567 |
Other reports, including Release 3 reports, will be supported in the future. |
| 568 |
|
| 569 |
=head1 SEE ALSO |
| 570 |
|
| 571 |
L<http://www.projectcounter.org/> |
| 572 |
|
| 573 |
=head1 AUTHOR |
| 574 |
|
| 575 |
Paul Hoffman (nkuitse AT cpan DOT org). |
| 576 |
|
| 577 |
=head1 COPYRIGHT |
| 578 |
|
| 579 |
Copyright 2008 Paul M. Hoffman. |
| 580 |
|
| 581 |
This is free software, and is made available under the same terms as Perl |
| 582 |
itself. |
| 583 |
|
| 584 |
=cut |