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.