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

COMMON FIELD RETRIEVAL METHODS

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

FIELD & SUBFIELD ACCESS METHODS

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

DESIGN NOTES

262       A brief discussion of why MARC::Record is done the way it is:
263
264       * It's built for quick prototyping
265           One of the areas Perl excels is in allowing the programmer to cre‐
266           ate easy solutions quickly.  MARC::Record is designed along those
267           same lines.  You want a program to dump all the 6XX tags in a file?
268           MARC::Record is your friend.
269
270       * It's built for extensibility
271           Currently, I'm using MARC::Record for analyzing bibliographic data,
272           but who knows what might happen in the future?  MARC::Record needs
273           to be just as adept at authority data, too.
274
275       * It's designed around accessor methods
276           I use method calls everywhere, and I expect calling programs to do
277           the same, rather than accessing internal data directly.  If you
278           access an object's hash fields on your own, future releases may
279           break your code.
280
281       * It's not built for speed
282           One of the tradeoffs in using accessor methods is some overhead in
283           the method calls.  Is this slow?  I don't know, I haven't measured.
284           I would suggest that if you're a cycle junkie that you use Bench‐
285           mark.pm to check to see where your bottlenecks are, and then decide
286           if MARC::Record is for you.
287

RELATED MODULES

289       MARC::Field, MARC::Batch, MARC::File::XML, MARC::Charset, MARC::Lint
290

TODO

307       * Incorporate MARC.pm in the distribution.
308           Combine MARC.pm and MARC::* into one distribution.
309
310       * Podify MARC.pm
311       * Allow regexes across the entire tag
312           Imagine something like this:
313
314             my @sears_headings = $marc->tag_grep( qr/Sears/ );
315
316           (from Mike O'Regan)
317
318       * Insert a field in an arbitrary place in the record
319       * Modifying an existing field
320

BUGS, WISHES AND CORRESPONDENCE

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

IDEAS

338       Ideas are things that have been considered, but nobody's actually asked
339       for.
340
341       * Create multiple output formats.
342           These could be ASCII or MarcMaker.
343

LICENSE

345       This code may be distributed under the same terms as Perl itself.
346
347       Please note that these modules are not products of or supported by the
348       employers of the various contributors to the code.
349

AUTHOR

351       Andy Lester, "<andy@petdance.com>"
352
353
354
355perl v5.8.8                       2005-04-27                   MARC::Record(3)