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

NAME

6       MARC::Field - Perl extension for handling MARC fields
7

SYNOPSIS

9         use MARC::Field;
10
11         # If your system uses wacky control field tags, add them
12         MARC::Field->allow_controlfield_tags('FMT', 'LLE');
13
14         my $field = MARC::Field->new( 245, '1', '0',
15              'a' => 'Raccoons and ripe corn / ',
16              'c' => 'Jim Arnosky.'
17         );
18         $field->add_subfields( "a", "1st ed." );
19

DESCRIPTION

21       Defines MARC fields for use in the MARC::Record module.  I suppose you
22       could use them on their own, but that wouldn't be very interesting.
23

EXPORT

25       None by default.  Any errors are stored in $MARC::Field::ERROR, which
26       $MARC::Record usually bubbles up to $MARC::Record::ERROR.
27

CLASS VARIABLES

29       extra_controlfield_tags: Some systems (notably Ex Libris's Aleph) throw
30       extra control fields in their MARC (e.g., Aleph's MARC-XML tends to
31       have a "FMT" control field). We keep a class-level hash to track to
32       track them; it can be manipulated with "allow_controlfield_tags" and
33       c<disallow_controlfield_tags>.
34

METHODS

36   new()
37       The constructor, which will return a MARC::Field object. Typically you
38       will pass in the tag number, indicator 1, indicator 2, and then a list
39       of any subfield/data pairs. For example:
40
41         my $field = MARC::Field->new(
42              245, '1', '0',
43              'a' => 'Raccoons and ripe corn / ',
44              'c' => 'Jim Arnosky.'
45         );
46
47       Or if you want to add a control field (< 010) that does not have
48       indicators.
49
50         my $field = MARC::Field->new( '001', ' 14919759' );
51
52   tag()
53       Returns the three digit tag for the field.
54
55   set_tag(tag)
56       Changes the tag number of this field. Updates the control status
57       accordingly.  Will "croak" if an invalid value is passed in.
58
59   indicator(indno)
60       Returns the specified indicator.  Returns "undef" and logs a warning if
61       field is a control field and thus doesn't have indicators.  If the
62       field is not a control field, croaks if the indno is not 1 or 2.
63
64   set_indicator($indno, $indval)
65       Set the indicator position $indno to the value specified by $indval.
66       Croaks if the indicator position, is invalid, the field is a control
67       field and thus doesn't have indicators, or if the new indicator value
68       is invalid.
69
70   allow_controlfield_tags($tag, $tag2, ...)
71       Add $tags to class-level list of strings to consider valid control
72       fields tags (in addition to 001 through 009).  Tags must have three
73       characters.
74
75   disallow_controlfield_tags($tag, $tag2, ...) =head2
76       disallow_controlfield_tags('*')
77       Revoke the validity of a control field tag previously added with
78       allow_controlfield_tags. As a special case, if you pass the string '*'
79       it will clear out all previously-added tags.
80
81       NOTE that this will only deal with stuff added with
82       allow_controlfield_tags; you can't disallow '001'.
83
84   is_valid_tag($tag) -- is the given tag valid?
85       Generally called as a class method (e.g.,
86       MARC::Field->is_valid_tag('001'))
87
88   is_valid_indicator($indval) -- is the given indicator value valid?
89       Generally called as a class method (e.g.,
90       MARC::Field->is_valid_indicator('4'))
91
92   is_controlfield_tag($tag) -- does the given tag denote a control field?
93       Generally called as a class method (e.g.,
94       MARC::Field->is_controlfield_tag('001'))
95
96   is_control_field()
97       Tells whether this field is one of the control tags from 001-009.
98
99   subfield(code)
100       When called in a scalar context returns the text from the first
101       subfield matching the subfield code.
102
103           my $subfield = $field->subfield( 'a' );
104
105       Or if you think there might be more than one you can get all of them by
106       calling in a list context:
107
108           my @subfields = $field->subfield( 'a' );
109
110       If no matching subfields are found, "undef" is returned in a scalar
111       context and an empty list in a list context.
112
113       If the tag is a control field, "undef" is returned and
114       $MARC::Field::ERROR is set.
115
116   subfields()
117       Returns all the subfields in the field.  What's returned is a list of
118       list refs, where the inner list is a subfield code and the subfield
119       data.
120
121       For example, this might be the subfields from a 245 field:
122
123               (
124                 [ 'a', 'Perl in a nutshell :' ],
125                 [ 'b', 'A desktop quick reference.' ],
126               )
127
128   data()
129       Returns the data part of the field, if the tag number is less than 10.
130
131   add_subfields(code,text[,code,text ...])
132       Adds subfields to the end of the subfield list.
133
134           $field->add_subfields( 'c' => '1985' );
135
136       Returns the number of subfields added, or "undef" if there was an
137       error.
138
139   delete_subfield()
140       delete_subfield() allows you to remove subfields from a field:
141
142           # delete any subfield a in the field
143           $field->delete_subfield(code => 'a');
144
145           # delete any subfield a or u in the field
146           $field->delete_subfield(code => ['a', 'u']);
147
148           # delete any subfield code matching a compiled regular expression
149           $field->delete_subfield(code => qr/[^a-z0-9]/);
150
151       If you want to only delete subfields at a particular position you can
152       use the pos parameter:
153
154           # delete subfield u at the first position
155           $field->delete_subfield(code => 'u', pos => 0);
156
157           # delete subfield u at first or second position
158           $field->delete_subfield(code => 'u', pos => [0,1]);
159
160           # delete the second subfield, no matter what it is
161           $field->delete_subfield(pos => 1);
162
163       You can specify a regex to for only deleting subfields that match:
164
165          # delete any subfield u that matches zombo.com
166          $field->delete_subfield(code => 'u', match => qr/zombo.com/);
167
168          # delete any subfield that matches quux
169          $field->delete_subfield(match => qr/quux/);
170
171       You can also pass a single subfield label:
172
173         # delete all subfield u
174         $field->delete_subfield('u');
175
176   delete_subfields()
177       Delete all subfields with a given subfield code. This is here for
178       backwards compatibility, you should use the more flexible
179       delete_subfield().
180
181   update()
182       Allows you to change the values of the field. You can update indicators
183       and subfields like this:
184
185         $field->update( ind2 => '4', a => 'The ballad of Abe Lincoln');
186
187       If you attempt to update a subfield which does not currently exist in
188       the field, then a new subfield will be appended to the field. If you
189       don't like this auto-vivification you must check for the existence of
190       the subfield prior to update.
191
192         if ( $field->subfield( 'a' ) ) {
193           $field->update( 'a' => 'Cryptonomicon' );
194         }
195
196       If you want to update a field that has no indicators or subfields
197       (000-009) just call update() with one argument, the string that you
198       would like to set the field to.
199
200         $field = $record->field( '003' );
201         $field->update('IMchF');
202
203       Note: when doing subfield updates be aware that update() will only
204       update the first occurrence. If you need to do anything more
205       complicated you will probably need to create a new field and use
206       replace_with().
207
208       Returns the number of items modified.
209
210   replace_with()
211       Allows you to replace an existing field with a new one. You need to
212       pass replace() a MARC::Field object to replace the existing field with.
213       For example:
214
215         $field = $record->field('245');
216         my $new_field = new MARC::Field('245','0','4','The ballad of Abe Lincoln.');
217         $field->replace_with($new_field);
218
219       Doesn't return a meaningful or reliable value.
220
221   as_string( [$subfields] [, $delimiter] )
222       Returns a string of all subfields run together. A space is added to the
223       result between each subfield, unless the delimiter parameter is passed.
224       The tag number and subfield character are not included.
225
226       Subfields appear in the output string in the order in which they occur
227       in the field.
228
229       If $subfields is specified, then only those subfields will be included.
230
231         my $field = MARC::Field->new(
232                       245, '1', '0',
233                               'a' => 'Abraham Lincoln',
234                               'h' => '[videorecording] :',
235                               'b' => 'preserving the union /',
236                               'c' => 'A&E Home Video.'
237                       );
238         print $field->as_string( 'abh' ); # Only those three subfields
239         # prints 'Abraham Lincoln [videorecording] : preserving the union /'.
240         print $field->as_string( 'ab', '--' ); # Only those two subfields, with a delimiter
241         # prints 'Abraham Lincoln--preserving the union /'.
242
243       Note that subfield h comes before subfield b in the output.
244
245   as_formatted()
246       Returns a pretty string for printing in a MARC dump.
247
248   as_usmarc()
249       Returns a string for putting into a USMARC file.  It's really only
250       useful for MARC::Record::as_usmarc().
251
252   clone()
253       Makes a copy of the field.  Note that this is not just the same as
254       saying
255
256           my $newfield = $field;
257
258       since that just makes a copy of the reference.  To get a new object,
259       you must
260
261           my $newfield = $field->clone;
262
263       Returns a MARC::Field record.
264
265   warnings()
266       Returns the warnings that were created when the record was read.  These
267       are things like "Invalid indicators converted to blanks".
268
269       The warnings are items that you might be interested in, or might not.
270       It depends on how stringently you're checking data.  If you're doing
271       some grunt data analysis, you probably don't care.
272

SEE ALSO

274       See the "SEE ALSO" section for MARC::Record.
275

TODO

277       See the "TODO" section for MARC::Record.
278

LICENSE

280       This code may be distributed under the same terms as Perl itself.
281
282       Please note that these modules are not products of or supported by the
283       employers of the various contributors to the code.
284

AUTHOR

286       Andy Lester, "<andy@petdance.com>"
287
288
289
290perl v5.38.0                      2023-07-20                    MARC::Field(3)
Impressum