.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Biblio::LCC 3pm"
.TH Biblio::LCC 3pm "2023-02-05" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Biblio::LCC \- parse and normalize LC\-style call numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Biblio::LCC;
\&    $normalized = Biblio::LCC\->normalize(\*(AqPS3573.A472242 A88 1998\*(Aq);
\&    ($begin, $limit) = Biblio::LCC\->normalize_range(\*(AqE184.5\-E185\*(Aq);
\&    @parts = Biblio::LCC\->parse($call_number);
\&    $call_number = Biblio::LCC\->add($class, $offset);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBBiblio::LCC\fR parses Library of Congress classification ranges and call numbers
and normalizes them into a form suitable for a straight \s-1ASCII\s0 sort.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.IP "\fBnormalize\fR(\fI\f(CI$call_number\fI\fR)" 4
.IX Item "normalize($call_number)"
.Vb 1
\&    $normalized = Biblio::LCC\->normalize(\*(AqPS3573.A472242 A88 1998\*(Aq);
.Ve
.Sp
Convert an LC-style class (e.g., '\s-1PS\s0' or 'E184.5') or call number (e.g.,
\&'\s-1PS3573.A472242 A88 1998\s0') into a string that may be compared to other
normalized call numbers (see \fBnormalize_range\fR below).
.IP "\fBnormalize_range\fR(\fI\f(CI$call_number_range\fI\fR)" 4
.IX Item "normalize_range($call_number_range)"
.Vb 1
\&    ($begin, $limit) = Biblio::LCC\->normalize_range(\*(AqE184.5\-E185\*(Aq);
.Ve
.Sp
Parse a call number range, producing a pair of strings \fIB\fR and \fIL\fR such
that a call number falls within the range if and only if its normalized
form, in a straight lexicographic \s-1ASCII\s0 comparison, is greater than or equal
to \fIB\fR and strictly less than \fIL\fR.
.Sp
The range may be specified in one of three ways:
.RS 4
.IP "\fIcall number\fR \fB\-\fR \fIcall number\fR" 4
.IX Item "call number - call number"
A pair of call numbers; the range includes the beginning call number, the
ending call number, and any call numbers that have the ending call number as
a prefix.
.Sp
For example, the (unnormalized) range \f(CW\*(C`AS131\-AS142\*(C'\fR encompasses any class
or call number from \f(CW\*(C`AS131\*(C'\fR up to \fBbut not including\fR \f(CW\*(C`AS143\*(C'\fR
.Sp
In this form, the alphabetic string that begins the second call number may
be omitted, so (for example) \f(CW\*(C`E184.5\-185\*(C'\fR is equivalent to \f(CW\*(C`E184.5\-E185\*(C'\fR.
.Sp
Space is optional around the hyphen.
.IP "\fIcall number\fR" 4
.IX Item "call number"
A single class or call number, in unnormalized form.  This is equivalent to
a pair in which each call number is the same.  For example, the unnormalized
range \f(CW\*(C`QA141.5.A1\*(C'\fR encompasses call numbers from \f(CW\*(C`QA141.5.A1\*(C'\fR up to but
not including \f(CW\*(C`QA141.5.A2\*(C'\fR.
.IP "\fIcall number\fR < \fIcall number\fR" 4
.IX Item "call number < call number"
A pair of call numbers; the range includes the first call number and any
call number up and not including the ending call number.
.Sp
For example, the unnormalized range \f(CW\*(C`DT6.7<DT7\*(C'\fR includes everything
greater than \f(CW\*(C`DT6.7\*(C'\fR and less than \f(CW\*(C`DT7\*(C'\fR.
.Sp
In this form, the alphabetic string that begins the second call number may
be omitted, as in the form of range that uses a hyphen to separate the parts.
.Sp
Space is optional around the less-than sign (<).
.RE
.RS 4
.RE
.IP "\fBparse\fR(\fI\f(CI$call_number\fI\fR)" 4
.IX Item "parse($call_number)"
.Vb 1
\&    ($alpha, $int, $frac, $rmdr) = Biblio::LCC\->parse($call_number);
.Ve
.Sp
Split an \s-1LC\s0 call number into alphabetic, integer, decimal fraction, and
remainder (i.e., everything else).
.IP "\fBadd\fR(\fI\f(CI$class\fI\fR, \fI\f(CI$offset\fI\fR)" 4
.IX Item "add($class, $offset)"
.Vb 1
\&    $call_number = Biblio::LCC\->add($class, $offset);
.Ve
.Sp
Add an offset (e.g., '180.3') to a base \s-1LC\s0 class (e.g., '\s-1GN1600\s0') to produce
another \s-1LC\s0 class (e.g., '\s-1GN1780.3\s0').
.Sp
The base class may have only alphabetic and integer parts; an exception will be
thrown if it has a fractional part (e.g., as in '\s-1GN1600.1\s0') or a remainder (e.g.,
as in '\s-1GN1600 R5\s0').
.SH "HOW IT WORKS"
.IX Header "HOW IT WORKS"
Call numbers are first analyzed into four parts.  For example, take the call number
\&\fB\s-1GB1001.72.M32 E73 1988\s0\fR.
.IP "\fBalpha\fR" 4
.IX Item "alpha"
.Vb 1
\&    GB
.Ve
.Sp
The one to three alphabetic characters that begin the call number.
.IP "\fBinteger\fR" 4
.IX Item "integer"
.Vb 1
\&    1001
.Ve
.Sp
An integer from 1 to 9999 that follows.
.IP "\fBfraction\fR" 4
.IX Item "fraction"
.Vb 1
\&    72
.Ve
.Sp
Digits that follow a decimal point after the integer part.
.IP "\fBremainder\fR" 4
.IX Item "remainder"
.Vb 1
\&    M32 E73 1988
.Ve
.Sp
Everything that follows.
.PP
The \s-1LC\s0 Classification allows for a wide range of possible call numbers that do
not fall into the simple (alpha, integer, fraction, remainder) model that this
module implements.  For example, the following are
all valid call numbers:
.IP "\fBE514.5 17th .S76 1986\fR =item \fBG3804.N4:3B7 K142t\fR =item \fBG3824.Y6C5 s50 .W5\fR" 4
.IX Item "E514.5 17th .S76 1986 =item G3804.N4:3B7 K142t =item G3824.Y6C5 s50 .W5"
.PP
It may be that in some cases further analysis, and fully correct sorting, are
not possible without hardcoded knowledge of the \s-1LC\s0 classification.  In many
cases, however, a more sophisticated parsing model, while more complex, would
result in better normalization.
.SH "BUGS"
.IX Header "BUGS"
There are no known bugs.  Please report bugs on this module's \s-1RT\s0 page:
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Biblio\-LCC>.
.SH "TO DO"
.IX Header "TO DO"
Implement a \f(CW\*(C`new\*(C'\fR method and rewrite other methods so they may be used as
class \fBor\fR instance methods.
.PP
Special handling of \*(L"special\*(R" call numbers (e.g., in the Gs).
.PP
Allow caller to specify prefixes to strip (e.g., \*(L"Folio\*(R").
.PP
Parse straight from the 050 or 090 field of a \s-1MARC\s0 record.
.PP
Better error reporting.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Hoffman (nkuitse \s-1AT\s0 cpan \s-1DOT\s0 org)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2007\-2008 Paul M. Hoffman.
.PP
This is free software, and is made available under the same terms as Perl
itself.