NAME
PICA::Record - Perl extension for handling PICA+ records
DESCRIPTION
Module for handling PICA+ records as Perl objects.
INTRODUCTION
What is PICA+?
PICA+ is the internal data format of the Local Library System (LBS) and the Central Library System (CBS) of OCLC, formerly PICA. Similar library formats are the MAchine Readable Cataloging format (MARC) and the Maschinelles Austauschformat für Bibliotheken (MAB). In addition to PICA+ in CBS there is the cataloging format Pica3 which can losslessly be convert to PICA+ and vice versa.
What is PICA::Record?
PICA::Record is a Perl package that provides an API for PICA+ record handling. The package contains a parser interface module PICA::Parser to parse PICA+ (PICA::PlainParser) and PICA XML (PICA::XMLParser). Corresponding modules exist to write data (PICA::Writer and PICA::XMLWriter). PICA+ data is handled in records (PICA::Record) that contain fields (PICA::Field). To fetch records from databases via SRU or Z39.50 there is the interface PICA::Source and to access a record store via CWS webcat interface there is PICA::Store.
You can use PICA::Record for instance to:
convert between PICA+ and PicaXML
process PICA+ records that you have downloaded with WinIBW
download records in native format via SRU or Z39.50
store PICA+ records in a database
CLIENTS AND EXAMPLES
This module includes and installs the scripts parsepica and picawebcat. They provide most functionality on the command line without having to deal with Perl code. Have a look at the documentation of this scripts. More examples are includes in the examples directory if this module - maybe the application you need it already included, so have a look!
SYNOPSIS
To get a deeper insight to the API have a look at the documentation, the examples (directory examples) and tests (directory t). Here are some additional two-liners:
# create a field
my $field = PICA::Field->new(
"028A", "9" => "117060275", "d" => "Martin", "a" => "Schrettinger" );
# create a record and add some fields (note that fields can be repeated)
my $record = PICA::Record->new();
$record->append( '044C', 'a' => "Perl", '044C', 'a' => "Programming", );
# read all records from a file
my @records = PICA::Parser->new->parsefile( $filename )->records();
# read one record from a string
my ($record) = PICA::Parser->parsedata( $picadata, Limit => 1)->records();
# get two fields of a record
my ($f1, $f2) = $record->field( 2, "028B/.." );
# extract some subfield values
my ($given, $surname) = ($record->sf(1,'028A$d'), $record->sf(1,'028A$a'));
# read records from a STDIN and print to STDOUT of field 003@ exists
PICA::Parser->new->parsefile( \STDIN, Record => sub {
my $record = shift;
print $record->to_string() if $record->field('003@');
return;
});
# print record in normalized format and in HTML
print $record->normalized();
print $record->to_html();
# write some records in XML to a file
my $writer = PICA::Writer->new( $filename, format => 'xml' );
$writer->write( @records );METHODS
new ( [ ...data... | $filehandle ] )
Base constructor for the class. A single string will be parsed line by line into PICA::Field objects, empty lines and start record markers will be skipped. More then one or non scalar parameters will be passed to append so you can use the constructor in the same way:
my $record = PICA::Record->new('037A','a' => 'My note');If no data is given then it just returns a completely empty record. To load PICA records from a file, see PICA::Parser, to load records from a SRU or Z39.50 server, see PICA::Source.
If you provide a file handle or IO::Handle, the first record is read from it. Each of the following three lines has the same result:
$record = PICA::Record->new( IO::Handle->new("< $filename") );
($record) = PICA::Parser->parsefile( $filename, Limit => 1 )->records(),
open (F, "<", $plainpicafile); $record = PICA::Record->new( \*F ); close F;copy ( )
Creates a clone of this record by copying all fields.
all_fields ( )
Returns an array of all the fields in the record. The array contains a PICA::Field object for each field in the record. An empty array is returns if the record is empty.
field ( [ $limit, ] $tagspec(s) )
Returns a list of PICA::Field objects with tags that match the field specifier, or in scalar context, just the first matching Field.
You may specify multiple tags and use regular expressions.
my $field = $record->field("021A","021C");
my $field = $record->field("009P/03");
my @fields = $record->field("02..");
my @fields = $record->field("039[B-E]");If the first parameter is an integer, it is used as a limitation of response size, for instance two get only two fields:
my ($f1, $f2) = $record->field( 2, "028B/.." );f ( $tagspec(s) )
Shortcut for method field.
subfield ( [ $limit, ] [ $tagspec , $subfield ] | $spec )
Shortcut method for getting just the subfield's value of a tag (see PICA::Field). Returns a list of subfield values that match or in scalar context, just the first matching subfield.
These are equivalent (in scalar context):
my $title = $pica->field('021A')->subfield('a');
my $title = $pica->subfield('021A','a');You may also specify both field and subfield seperated by '$'. Don't forget to quote the dollar sign!
my $title = $pica->subfield('021A$a');
my $title = $pica->subfield("021A\$a");
my $title = $pica->subfield("021A$a"); # this won't work!If either the field or subfield can't be found, undef is returned.
You may also use wildcards like in field() and the subfield() method of PICA::Field:
my @values = $pica->subfield('005A', '0a'); # 005A$0 and 005A$a
my @values = $pica->subfield('005[AIJ]', '0'); # 005A$0, 005I$0, and 005J$0If the first parameter is an integer, it is used as a limitation of response size, for instance two get only two fields:
my ($f1, $f2) = $record->subfield( 2, '028B/..$a' );sf ( [ $tagspec , $subfield ] | $spec )
Shortcut for method subfield.
values ( )
Shortcut method to get subfield values of multiple fields and subfields. The fields and subfields are specified in a list of strings, for instance:
my @titles = $pica->values( '021A$a', '025@$a', '026C$a');This method always returns an array.
You may also use wildcards in the field specifications, see subfield() and field().
ppn ( )
Get the PICA Produktionsnummer (PPN) of this record (field 003@, subfield 0). This is equivalent to $self-subfield('003@$0')> but it always returns a scalar or undef.
epn ( )
Get zero or more EPNs (item numbers) of this record, which is field 203@/.., subfield 0. Returns the first EPN (or undef) in scalar context or a list in array context. Each copy record (get them with method copy_records) should have only one EPN.
main_record ( )
Get the main record (level 0, all tags starting with '0').
holdings ( )
Get a list of local records (holdings, level 1 and 2). Returns an array of PICA::Record objects.
local_records ( )
Alias for method holdings (deprecated).
items ( )
Get an array of PICA::Record objects with fields of each copy/item included in the record. Copy records are located at level 2 (tags starting with '2') and differ by tag occurrence.
copy_records ( )
Alias for method items (deprecated).
empty ( )
Return true if the record is empty (no fields or all fields empty)
is_empty ( )
Aloas for method empty (deprecated).
delete_fields ( <tagspec(s)> )
Delete fields specified by tags. You can also use wildcards, see field() for examples Returns the number of deleted fields.
append ( ...fields or records... )
Appends one or more fields to the end of the record. Parameters can be PICA::Field objects or parameters that are passed to PICA::Field-new>.
my $field = PICA::Field->new( '037A','a' => 'My note' );
$record->append( $field );is equivalent to
$record->append('037A','a' => 'My note');You can also append multiple fields with one call:
my $field = PICA::Field->new('037A','a' => 'First note');
$record->append( $field, '037A','a' => 'Second note' );
$record->append(
'037A', 'a' => '1st note',
'037A', 'a' => '2nd note',
);Please note that passed PICA::Field objects are not be copied but directly used:
my $field = PICA::Field->new('037A','a' => 'My note');
$record->append( $field );
$field->replace( 'a' => 'Your note' ); # Also changes $record's field!You can avoid this by cloning fields or by using the appendif method:
$record->append( $field->copy() );
$record->appendif( $field );You can also append copies of all fields of another record:
$record->append( $record2 );The append method returns the number of fields appended.
appendif ( ...fields or records... )
Optionally appends one or more fields to the end of the record. Parameters can be PICA::Field objects or parameters that are passed to PICA::Field-new>.
In contrast to the append method this method always copies values, it ignores empty subfields and empty fields (that are fields without subfields or with empty subfields only), and it returns the resulting PICA::Record object.
For instance this command will not add a field if $country is undef or "":
$r->appendif( "119@", "a" => $country );replace ( $tag, $field | @fieldspec )
Replace a field. You must pass a tag and a field. Attention: Only the first occurence will be replaced so better not use this method for repeatable fields.
sort ( )
Sort all fields. Most times the order of fields is not changed and not relevant but sorted fields may be helpful for viewing records.
to_string ( [ %options ] )
Returns a string representation of the record for printing. See also PICA::Writer for printing to a file or file handle.
normalized ( [ $prefix ] )
Returns record as a normalized string. Optionally adds prefix data at the beginning.
print $record->normalized();
print $record->normalized("##TitleSequenceNumber 1\n");See also PICA::Writer for printing to a file or file handle.
to_xml ( [ $xmlwriter | %params ] )
Write the record to an XML::Writer or return an XML string of the record. If you pass an existing XML::Writer object, the record will be written with it and nothing is returned. Otherwise the passed parameters are used to create a new XML writer. Unless you specify an XML writer or an OUTPUT parameter, the resulting XML is returned as string. By default the PICA-XML namespaces with namespace prefix 'pica' is included. In addition to XML::Writer this methods knows the 'header' parameter that first adds the XML declaration and the 'xslt' parameter that adds an XSLT stylesheet.
write_xml ( $writer )
Write the record to a XML::Writer object.
to_html ( [ %options ] )
Returns a HTML representation of the record for browser display. See also the pica2html.xsl script to generate a more elaborated HTML view from PICA-XML.
add_headers ( [ %options ] )
Add header fields to a PICA::Record. You must specify two named parameters (eln and status). This method is experimental. There is no test whether the header fields already exist.
INTERNAL METHDOS
_get_regex ( $reg )
Get a complied regular expression.
SEE ALSO
At CPAN there are the modules MARC::Record, MARC, and MARC::XML for MARC records and Encode::MAB2 for MAB records. The deprecated module Net::Z3950::Record also had a subclass Net::Z3950::Record::MAB for MAB records. You should now better use Net::Z3950::ZOOM which is also needed if you query Z39.50 servers with PICA::Source.
AUTHOR
Jakob Voss <jakob.voss@gbv.de>
LICENSE
Copyright (C) 2007-2009 by Verbundzentrale Göttingen (VZG) and Jakob Voß
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 36:
Non-ASCII character seen before =encoding in 'für'. Assuming UTF-8