| Biblio::COUNTER(3pm) | User Contributed Perl Documentation | Biblio::COUNTER(3pm) |
Biblio::COUNTER - COUNTER Codes of Practice report processing
# --- Process a report
# (1) Using Biblio::COUNTER
$report = Biblio::COUNTER->report(\*STDIN)->process;
$report = Biblio::COUNTER->report($file)->process;
# (2) Using Biblio::COUNTER::Processor or a subclass
$processor = Biblio::COUNTER::Processor::Default->new;\
$report = $processor->run(\*STDIN);
$report = $processor->run($file);
$report = $processor->run(Biblio::COUNTER->new(\*STDIN));
# --- Access information in a processed report
warn "Invalid report" unless $report->is_valid;
# Access data in the report
$name = $report->name;
# e.g., "Database Report 2 (R2)"
$descrip = $report->description;
# e.g., "Turnaways by Month and Database"
$date_run = $report->date_run;
# e.g., "2008-04-11"
$criteria = $report->criteria;
$publisher = $report->publisher;
$platform = $report->platform;
$periods = $report->periods;
# e.g., [ "2008-01", "2008-02", "2008-03" ]
foreach $rec ($report->records) {
$title = $rec->{title};
$publisher = $rec->{publisher};
$platform = $rec->{platform};
$count = $rec->{count};
foreach $period (@periods) {
$period_count = $count->{$period};
while (($metric, $n) = each %$period_count) {
# e.g., ("turnaways", 3)
}
}
}
Because the COUNTER Codes of Practice are so poorly written and documented, with incomplete specifications and inconsistent terminology, it has been necessary to make certain assumptions and normalizations in the code and documentation of this module.
First, all reports must be in plain text, tab- or comma-delimited format; Excel spreadsheets are not allowed. (To convert an Excel spreadsheet to tab-delimited text, consider using Spreadsheet::ParseExcel::Simple.
(XML formats may be handled in a future version of this module.)
Some terminology notes are in order:
Set $how to a glob ref (e.g., "\*STDIN") to specify a filehandle from which an existing report will be read.
Specify a report name in $how (e.g., "Database Report 2 (R2)") to instantiate a new, empty report. (Report generation is not yet implemented.)
%args may contain any of the following:
Each $code must be a coderef, not the name of a function or method.
If an event is not specified in this hash, then the default action for the event will be taken.
While processing a report, a number of different events occur. For example, a fixed event occurs when a field whose value is invalid is corrected. For event different kind of event, a callback may be specified that is triggered each time the event occurs; see the report method for how to specify a callback.
Callbacks must be coderefs, not function or method names.
For example, the following callbacks may be used to provide an indication of the progress in processing it:
$record_number = 0;
%callbacks = (
'begin_report' => sub {
print STDERR "Beginning report: ";
},
'end_header' => sub {
my ($report, $header) = @_;
print STDERR $report->name, "\n";
}
'end_record' => sub {
my ($report, $record) = @_;
++$record_number;
print STDERR "$record_number "
if $record_number % 20 == 0;
print STDERR "\n"
if $record_number % 200 == 0;
},
'end_report' => sub {
my ($report) = @_;
if ($report->is_valid) {
print STDERR "OK\n";
}
else {
print STDERR "INVALID\n";
}
},
);
By default, the only callback defined is for output; it prints each line of input (corrected, if there were correctable problems) to standard output. (Spurious blank lines are not printed.)
Events fall into four broad categories: structure, validation, tracing, and data.
Logically, a COUNTER report has the following structure:
report
header
body
record
record
...
$header is a reference to an empty hash; the callback code may, if it wishes, put something into this hash.
$header is a reference to the same hash referenced in the begin_header callback, but which now contains one or more of the elements listed below. (These elements are described under METHODS above):
$record is a reference to a hash, which is empty at the time the event is triggered.
Each of these events is triggered when a cell (or, in the case of skip_blank_row, a row) is validated.
The cell's row and column (e.g., "D7") may be retrieved by calling "$report->current_position".
Note that a single cell may trigger more than one validation event -- e.g., a cell may be trimmed and then deleted -- and there is no guarantee that these events will occur in any particular order.
$scope is either "report" (for summary counts that appear at the top of the report) or "record" (for counts that occur within the body of the report).
$metric is the type of event being counted, and is always one of the following:
$period is a year and month, in the ISO8601 form "YYYY-MM".
$value is the number of requests (or searches, or whatever).
count events are not triggered for blank counts unless the treat_blank_counts_as_zero option was set to a true value when the report was instantiated.
$scope is either "report" (for summary counts that appear at the top of the report) or "record" (for counts that occur within the body of the report).
Biblio::COUNTER implements processing of text-format (comma- or tab-delimited) COUNTER reports only. XML formats are not supported at this time.
The following is a list of COUNTER reports, with full name and description, that are supported by this version of Biblio::COUNTER:
Other reports, including Release 3 reports, will be supported in the future.
<http://www.projectcounter.org/>
Paul Hoffman (nkuitse AT cpan DOT org).
Copyright 2008 Paul M. Hoffman.
This is free software, and is made available under the same terms as Perl itself.
| 2023-02-04 | perl v5.36.0 |