Debian Codegraph @

lib/Biblio/SICI.pm

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1
2 package Biblio::SICI;
3 {
4 $Biblio::SICI::VERSION = '0.04';
5 }
6
7 # ABSTRACT: Provides methods for assembling, parsing, manipulating and serialising SICIs
8
9 use strict;
10 use warnings;
11 use 5.010001;
12
13 use Moo;
14 use Sub::Quote;
15
16 use Biblio::SICI::ItemSegment;
17 use Biblio::SICI::ContributionSegment;
18 use Biblio::SICI::ControlSegment;
19
20 use Biblio::SICI::Util qw( calculate_check_char );
21
22
23 has 'item' => (
24 is => 'ro',
25 lazy => 1,
26 isa => quote_sub(q{ die unless ( defined $_[0] and $_[0]->isa('Biblio::SICI::ItemSegment') ) }),
27 builder =>
28 quote_sub(q{ my ($self) = @_; return Biblio::SICI::ItemSegment->new( _sici => $self ); }),
29 init_arg => undef,
30 );
31
32
33 has 'contribution' => (
34 is => 'ro',
35 lazy => 1,
36 isa => quote_sub(
37 q{ die unless ( defined $_[0] and $_[0]->isa('Biblio::SICI::ContributionSegment') ) }),
38 builder => quote_sub(
39 q{ my ($self) = @_; return Biblio::SICI::ContributionSegment->new( _sici => $self ); }),
40 init_arg => undef,
41 );
42
43
44 has 'control' => (
45 is => 'ro',
46 lazy => 1,
47 isa => quote_sub(
48 q{ my ($val) = @_; die unless ( defined $val and $val->isa('Biblio::SICI::ControlSegment') ) }
49 ),
50 builder => quote_sub(
51 q{ my ($self) = @_; return Biblio::SICI::ControlSegment->new( _sici => $self ); }),
52 init_arg => undef,
53 );
54
55
56 has 'mode' => (
57 is => 'rw',
58 isa => quote_sub(q{ my ($val) = @_; die unless ( $val eq 'strict' or $val eq 'lax' ) }),
59 required => 1,
60 coerce => sub {
61 my ($val) = @_;
62 $val = join( '', split( " ", lc($val) ) );
63 return $val if ( $val eq 'strict' or $val eq 'lax' );
64 return 'lax';
65 },
66 default => quote_sub(q{ "lax" }),
67 );
68
69
70 has 'parsedString' => ( is => 'rwp', init_arg => undef, );
71
72
73 sub parse {
74 my ( $self, $string ) = @_;
75 my $strictMode = $self->mode() eq 'strict' ? 1 : 0;
76
77 if ( defined $string ) {
78 $string =~ s/\r/ /go;
79 $string =~ s/\n/ /go;
80 $string = join( '', split( " ", $string ) );
81 }
82
83 unless ($string) {
84 $strictMode ? die 'no string to parse' : return ( undef, undef, ['no string to parse'] );
85 }
86 $self->_set_parsedString($string);
87
88 my $checkChar = '';
89 if ( $string =~ /;([0-9])(?:-.)?\Z/ ) {
90 if ( "$1" ne "2" ) {
91 $strictMode
92 ? die 'unsupported SICI version'
93 : return ( undef, undef, ['unsupported SICI version'] );
94 }
95 else {
96 $self->control()->version(2);
97 if ( $string =~ s/;2-(.)\Z// ) {
98 $checkChar = $1;
99 }
100 }
101 }
102
103 my $parserProblems = [];
104
105 my @chars = split( //, $string );
106 my $tmp = '';
107 while ( exists( $chars[0] ) and $chars[0] !~ /[(<]/ ) {
108 $tmp .= shift @chars;
109 }
110
111 if ( $tmp and exists( $chars[0] ) ) {
112 if ( $chars[0] eq '(' ) {
113
114 # warn 'ISSN candidate: ' . $tmp;
115 $self->item()->issn($tmp);
116 shift @chars;
117 }
118 elsif ( $chars[0] eq '<' ) {
119 push @{$parserProblems}, "item information missing";
120
121 # warn 'Missing item info';
122 # warn 'Enumeration candidate: ' . $tmp;
123 if ( $tmp =~ /\A([A-Z0-9\/]+):([A-Z0-9\/]+)(?::([+*]))?\Z/ ) {
124 $self->item()->volume($1);
125 $self->item()->issue($2);
126 $self->item()->supplOrIdx($3) if $3;
127 }
128 elsif ($tmp) {
129 $self->item()->enumeration($tmp);
130 }
131 shift @chars;
132 goto CONTRIB;
133 }
134 else {
135 $strictMode ? die 'unparsable string' : return ( undef, undef, ['unparsable string'] );
136 }
137 } ## end if ( $tmp and exists( ...))
138 else {
139 $strictMode ? die 'unparsable string' : return ( undef, undef, ['unparsable string'] );
140 }
141
142 $tmp = '';
143 while ( exists( $chars[0] ) and $chars[0] ne ')' ) {
144 $tmp .= shift @chars;
145 }
146 if ( $tmp and exists( $chars[0] ) and $chars[0] eq ')' ) {
147
148 # warn 'Chronology candidate: ' . $tmp;
149 $self->item()->chronology($tmp);
150 shift @chars;
151 }
152 elsif ( exists( $chars[0] ) and $chars[0] eq ')' ) {
153 shift @chars;
154 }
155 else {
156 $strictMode ? die 'unparsable string' : return ( undef, undef, ['unparsable string'] );
157 }
158
159 $tmp = '';
160 while ( exists( $chars[0] ) and $chars[0] ne '<' ) {
161 $tmp .= shift @chars;
162 }
163 if ( $tmp and exists( $chars[0] ) and $chars[0] eq '<' ) {
164
165 # warn 'Enumeration candidate: ' . $tmp;
166 if ( $tmp =~ /\A([A-Z0-9\/]+):([A-Z0-9\/]+)(?::([+*]))?\Z/ ) {
167 $self->item()->volume($1);
168 $self->item()->issue($2);
169 $self->item()->supplOrIdx($3) if $3;
170 }
171 elsif ($tmp) {
172 $self->item()->enumeration($tmp);
173 }
174 shift @chars;
175 }
176 elsif ( exists( $chars[0] ) and $chars[0] eq '<' ) {
177 shift @chars;
178 }
179 else {
180 $strictMode ? die 'unparsable string' : return ( undef, undef, ['unparsable string'] );
181 }
182
183 CONTRIB:
184 $tmp = '';
185 while ( exists( $chars[0] ) and $chars[0] ne '>' ) {
186 $tmp .= shift @chars;
187 }
188 if ( $tmp and exists( $chars[0] ) and $chars[0] eq '>' ) {
189
190 # warn 'Contribution candidate: ' . $tmp;
191 if ( $tmp =~ /\A::(.+)\Z/ ) {
192 $self->contribution()->localNumber($1);
193 }
194 elsif ( $tmp =~ /\A:([^:]+)(?::(.+))?\Z/ ) {
195 $self->contribution()->titleCode($1);
196 $self->contribution()->localNumber($2) if $2;
197 }
198 elsif ( $tmp =~ /\A([^:]+):([^:]+)(?::(.+))?\Z/ ) {
199 $self->contribution()->location($1);
200 $self->contribution()->titleCode($2);
201 $self->contribution()->localNumber($3) if $3;
202 }
203 else {
204 $self->contribution()->location($tmp);
205 }
206 shift @chars;
207 }
208 elsif ( exists( $chars[0] ) and $chars[0] eq '>' ) {
209 shift @chars;
210 }
211 else {
212 $strictMode ? die 'unparsable string' : return ( undef, undef, ['unparsable string'] );
213 }
214
215 my $csi = '';
216 if ( exists( $chars[0] ) ) {
217 $csi = shift @chars;
218 }
219
220 if ( exists( $chars[0] ) and $chars[0] eq '.' ) {
221 shift @chars;
222 }
223 elsif ( exists( $chars[0] ) ) {
224 shift(@chars) while ( $chars[0] ne '.' );
225 }
226
227 if ( exists( $chars[0] ) ) {
228 $self->control()->dpi( shift @chars );
229 }
230
231 if ( exists( $chars[0] ) and $chars[0] eq '.' ) {
232 shift @chars;
233 }
234 elsif ( exists( $chars[0] ) ) {
235 shift(@chars) while ( $chars[0] ne '.' );
236 }
237
238 if ( exists( $chars[0] ) and exists( $chars[1] ) ) {
239 $self->control()->mfi( join( '', splice( @chars, 0, 2 ) ) );
240 }
241
242 my $isValid = $self->is_valid();
243 if ( $strictMode && !$isValid ) {
244 die 'parsing failed: invalid SICI';
245 }
246
247 if ( $checkChar ne $self->checkchar() ) {
248 push @{$parserProblems}, "wrong check char; was '$checkChar', should have been '$1'";
249 }
250 if ( $checkChar !~ /\A[0-9A-Z#]\Z/ ) {
251 push @{$parserProblems}, 'invalid original check char';
252 }
253
254 if ( $self->control()->csi() ne $csi ) {
255 push @{$parserProblems}, 'wrong csi in string input';
256 }
257
258 my $roundTrip = ( $self->parsedString() eq $self->to_string() ? 1 : 0 );
259 return ( $isValid, $roundTrip, $parserProblems );
260 } ## end sub parse
261
262
263 sub to_string {
264 my $self = shift;
265
266 my $str = $self->_to_string();
267 my $cs = calculate_check_char($str);
268
269 return $str . $cs;
270 }
271
272 sub _to_string {
273 my $self = shift;
274
275 my $item = $self->item()->to_string();
276 my $contrib = $self->contribution()->to_string();
277 my $control = $self->control()->to_string();
278
279 return sprintf( '%s<%s>%s-', $item, $contrib, $control );
280 }
281
282
283 sub checkchar {
284 my $self = shift;
285
286 my $siciAsString = $self->_to_string();
287
288 return calculate_check_char($siciAsString);
289 }
290
291
292 sub reset {
293 my $self = shift;
294 $self->item()->reset();
295 $self->contribution()->reset();
296 $self->control()->reset();
297 return;
298 }
299
300
301 sub is_valid {
302 my $self = shift;
303
304 my $itemIsValid = $self->item()->is_valid();
305 my $contribIsValid = $self->contribution()->is_valid();
306 my $controlIsValid = $self->control()->is_valid();
307
308 if ( $itemIsValid && $contribIsValid && $controlIsValid ) {
309 return 1;
310 }
311
312 return 0;
313 }
314
315
316 sub list_problems {
317 my $self = shift;
318
319 my $hasProblems = 0;
320 my %problems = ();
321 if ( not $self->item()->is_valid() ) {
322 $hasProblems++;
323 $problems{'item'} = { $self->item()->list_problems() };
324 }
325 if ( not $self->contribution()->is_valid() ) {
326 $hasProblems++;
327 $problems{'contribution'} = { $self->contribution()->list_problems() };
328 }
329 if ( not $self->control()->is_valid() ) {
330 $hasProblems++;
331 $problems{'control'} = { $self->control()->list_problems() };
332 }
333
334 if ($hasProblems) {
335 return %problems;
336 }
337 return;
338 }
339
340 1;
341
342 __END__
343
344 =pod
345
346 =encoding utf-8
347
348 =head1 NAME
349
350 Biblio::SICI - Provides methods for assembling, parsing, manipulating and serialising SICIs
351
352 =head1 VERSION
353
354 version 0.04
355
356 =head1 SYNOPSIS
357
358 use Biblio::SICI;
359
360 my $sici = Biblio::SICI->new()->parse($someSICI);
361
362 # or
363
364 my $sici2 = Biblio::SICI->new();
365
366 $sici2->item->issn('0361-526X');
367
368 # ... setting more data attributes ...
369
370 if ( $sici2->is_valid ) {
371 say $sici->to_string;
372 }
373
374 =head1 DESCRIPTION
375
376 A "Serial Item and Contribution Identifier" (SICI) is a code (ANSI/NISO
377 standard Z39.56) used to uniquely identify specific volumes, articles
378 or other identifiable parts of a periodical.
379
380 This module provides methods for assembling, parsing, manipulating and
381 serialising SICIs.
382
383 Both internal implementation and public API are currently considered BETA
384 and may change without warning in a future release. For more information
385 on this have a look at the L<TODO section|/TODO> below.
386
387 =head1 WARNING
388
389 This software is currently considered BETA. Things should work as intended
390 and documented but if you use it you should test your own software extensively
391 after any update to a new release of Biblio::SICI since both API and behaviour
392 might have changed.
393
394 =head1 CONFIGURATION
395
396 You may specify the following option when instantiating a SICI object
397 (i.e., when calling the "new()" constructor):
398
399 =over 4
400
401 =item C<mode>
402
403 Can be either C<strict> or C<lax>.
404
405 C<strict> mode means that any operation that gets called with an
406 invalid (according to the standard) value for an attribute will
407 C<die()>.
408
409 C<lax> mode means that any value is accepted and that you can use
410 the C<is_valid()> and C<list_problems()> methods to analyze the
411 object state.
412
413 =back
414
415 =head1 ATTRIBUTES
416
417 =over 4
418
419 =item C<item>
420
421 An instance of L<Biblio::SICI::ItemSegment>; this segment contains
422 information about the serial item itself.
423
424 =item C<contribution>
425
426 An instance of L<Biblio::SICI::ContributionSegment>; this segment
427 contains information about an individual contribution to the whole
428 item, e.g. an article in a journal issue.
429
430 =item C<control>
431
432 An instance of L<Biblio::SICI::ControlSegment>; this segment
433 contains some meta-information about the thing described by the
434 SICI and about the SICI itself.
435
436 =item C<mode>
437
438 Describes wether the object enforces strict conformance to
439 the standard or not.
440 Can be set to either C<strict> or C<lax>.
441 This attribute is the only one that can be specified directly
442 in the call of the constructor.
443
444 Please keep in mind that changing the value does B<not> mean
445 that the attributes already present are re-checked!
446
447 =item C<parsedString>
448
449 Returns the original string that was passed to the C<parse()>
450 method or C<undef> if C<parse> was not called before.
451
452 =back
453
454 =head1 METHODS
455
456 =over 4
457
458 =item C<parse>( STRING )
459
460 Tries to disassemble a string passed to it into the various
461 components of a SICI.
462
463 If I<strict> mode is enabled, it will C<die()> if either the
464 string cannot be parsed or if no valid SICI can be derived
465 from the string.
466
467 If I<lax> mode is enabled, it returns a list of three values:
468
469 The first value is C<undef> if parsing the string failed, or
470 C<0> if the string could be parsed but the SICI is invalid, or
471 C<1> if a valid SICI was found.
472
473 The second value is also C<undef> if parsing the string failed,
474 or C<0> if the string could be parsed but serializing the SICI
475 does not result in the exact same string or C<1> if we get a full
476 round-trip.
477
478 The third value is a (possibly empty) array ref with a list of
479 problems the parser detected. B<Please note:> these problems
480 are distinct from those reported by the C<list_problems> method
481 and can be retrieved again later.
482
483 =item C<to_string>
484
485 Serializes the object to a string using the separator characters
486 specified in the standard and returns it together with the check
487 character appended.
488
489 Does B<not> verify if the resulting SICI is valid!
490
491 =item STRING C<checkchar>()
492
493 Stringifies the object first, then calculates (and returns)
494 the checksum character.
495 Does B<not> check, if the stringified SICI is valid!
496
497 =item C<reset>()
498
499 Resets all attributes to their default values.
500
501 Does not modify the C<mode> attribute.
502
503 =item BOOL C<is_valid>()
504
505 Determines if all of the attribute values stored in the object
506 are valid and returns either a I<true> or I<false> value.
507
508 B<TODO> check if any required information is missing!
509
510 =item HASHREF C<list_problems>()
511
512 Returns either a hash of hashes of arrays containing the
513 problems that were found when setting the various attributes
514 of the SICI segments or C<undef> if there are no problems.
515
516 The first hash level is indexed by the three SICI segments:
517 I<item>, I<contribution>, and/or I<control>.
518
519 The level below is indexed by the attribute names (cf. the
520 docs of the segment modules).
521
522 For every attribute the third level contains an array reference
523 with descriptive messages.
524
525 {
526 'contribution' => {
527 'titleCode' => [
528 'contains more than 6 characters',
529 ],
530 },
531 };
532
533 B<TODO> check for meta problems (e.g. missing attributes).
534
535 =back
536
537 =head1 TODO
538
539 The parsing of SICI strings sort-of works but I need to find
540 out more about how the code copes with real world SICIs (i.e.
541 especially those that are slightly malformed or invalid).
542
543 It would probably make for a better programming style if I were
544 using real type specifications for the attributes. On the other
545 hand doing so would make the module employ overly strict checks
546 when dealing with imperfect SICIs.
547 Since type checks in Moo (or Moose) know nothing about the object,
548 the only other solution I can think of would be using objects of
549 type C<Biblio::SICI> act as frontend for instances of either
550 I<Biblio::SICI::Strict> or I<Biblio::SICI::Lax>.
551 This would require two separate sets of type definitions and make
552 everything more complicated - and I am not sure if would provide
553 us with a better way to handle and report formal problems.
554
555 That said, I´m also not particularly happy with how
556 C<list_problems()> works right now and I´d be grateful for any
557 suggestions for improvements (or for positive feedback if it works
558 for you).
559
560 Also for now only problems with the available data are detected
561 while missing or inconsistend data is not checked for.
562
563 And of course we need a more comprehensive test suite.
564
565 =head1 SEE ALSO
566
567 L<https://en.wikipedia.org/wiki/Serial_Item_and_Contribution_Identifier>
568
569 =head1 AUTHOR
570
571 Heiko Jansen <[email protected]>
572
573 =head1 COPYRIGHT AND LICENSE
574
575 This software is copyright (c) 2014 by Heiko Jansen.
576
577 This is free software; you can redistribute it and/or modify it under
578 the same terms as the Perl 5 programming language system itself.
579
580 =cut