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

FreeBSD Manual Pages

  
 
  

home | help
WebService::ISBNDB::APUseruContributed PWebService::ISBNDB::API::Publishers(3)

NAME
       WebService::ISBNDB::API::Publishers - Data class	for publisher
       information

SYNOPSIS
	   use WebService::ISBNDB::API::Publishers;

	   $oreilly = WebService::ISBNDB::API::Publishers->
			  search({ name	=> 'oreilly' });

DESCRIPTION
       The WebService::ISBNDB::API::Publishers class extends the
       WebService::ISBNDB::API class to	add attributes specific	to the data
       isbndb.com provides on publishers.

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($PUBLISHER_ID|$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 assumed to be
	   the publisher's ID within the system, and is	looked up by that.

	   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::Publishers->new({ id =>	"oreilly" });

	       $book = WebService::ISBNDB::API::Publishers->new('oreilly');

	   The first creates a new object that has only	the "id" attribute
	   set.	The second returns a new object	that represents	the publisher
	   with	ID "oreilly", 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
       publisher object:

       id  The unique ID within	the isbndb.com system for this publisher.

       name
	   The name of the publisher.

       location
	   The publisher's location.

       categories
	   A list of category objects for the categories in which this
	   publisher has books.

       The following accessors are provided to manage these attributes:

       get_id
	   Return the publisher	ID.

       set_id($ID)
	   Sets	the publisher 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_name
	   Return the publisher's name.

       set_name($NAME)
	   Set the name	to the value in	$NAME.

       get_location
	   Get the publisher's location.

       set_locataion($LOCATION)
	   Set the location to the value in $LOCATION.

       get_categories
	   Return a list-reference of the categories for the publisher.	Each
	   element of the list will be an instance of
	   WebService::ISBNDB::API::Categories.

       set_categories($CATEGORIES)
	   Set the categories to the list-reference given in $CATEGORIES. When
	   the publisher object	is first created from the XML data, this list
	   is populated	with the IDs of	the categories.	They are not converted
	   to objects until requested (via get_categories()) by	the user.

   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 searched for as if it
	   were	the ID.	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
	   categories, location, 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:

       name
	   The value should be a text string. The search returns publishers
	   whose name matches the string.

       id|publisher_id
	   The value should be a text string. The search returns the publisher
	   whose ID in the system matches the value.

       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
       Get the record for the ID "oreilly":

	   $oreilly = WebService::ISBNDB::API::Publishers->find('oreilly');

       Find all	publisher records containing "oreilly":

	   $ora	= WebService::ISBNDB::API::Publishers->
		      search({ name => 'oreilly' });

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::Categories

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-0WebService::ISBNDB::API::Publishers(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::Publishers&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help