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->update( "8", "Schrettinger, Martin" );
  print $field->normalized();

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. 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');

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()

Returns the PICA+ tag and occurrence of the field.

set_tag()

Sets the tag and occurence of the field. Does not return a value.

level()

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

subfield(code)

When called in a scalar context returns the text from the first subfield matching the subfield code. You may specify multiple subfields.

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

Or if you think there might be more than one you can get all of them by calling in a list context:

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

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

subfields()

Returns all the subfields in the field. What's returned is a list of lists, where the inner list is a subfield code and the subfield data.

For example, this might be the subfields from a 021A field:

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

add_subfields(code,text[,code,text ...])

Adds subfields to the end of the subfield list.

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

Returns the number of subfields added, or undef if there was an error.

update()

Allows you to change the values of the field. You can update indicators and subfields like this:

  $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 to the field. If you don't like this auto-vivification you must check for the existence of the subfield prior to update.

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

Note: when doing subfield updates be aware that update() will only update the first occurrence. If you need to do anything more complicated you will probably need to create a new field and use replace().

Returns the number of items modified.

replace()

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.

is_empty()

Test whether there are no subfields or all subfields are 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.

to_string()

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.

to_xml

Returns the field in XML format. The XML format is an unofficial beta format and may change.

STATIC METHODS

parse_pp_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!). This method can be used to parse and test tag specifiers this way:

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

SEE ALSO

See the "SEE ALSO" section for PICA::Record.

This module is mainly based on MARC::Field by Andy Lester.

TODO

A method to clone fields needs to be implemented. Better handling of errors and warnings is needed.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2007 by Verbundzentrale Göttingen (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.

Please note that these module s not product of or supported by the employers of the various contributors to the code nor by OCLC PICA.

cpanm PICA::Record

perl -MCPAN -e shell
install PICA::Record