.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MARC::Record 3pm"
.TH MARC::Record 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MARC::Record \- Perl extension for handling MARC records
.SH "VERSION"
.IX Header "VERSION"
Version 2.0.7
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Module for handling \s-1MARC\s0 records as objects.  The file-handling stuff is
in MARC::File::*.
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
Any errors generated are stored in \f(CW$MARC::Record::ERROR\fR.
Warnings are kept with the record and accessible in the \f(CW\*(C`warnings()\*(C'\fR method.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "\fBnew()\fP"
.IX Subsection "new()"
Base constructor for the class.  It just returns a completely empty record.
To get real data, you'll need to populate it with fields, or use one of
the MARC::File::* modules to read from a file.
.ie n .SS "new_from_usmarc( $marcblob [, \e&filter_func($tagno,$tagdata)] )"
.el .SS "new_from_usmarc( \f(CW$marcblob\fP [, \e&filter_func($tagno,$tagdata)] )"
.IX Subsection "new_from_usmarc( $marcblob [, &filter_func($tagno,$tagdata)] )"
This is a wrapper around \f(CW\*(C`MARC::File::USMARC::decode()\*(C'\fR for compatibility with
older versions of MARC::Record.
.PP
The \f(CW\*(C`wanted_func()\*(C'\fR is optional.  See MARC::File::USMARC::decode for details.
.SH "COMMON FIELD RETRIEVAL METHODS"
.IX Header "COMMON FIELD RETRIEVAL METHODS"
Following are a number of convenience methods for commonly-retrieved
data fields.  Please note that they each return strings, not MARC::Field
objects.  They return empty strings if the appropriate field or subfield
is not found.  This is as opposed to the \f(CW\*(C`field()\*(C'\fR/\f(CW\*(C`subfield()\*(C'\fR methods
which return \f(CW\*(C`undef\*(C'\fR if something's not found.  My assumption is that
these methods are used for quick & dirty reports and you don't want to
mess around with noting if something is undef.
.PP
Also note that no punctuation cleanup is done.  If the 245a is
\&\*(L"Programming Perl / \*(R", then that's what you'll get back, rather than
\&\*(L"Programming Perl\*(R".
.SS "\fBtitle()\fP"
.IX Subsection "title()"
Returns the title from the 245 tag.
.SS "\fBtitle_proper()\fP"
.IX Subsection "title_proper()"
Returns the title proper from the 245 tag, subfields a, n and p.
.SS "\fBauthor()\fP"
.IX Subsection "author()"
Returns the author from the 100, 110 or 111 tag.
.SS "\fBedition()\fP"
.IX Subsection "edition()"
Returns the edition from the 250 tag, subfield a.
.SS "\fBpublication_date()\fP"
.IX Subsection "publication_date()"
Returns the publication date from the 260 tag, subfield c.
.SH "FIELD & SUBFIELD ACCESS METHODS"
.IX Header "FIELD & SUBFIELD ACCESS METHODS"
.SS "\fBfields()\fP"
.IX Subsection "fields()"
Returns a list of all the fields in the record. The list contains
a MARC::Field object for each field in the record.
.SS "field( \fItagspec(s)\fP )"
.IX Subsection "field( tagspec(s) )"
Returns a list of tags that match the field specifier, or an empty
list if nothing matched.  In scalar context, returns the first
matching tag, or undef if nothing matched.
.PP
The field specifier can be a simple number (i.e. \*(L"245\*(R"), or use the \*(L".\*(R"
notation of wildcarding (i.e. subject tags are \*(L"6..\*(R").
.ie n .SS "subfield( $tag, $subfield )"
.el .SS "subfield( \f(CW$tag\fP, \f(CW$subfield\fP )"
.IX Subsection "subfield( $tag, $subfield )"
Shortcut method for getting just a subfield for a tag.  These are equivalent:
.PP
.Vb 2
\&  my $title = $marc\->field(\*(Aq245\*(Aq)\->subfield("a");
\&  my $title = $marc\->subfield(\*(Aq245\*(Aq,"a");
.Ve
.PP
If either the field or subfield can't be found, \f(CW\*(C`undef\*(C'\fR is returned.
.ie n .SS "append_fields( @fields )"
.el .SS "append_fields( \f(CW@fields\fP )"
.IX Subsection "append_fields( @fields )"
Appends the field specified by \f(CW$field\fR to the end of the record.
\&\f(CW@fields\fR need to be MARC::Field objects.
.PP
.Vb 2
\&    my $field = MARC::Field\->new(\*(Aq590\*(Aq,\*(Aq\*(Aq,\*(Aq\*(Aq,\*(Aqa\*(Aq => \*(AqMy local note.\*(Aq);
\&    $record\->append_fields($field);
.Ve
.PP
Returns the number of fields appended.
.ie n .SS "insert_fields_before( $before_field, @new_fields )"
.el .SS "insert_fields_before( \f(CW$before_field\fP, \f(CW@new_fields\fP )"
.IX Subsection "insert_fields_before( $before_field, @new_fields )"
Inserts the field specified by \f(CW$new_field\fR before the field \f(CW$before_field\fR.
Returns the number of fields inserted, or undef on failures.
Both \f(CW$before_field\fR and all \f(CW@new_fields\fR need to be MARC::Field objects.
If they are not an exception will be thrown.
.PP
.Vb 3
\&    my $before_field = $record\->field(\*(Aq260\*(Aq);
\&    my $new_field = MARC::Field\->new(\*(Aq250\*(Aq,\*(Aq\*(Aq,\*(Aq\*(Aq,\*(Aqa\*(Aq => \*(Aq2nd ed.\*(Aq);
\&    $record\->insert_fields_before($before_field,$new_field);
.Ve
.ie n .SS "insert_fields_after( $after_field, @new_fields )"
.el .SS "insert_fields_after( \f(CW$after_field\fP, \f(CW@new_fields\fP )"
.IX Subsection "insert_fields_after( $after_field, @new_fields )"
Identical to \f(CW\*(C`insert_fields_before()\*(C'\fR, but fields are added after
\&\f(CW$after_field\fR. Remember, \f(CW$after_field\fR and any new fields must be
valid MARC::Field objects or else an exception will be thrown.
.ie n .SS "insert_fields_ordered( @new_fields )"
.el .SS "insert_fields_ordered( \f(CW@new_fields\fP )"
.IX Subsection "insert_fields_ordered( @new_fields )"
Will insert fields in strictly numerical order. So a 008 will be filed
after a 001 field. See \f(CW\*(C`insert_grouped_field()\*(C'\fR for an additional ordering.
.ie n .SS "insert_grouped_field( $field )"
.el .SS "insert_grouped_field( \f(CW$field\fP )"
.IX Subsection "insert_grouped_field( $field )"
Will insert the specified MARC::Field object into the record in grouped
order and return true (1) on success, and false (undef) on failure.
.PP
.Vb 2
\&    my $field = MARC::Field\->new( \*(Aq510\*(Aq, \*(AqIndexed by Google.\*(Aq );
\&    $record\->insert_grouped_field( $field );
.Ve
.PP
For example, if a '650' field is inserted with \f(CW\*(C`insert_grouped_field()\*(C'\fR
it will be inserted at the end of the 6XX group of tags. After discussion
most people wanted the ability to add a new field to the end of the
hundred group where it belonged. The reason is that according to the \s-1MARC\s0
format, fields within a record are supposed to be grouped by block
(hundred groups). This means that fields may not necessarily be in tag
order.
.ie n .SS "delete_fields( $field )"
.el .SS "delete_fields( \f(CW$field\fP )"
.IX Subsection "delete_fields( $field )"
Deletes a given list of MARC::Field objects from the the record.
.PP
.Vb 3
\&    # delete all note fields
\&    my @notes = $record\->field(\*(Aq5..\*(Aq);
\&    $record\->delete_fields(@notes);
.Ve
.PP
\&\fBdelete_fields()\fR will return the number of fields that were deleted.
.SS "\fBdelete_field()\fP"
.IX Subsection "delete_field()"
Same thing as \fBdelete_fields()\fR but only expects a single MARC::Field to be passed
in. Mainly here for backwards compatibility.
.SS "\fBas_usmarc()\fP"
.IX Subsection "as_usmarc()"
This is a wrapper around \f(CW\*(C`MARC::File::USMARC::encode()\*(C'\fR for compatibility with
older versions of MARC::Record.
.SS "\fBas_formatted()\fP"
.IX Subsection "as_formatted()"
Returns a pretty string for printing in a \s-1MARC\s0 dump.
.SS "\fBleader()\fP"
.IX Subsection "leader()"
Returns the leader for the record.  Sets the leader if \fItext\fR is defined.
No error checking is done on the validity of the leader.
.SS "\fBencoding()\fP"
.IX Subsection "encoding()"
A method for getting/setting the encoding for a record. The encoding for a
record is determined by position 09 in the leader, which is blank for \s-1MARC\-8\s0
encoding, and 'a' for UCS/Unicode. \fBencoding()\fR will return a string, either 
\&'\s-1MARC\-8\s0' or '\s-1UTF\-8\s0' appropriately.
.PP
If you want to set the encoding for a MARC::Record object you can use the
string values:
.PP
.Vb 1
\&    $record\->encoding( \*(AqUTF\-8\*(Aq );
.Ve
.PP
\&\s-1NOTE:\s0 MARC::Record objects created from scratch have an a default encoding
of \s-1MARC\-8,\s0 which has been the standard for years...but many online catlogs
and record vendors are migrating to \s-1UTF\-8.\s0
.PP
\&\s-1WARNING:\s0 you should be sure your record really does contain valid \s-1UTF\-8\s0 data
when you manually set the encoding.
.ie n .SS "set_leader_lengths( $reclen, $baseaddr )"
.el .SS "set_leader_lengths( \f(CW$reclen\fP, \f(CW$baseaddr\fP )"
.IX Subsection "set_leader_lengths( $reclen, $baseaddr )"
Internal function for updating the leader's length and base address.
.SS "\fBclone()\fP"
.IX Subsection "clone()"
The \f(CW\*(C`clone()\*(C'\fR method makes a copy of an existing \s-1MARC\s0 record and returns
the new version.  Note that you cannot just say:
.PP
.Vb 1
\&    my $newmarc = $oldmarc;
.Ve
.PP
This just makes a copy of the reference, not a new object.  You must use
the \f(CW\*(C`clone()\*(C'\fR method like so:
.PP
.Vb 1
\&    my $newmarc = $oldmarc\->clone;
.Ve
.PP
You can also specify field specs to filter down only a
certain subset of fields.  For instance, if you only wanted the
title and \s-1ISBN\s0 tags from a record, you could do this:
.PP
.Vb 1
\&    my $small_marc = $marc\->clone( 245, \*(Aq020\*(Aq );
.Ve
.PP
The order of the fields is preserved as it was in the original record.
.SS "\fBwarnings()\fP"
.IX Subsection "warnings()"
Returns the warnings (as a list) that were created when the record was read.
These are things like \*(L"Invalid indicators converted to blanks\*(R".
.PP
.Vb 1
\&    my @warnings = $record\->warnings();
.Ve
.PP
The warnings are items that you might be interested in, or might
not.  It depends on how stringently you're checking data.  If
you're doing some grunt data analysis, you probably don't care.
.PP
A side effect of calling \fBwarnings()\fR is that the warning buffer will
be cleared.
.SS "\fBadd_fields()\fP"
.IX Subsection "add_fields()"
\&\f(CW\*(C`add_fields()\*(C'\fR is now deprecated, and users are encouraged to use
\&\f(CW\*(C`append_fields()\*(C'\fR, \f(CW\*(C`insert_fields_after()\*(C'\fR, and \f(CW\*(C`insert_fields_before()\*(C'\fR
since they do what you want probably. It is still here though, for backwards
compatibility.
.PP
\&\f(CW\*(C`add_fields()\*(C'\fR adds MARC::Field objects to the end of the list.  Returns the
number of fields added, or \f(CW\*(C`undef\*(C'\fR if there was an error.
.PP
There are three ways of calling \f(CW\*(C`add_fields()\*(C'\fR to add data to the record.
.IP "1 Create a MARC::Field object and add it" 4
.IX Item "1 Create a MARC::Field object and add it"
.Vb 4
\&  my $author = MARC::Field\->new(
\&                100, "1", " ", a => "Arnosky, Jim."
\&                );
\&  $marc\->add_fields( $author );
.Ve
.ie n .IP "2 Add the data fields directly, and let ""add_fields()"" take care of the objectifying." 4
.el .IP "2 Add the data fields directly, and let \f(CWadd_fields()\fR take care of the objectifying." 4
.IX Item "2 Add the data fields directly, and let add_fields() take care of the objectifying."
.Vb 5
\&  $marc\->add_fields(
\&        245, "1", "0",
\&                a => "Raccoons and ripe corn /",
\&                c => "Jim Arnosky.",
\&                );
.Ve
.IP "3 Same as #2 above, but pass multiple fields of data in anonymous lists" 4
.IX Item "3 Same as #2 above, but pass multiple fields of data in anonymous lists"
.Vb 4
\&  $marc\->add_fields(
\&        [ 250, " ", " ", a => "1st ed." ],
\&        [ 650, "1", " ", a => "Raccoons." ],
\&        );
.Ve
.SH "DESIGN NOTES"
.IX Header "DESIGN NOTES"
A brief discussion of why MARC::Record is done the way it is:
.IP "\(bu" 4
It's built for quick prototyping
.Sp
One of the areas Perl excels is in allowing the programmer to
create easy solutions quickly.  MARC::Record is designed along
those same lines.  You want a program to dump all the 6XX
tags in a file?  MARC::Record is your friend.
.IP "\(bu" 4
It's built for extensibility
.Sp
Currently, I'm using MARC::Record for analyzing bibliographic
data, but who knows what might happen in the future?  MARC::Record
needs to be just as adept at authority data, too.
.IP "\(bu" 4
It's designed around accessor methods
.Sp
I use method calls everywhere, and I expect calling programs to do
the same, rather than accessing internal data directly.  If you
access an object's hash fields on your own, future releases may
break your code.
.IP "\(bu" 4
It's not built for speed
.Sp
One of the tradeoffs in using accessor methods is some overhead
in the method calls.  Is this slow?  I don't know, I haven't measured.
I would suggest that if you're a cycle junkie that you use
Benchmark.pm to check to see where your bottlenecks are, and then
decide if MARC::Record is for you.
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
MARC::Field, MARC::Batch, MARC::File::XML, MARC::Charset, 
MARC::Lint
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
perl4lib (<http://perl4lib.perl.org/>)
.Sp
A mailing list devoted to the use of Perl in libraries.
.IP "\(bu" 4
Library Of Congress \s-1MARC\s0 pages (<http://www.loc.gov/marc/>)
.Sp
The definitive source for all things \s-1MARC.\s0
.IP "\(bu" 4
\&\fIUnderstanding \s-1MARC\s0 Bibliographic\fR (<http://lcweb.loc.gov/marc/umb/>)
.Sp
Online version of the free booklet.  An excellent overview of the \s-1MARC\s0 format.  Essential.
.IP "\(bu" 4
Tag Of The Month (<http://www.follettsoftware.com/sub/tag_of_the_month/>)
.Sp
Follett Software Company's
(<http://www.fsc.follett.com/>) monthly discussion of various \s-1MARC\s0 tags.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Incorporate \s-1MARC\s0.pm in the distribution.
.Sp
Combine \s-1MARC\s0.pm and MARC::* into one distribution.
.IP "\(bu" 4
Podify \s-1MARC\s0.pm
.IP "\(bu" 4
Allow regexes across the entire tag
.Sp
Imagine something like this:
.Sp
.Vb 1
\&  my @sears_headings = $marc\->tag_grep( qr/Sears/ );
.Ve
.Sp
(from Mike O'Regan)
.IP "\(bu" 4
Insert a field in an arbitrary place in the record
.IP "\(bu" 4
Modifying an existing field
.SH "BUGS, WISHES AND CORRESPONDENCE"
.IX Header "BUGS, WISHES AND CORRESPONDENCE"
Please feel free to email me at \f(CW\*(C`<mrylander@gmail.com>\*(C'\fR.  I'm glad
to help as best I can, and I'm always interested in bugs, suggestions
and patches.
.PP
An excellent place to look for information, and get quick help, is from
the perl4lib mailing list.  See <http://perl4lib.perl.org> for more
information about this list, and other helpful \s-1MARC\s0 information.
.PP
The MARC::Record development team uses the \s-1RT\s0 bug tracking system at
<http://rt.cpan.org>.  If your email is about a bug or suggestion,
please report it through the \s-1RT\s0 system.  This is a huge help for the
team, and you'll be notified of progress as things get fixed or updated.
If you prefer not to use the website, you can send your bug to \f(CW\*(C`<bug\-MARC\-Record@rt.cpan.org>\*(C'\fR
.SH "IDEAS"
.IX Header "IDEAS"
Ideas are things that have been considered, but nobody's actually asked for.
.IP "\(bu" 4
Create multiple output formats.
.Sp
These could be \s-1ASCII\s0 or MarcMaker.
.SH "LICENSE"
.IX Header "LICENSE"
This code may be distributed under the same terms as Perl itself.
.PP
Please note that these modules are not products of or supported by the
employers of the various contributors to the code.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Andy Lester
.IP "\(bu" 4
Mike O'Regan
.IP "\(bu" 4
Ed Summers
.IP "\(bu" 4
Mike Rylander
.IP "\(bu" 4
Galen Charlton