 |
|
| |
WebService::ISBNDB::API::Books(3) |
User Contributed Perl Documentation |
WebService::ISBNDB::API::Books(3) |
WebService::ISBNDB::API::Books - Data class for book information
use WebService::ISBNDB::API::Books;
my $book = WebService::ISBNDB::API->new({ api_key => $key,
isbn => '0596002068' });
This class represents book data from isbndb.com. It is a sub-class of
WebService::ISBNDB::API (see WebService::ISBNDB::API), and inherits all
the attributes and methods from that class.
The following methods are specific to this class, or overridden from the
super-class.
The constructor for this class may take a single scalar argument in lieu of a
hash reference:
- 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
Class::Std mechanics. If the value is a scalar, it is tested to see
if it is a valid ISBN (using the Business::ISBN module). If it is,
it is used as a search key to find the corresponding book. If it is not a
valid ISBN, 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.
If the argument is the hash-reference form, then a new object
is always constructed; to perform searches see the search() and
find() methods. Thus, the following two lines are in fact
different:
$book = WebService::ISBNDB::API::Books->new({ isbn => '0596002068' });
$book = WebService::ISBNDB::API::Books->new('0596002068');
The first creates a new object that has only the
"isbn" attribute set. The second
returns a new object that represents the book with ISBN
0596002068, with all data present.
The class also defines:
- copy($TARGET)
- Copies the target object into the calling object. All attributes
(including the ID) are copied. This method is marked
"CUMULATIVE" (see Class::Std), and any sub-class of this class
should provide their own copy() and also mark it
"CUMULATIVE", to ensure that all attributes at all levels are
copied.
See the copy() method in WebService::ISBNDB::API.
The following attributes are used to maintain the content of a book object:
- id
- The unique ID within the isbndb.com system for this book.
- isbn
- The ISBN (International Standard Book Number) for the book (without
hyphens).
- title
- The title of the book.
- longtitle
- The full title of the book, including any sub-title.
- authors
- An array (stored as a reference) of the
WebService::ISBNDB::API::Authors objects that refer to the authors
of the book. These are not actually loaded from the service until they are
first fetched.
- 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.
- publisher
- The WebService::ISBNDB::API::Publisher object that refers to the
book's publisher. This is not loaded until the first request to fetch it
is made.
- 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.
- subjects
- An array (stored as a reference) of the
WebService::ISBNDB::API::Subjects objects that refer to the
subjects this book is associated with. As with the authors, the actual
objects are not loaded until requested.
- dewey_decimal
- The book's Dewey Decimal classification number.
- dewey_decimal_normalized
- The normalized form of the Dewey Decimal number for the book.
- lcc_number
- The Library of Congress Classification number for the book.
- language
- The language the book is printed in. The form and content of this field
may not be standardized.
- physical_description_text
- Text describing the physical dimensions of the book.
- edition_info
- Any additional information on the particular edition of the book.
- change_time
- A string representation of the time when this record was last changed. The
string is in ISO 8601 form, with no explicit time-zone specified. UTC time
is assumed in internal manipulations.
- change_time_sec
- If the Date::Parse module is available, this attribute will hold
the value from "change_time", converted
to seconds since the UNIX Epoch. Otherwise, this attribute will always be
"undef".
- price_time
- A string representation of the time when the price information for this
record was last updated. As above, the string is in ISO 8601 format with
no time-zone, and it assumed to be UTC internally.
- price_time_sec
- As with "change_time_sec", only for the
price-change value. Requires the availability of Date::Parse, or
else the value will always be
"undef".
- summary
- The content of the "<Summary>"
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.
- notes
- Another free-form text field, similar to
"summary", but less used.
- urlstext
- Fairly free-form text, used to specify URLs related to the book.
- awardstext
- More free-form text, this to specify any awards the book has
received.
- 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
"undef"):
- store_isbn
- The ISBN for the book at the store, if different from the book's regular
ISBN. Not set if the two are the same.
- 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.
- store_url
- URL for the book. This may be a relative URL, in which case it is relative
to the store's website. If it is an absolute URL (complete URL), it is a
redirector URL originating at isbndb.com. The URL is used for
purchasing the book, and the redirect URLs allow isbndb.com to
collect small commissions off of sales they facilitate, which in turn
helps to keep their service available and free.
- store_id
- Unique identifier for the store.
- currency_code
- The code for the currency the price is expressed in.
- is_in_stock
- A boolean value indicating whether the book is in stock.
- is_historic
- A boolean value indicating whether the price this record describes is
considered "historic". Any price older than 24 hours should
generally be considered historic, even if this value is true.
- is_new
- A boolean value indicating whether the book offered is new or used.
- currency_rate
- Currency rate against the US dollar, only set if the
"currency_code" is not
"USD".
- price
- The price of the book (expressed in the currency indicated by
"currency_code", above).
- check_time
- String representation of the time when this price was last checked. As
with the other time-oriented values, this is in ISO 8601 format with no
explicit time-zone.
- check_time_sec
- If the Date::Parse package is available, this is the value of
"check_time" expressed in seconds,
suitable for use with the Perl localtime keyword.
- marc
- If MARC 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
"undef"):
- library_name
- Name of the library this record is taken from.
- last_update
- ISO 8601 string representing the last time the record was updated from the
library.
- last_update_sec
- If Date::Parse is available, this will be the
"last_update" attribute converted to
seconds, measured from the UNIX epoch.
- marc_url
- The URL to the MARC record on the library's site.
The following accessors are provided to manage these
attributes:
- get_id
- Return the book ID.
- set_id($ID)
- Sets the book ID. This method is restricted to this class, and cannot be
called outside of it. In general, you shouldn't need to set the ID after
the object is created, since isbndb.com is a read-only source.
- get_isbn
- Return the ISBN of the book. In general, the ISBN has had any hyphens
removed.
- set_isbn($ISBN)
- Set the book ISBN. The value is tested with Business::ISBN to
ensure that the value is a valid ISBN.
- get_title
- Return the common title of the book.
- set_title($TITLE)
- Set the title of the book.
- get_longtitle
- Return the long title of the book. This will include subtitles, for
example.
- set_longtitle($LONGTITLE)
- Set the long title of the book.
- get_authors
- Get the list of author objects (instances of
WebService::ISBNDB::API::Authors or a sub-class) for the book. The
objects are not fetched from the source until the first call to this
method.
- 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 get_authors() will convert them into objects. The
strings must be the author ID values as returned by the service.
- get_authors_text
- Return the text-representation of the authors, as returned by the
service.
- set_authors_text($TEXT)
- Set the text-representation of the authors.
- get_publisher
- Return the publisher object (instance of
WebService::ISBNDB::API::Publishers or a sub-class) for this book.
The object is not loaded from the source until the first request to this
method.
- set_publisher($PUBLISHER)
- Set the publisher for this book. The value should be either a publisher
object or a string containing the publisher ID. If the ID is set as the
value, the next call to get_publisher() will resolve it into an
object.
- get_subjects
- Get the list of subject objects (instances of
WebService::ISBNDB::API::Subjects or a sub-class) for the book. The
objects are not fetched from the source until the first call to this
method.
- 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 ID values as returned
by the source. If the content is the ID values, then the next call to
get_subjects() will resolve them to objects.
- get_dewey_decimal
- Get the Dewey Decimal number.
- set_dewey_decimal($DEWEY)
- Set the Dewey Decimal number.
- get_dewey_decimal_normalized
- Get the normalized Dewey Decimal number.
- set_dewey_decimal_normalized($DEWEY_NORM)
- Set the normalized Dewey Decimal number.
- get_lcc_number
- Get the Library of Congress Classification number.
- set_lcc_number($LCC)
- Set the Library of Congress Classification number.
- get_language
- Get the language code for the book's text.
- set_language($LANG)
- Set the language code.
- get_physical_description_text
- Get the book's physical description text.
- set_physical_description_text($PHYS)
- Set the book's physical description text.
- get_edition_info
- Get any information on the specific edition of the book.
- set_edition_info($INFO)
- Set the edition information for the book.
- get_change_time
- Get the change-time of the book record (an ISO 8601 string, no explicit
time-zone, presumed to be UTC).
- set_change_time($TIME)
- Sets the change-time of the book record. If Parse::Date is
available, and the value passed in $TIME is
parsable, then the "change_time_sec"
attribute will also be updated with the equivalent value.
- get_change_time_sec
- Get the change-time as a number of seconds since the Epoch (as defined in
UNIX terms, see Parse::Date). This attribute is only set if the
Date::Parse module is available.
- set_change_time_sec($TIME)
- Set the seconds-since-Epoch representation of the change-time to the new
value. This will also update the
"change_time" attribute, setting it to
an ISO 8601-style string that is the textual representation of
$TIME.
- get_price_time
- set_price_time($TIME)
- get_price_time_sec
- set_price_time_sec($TIME)
- 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
"price_time_sec" attribute
(Parse::Date is required for it to be set when data is read from
the source).
- 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.
- set_summary($SUMMARY)
- Set the summary text to the new content in
$SUMMARY.
- get_notes
- Get the notes for the book. The notes are also free-form text, and are
trimmed in the same fashion as
"summary".
- set_notes($NOTES)
- Set the notes text for the book.
- get_urlstext
- Get the "urlstext" attribute. This text
should provide URLs related to the book, when present.
- set_urlstext($URLS)
- Set the "urlstext" attribute to the new
value.
- get_awardstext
- Get the awards-text data for the book. If present, this should refer to
any awards the book has won.
- set_awardstext($AWARDS)
- Set the awards-text to the new data given.
- 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).
- 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.
- get_marc
- Get the MARC data for the book. MARC data comes in the form of a
list-reference of hash-references (see above for description of the
keys).
- set_marc($MARCLIST)
- Set the MARC 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.
Besides the constructor and the accessors, the following methods are provided
for utility:
- find($ARG|$ARGS)
- This is a specialization of find() 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
ISBN, and if so the search is made against the ISBN with that value. If
the scalar value is not a valid ISBN, the search is made against the title
instead. If the value is a hash reference, it is passed to the super-class
method.
- normalize_args($ARGS)
- This method maps the user-visible arguments as defined for find()
and search() 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 $ARGS in
place, and also returns $ARGS as the value from
the method.
See the next section for an explanation of the available keys for
searches.
Both find() and search() allow the user to look up data in the
isbndb.com database. The allowable search fields are limited to a
certain set, however. When either of find() or search() 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
find() can accept a single string, which has special meaning as
detailed earlier).
Searches in the text fields are done in a case-insensitive
manner.
The available search keys are:
- title
- The value should be a text string. The search returns books whose title
matches the string.
- isbn
- The value should be a text string. The search returns the book whose ISBN
matches the string. The string is not checked for validity, so a bad ISBN
will simply not return any records.
- author
- The value for this key should be either an object of the
WebService::ISBNDB::API::Authors class (or sub-class thereof), or a
text string. If the value is an object, the search is done against the
specific author ID. If the value is a string, the search is done using the
"combined" search key, and may return results unrelated to the
intended query.
- publisher
- The value for this key may be an object of the
WebService::ISBNDB::API::Publishers class (or sub-class thereof) or
a text string. If it is an object, the ID is used in a specific search. If
the value is a string, it is used with the "combined"
search-key, and may return unexpected results.
- subject
- The value for this key is expected to be either an object (of the
WebService::ISBNDB::API::Subjects class or sub-class thereof) or a
literal subject ID as a string. The subject cannot be searched for using
the "combined" key.
- combined
- The value should be a text string, and is searched against a combined
field that includes titles, authors and publisher names.
- 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.
- dewey_decimal
- The value should be a Dewey Decimal Classification number, and is used
directly in the search.
- lcc_number
- The value should be a Library of Congress Classification number, and is
used directly in the search.
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.
Search for all books with "perl" in the title:
$perlbooks = WebService::ISBNDB::API::Books->
search({ title => "perl" });
Search for all books by Edgar Allan Poe:
$poebooks = WebService::ISBNDB::API::Books->
search({ author => 'edgar allan poe' });
Find the record for "Progamming Web Services With
Perl":
$pwswp = WebService::ISBNDB::API::Books->find('0596002068');
The data returned by this class is only as accurate as the data retrieved from
isbndb.com.
The list of results from calling search() is currently
limited to 10 items. This limit will be removed in an upcoming release, when
iterators are implemented.
WebService::ISBNDB::API, WebService::ISBNDB::API::Authors,
WebService::ISBNDB::API::Publishers, WebService::ISBNDB::API::Subjects,
Business::ISBN, Date::Parse
Randy J. Ray <rjray@blackperl.com>
This module and the code within are released under the terms of the Artistic
License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php).
This code may be redistributed under either the Artistic License or the GNU
Lesser General Public License (LGPL) version 2.1
(http://www.opensource.org/licenses/lgpl-license.php).
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|