blib/lib/Biblio/LCC.pm untested

filter: Statementstmt 0.0% 0 / 57 Branchbran 0.0% 0 / 22 Conditioncond 0.0% 0 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 0.0% 0 / 7 Podpod 0.0% 0 / 4 totaltotal 0.0% 0 / 98 CC 12 SCAR 28.4
CC
12
Cov
0%
normalize_range
30.0
add
20.0
normalize
12.0
CRAP 17.1
1 package Biblio::LCC;
2  
3 use strict;
4 use warnings;
5  
6 use vars qw($VERSION);
7  
8 $VERSION = '0.09';
9  
10 # Normalize a class (e.g., "PN1997.5") or an actual call number
11 # (e.g., "PN1997.5 .B3 B5 1977")
12 sub normalize {
13 my ($cls, $lcc) = @_;
14 my ($alpha, $int, $frac, $rmdr) = $cls->parse($lcc);
15 my $norm;
16 if ($frac eq '') {
17 if ($int eq '') {
18 $norm = sprintf "%-3s", $alpha;
19 }
20 else {
21 $norm = sprintf "%-3s%4d %s", $alpha, $int, $rmdr;
22 }
23 }
24 else {
25 $norm = sprintf "%-3s%4d.%d %s", $alpha, $int, $frac, $rmdr;
26 }
27 $norm =~ s/ +$//;
28 return $norm;
29 }
30  
31 # Normalize a classification range
32 # NOTE: A range can be specified using a hyphen (e.g., 'Z105-106'), which
33 # is the usual way, or a less-than sign (e.g., 'Z105<107'), which
34 # lets you do specify that a call number must be strictly less than
35 # the end of the range. If you just specify one classification (e.g.,
36 # "AS137"), the second classification is the same as the first and a
37 # hyphen is assumed.
38 sub normalize_range {
39 my ($cls, $str) = @_;
40 my ($begin, $end, $rel);
41 $str =~ s/ +A\s*-\s*Z$//; # Strip " A-Z" at end -- common (but meaningless) idiom
42 $str =~ s/(.+)\.([^-<.]+)\s*(<|--?)\s*\.(.+)/$1.$2$3$1.$4/; # foo.bar-.baz ==> foo.bar-foo.baz
43 if ($str =~ /^([^-<]+)\s*(<|--?)\s*(.+)/) {
44 # Examples:
45 # PN1997-1999
46 # PN 1997-PN 1999
47 # PN1997<2000
48 ($begin, $rel, $end) = ($1, substr($2, 0, 1), $3);
49 }
50 elsif ($str =~ /^([^-<]+)$/) {
51 # Examples:
52 # KNW
53 # RA 401.3
54 # HD1308.A5
55 ($begin, $rel, $end) = ($1, '-', $1);
56 }
57 else {
58 return; # XXX
59 }
60 if ($end =~ /^\d+/) {
61 $begin =~ /^([A-Z]+)/ and $end = "$1$end";
62 }
63 ($begin, $end) = map { $cls->normalize($_) } ($begin, $end);
64 if ($rel eq '-') {
65 $end .= '~';
66 }
67 return ($begin, $end);
68 }
69  
70 # Parse a classification or call number
71 sub parse {
72 my ($cls, $lcc) = @_;
73 my ($alpha, $int, $frac, $rmdr) = ('', '', '', '');
74 $lcc =~ s/^([A-Z]{1,3}) *// or die "Invalid LCC: $lcc";
75 $alpha = $1;
76 if ($lcc =~ s/^(\d+)//) {
77 $int = $1;
78 if ($lcc =~ s/^\.(\d+)//) {
79 $frac = $1;
80 }
81 $rmdr = $lcc;
82 $rmdr =~ s/^ *\.?(?=[A-Z])/./;
83 }
84 $rmdr =~ s/\.(?=[A-Z])//g;
85 $rmdr =~ s/(?<=\d)(?=[A-Z])/ /g;
86 return ($alpha, $int, $frac, $rmdr);
87 }
88  
89 # Add an offset (e.g, '116.5') to a classification (e.g., 'HD6290')
90 sub add {
91 my ($cls, $lcc, $offset) = @_;
92 my ($alpha, $int, $frac, $rmdr) = $cls->parse($lcc);
93 die "Can't add to a classification with a fractional part" if $frac ne '';
94 die "Can't add to a classification with a remainder" if $rmdr ne '';
95 $int += int($offset);
96 if ($offset =~ /\./) {
97 $frac = $offset - $int;
98 return "$alpha$int.$frac"
99 }
100 else {
101 return "$alpha$int";
102 }
103 }
104  
105 =head1 NAME
106  
107 Biblio::LCC - parse and normalize LC-style call numbers
108  
109 =head1 SYNOPSIS
110  
111 use Biblio::LCC;
112 $normalized = Biblio::LCC->normalize('PS3573.A472242 A88 1998');
113 ($begin, $limit) = Biblio::LCC->normalize_range('E184.5-E185');
114 @parts = Biblio::LCC->parse($call_number);
115 $call_number = Biblio::LCC->add($class, $offset);
116  
117 =head1 DESCRIPTION
118  
119 B<Biblio::LCC> parses Library of Congress classification ranges and call numbers
120 and normalizes them into a form suitable for a straight ASCII sort.
121  
122 =head1 PUBLIC METHODS
123  
124 =over 4
125  
126 =item B<normalize>(I<$call_number>)
127  
128 $normalized = Biblio::LCC->normalize('PS3573.A472242 A88 1998');
129  
130 Convert an LC-style class (e.g., 'PS' or 'E184.5') or call number (e.g.,
131 'PS3573.A472242 A88 1998') into a string that may be compared to other
132 normalized call numbers (see B<normalize_range> below).
133  
134 =item B<normalize_range>(I<$call_number_range>)
135  
136 ($begin, $limit) = Biblio::LCC->normalize_range('E184.5-E185');
137  
138 Parse a call number range, producing a pair of strings I<B> and I<L> such
139 that a call number falls within the range if and only if its normalized
140 form, in a straight lexicographic ASCII comparison, is greater than or equal
141 to I<B> and strictly less than I<L>.
142  
143 The range may be specified in one of three ways:
144  
145 =over 4
146  
147 =item I<call number> B<-> I<call number>
148  
149 A pair of call numbers; the range includes the beginning call number, the
150 ending call number, and any call numbers that have the ending call number as
151 a prefix.
152  
153 For example, the (unnormalized) range C<AS131-AS142> encompasses any class
154 or call number from C<AS131> up to B<but not including> C<AS143>
155  
156 In this form, the alphabetic string that begins the second call number may
157 be omitted, so (for example) C<E184.5-185> is equivalent to C<E184.5-E185>.
158  
159 Space is optional around the hyphen.
160  
161 =item I<call number>
162  
163 A single class or call number, in unnormalized form. This is equivalent to
164 a pair in which each call number is the same. For example, the unnormalized
165 range C<QA141.5.A1> encompasses call numbers from C<QA141.5.A1> up to but
166 not including C<QA141.5.A2>.
167  
168 =item I<call number> E<lt> I<call number>
169  
170 A pair of call numbers; the range includes the first call number and any
171 call number up and not including the ending call number.
172  
173 For example, the unnormalized range C<< DT6.7E<lt>DT7 >> includes everything
174 greater than C<DT6.7> and less than C<DT7>.
175  
176 In this form, the alphabetic string that begins the second call number may
177 be omitted, as in the form of range that uses a hyphen to separate the parts.
178  
179 Space is optional around the less-than sign (E<lt>).
180  
181 =back
182  
183 =item B<parse>(I<$call_number>)
184  
185 ($alpha, $int, $frac, $rmdr) = Biblio::LCC->parse($call_number);
186  
187 Split an LC call number into alphabetic, integer, decimal fraction, and
188 remainder (i.e., everything else).
189  
190 =item B<add>(I<$class>, I<$offset>)
191  
192 $call_number = Biblio::LCC->add($class, $offset);
193  
194 Add an offset (e.g., '180.3') to a base LC class (e.g., 'GN1600') to produce
195 another LC class (e.g., 'GN1780.3').
196  
197 The base class may have only alphabetic and integer parts; an exception will be
198 thrown if it has a fractional part (e.g., as in 'GN1600.1') or a remainder (e.g.,
199 as in 'GN1600 R5').
200  
201 =back
202  
203 =head1 HOW IT WORKS
204  
205 Call numbers are first analyzed into four parts. For example, take the call number
206 B<GB1001.72.M32 E73 1988>.
207  
208 =over 4
209  
210 =item B<alpha>
211  
212 GB
213  
214 The one to three alphabetic characters that begin the call number.
215  
216 =item B<integer>
217  
218 1001
219  
220 An integer from 1 to 9999 that follows.
221  
222 =item B<fraction>
223  
224 72
225  
226 Digits that follow a decimal point after the integer part.
227  
228 =item B<remainder>
229  
230 M32 E73 1988
231  
232 Everything that follows.
233  
234 =back
235  
236 The LC Classification allows for a wide range of possible call numbers that do
237 not fall into the simple (alpha, integer, fraction, remainder) model that this
238 module implements. For example, the following are
239 all valid call numbers:
240  
241 =over 4
242  
243 =item B<E514.5 17th .S76 1986>
244 =item B<G3804.N4:3B7 K142t>
245 =item B<G3824.Y6C5 s50 .W5>
246  
247 =back
248  
249 It may be that in some cases further analysis, and fully correct sorting, are
250 not possible without hardcoded knowledge of the LC classification. In many
251 cases, however, a more sophisticated parsing model, while more complex, would
252 result in better normalization.
253  
254 =head1 BUGS
255  
256 There are no known bugs. Please report bugs on this module's RT page:
257 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Biblio-LCC>.
258  
259 =head1 TO DO
260  
261 Implement a C<new> method and rewrite other methods so they may be used as
262 class B<or> instance methods.
263  
264 Special handling of "special" call numbers (e.g., in the Gs).
265  
266 Allow caller to specify prefixes to strip (e.g., "Folio").
267  
268 Parse straight from the 050 or 090 field of a MARC record.
269  
270 Better error reporting.
271  
272 =head1 AUTHOR
273  
274 Paul Hoffman (nkuitse AT cpan DOT org)
275  
276 =head1 COPYRIGHT
277  
278 Copyright 2007-2008 Paul M. Hoffman.
279  
280 This is free software, and is made available under the same terms as Perl
281 itself.