Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WebService::ISBNDB::APUseroContributed Perl DWebService::ISBNDB::API::Books(3)

NAME
       WebService::ISBNDB::API::Books -	Data class for book information

SYNOPSIS
	   use WebService::ISBNDB::API::Books;

	   my $book = WebService::ISBNDB::API->new({ api_key =>	$key,
						     isbn => '0596002068' });

DESCRIPTION
       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.

METHODS
       The following methods are specific to this class, or overridden from
       the super-class.

   Constructor
       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.

   Accessors
       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.

   Utility Methods
       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.

SEARCHING
       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.

EXAMPLES
       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');

CAVEATS
       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.

SEE ALSO
       WebService::ISBNDB::API,	WebService::ISBNDB::API::Authors,
       WebService::ISBNDB::API::Publishers, WebService::ISBNDB::API::Subjects,
       Business::ISBN, Date::Parse

AUTHOR
       Randy J.	Ray <rjray@blackperl.com>

LICENSE
       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).

perl v5.32.0			  2020-08-25 WebService::ISBNDB::API::Books(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEARCHING | EXAMPLES | CAVEATS | SEE ALSO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=WebService::ISBNDB::API::Books&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help