Constructor

new($PERSON_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 author'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::Authors->new({ id => "ray_randy_j" });

    $book = WebService::ISBNDB::API::Authors->new('ray_randy_j');
    

The first creates a new object that has only the "id" attribute set. The second returns a new object that represents the given author, 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

id

The unique ID within the isbndb.com system for this author.

name

The full name of the author.

first_name

The author's first name only.

last_name

The author's last name only.

dates

If the author is deceased, this will have the years of birth and death, separated by a hyphen, e.g., "1900-1988".

has_books

A boolean value indicating whether the author has books in the database.

categories

A list of category objects for the categories the author is listed in.

subjects

A list of subject objects for the subjects the author's books are listed under.

The instances of Subjects objects stored in this attribute differ from those instantiated from the service normally. The "book_count" attribute in these objects indicates the number of books belonging to this author that fall into this subject, not the total number of books in the database that do.

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 author's name. This is the full name, as would appear in the "author_text" field of a WebService::ISBNDB::API::Books object.

set_name($NAME)

Set the name to the value in $NAME.

get_first_name

Returns the author's first name only.

set_first_name($NAME)

Set the authors's first name. Note that "first_name" and "last_name" combined may not always be the same value as "name".

get_last_name

Get the author's last name only.

set_last_name($NAME)

Set the authors's last name. Note that "first_name" and "last_name" combined may not always be the same value as "name".

get_dates

If the author is deceased, this returns the years of birth and death.

set_dates($DATES)

Set birth-death date range.

get_has_books

Get the boolean indicating whether this author has books in the service database.

set_has_books($BOOL)

Set the boolean flag that indicates whether this author has any books in the service's database.

get_categories

Return a list-reference of the categories this author is listed in. 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 author 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.

get_subjects

Return a list-reference of the subjects this author has books in. Each element of the list will be an instance of WebService::ISBNDB::API::Subjects. Note that these subject objects differ slightly from having instantiated the same subjects directly; their "book_count" attributes indicate the number of books specific to this author that fall under the subject, not the total number of books from the database as a whole.

set_subjects($SUBJECTS)

Set the list of subjects to the contents of the list-reference passed in $SUBJECTS. When the author object is first created from the XML data, this list is populated with the IDs of the subjects. They are not converted to objects until requested (via get_subjects()) by the user.

Utility Methods

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.