blib/lib/Library/CallNumber/LC.pm

filter: Statementstmt 95.8% 138 / 144 Branchbran 83.3% 45 / 54 Conditioncond 61.5% 8 / 13 MC/DCmcdc 25.0% 2 / 8 Subroutinesub 100% 16 / 16 Podpod 100% 9 / 9 totaltotal 89.3% 218 / 244 CC 35 SCAR 17.9
CC
35
Cov
91%
toLongInt
11.8
components
9.0
new
5.1
CRAP 6.0
↑ Summary
1 package Library::CallNumber::LC;
2  
3 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶use Math::BigInt;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 Library::CallNumber::LC - Deal with Library-of-Congress call numbers
10  
11 =head1 VERSION
12  
13 Version 0.23;
14  
15 =cut
16  
17 3 our $VERSION = '0.23';
18  
19  
20 =head1 SYNOPSIS
21  
22 Utility functions to deal with Library of Congress Call Numbers
23  
24 use Library::CallNumber::LC;
25 my $a = Library::CallNumber::LC->new('A 123.4 .c11');
26 print $a->normalize; # normalizes for string comparisons.
27 # gives 'A01234 C11'
28 print $a->start_of_range; # same as "normalize"
29 my $b = Library::CallNumber::LC->new('B11 .c13 .d11');
30 print $b->normalize;
31 # gives 'B0011 C13 D11'
32 my @range = ($a->start_of_range, $b->end_of_range);
33 # end of range is 'B0011 C13 D11~'
34
35 # Get components suitable for printing (e.g., number and decimal joined, leading dot on first cutter)
36 @comps = Library::CallNumber::LC->new('A 123.4 .c11')->components()
37
38 # Same thing, but return empty strings for missing components (e.g., the cutters)
39 @comps = Library::CallNumber::LC->new('A 123.4 .c11')->components('true');
40  
41 =head1 ABSTRACT
42  
43 Library::CallNumber::LC is mostly designed to do call number normalization, with the following goals:
44  
45 =over 4
46  
47 =item * The normalized call numbers are comparable with each other, for proper sorting
48  
49 =item * The normalized call number is a short as possible, so left-anchored wildcard searches are possible (e.g., searching on "A11*" should give you all the A11 call numbers)
50  
51 =item * A range defined by start_of_range and end_of_range should be correct, assuming that the string given for the end of the range is, in fact, a left prefix.
52  
53 =back
54  
55 That last point needs some explanation. The idea is that if someone gives a range of, say, A-AZ, what they really mean is A - AZ9999.99. The end_of_range method generates a key which lies immediately beyond the last possible key for a given starting point. There is no attempt to make end_of_range normalization correspond to anything in real life.
56  
57 =cut
58  
59 # Set up the prefix mapping for longints
60 3 my %intmap;
61 3 my $i = 0;
62 3 foreach my $prefix (qw(a aa ab abc ac ae ag ah ai al am an anl ao ap aq arx as at aug aw awo ay az b bc bd bf bg bh bj bl bm bn bp bq br bs bt bu bv bx c cb cc cd ce cg cis cj cmh cmm cn cr cs ct cz d da daa daw db dc dd de df dff dg dh dj djk dk dkj dl doc dp dq dr ds dt dth du dx e ea eb ec ed ee ek ep epa ex f fb fc fem fg fj fnd fp fsd ft ful g ga gb gc gda ge gf gh gn gr gs gt gv h ha hb hc hcg hd he hf hfs hg hh hhg hj hjc hm hmk hn hq hs ht hv hx i ia ib iid ill ilm in ioe ip j ja jan jb jc jf jg jh jhe jj jk jkc jl jln jn jq js jv jx jz k kb kbm kbp kbq kbr kbu kc kd kdc kde kdg kdk kds kdz ke kea keb kem ken keo keq kes kf kfa kfc kfd kff kfg kfh kfi kfk kfl kfm kfn kfo kfp kfr kfs kft kfu kfv kfw kfx kfz kg kga kgb kgc kgd kge kgf kgg kgh kgj kgk kgl kgn kgq kgs kgt kgv kgx kh kha khc khd khf khh khk khp khq khu khw kit kj kja kjc kje kjg kjj kjk kjm kjn kjp kjq kjr kjs kjt kjv kjw kk kka kkb kkc kke kkf kkg kkh kki kkj kkm kkn kkp kkq kkr kks kkt kkv kkw kkx kky kkz kl kla klb kld kle klf klg klh klm kln klp klr kls klt klv klw km kmc kme kmf kmh kmj kmk kml kmm kmn kmo kmp kmq kmt kmu kmv kmx kn knc knd kne knf kng knh knk knl knm knn knp knq knr kns knt knu knw knx kny kp kpa kpc kpe kpf kpg kph kpj kpk kpl kpm kpp kps kpt kpv kpw kq kqc kqe kqg kqj kqk kqp kqw krb krc krg krm krn krp krr krs kru krv krx ks ksa ksc ksh ksj ksk ksl ksp kss kst ksv ksw ksx ksy kta ktd ktg ktj ktk ktl ktq ktr ktt ktu ktv ktw ktx kty ktz ku kuc kuq kvc kvf kvm kvn kvp kvq kvr kvs kvw kwc kwg kwh kwl kwp kwr kww kwx kz kza kzd l la law lb lc ld le lf lg lh lj ll ln lrm lt lv m may mb mc me mf mh mkl ml mpc mr ms mt my n na nat nax nb nc nd nda nds ne ner new ng nh nk nl nmb nn no nt nv nx ok onc p pa pb pc pcr pd pe pf pg ph phd pj pjc pk pl pm pn pnb pp pq pr ps pt pz q qa qb qc qd qe qh qk ql qm qp qr qry qu qv r ra rb rbw rc rcc rd re ref res rf rg rh rj rk rl rm rn rp rs rt rv rx rz s sb sd see sf sfk sgv sh sk sn sql sw t ta tc td tdd te tf tg tgg th tj tk tl tn tnj to tp tr ts tt tx tz u ua ub uc ud ue uf ug uh un use v va vb vc vd ve vf vg vk vla vm w wq x xp xx y yh yl yy z za zhn zz zzz)) {
63 1824 $intmap{$prefix} = $i;
64 1824 $i++;
65 }
66  
67 # Regexp constants to deal with matching LC and variants
68  
69 3 my $lcregex = qr/^
70 \s*
71 (?:VIDEO-D)? # for video stuff
72 (?:DVD-ROM)? # DVDs, obviously
73 (?:CD-ROM)? # CDs
74 (?:TAPE-C)? # Tapes
75 \s*
76 ([A-Z]{1,3}) # alpha
77 \s*
78 (?: # optional numbers with optional decimal point
79 (\d+)
80 (?:\s*?\.\s*?(\d+))?
81 )?
82 \s*
83 (\d+[stndrh]*)? # optional extra numbering including suffixes (1st, 2nd, etc.)
84 \s*
85 (?: # optional cutter
86 (\.)? \s* # optional decimal
87 ([A-Z]) # cutter letter
88 \s*
89 (\d+ | \Z)? # cutter numbers
90 )?
91 \s*
92 (?: # optional cutter
93 \.? \s*
94 ([A-Z]) # cutter letter
95 \s*
96 (\d+ | \Z)? # cutter numbers
97 )?
98 \s*
99 (?: # optional cutter
100 \.? \s*
101 ([A-Z]) # cutter letter
102 \s*
103 (\d+ | \Z)? # cutter numbers
104 )?
105 (\s+.+?)? # everthing else
106 \s*$
107 /x;
108  
109  
110  
111 3 my $weird = qr/
112 ^
113 \s*[A-Z]+\s*\d+\.\d+\.\d+
114 /x;
115  
116 # Class variables for top/bottom sort chars
117 3 my $Topper = ' '; # must sort before 'A'
118 3 my $Bottomer = '~'; # must sort after 'Z' and '9'
119  
120  
121 =head1 CONSTRUCTORS
122  
123 =head2 new([call_number_text, [topper_character, [bottomer_character]]]) -- create a new object, optionally passing in the initial string, a "topper", and a "bottomer" (explained below)
124  
125 =cut
126  
127 7 ▶sub new {
Subroutine new: called CC=5 SCAR=16.3
Pod documented
128 7 my $proto = shift;
129 7 ▶ my $class = ref($proto) || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
070
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
130 7 ▶ my $lc = shift || '';
Condition100%2/2
shift() || ''
l!l
61
MC/DC100%1/1
shift() || ''
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
131 7 my $topper = shift;
132 7 ▶ $topper = $Topper if !defined($topper); # ZERO is false but might be a reasonable value, so we need this more specific check
Branch: 1 branch
BranchTrueFalseTotal
unless defined $topper 6 1 7
133 7 ▶ my $bottomer = shift || $Bottomer;
Condition66%2/3
shift() || $Bottomer
l!l&&r!l&&!r
160
MC/DC0%0/2
shift() || $Bottomer
shift() $Bottomer
Truth table66%2/3
A || B
A= shift()B= $Bottomer
ABresult
1X1
011
000
134 7 my $self = {
135 callno => $lc,
136 topper => $topper,
137 bottomer => $bottomer
138 };
139 7 bless $self, $class;
140 7 return $self;
141 }
142  
143  
144 =head1 BASIC ACCESSORS
145  
146 =head2 call_number([call_number_text])
147  
148 The text of the call number we are dealing with.
149  
150 =cut
151  
152 2 ▶sub call_number {
Subroutine call_number: called CC=2 SCAR=6.9
Pod documented
153 2 my $self = shift;
154 2 ▶ if (@_) { $self->{callno} = uc(shift) }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 1 1 2
155 2 return $self->{callno};
156 }
157  
158 =head2 topper([character])
159  
160 Specify which character occupies the 'always-sort-to-the-top' slots in the sort keys. Defaults to the SPACE character, but can reasonably be anything with an ASCII value lower than 48 (i.e. the 'zero' character, '0'). This can function as either a class or instance method depending on need.
161  
162 =cut
163  
164 402 ▶sub topper {
Subroutine topper: called CC=4 SCAR=13.9
Pod documented
165 402 my $self = shift;
166 402 my $topper = shift;
167 402 ▶ if (ref $self) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self) { } 397 5 402
168 397 ▶ $self->{topper} = $topper if $topper; # just myself
Branch: 1 branch
BranchTrueFalseTotal
if $topper 2 395 397
169 397 return $self->{topper};
170 } else {
171 5 ▶ $Topper = $topper if $topper; # whole class
Branch: 1 branch
BranchTrueFalseTotal
if $topper 2 3 5
172 5 return $Topper;
173 }
174 }
175  
176 =head2 bottomer([character])
177  
178 Specify which character occupies the 'always-sort-to-the-bottom' slots in the sort keys. Defaults to the TILDE character, but can reasonably be anything with an ASCII value higher than 90 (i.e. 'Z'). This can function as either a class or instance method depending on need.
179  
180 =cut
181  
182 153 ▶sub bottomer {
Subroutine bottomer: called CC=4 SCAR=13.9
Pod documented
183 153 my $self = shift;
184 153 my $bottomer = shift;
185 153 ▶ if (ref $self) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self) { } 150 3 153
186 150 ▶ $self->{bottomer} = $bottomer if $bottomer; # just myself
Branch: 1 branch
BranchTrueFalseTotal
if $bottomer 2 148 150
187 150 return $self->{bottomer};
188 } else {
189 3 ▶ $Bottomer = $bottomer if $bottomer; # whole class
Branch: 1 branch
BranchTrueFalseTotal
if $bottomer 2 1 3
190 3 return $Bottomer;
191 }
192 }
193  
194 =head1 OTHER METHODS
195  
196 =head2 components(boolean returnAll = false)
197  
198 @comps = Library::CallNumber::LC->new('A 123.4 .c11')->components($returnAll)
199  
200 Returns an array of the individual components of the call number (or undef if it doesn't look like a call number).
201 Components are:
202  
203 =over 4
204  
205 =item * alpha
206  
207 =item * number (numeric.decimal)
208  
209 =item * cutter1
210  
211 =item * cutter2
212  
213 =item * cutter3
214  
215 =item * "extra" (anything after the cutters)
216  
217 =back
218  
219 The optional argument <I returnAll> (false by default) determines whether or not empty components (e.g.,
220 extra cutters) get a slot in the returned list.
221  
222 =cut
223  
224 4 ▶sub components {
Subroutine components: called CC=9 SCAR=22.0
Pod documented
225 4 my $self = shift;
226 4 my $returnAll = shift;
227 4 my $lc = $self->{callno};
228  
229 4 ▶ return undef if ($lc =~ $weird);
Branch: 1 branch
BranchTrueFalseTotal
if $lc =~ /$weird/ 0 4 4
230 4 ▶ return undef unless ($lc =~ $lcregex);
Branch: 1 branch
BranchTrueFalseTotal
unless $lc =~ /$lcregex/ 0 4 4
231  
232  
233 4 my ($alpha, $num, $dec, $othernum, $c1dec, $c1alpha, $c1num, $c2alpha, $c2num, $c3alpha, $c3num, $extra) = ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12);
234  
235 #combine stuff if need be
236
237 4 ▶ if ($dec) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dec) 2 2 4
238 2 $num .= '.' . $dec;
239 }
240
241 3 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
242 4 my $c1 = join('', $c1alpha, $c1num);
243 4 my $c2 = join('', $c2alpha, $c2num);
244 4 my $c3 = join('', $c3alpha, $c3num);
245
246 3 ▶ use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
247  
248 4 ▶ $c1 = '.' . $c1 if $c1dec;
Branch: 1 branch
BranchTrueFalseTotal
if $c1dec 3 1 4
249  
250 4 my @return;
251 4 foreach my $comp ($alpha, $num, $othernum, $c1, $c2, $c3, $extra) {
252 28 ▶ $comp = '' unless (defined $comp);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $comp 5 23 28
253 28 ▶ next unless ($comp =~ /\S/ or $returnAll);
Branch: 1 branch
BranchTrueFalseTotal
unless $comp =~ /\S/ or $returnAll 10 18 28
Condition66%2/3
$comp =~ /\S/ or $returnAll
l!l&&r!l&&!r
18010
MC/DC50%1/2
$comp =~ /\S/ or $returnAll
$comp =~ /\S/ $returnAll
Truth table66%2/3
A or B
A= $comp =~ /\S/B= $returnAll
ABresult
1X1
011
000
254 18 $comp =~ m/^\s*(.*?)\s*$/;
255 18 $comp = $1;
256 18 push @return, $comp;
257 }
258 4 return @return;
259 }
260  
261 =head2 _normalize(call_number_text)
262  
263 Base function to perform normalization.
264  
265 =cut
266  
267 255 ▶sub _normalize {
Subroutine _normalize: called CC=5 SCAR=16.1
268 255 my $self = shift;
269 255 my $lc = uc(shift);
270  
271 255 my $topper = $self->topper;
272  
273 # return undef if ($lc =~ $weird);
274 255 ▶ return undef unless ($lc =~ $lcregex);
Branch: 1 branch
BranchTrueFalseTotal
unless $lc =~ /$lcregex/ 0 255 255
275
276 255 my ($alpha, $num, $dec, $othernum, $c1dec, $c1alpha, $c1num, $c2alpha, $c2num, $c3alpha, $c3num, $extra) = ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12);
277  
278 3 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
279 255 my $class = $alpha;
280 255 ▶ $class .= sprintf('%04s', $num) if $num;
Branch: 1 branch
BranchTrueFalseTotal
if $num 233 22 255
281 255 ▶ $class .= $dec if $dec;
Branch: 1 branch
BranchTrueFalseTotal
if $dec 109 146 255
282 255 my $c1 = $c1alpha.$c1num;
283 255 my $c2 = $c2alpha.$c2num;
284 255 my $c3 = $c3alpha.$c3num;
285  
286 # normalize extra (most commonly years/numbering, benefits from padding)
287 # this could be reduced to a four digit pad, as very, very few numbers
288 # reach 10000, but we'll be conservative here (for now)
289 255 $extra =~ s/^\s+//g;
290 255 $extra =~ s/\.\s+/./g;
291 255 $extra =~ s/(\d)\s*-\s*(\d)/$1-$2/g;
292 255 $extra =~ s/(\d+)/sprintf("%05s", $1)/ge;
293 255 ▶ $extra = $topper . $extra if ($extra ne ''); # give the extra less 'weight' for falling down the list
Branch: 1 branch
BranchTrueFalseTotal
if $extra ne "" 43 212 255
294
295 # pad out othernum (again, conservatively)
296 255 $othernum =~ s/(\d+)/sprintf("%05s", $1)/ge;
297  
298 255 return join($topper, grep {/\S/} ($class, $othernum, $c1, $c2, $c3, $extra));
299 }
300  
301 =head2 normalize([call_number_text])
302  
303 Normalize the stored or passed call number as a sortable string
304  
305 =cut
306  
307 249 ▶sub normalize {
Subroutine normalize: called CC=2 SCAR=6.9
Pod documented
308 249 my $self = shift;
309 249 my $lc = shift;
310 249 ▶ $lc = $lc? uc($lc) : $self->{callno};
Branch: 1 branch
BranchTrueFalseTotal
$lc ? : 245 4 249
311 249 return $self->_normalize($lc)
312 }
313  
314 =head2 start_of_range([call_number_text])
315  
316 Alias for normalize
317  
318 =cut
319  
320 2 ▶sub start_of_range {
Subroutine start_of_range: called CC=1 SCAR=0.0
Pod documented
321 2 my $self = shift;
322 2 return $self->normalize(@_);
323 }
324  
325 =head2 end_of_range([call_number_text])
326  
327 Downshift an lc number so it represents the end of a range
328  
329 =cut
330  
331 6 ▶sub end_of_range {
Subroutine end_of_range: called CC=2 SCAR=6.9
Pod documented
332 6 my $self = shift;
333 6 my $lc = shift;
334 6 ▶ $lc = $lc? uc($lc) : $self->{callno};
Branch: 1 branch
BranchTrueFalseTotal
$lc ? : 4 2 6
335 6 my $bottomer = $self->bottomer;
336 6 return $self->_normalize($lc) . $bottomer;
337 }
338  
339 =head2 toLongInt(call_number_text, num_digits)
340  
341 Attempt to turn a call number into an integer value. Possibly useful for fast range checks, although obviously not perfectly accurate. Optional argument I<$num_digits> can be used to control the number of digits used, and therefore the precision of the results.
342  
343 =cut
344  
345 3 my $minval = new Math::BigInt('0'); # set to zero until this code matures
346 3 my $minvalstring = $minval->bstr;
347  
348 # this is a work in progress, with room for improvement in both exception
349 # logic and overall economy of bits
350 142 ▶sub toLongInt {
Subroutine toLongInt: called CC=10 SCAR=24.6
Pod documented
351 142 my $self = shift;
352 142 my $lc = shift;
353 142 ▶ my $num_digits = shift || 19; # 19 is a max-fit for 64-bits within our scope
Condition50%1/2
shift() || 19
l!l
0142
MC/DC0%0/1
shift() || 19
shift()
Truth table50%1/2
A
A= shift()
Aresult
11
00
354  
355 142 my $topper = $self->topper;
356 142 my $bottomer = $self->bottomer;
357  
358 #print "$lc\n";
359 142 my $topper_ord = ord($topper);
360 142 my $long = $self->normalize($lc);
361  
362 142 ▶ return $minvalstring unless ($long);
Branch: 1 branch
BranchTrueFalseTotal
unless $long 0 142 142
363  
364 142 my ($alpha, $num, $rest);
365 142 ▶ if ($long =~ /^([A-Z]+)(\d{4})(.*)$/) { # we have a 'full' call number
Branch: 2 branches
BranchTrueFalseTotal
if ($long =~ /^([A-Z]+)(\d{4})(.*)$/) { } 131 11 142
elsif ($long =~ /^([A-Z]+)(.*)$/) { } 11 0 11
366 131 ($alpha, $num, $rest) = (lc($1), $2, $3);
367 } elsif ($long =~ /^([A-Z]+)(.*)$/) { # numberless class; generally invalid, but let it slide for now
368 11 ($alpha, $rest) = (lc($1), $2);
369 11 ▶ if ($rest =~ /^$bottomer/) { # bottomed-out class
Branch: 1 branch
BranchTrueFalseTotal
if ($rest =~ /^$bottomer/) { } 0 11 11
370 0 $num = '9999';
371 } else {
372 11 $num = '0000';
373 }
374 }
375 142 my $class_int_string = '';
376 142 ▶ if (defined($intmap{$alpha})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $intmap{$alpha}) { } 142 0 142
377 142 $class_int_string .= $intmap{$alpha} . $num;
378 } else {
379 0 warn "Unknown prefix '$alpha'\n";
380 0 return $minvalstring;
381 }
382 142 my $rest_int_string = '';
383 142 my $bottomout;
384 142 foreach my $char (split('', $rest)) {
385 1103 ▶ if ($char eq $bottomer) {
Branch: 1 branch
BranchTrueFalseTotal
if ($char eq $bottomer) 0 1103 1103
386 0 $bottomout = 1;
387 0 last;
388 }
389 1103 $rest_int_string .= sprintf('%02d', ord($char) - $topper_ord);
390 }
391  
392 142 $rest_int_string = substr($rest_int_string, 0, $num_digits - 7); # Reserve first seven digits for $alpha and $num
393 142 ▶ if ($bottomout) {
Branch: 1 branch
BranchTrueFalseTotal
if ($bottomout) { } 0 142 142
394 0 $rest_int_string .= '9' x (($num_digits - 7) - length($rest_int_string)); # pad it if need be
395 } else {
396 142 $rest_int_string .= '0' x (($num_digits - 7) - length($rest_int_string)); # pad it if need be
397 }
398  
399 # print " $long => ", join('', @rv), "\n";
400 142 my $longint = Math::BigInt->new($class_int_string . $rest_int_string);
401 142 $longint->badd($minval);
402 # warn "\n\n".$self->_normalize($lc)." = ".$longint->bstr." ( $class_int_string + $rest_int_string) \n\n";
403 142 return $longint->bstr;
404
405 }
406  
407  
408  
409 =head1 AUTHOR
410  
411 Current Maintainer: Dan Wells, C<< <dbw2 at calvin.edu> >>
412 Original Author: Bill Dueber, C<< <dueberb at umich.edu> >>
413  
414 =head1 BUGS
415  
416 Please report any bugs or feature requests through the web interface at
417 L<http://code.google.com/p/library-callnumber-lc/issues/list>. I will be
418 notified, and then you'll automatically be notified of progress on your bug as
419 I make changes.
420  
421  
422 =head1 SUPPORT
423  
424 You can find documentation for this module with the perldoc command.
425  
426 perldoc Library::CallNumber::LC
427  
428  
429 You can also look for information at the Google Code page:
430  
431 http://code.google.com/p/library-callnumber-lc/
432  
433  
434 =head1 COPYRIGHT & LICENSE
435  
436 Copyright 2009 Bill Dueber, all rights reserved.
437 Copyright 2011 Dan Wells, all rights reserved.
438  
439 This program is free software; you can redistribute it and/or modify it
440 under the same terms as Perl itself and also under the new BSD license
441 as described at http://www.opensource.org/licenses/bsd-license.php
442  
443  
444 =cut
445  
446 3 1; # End of Library::CallNumber::LC
↑ Summary