Debian Codegraph @

lib/Biblio/COUNTER.pm

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
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