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

FreeBSD Manual Pages

  
 
  

home | help
WebService::ISBNDB::APUseruContributed PerlWebService::ISBNDB::API::Authors(3)

NAME
       WebService::ISBNDB::API::Authors	- Data class for author	information

SYNOPSIS
	   use WebService::ISBNDB::API::Authors;

	   $me = WebService::ISBNDB::API::Authors->find('ray_randy_j');

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

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($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
       The following attributes	are used to maintain the content of an author
       object:

       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
       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 authors whose
	   name	matches	the string.

       id|person_id
	   The value should be a text string. The search returns the author
	   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 author of	this module:

	   $me = WebService::ISBNDB::API::Authors->find('ray_randy_j');

       Find all	authors	with "Clinton" in their	name:

	   $clintons = WebService::ISBNDB::API::Authors->
			   search({ name => 'clinton' });

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,
       WebService::ISBNDB::API::Subjects

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

home | help