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

FreeBSD Manual Pages

  
 
  

home | help
WebService::ISBNDB::APUseraContributed PWebService::ISBNDB::API::Categories(3)

NAME
       WebService::ISBNDB::API::Categories - Data class	for category
       information

SYNOPSIS
	   use WebService::ISBNDB::API::Categories;

	   $ray_authors	= WebService::ISBNDB::API::Categories->
			      search({ name => 'alphabetically.authors.r.a.y' });

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

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($CATEGORY_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 category'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::Categories->
			   new({ id => "arts.music" });

	       $book = WebService::ISBNDB::API::Categories->new('arts.music');

	   The first creates a new object that has only	the "id" attribute
	   set.	The second returns a new object	that represents	the category
	   named "arts.music", 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 category
       object:

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

       name
	   The name of the category.

       parent
	   The parent category,	if there is one, that this category falls
	   under.

       summary
	   A brief summary of the category, if available.

       depth
	   The depth of	the category in	the hierarchy. Top-level categories
	   are at a depth of 0.	"arts.opera.regions.france", for example, is
	   at a	depth of 3.

       element_count
	   Not documented in the isbndb.com API; appears be the	number of
	   books in the	category and all of its	sub-categories.

       sub_categories
	   A list of category objects for the sub-categories that fall below
	   this	one.

       The following accessors are provided to manage these attributes:

       get_id
	   Return the category ID.

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

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

       get_parent
	   Return the WebService::ISBNDB::API::Categories object that
	   represents this category's parent. If this is a top-level category,
	   then	the method returns "undef".

       set_parent($PARENT)
	   Set the category's parent to	the value in $PARENT. This may be an
	   object, or it may be	a category ID. If the value is not an object,
	   the next call to get_parent() will attempt to convert it to one by
	   calling the service.

       get_summary
	   Get the category summary.

       set_summary($SUMMARY)
	   Set the category summary to $SUMMARY.

       get_depth
	   Get the category depth.

       set_depth($DEPTH)
	   Set the category depth to $DEPTH.

       get_element_count
	   Get the count of elements.

       set_element_count($COUNT)
	   Set the element count.

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

       set_sub_categories($CATEGORIES)
	   Set the sub-categories to the list-reference	given in $CATEGORIES.
	   When	the category object is first created from the XML data,	this
	   list	is populated with the IDs of the sub-categories. They are not
	   converted to	objects	until requested	(via get_sub_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 as though 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 categories
	   whose name matches the string.

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

       parent|parent_id
	   You can also	search by the parent. The search-key "parent" will
	   accept either a string (taken as the	ID) or a Categories object, in
	   which case the ID is	derived	from it. If the	key used is
	   "parent_id",	the value is assumed to	be the ID.

       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 "science":

	   $science = WebService::ISBNDB::API::Categories->find('science');

       Find all	category records that are sub-categories of "science":

	   $science2 = WebService::ISBNDB::API::Categories->
			   search({ parent => $science });

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

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::Categories(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::Categories&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help