NAME

PICA::Field - Perl extension for handling PICA+ fields

SYNOPSIS

  use PICA::Field;
  my $field = PICA::Field->new( '028A',
    '9' => '117060275',
    '8' => 'Martin Schrettinger'
  );

  $field->add( 'd' => 'Martin', 'a' => 'Schrettinger' );
  $field->update( "8", "Schrettinger, Martin" );

  print $field->normalized;
  print $field->xml;

DESCRIPTION

Defines PICA+ fields for use in the PICA::Record module.

EXPORT

The method parse_pp_tag is exported.

METHODS

new ( [...] )

The constructor, which will return a PICA::Field object or croak on error. You can call the constructor with a tag and a list of subfields:

  PICA::Field->new( '028A',
    '9' => '117060275',
    '8' => 'Martin Schrettinger'
  );

With a string of normalized PICA+ data of one field:

  PICA::Field->new("\x1E028A \x1F9117060275\x1F8Martin Schrettinger\x0A');

With a string of readable PICA+ data:

  PICA::Field->new('028A $9117060275$8Martin Schrettinger');

copy ( $field )

Creates and returns a copy of this object.

parse ( $string, [, \&tag_filter_func ] )

The constructur will return a PICA::Field object based on data that is parsed if null if the filter dropped the field. Dropped fields will not be parsed so they are also not validated.

The $tag_filter_func is an optional reference to a user-supplied function that determines on a tag-by-tag basis if you want the tag to be parsed or dropped. The function is passed the tag number (including occurrence), and must return a boolean.

For example, if you only want to 021A fields, try this:

The filter function can be used to select only required fields

   sub filter {
        my $tagno = shift;
        return $tagno eq "021A";
    }
    my $field = PICA::Field->parse( $string, \&filter );

tag ( [ $tag ] )

Returns the PICA+ tag and occurrence of the field. Optionally sets tag (and occurrence) to a new value.

occurrence ( [ $occurrence ] ) or occ ( ... )

Returns the ocurrence or undef. Optionally sets the ocurrence to a new value.

level ( )

Returns the level (0: main, 1: local, 2: copy) of this field.

subfield ( [ $code(s) ] ) or sf ( ... )

Return selected or all subfield values. If you specify one ore more subfield codes, only matching subfields are returned. When called in a scalar context returns only the first (matching) subfield. You may specify multiple subfield codes:

    my $subfield = $field->subfield( 'a' );   # first $a
    my $subfield = $field->subfield( 'acr' ); # first of $a, $c, $r
    my $subfield = $field->subfield( 'a', 'c', 'r' ); # the same

    my @subfields = $field->subfield( '0-9' );     # $0 ... $9
    my @subfields = $field->subfield( qr/[0-9]/ ); # $0 ... $9

    my @subfields = $field->subfield( 'a' );
    my @all_subfields = $field->subfield();

If no matching subfields are found, undef is returned in a scalar context or an empty list in a list context.

Remember that there can be more than one subfield of a given code!

content ( [ $code(s) ] )

Return selected or all subfields as an array of arrays. If you specify one ore more subfield codes, only matching subfields are returned. See the subfield method for more examples.

This shows the subfields from a 021A field:

        [
          [ 'a', '@Traité de documentation' ],
          [ 'd', 'Le livre sur le livre ; Théorie et pratique' ],
          [ 'h', 'Paul Otlet' ]
        ]

add ( $code, $value [, $code, $value ...] )

Adds subfields to the end of the subfield list. Whitespace in subfield values is normalized.

    $field->add( 'c' => '1985' );

Returns the number of subfields added.

update ( $sf => $value [ $sf => $value ...] )

Allows you to change the values of the field for one or more given subfields:

  $field->update( a => 'Little Science, Big Science' );

If you attempt to update a subfield which does not currently exist in the field, then a new subfield will be appended. If you don't like this auto-vivification you must check for the existence of the subfield prior to update.

  if ( defined $field->subfield( 'a' ) ) {
      $field->update( 'a' => 'Cryptonomicon' );
  }

Instead of a single value you can also pass an array reference. The following statements should have the same result:

  $field->update( 'x', 'foo', 'x', 'bar' );
  $field->update( 'x' => ['foo', 'bar'] );

To remove a subfield, update it to undef or an empty array reference:

  $field->update( 'a' => undef );
  $field->update( 'a' => [] );

replace ( $field | ... )

Allows you to replace an existing field with a new one. You may pass a PICA::Field object or parameters for a new field to replace the existing field with. Replace does not return a meaningful or reliable value.

empty_subfields ( )

Returns a list of all codes of empty subfields.

empty ( )

Test whether there are no subfields or all subfields are empty. This method is automatically called by overloading whenever a PICA::Field is converted to a boolean value.

purged ( )

Remove a copy of this field with empty subfields removed or undef if the whole field is empty.

normalized ( [$subfields] )

Returns the field as a string. The tag number, occurrence and subfield indicators are included.

If $subfields is specified, then only those subfields will be included.

sort ( [ $order ] )

Sort subfields by subfield indicators. You can optionally specify an order as string of subfield codes.

size

Returns the number of subfields (no matter if empty or not).

as_string ( [ %params ] )

Returns a pretty string for printing.

Returns the field as a string. The tag number, occurrence and subfield indicators are included.

If subfields is specified, then only those subfields will be included.

Fields without subfields return an empty string.

as_string ( [ %options ] )

to_string ( [ %options ] )

Alias for as_string.

xml ( [ [ writer => ] $writer | [ OUTPUT ] => \$sref | %param ] )

Return the field in PICA-XML format or write it to an XML::Writer and return the writer. If you provide parameters, they will be passed to a newly created XML::Writer that is used to write to a 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.

html ( [ %options ] )

Returns a HTML representation of the field for browser display. See also the pica2html.xsl script to generate a more elaborated HTML view from PICA-XML.

STATIC METHODS

parse_pp_tag tag ( $tag )

Tests whether a string can be used as a tag/occurrence specifier. A tag indicator consists of a 'type' (00-99) and an 'indicator' (A-Z and @), both conflated as the 'tag', and an optional occurrence (00-99). This method returns a list of two values: occurrence and tag (this order!). It can be used to parse and test tag specifiers this ways:

  ($occurrence, $tag) = parse_pp_tag( $t );
  parse_pp_tag( $t ) or print STDERR "Not a valid tag: $t\n";

SEE ALSO

This module was inspired by MARC::Field by Andy Lester.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2007-2010 by Verbundzentrale Goettingen (VZG) and Jakob Voss

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.

cpanm PICA::Record

perl -MCPAN -e shell
install PICA::Record