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

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

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.

all_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.

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.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2007 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