.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WebService::ISBNDB::API::Books 3"
.TH WebService::ISBNDB::API::Books 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
WebService::ISBNDB::API::Books \- Data class for book information
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use WebService::ISBNDB::API::Books;
.Ve
.PP
.Vb 2
\&    my $book = WebService::ISBNDB::API->new({ api_key => $key,
\&                                              isbn => '0596002068' });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents book data from \fBisbndb.com\fR. It is a sub-class of
\&\fBWebService::ISBNDB::API\fR (see WebService::ISBNDB::API), and inherits all
the attributes and methods from that class.
.SH "METHODS"
.IX Header "METHODS"
The following methods are specific to this class, or overridden from the
super\-class.
.Sh "Constructor"
.IX Subsection "Constructor"
The constructor for this class may take a single scalar argument in lieu of a
hash reference:
.IP "new($ISBN|$TITLE|$ARGS)" 4
.IX Item "new($ISBN|$TITLE|$ARGS)"
This constructs a new object and returns a referent to it. If the parameter
passed is a hash reference, it is handled as normal, per \fBClass::Std\fR
mechanics. If the value is a scalar, it is tested to see if it is a valid
\&\s-1ISBN\s0 (using the \fBBusiness::ISBN\fR module). If it is, it is used as a search
key to find the corresponding book. If it is not a valid \s-1ISBN\s0, it is assumed
to be the title, and is likewise used as a search key. Since the title may
return more than one match, the first matching record from the source is used
to construct the object.
.Sp
If the argument is the hash-reference form, then a new object is always
constructed; to perform searches see the \fIsearch()\fR and \fIfind()\fR methods. Thus,
the following two lines are in fact different:
.Sp
.Vb 1
\&    $book = WebService::ISBNDB::API::Books->new({ isbn => '0596002068' });
.Ve
.Sp
.Vb 1
\&    $book = WebService::ISBNDB::API::Books->new('0596002068');
.Ve
.Sp
The first creates a new object that has only the \f(CW\*(C`isbn\*(C'\fR attribute set. The
second returns a new object that represents the book with \s-1ISBN\s0 \f(CW0596002068\fR,
with all data present.
.PP
The class also defines:
.IP "copy($TARGET)" 4
.IX Item "copy($TARGET)"
Copies the target object into the calling object. All attributes (including
the \s-1ID\s0) are copied. This method is marked \*(L"\s-1CUMULATIVE\s0\*(R" (see Class::Std),
and any sub-class of this class should provide their own \fIcopy()\fR and also mark
it \*(L"\s-1CUMULATIVE\s0\*(R", to ensure that all attributes at all levels are copied.
.PP
See the \fIcopy()\fR method in WebService::ISBNDB::API.
.Sh "Accessors"
.IX Subsection "Accessors"
The following attributes are used to maintain the content of a book object:
.IP "id" 4
.IX Item "id"
The unique \s-1ID\s0 within the \fBisbndb.com\fR system for this book.
.IP "isbn" 4
.IX Item "isbn"
The \s-1ISBN\s0 (International Standard Book Number) for the book (without hyphens).
.IP "title" 4
.IX Item "title"
The title of the book.
.IP "longtitle" 4
.IX Item "longtitle"
The full title of the book, including any sub\-title.
.IP "authors" 4
.IX Item "authors"
An array (stored as a reference) of the \fBWebService::ISBNDB::API::Authors\fR
objects that refer to the authors of the book. These are not actually loaded
from the service until they are first fetched.
.IP "authors_text" 4
.IX Item "authors_text"
A simple textual representation of the authors, as returned by the service.
This may be more convenient to use than the author objects, if you only want
to display the names themselves.
.IP "publisher" 4
.IX Item "publisher"
The \fBWebService::ISBNDB::API::Publisher\fR object that refers to the book's
publisher.  This is not loaded until the first request to fetch it is made.
.IP "publisher_text" 4
.IX Item "publisher_text"
A simple textual representation of the publisher, as returned by the service.
This may be more convenient to use than the object, if you only wish to
display the publisher's name.
.IP "subjects" 4
.IX Item "subjects"
An array (stored as a reference) of the \fBWebService::ISBNDB::API::Subjects\fR
objects that refer to the subjects this book is associated with. As with the
authors, the actual objects are not loaded until requested.
.IP "dewey_decimal" 4
.IX Item "dewey_decimal"
The book's Dewey Decimal classification number.
.IP "dewey_decimal_normalized" 4
.IX Item "dewey_decimal_normalized"
The normalized form of the Dewey Decimal number for the book.
.IP "lcc_number" 4
.IX Item "lcc_number"
The Library of Congress Classification number for the book.
.IP "language" 4
.IX Item "language"
The language the book is printed in. The form and content of this field may
not be standardized.
.IP "physical_description_text" 4
.IX Item "physical_description_text"
Text describing the physical dimensions of the book.
.IP "edition_info" 4
.IX Item "edition_info"
Any additional information on the particular edition of the book.
.IP "change_time" 4
.IX Item "change_time"
A string representation of the time when this record was last changed. The
string is in \s-1ISO\s0 8601 form, with no explicit time-zone specified. \s-1UTC\s0 time
is assumed in internal manipulations.
.IP "change_time_sec" 4
.IX Item "change_time_sec"
If the \fBDate::Parse\fR module is available, this attribute will hold the value
from \f(CW\*(C`change_time\*(C'\fR, converted to seconds since the \s-1UNIX\s0 Epoch. Otherwise,
this attribute will always be \f(CW\*(C`undef\*(C'\fR.
.IP "price_time" 4
.IX Item "price_time"
A string representation of the time when the price information for this
record was last updated. As above, the string is in \s-1ISO\s0 8601 format with no
time\-zone, and it assumed to be \s-1UTC\s0 internally.
.IP "price_time_sec" 4
.IX Item "price_time_sec"
As with \f(CW\*(C`change_time_sec\*(C'\fR, only for the price-change value. Requires the
availability of \fBDate::Parse\fR, or else the value will always be \f(CW\*(C`undef\*(C'\fR.
.IP "summary" 4
.IX Item "summary"
The content of the \f(CW\*(C`<Summary>\*(C'\fR tag, which is free-form text. The
text has leading and trailing white-space removed, and all new-lines
converted to spaces, to yield a single-line string value.
.IP "notes" 4
.IX Item "notes"
Another free-form text field, similar to \f(CW\*(C`summary\*(C'\fR, but less used.
.IP "urlstext" 4
.IX Item "urlstext"
Fairly free-form text, used to specify URLs related to the book.
.IP "awardstext" 4
.IX Item "awardstext"
More free-form text, this to specify any awards the book has received.
.IP "prices" 4
.IX Item "prices"
If price information is available for the book, this attribute will contain
a list-reference containing zero or more hash references. Each hash reference
will have the following keys (all will be present on every hash reference, but
some may be empty or \f(CW\*(C`undef\*(C'\fR):
.RS 4
.IP "store_isbn" 8
.IX Item "store_isbn"
The \s-1ISBN\s0 for the book at the store, if different from the book's regular
\&\s-1ISBN\s0. Not set if the two are the same.
.IP "store_title" 8
.IX Item "store_title"
The book's title at the store, if different from the book's regular title.
Not usually set if the two are the same.
.IP "store_url" 8
.IX Item "store_url"
\&\s-1URL\s0 for the book. This may be a relative \s-1URL\s0, in which case it is relative to
the store's website. If it is an absolute \s-1URL\s0 (complete \s-1URL\s0), it is a
redirector \s-1URL\s0 originating at \fBisbndb.com\fR. The \s-1URL\s0 is used for purchasing
the book, and the redirect URLs allow \fBisbndb.com\fR to collect small
commissions off of sales they facilitate, which in turn helps to keep their
service available and free.
.IP "store_id" 8
.IX Item "store_id"
Unique identifier for the store.
.IP "currency_code" 8
.IX Item "currency_code"
The code for the currency the price is expressed in.
.IP "is_in_stock" 8
.IX Item "is_in_stock"
A boolean value indicating whether the book is in stock.
.IP "is_historic" 8
.IX Item "is_historic"
A boolean value indicating whether the price this record describes is
considered \*(L"historic\*(R". Any price older than 24 hours should generally be
considered historic, even if this value is true.
.IP "is_new" 8
.IX Item "is_new"
A boolean value indicating whether the book offered is new or used.
.IP "currency_rate" 8
.IX Item "currency_rate"
Currency rate against the \s-1US\s0 dollar, only set if the \f(CW\*(C`currency_code\*(C'\fR is not
\&\f(CW\*(C`USD\*(C'\fR.
.IP "price" 8
.IX Item "price"
The price of the book (expressed in the currency indicated by \f(CW\*(C`currency_code\*(C'\fR,
above).
.IP "check_time" 8
.IX Item "check_time"
String representation of the time when this price was last checked. As with
the other time-oriented values, this is in \s-1ISO\s0 8601 format with no explicit
time\-zone.
.IP "check_time_sec" 8
.IX Item "check_time_sec"
If the \fBDate::Parse\fR package is available, this is the value of \f(CW\*(C`check_time\*(C'\fR
expressed in seconds, suitable for use with the Perl \fBlocaltime\fR keyword.
.RE
.RS 4
.RE
.IP "marc" 4
.IX Item "marc"
If \s-1MARC\s0 information is available for the book, this attribute will contain
a list-reference containing zero or more hash references. Each hash reference
will have the following keys (all will be present on every hash reference, but
some may be empty or \f(CW\*(C`undef\*(C'\fR):
.RS 4
.IP "library_name" 8
.IX Item "library_name"
Name of the library this record is taken from.
.IP "last_update" 8
.IX Item "last_update"
\&\s-1ISO\s0 8601 string representing the last time the record was updated from the
library.
.IP "last_update_sec" 8
.IX Item "last_update_sec"
If \fBDate::Parse\fR is available, this will be the \f(CW\*(C`last_update\*(C'\fR attribute
converted to seconds, measured from the \s-1UNIX\s0 epoch.
.IP "marc_url" 8
.IX Item "marc_url"
The \s-1URL\s0 to the \s-1MARC\s0 record on the library's site.
.RE
.RS 4
.RE
.PP
The following accessors are provided to manage these attributes:
.IP "get_id" 4
.IX Item "get_id"
Return the book \s-1ID\s0.
.IP "set_id($ID)" 4
.IX Item "set_id($ID)"
Sets the book \s-1ID\s0. This method is restricted to this class, and cannot be
called outside of it. In general, you shouldn't need to set the \s-1ID\s0 after the
object is created, since \fBisbndb.com\fR is a read-only source.
.IP "get_isbn" 4
.IX Item "get_isbn"
Return the \s-1ISBN\s0 of the book. In general, the \s-1ISBN\s0 has had any hyphens removed.
.IP "set_isbn($ISBN)" 4
.IX Item "set_isbn($ISBN)"
Set the book \s-1ISBN\s0. The value is tested with \fBBusiness::ISBN\fR to ensure that
the value is a valid \s-1ISBN\s0.
.IP "get_title" 4
.IX Item "get_title"
Return the common title of the book.
.IP "set_title($TITLE)" 4
.IX Item "set_title($TITLE)"
Set the title of the book.
.IP "get_longtitle" 4
.IX Item "get_longtitle"
Return the long title of the book. This will include subtitles, for example.
.IP "set_longtitle($LONGTITLE)" 4
.IX Item "set_longtitle($LONGTITLE)"
Set the long title of the book.
.IP "get_authors" 4
.IX Item "get_authors"
Get the list of author objects (instances of
\&\fBWebService::ISBNDB::API::Authors\fR or a sub\-class) for the book. The objects
are not fetched from the source until the first call to this method.
.IP "set_authors($LIST)" 4
.IX Item "set_authors($LIST)"
Set the list of authors for this book. The value must be a list\-reference. If
the values in the list reference are strings instead of objects, then the
first call to \fIget_authors()\fR will convert them into objects. The strings must
be the author \s-1ID\s0 values as returned by the service.
.IP "get_authors_text" 4
.IX Item "get_authors_text"
Return the text-representation of the authors, as returned by the service.
.IP "set_authors_text($TEXT)" 4
.IX Item "set_authors_text($TEXT)"
Set the text-representation of the authors.
.IP "get_publisher" 4
.IX Item "get_publisher"
Return the publisher object (instance of
\&\fBWebService::ISBNDB::API::Publishers\fR or a sub\-class) for this book. The
object is not loaded from the source until the first request to this method.
.IP "set_publisher($PUBLISHER)" 4
.IX Item "set_publisher($PUBLISHER)"
Set the publisher for this book. The value should be either a publisher object
or a string containing the publisher \s-1ID\s0. If the \s-1ID\s0 is set as the value, the
next call to \fIget_publisher()\fR will resolve it into an object.
.IP "get_subjects" 4
.IX Item "get_subjects"
Get the list of subject objects (instances of
\&\fBWebService::ISBNDB::API::Subjects\fR or a sub\-class) for the book. The objects
are not fetched from the source until the first call to this method.
.IP "set_subjects($LIST)" 4
.IX Item "set_subjects($LIST)"
Set the list of subjects. The value must be a list\-reference, and may contain
either the objects themselves or the subject \s-1ID\s0 values as returned by the
source. If the content is the \s-1ID\s0 values, then the next call to \fIget_subjects()\fR
will resolve them to objects.
.IP "get_dewey_decimal" 4
.IX Item "get_dewey_decimal"
Get the Dewey Decimal number.
.IP "set_dewey_decimal($DEWEY)" 4
.IX Item "set_dewey_decimal($DEWEY)"
Set the Dewey Decimal number.
.IP "get_dewey_decimal_normalized" 4
.IX Item "get_dewey_decimal_normalized"
Get the normalized Dewey Decimal number.
.IP "set_dewey_decimal_normalized($DEWEY_NORM)" 4
.IX Item "set_dewey_decimal_normalized($DEWEY_NORM)"
Set the normalized Dewey Decimal number.
.IP "get_lcc_number" 4
.IX Item "get_lcc_number"
Get the Library of Congress Classification number.
.IP "set_lcc_number($LCC)" 4
.IX Item "set_lcc_number($LCC)"
Set the Library of Congress Classification number.
.IP "get_language" 4
.IX Item "get_language"
Get the language code for the book's text.
.IP "set_language($LANG)" 4
.IX Item "set_language($LANG)"
Set the language code.
.IP "get_physical_description_text" 4
.IX Item "get_physical_description_text"
Get the book's physical description text.
.IP "set_physical_description_text($PHYS)" 4
.IX Item "set_physical_description_text($PHYS)"
Set the book's physical description text.
.IP "get_edition_info" 4
.IX Item "get_edition_info"
Get any information on the specific edition of the book.
.IP "set_edition_info($INFO)" 4
.IX Item "set_edition_info($INFO)"
Set the edition information for the book.
.IP "get_change_time" 4
.IX Item "get_change_time"
Get the change-time of the book record (an \s-1ISO\s0 8601 string, no explicit
time\-zone, presumed to be \s-1UTC\s0).
.IP "set_change_time($TIME)" 4
.IX Item "set_change_time($TIME)"
Sets the change-time of the book record. If \fBParse::Date\fR is available, and
the value passed in \f(CW$TIME\fR is parsable, then the \f(CW\*(C`change_time_sec\*(C'\fR
attribute will also be updated with the equivalent value.
.IP "get_change_time_sec" 4
.IX Item "get_change_time_sec"
Get the change-time as a number of seconds since the Epoch (as defined in
\&\s-1UNIX\s0 terms, see Parse::Date). This attribute is only set if the
\&\fBDate::Parse\fR module is available.
.IP "set_change_time_sec($TIME)" 4
.IX Item "set_change_time_sec($TIME)"
Set the seconds-since-Epoch representation of the change-time to the new
value. This will also update the \f(CW\*(C`change_time\*(C'\fR attribute, setting it to an
\&\s-1ISO\s0 8601\-style string that is the textual representation of \f(CW$TIME\fR.
.IP "get_price_time" 4
.IX Item "get_price_time"
.PD 0
.IP "set_price_time($TIME)" 4
.IX Item "set_price_time($TIME)"
.IP "get_price_time_sec" 4
.IX Item "get_price_time_sec"
.IP "set_price_time_sec($TIME)" 4
.IX Item "set_price_time_sec($TIME)"
.PD
These are identical to the previous four, only they apply to the time-stamp
marking when the price information was last updated. The same restrictions
apply to the \f(CW\*(C`price_time_sec\*(C'\fR attribute (\fBParse::Date\fR is required for it
to be set when data is read from the source).
.IP "get_summary" 4
.IX Item "get_summary"
Get the summary text for this book. The summary is free-form text that has
has leading and trailing white-space removed, as well as having any internal
new-lines or tabs converted to single spaces.
.IP "set_summary($SUMMARY)" 4
.IX Item "set_summary($SUMMARY)"
Set the summary text to the new content in \f(CW$SUMMARY\fR.
.IP "get_notes" 4
.IX Item "get_notes"
Get the notes for the book. The notes are also free-form text, and are
trimmed in the same fashion as \f(CW\*(C`summary\*(C'\fR.
.IP "set_notes($NOTES)" 4
.IX Item "set_notes($NOTES)"
Set the notes text for the book.
.IP "get_urlstext" 4
.IX Item "get_urlstext"
Get the \f(CW\*(C`urlstext\*(C'\fR attribute. This text should provide URLs related to
the book, when present.
.IP "set_urlstext($URLS)" 4
.IX Item "set_urlstext($URLS)"
Set the \f(CW\*(C`urlstext\*(C'\fR attribute to the new value.
.IP "get_awardstext" 4
.IX Item "get_awardstext"
Get the awards-text data for the book. If present, this should refer to any
awards the book has won.
.IP "set_awardstext($AWARDS)" 4
.IX Item "set_awardstext($AWARDS)"
Set the awards-text to the new data given.
.IP "get_prices" 4
.IX Item "get_prices"
Get the price data for the book. This comes in the form of a list-reference
of hash-references (see earlier description of the keys).
.IP "set_prices($PRICELIST)" 4
.IX Item "set_prices($PRICELIST)"
Set the price data. The value passed in must be a list reference, and every
element in the list mush be a hash reference. Otherwise an exception will be
thrown.
.IP "get_marc" 4
.IX Item "get_marc"
Get the \s-1MARC\s0 data for the book. \s-1MARC\s0 data comes in the form of a
list-reference of hash-references (see above for description of the keys).
.IP "set_marc($MARCLIST)" 4
.IX Item "set_marc($MARCLIST)"
Set the \s-1MARC\s0 data. The value passed in must be a list reference, and every
element in the list mush be a hash reference. Otherwise an exception will be
thrown.
.Sh "Utility Methods"
.IX Subsection "Utility Methods"
Besides the constructor and the accessors, the following methods are provided
for utility:
.IP "find($ARG|$ARGS)" 4
.IX Item "find($ARG|$ARGS)"
This is a specialization of \fIfind()\fR from the parent class. It allows the
argument passed in to be a scalar in place of the usual hash reference. If the
value is a scalar, it is tested to see if it is a valid \s-1ISBN\s0, and if so the
search is made against the \s-1ISBN\s0 with that value. If the scalar value is not a
valid \s-1ISBN\s0, the search is made against the title instead. If the value is a
hash reference, it is passed to the super-class method.
.IP "normalize_args($ARGS)" 4
.IX Item "normalize_args($ARGS)"
This method maps the user-visible arguments as defined for \fIfind()\fR and \fIsearch()\fR
into the actual arguments that must be passed to the service itself. In
addition, some arguments are added to the request to make the service return
extra data used for retrieving subjects, publisher information, etc. The
method changes \f(CW$ARGS\fR in place, and also returns \f(CW$ARGS\fR as the value from
the method.
.PP
See the next section for an explanation of the available keys for searches.
.SH "SEARCHING"
.IX Header "SEARCHING"
Both \fIfind()\fR and \fIsearch()\fR allow the user to look up data in the \fBisbndb.com\fR
database. The allowable search fields are limited to a certain set, however.
When either of \fIfind()\fR or \fIsearch()\fR are called, the argument to the method
should be a hash reference of key/value pairs to be passed as arguments for
the search (the exception being that \fIfind()\fR can accept a single string, which
has special meaning as detailed earlier).
.PP
Searches in the text fields are done in a case-insensitive manner.
.PP
The available search keys are:
.IP "title" 4
.IX Item "title"
The value should be a text string. The search returns books whose title
matches the string.
.IP "isbn" 4
.IX Item "isbn"
The value should be a text string. The search returns the book whose \s-1ISBN\s0
matches the string. The string is not checked for validity, so a bad \s-1ISBN\s0
will simply not return any records.
.IP "author" 4
.IX Item "author"
The value for this key should be either an object of the
\&\fBWebService::ISBNDB::API::Authors\fR class (or sub-class thereof), or a text
string.  If the value is an object, the search is done against the specific
author \s-1ID\s0.  If the value is a string, the search is done using the \*(L"combined\*(R"
search key, and may return results unrelated to the intended query.
.IP "publisher" 4
.IX Item "publisher"
The value for this key may be an object of the
\&\fBWebService::ISBNDB::API::Publishers\fR class (or sub-class thereof) or a text
string. If it is an object, the \s-1ID\s0 is used in a specific search. If the value
is a string, it is used with the \*(L"combined\*(R" search\-key, and may return
unexpected results.
.IP "subject" 4
.IX Item "subject"
The value for this key is expected to be either an object (of the
\&\fBWebService::ISBNDB::API::Subjects\fR class or sub-class thereof) or a literal
subject \s-1ID\s0 as a string. The subject cannot be searched for using the
\&\*(L"combined\*(R" key.
.IP "combined" 4
.IX Item "combined"
The value should be a text string, and is searched against a combined field
that includes titles, authors and publisher names.
.IP "full" 4
.IX Item "full"
The value should be a text string, and is searched against almost all of the
textual data, including title, authors, publishers, summary, notes, award
information, etc.
.IP "dewey_decimal" 4
.IX Item "dewey_decimal"
The value should be a Dewey Decimal Classification number, and is used
directly in the search.
.IP "lcc_number" 4
.IX Item "lcc_number"
The value should be a Library of Congress Classification number, and is used
directly in the search.
.PP
Note that the names above may not be the same as the corresponding parameters
to the service. The names are chosen to match the related attributes as
closely as possible, for ease of understanding.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Search for all books with \*(L"perl\*(R" in the title:
.PP
.Vb 2
\&    $perlbooks = WebService::ISBNDB::API::Books->
\&                     search({ title => "perl" });
.Ve
.PP
Search for all books by Edgar Allan Poe:
.PP
.Vb 2
\&    $poebooks = WebService::ISBNDB::API::Books->
\&                    search({ author => 'edgar allan poe' });
.Ve
.PP
Find the record for \*(L"Progamming Web Services With Perl\*(R":
.PP
.Vb 1
\&    $pwswp = WebService::ISBNDB::API::Books->find('0596002068');
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
The data returned by this class is only as accurate as the data retrieved from
\&\fBisbndb.com\fR.
.PP
The list of results from calling \fIsearch()\fR is currently limited to 10 items.
This limit will be removed in an upcoming release, when iterators are
implemented.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
WebService::ISBNDB::API, WebService::ISBNDB::API::Authors,
WebService::ISBNDB::API::Publishers, WebService::ISBNDB::API::Subjects,
Business::ISBN, Date::Parse
.SH "AUTHOR"
.IX Header "AUTHOR"
Randy J. Ray <rjray@blackperl.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module and the code within are copyright (c) 2006 by Randy J. Ray and
released under the terms of the Artistic License
(http://www.opensource.org/licenses/artistic\-license.php). This
code may be redistributed under either the Artistic License or the \s-1GNU\s0
Lesser General Public License (\s-1LGPL\s0) version 2.1
(http://www.opensource.org/licenses/lgpl\-license.php).