MARC::Record(3pm)

1MARC::Record(3)       User Contributed Perl Documentation      MARC::Record(3)
2
3
4

NAME

6       MARC::Record - Perl extension for handling MARC records
7

VERSION

9       Version 2.0.7
10

DESCRIPTION

12       Module for handling MARC records as objects.  The file-handling stuff
13       is in MARC::File::*.
14

ERROR HANDLING

16       Any errors generated are stored in $MARC::Record::ERROR.  Warnings are
17       kept with the record and accessible in the "warnings()" method.
18

CONSTRUCTORS

20   new()
21       Base constructor for the class.  It just returns a completely empty
22       record.  To get real data, you'll need to populate it with fields, or
23       use one of the MARC::File::* modules to read from a file.
24
25   new_from_usmarc( $marcblob [, \&filter_func($tagno,$tagdata)] )
26       This is a wrapper around "MARC::File::USMARC::decode()" for
27       compatibility with older versions of MARC::Record.
28
29       The "wanted_func()" is optional.  See MARC::File::USMARC::decode for
30       details.
31

COMMON FIELD RETRIEVAL METHODS

33       Following are a number of convenience methods for commonly-retrieved
34       data fields.  Please note that they each return strings, not
35       MARC::Field objects.  They return empty strings if the appropriate
36       field or subfield is not found.  This is as opposed to the
37       "field()"/"subfield()" methods which return "undef" if something's not
38       found.  My assumption is that these methods are used for quick & dirty
39       reports and you don't want to mess around with noting if something is
40       undef.
41
42       Also note that no punctuation cleanup is done.  If the 245a is
43       "Programming Perl / ", then that's what you'll get back, rather than
44       "Programming Perl".
45
46   title()
47       Returns the title from the 245 tag.
48
49   title_proper()
50       Returns the title proper from the 245 tag, subfields a, n and p.
51
52   author()
53       Returns the author from the 100, 110 or 111 tag.
54
55   edition()
56       Returns the edition from the 250 tag, subfield a.
57
58   publication_date()
59       Returns the publication date from the 260 tag, subfield c.
60

FIELD & SUBFIELD ACCESS METHODS

62   fields()
63       Returns a list of all the fields in the record. The list contains a
64       MARC::Field object for each field in the record.
65
66   field( tagspec(s) )
67       Returns a list of tags that match the field specifier, or an empty list
68       if nothing matched.  In scalar context, returns the first matching tag,
69       or undef if nothing matched.
70
71       The field specifier can be a simple number (i.e. "245"), or use the "."
72       notation of wildcarding (i.e. subject tags are "6..").
73
74   subfield( $tag, $subfield )
75       Shortcut method for getting just a subfield for a tag.  These are
76       equivalent:
77
78         my $title = $marc->field('245')->subfield("a");
79         my $title = $marc->subfield('245',"a");
80
81       If either the field or subfield can't be found, "undef" is returned.
82
83   append_fields( @fields )
84       Appends the field specified by $field to the end of the record.
85       @fields need to be MARC::Field objects.
86
87           my $field = MARC::Field->new('590','','','a' => 'My local note.');
88           $record->append_fields($field);
89
90       Returns the number of fields appended.
91
92   insert_fields_before( $before_field, @new_fields )
93       Inserts the field specified by $new_field before the field
94       $before_field.  Returns the number of fields inserted, or undef on
95       failures.  Both $before_field and all @new_fields need to be
96       MARC::Field objects.  If they are not an exception will be thrown.
97
98           my $before_field = $record->field('260');
99           my $new_field = MARC::Field->new('250','','','a' => '2nd ed.');
100           $record->insert_fields_before($before_field,$new_field);
101
102   insert_fields_after( $after_field, @new_fields )
103       Identical to "insert_fields_before()", but fields are added after
104       $after_field. Remember, $after_field and any new fields must be valid
105       MARC::Field objects or else an exception will be thrown.
106
107   insert_fields_ordered( @new_fields )
108       Will insert fields in strictly numerical order. So a 008 will be filed
109       after a 001 field. See "insert_grouped_field()" for an additional
110       ordering.
111
112   insert_grouped_field( $field )
113       Will insert the specified MARC::Field object into the record in grouped
114       order and return true (1) on success, and false (undef) on failure.
115
116           my $field = MARC::Field->new( '510', 'Indexed by Google.' );
117           $record->insert_grouped_field( $field );
118
119       For example, if a '650' field is inserted with "insert_grouped_field()"
120       it will be inserted at the end of the 6XX group of tags. After
121       discussion most people wanted the ability to add a new field to the end
122       of the hundred group where it belonged. The reason is that according to
123       the MARC format, fields within a record are supposed to be grouped by
124       block (hundred groups). This means that fields may not necessarily be
125       in tag order.
126
127   delete_fields( $field )
128       Deletes a given list of MARC::Field objects from the the record.
129
130           # delete all note fields
131           my @notes = $record->field('5..');
132           $record->delete_fields(@notes);
133
134       delete_fields() will return the number of fields that were deleted.
135
136   delete_field()
137       Same thing as delete_fields() but only expects a single MARC::Field to
138       be passed in. Mainly here for backwards compatibility.
139
140   as_usmarc()
141       This is a wrapper around "MARC::File::USMARC::encode()" for
142       compatibility with older versions of MARC::Record.
143
144   as_formatted()
145       Returns a pretty string for printing in a MARC dump.
146
147   leader()
148       Returns the leader for the record.  Sets the leader if text is defined.
149       No error checking is done on the validity of the leader.
150
151   encoding()
152       A method for getting/setting the encoding for a record. The encoding
153       for a record is determined by position 09 in the leader, which is blank
154       for MARC-8 encoding, and 'a' for UCS/Unicode. encoding() will return a
155       string, either 'MARC-8' or 'UTF-8' appropriately.
156
157       If you want to set the encoding for a MARC::Record object you can use
158       the string values:
159
160           $record->encoding( 'UTF-8' );
161
162       NOTE: MARC::Record objects created from scratch have an a default
163       encoding of MARC-8, which has been the standard for years...but many
164       online catlogs and record vendors are migrating to UTF-8.
165
166       WARNING: you should be sure your record really does contain valid UTF-8
167       data when you manually set the encoding.
168
169   set_leader_lengths( $reclen, $baseaddr )
170       Internal function for updating the leader's length and base address.
171
172   clone()
173       The "clone()" method makes a copy of an existing MARC record and
174       returns the new version.  Note that you cannot just say:
175
176           my $newmarc = $oldmarc;
177
178       This just makes a copy of the reference, not a new object.  You must
179       use the "clone()" method like so:
180
181           my $newmarc = $oldmarc->clone;
182
183       You can also specify field specs to filter down only a certain subset
184       of fields.  For instance, if you only wanted the title and ISBN tags
185       from a record, you could do this:
186
187           my $small_marc = $marc->clone( 245, '020' );
188
189       The order of the fields is preserved as it was in the original record.
190
191   warnings()
192       Returns the warnings (as a list) that were created when the record was
193       read.  These are things like "Invalid indicators converted to blanks".
194
195           my @warnings = $record->warnings();
196
197       The warnings are items that you might be interested in, or might not.
198       It depends on how stringently you're checking data.  If you're doing
199       some grunt data analysis, you probably don't care.
200
201       A side effect of calling warnings() is that the warning buffer will be
202       cleared.
203
204   add_fields()
205       "add_fields()" is now deprecated, and users are encouraged to use
206       "append_fields()", "insert_fields_after()", and
207       "insert_fields_before()" since they do what you want probably. It is
208       still here though, for backwards compatibility.
209
210       "add_fields()" adds MARC::Field objects to the end of the list.
211       Returns the number of fields added, or "undef" if there was an error.
212
213       There are three ways of calling "add_fields()" to add data to the
214       record.
215
216       1 Create a MARC::Field object and add it
217             my $author = MARC::Field->new(
218                           100, "1", " ", a => "Arnosky, Jim."
219                           );
220             $marc->add_fields( $author );
221
222       2 Add the data fields directly, and let "add_fields()" take care of the
223       objectifying.
224             $marc->add_fields(
225                   245, "1", "0",
226                           a => "Raccoons and ripe corn /",
227                           c => "Jim Arnosky.",
228                           );
229
230       3 Same as #2 above, but pass multiple fields of data in anonymous lists
231             $marc->add_fields(
232                   [ 250, " ", " ", a => "1st ed." ],
233                   [ 650, "1", " ", a => "Raccoons." ],
234                   );
235

DESIGN NOTES

237       A brief discussion of why MARC::Record is done the way it is:
238
239       •   It's built for quick prototyping
240
241           One of the areas Perl excels is in allowing the programmer to
242           create easy solutions quickly.  MARC::Record is designed along
243           those same lines.  You want a program to dump all the 6XX tags in a
244           file?  MARC::Record is your friend.
245
246       •   It's built for extensibility
247
248           Currently, I'm using MARC::Record for analyzing bibliographic data,
249           but who knows what might happen in the future?  MARC::Record needs
250           to be just as adept at authority data, too.
251
252       •   It's designed around accessor methods
253
254           I use method calls everywhere, and I expect calling programs to do
255           the same, rather than accessing internal data directly.  If you
256           access an object's hash fields on your own, future releases may
257           break your code.
258
259       •   It's not built for speed
260
261           One of the tradeoffs in using accessor methods is some overhead in
262           the method calls.  Is this slow?  I don't know, I haven't measured.
263           I would suggest that if you're a cycle junkie that you use
264           Benchmark.pm to check to see where your bottlenecks are, and then
265           decide if MARC::Record is for you.
266

RELATED MODULES

268       MARC::Field, MARC::Batch, MARC::File::XML, MARC::Charset, MARC::Lint
269

TODO

291       •   Incorporate MARC.pm in the distribution.
292
293           Combine MARC.pm and MARC::* into one distribution.
294
295       •   Podify MARC.pm
296
297       •   Allow regexes across the entire tag
298
299           Imagine something like this:
300
301             my @sears_headings = $marc->tag_grep( qr/Sears/ );
302
303           (from Mike O'Regan)
304
305       •   Insert a field in an arbitrary place in the record
306
307       •   Modifying an existing field
308

BUGS, WISHES AND CORRESPONDENCE

310       Please feel free to email me at "<mrylander@gmail.com>".  I'm glad to
311       help as best I can, and I'm always interested in bugs, suggestions and
312       patches.
313
314       An excellent place to look for information, and get quick help, is from
315       the perl4lib mailing list.  See <http://perl4lib.perl.org> for more
316       information about this list, and other helpful MARC information.
317
318       The MARC::Record development team uses the RT bug tracking system at
319       <http://rt.cpan.org>.  If your email is about a bug or suggestion,
320       please report it through the RT system.  This is a huge help for the
321       team, and you'll be notified of progress as things get fixed or
322       updated.  If you prefer not to use the website, you can send your bug
323       to "<bug-MARC-Record@rt.cpan.org>"
324

IDEAS

326       Ideas are things that have been considered, but nobody's actually asked
327       for.
328
329       •   Create multiple output formats.
330
331           These could be ASCII or MarcMaker.
332

LICENSE

334       This code may be distributed under the same terms as Perl itself.
335
336       Please note that these modules are not products of or supported by the
337       employers of the various contributors to the code.
338

AUTHORS

340       •   Andy Lester
341
342       •   Mike O'Regan
343
344       •   Ed Summers
345
346       •   Mike Rylander
347
348       •   Galen Charlton
349
350
351
352perl v5.34.0                      2022-01-21                   MARC::Record(3)