Debian Codegraph @

README

raw
1 NAME
2
3 MODS::Record - Perl extension for handling MODS records
4
5 SYNOPSIS
6
7 use MODS::Record qw(xml_string);
8 use open qw(:utf8);
9
10 my $mods = MODS::Record->new;
11
12 my $collection = MODS::Collection->new;
13
14 my $mods = $collection->add_mods(ID => '1234');
15
16 $mods->add_abstract("Hello", lang => 'eng');
17 $mods->add_abstract("Bonjour", lang => 'fra');
18
19 # Set a deeply nested field...
20 $mods->add_language()->add_languageTerm('eng');
21
22 # Set a list of deeply nested fields...
23 $mods->add_location(sub {
24 $_[0]->add_physicalLocation('here');
25 $_[0]->add_shelfLocator('here too');
26 $_[0]->add_url('http://here.org/there');
27 });
28
29 # Set an inline XML extension...
30 $mods->add_accessCondition(xml_string("<x:foo><x:bar>21212</x:bar></x:foo>"));
31
32 # Retrieve a field by a filter...
33 $mods->get_abstract(lang => 'fra')->body("Bonjour :)");
34 $mods->get_abstract(lang => 'fra')->contentType('text/plain');
35
36 for ($mods->get_abstract(lang => 'fra')) {
37 printf "%s\n" , $_->body;
38 }
39
40 # Set a field to a new value
41 my @newabstract;
42 for ($mods->get_abstract) {
43 push @newabstract, $_ unless $_->lang eq 'fra';
44 }
45 $mods->set_abstract(@newabstract);
46
47 # Clear all abstracts;
48 $mods->set_abstract(undef);
49
50 # Serialize
51 print $mods->as_json(pretty => 1);
52 print $mods->as_xml;
53
54 # Deserialize
55 my $mods = MODS::Record->from_xml(IO::File->new('mods.xml'));
56 my $mods = MODS::Record->from_json(IO::File->new('mods.js'));
57
58 my $count = MODS::Record->from_xml(IO::File->new('mods.xml'), sub {
59 my $mods = shift;
60 ...
61 });
62
63 my $count = MODS::Record->from_json(IO::File->new('mods.js'), sub {
64 my $mods = shift;
65 ...
66 });
67
68 DESCRIPTION
69
70 This module provides MODS (http://www.loc.gov/standards/mods/) parsing
71 and creation for MODS Schema 3.5.
72
73 METHODS
74
75 MODS::Record->new(%attribs)
76
77 MODS::Collection->new(%attribs)
78
79 Create a new MODS record or collection. Optionally attributes can be
80 provided as defined by the MODS specification. E.g.
81
82 $mods = MODS::Record->new(ID='123');
83
84 add_xxx()
85
86 Add a new element to the record where 'xxx' is the name of a MODS
87 element (e.g. titleInfo, name, genre, etc). This method returns an
88 instance of the added MODS element. E.g.
89
90 $titleInfo = $mods->add_titleInfo; # $titleInfo is a 'MODS::Element::TitleInfo'
91
92 add_xxx($text,%attribs)
93
94 Add a new element to the record where 'xxx' is the name of a MODS
95 element. Set the text content of the element to $text and optionally
96 provide further attributes. This method returns an instance of the
97 added MODS element. E.g.
98
99 $mods->add_abstract("My abstract", lang=>'eng');
100
101 add_xxx(sub { })
102
103 Add a new element to the record where 'xxx' is the name of a MODS
104 element. The provided coderef gets as input an instance of the added
105 MODS element. This method returns an instance of the added MODS
106 element. E.g.
107
108 $mods->add_abstract(sub {
109 my $o = shift;
110 $o->body("My abstract");
111 $o->lang("eng");
112 })
113
114 add_xxx($obj)
115
116 Add a new element to the record where 'xxx' is the name of a MODS
117 element. The $obj is an instance of a MODS::Element::Xxx class (where
118 Xxx is the corresponding MODS element). This method returns an instance
119 of the added MODS element. E.g.
120
121 $mods->add_abstract(
122 MODS::Element::Abstract->new(_body=>'My abstract', lang=>'eng')
123 );
124
125 get_xxx()
126
127 get_xxx(%filter)
128
129 get_xxx(sub { })
130
131 Retrieve an element from the record where 'xxx' is the name of a MODS
132 element. This methods return in array context all the matching elements
133 or the first match in scalar context. Optionally provide a %filter or a
134 coderef filter function. E.g.
135
136 @titles = $mods->get_titleInfo();
137 $alt = $mods->get_titleInfo(type=>'alternate');
138 $alt = $mods->get_titleInfo(sub { shift->type eq 'alternate'});
139
140 set_xxxx()
141
142 set_xxx(undef)
143
144 set_xxx($array_ref)
145
146 set_xxx($xxx1,$xxx2,...)
147
148 Set an element of the record to a new value where 'xxx' is the name of
149 a MODS element. When no arguments are provided, then this is a null
150 operation. When undef als argument is provided, then the element is
151 deleted. To overwrite the existing content of the element an ARRAY
152 (ref) of MODS::Element::Xxx can be provided (where 'Xxx' is the
153 corresponding MODS element). E.g.
154
155 # Delete all abstracts
156 $mods->set_abstract(undef);
157
158 # Set all abstracts
159 $mods->set_abstract(MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ...);
160 $mods->set_abstract([ MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ... ]);
161
162 as_xml()
163
164 as_xml(xml_prolog=>1)
165
166 Return the record as XML.
167
168 from_xml($string [, $callback])
169
170 from_xml(IO::Handle [, $callback])
171
172 Parse an XML string or IO::Handle into a MODS::Record. This method
173 return the parsed JSON.
174
175 If a callback function is provided then for each MODS element in the
176 XML stream the callback will be called. The method returns the number
177 of parsed MODS elements.
178
179 E.g.
180 my $mods = MODS::Record->from_xml( IO::File->new(...) );
181
182 my $count = MODS::Record->from_xml( IO::File->new(...) , sub {
183 my $mods = shift;
184 } );
185
186 as_json()
187
188 as_json(pretty=>1)
189
190 Return the record as JSON string.
191
192 from_json($string [, $callback])
193
194 from_json(IO::Handle [, $callback])
195
196 Parse and JSON string or JSON::Handle into a MODS::Record. This method
197 return the parsed JSON.
198
199 If a callback function is provided then we expect as input a stream of
200 JSON strings (each line one JSON string). For each MODS object in the
201 JSON stream the callback will be called. The method returns the number
202 of parsed strings.
203
204 E.g.
205 my $mods = MODS::Record->from_json( IO::File->new(...) );
206
207 my $count = MODS::Record->from_json( IO::File->new(...) , sub {
208 my $mods = shift;
209 } );
210
211 SEE ALSO
212
213 * Library Of Congress MODS pages (http://www.loc.gov/standards/mods/)
214
215 DESIGN NOTES
216
217 * I'm not a MODS expert
218
219 * I needed a MODS module to parse and create MODS records for our
220 institutional repository
221
222 * This module is part of the LibreCat/Catmandu project
223 http://librecat.org
224
225 * This module is not created for speed
226
227 * This module doesn't have any notion of ordering of MODS elements
228 themselves (e.g. first 'titleInfo', then 'name'). But each
229 sub-element keeps its original order (e.g. each 'title' in
230 'titleInfo').
231
232 * Heiko Jansen provides at GitHub a Moose-based MODS parser
233 https://github.com/heikojansen/MODS--Record
234
235 AUTHOR
236
237 Patrick Hochstenbach <Patrick.Hochstenbach at UGent.be>
238
239 LICENSE AND COPYRIGHT
240
241 This program is free software; you can redistribute it and/or modify it
242 under the terms of either: the GNU General Public License as published
243 by the Free Software Foundation; or the Artistic License.
244
245 See http://dev.perl.org/licenses/ for more information.
246