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

FreeBSD Manual Pages

  
 
  

home | help
WebService::ISBNDB::APUseruContributed PerWebService::ISBNDB::API::Subjects(3)

NAME
       WebService::ISBNDB::API::Subjects - Data	class for subject information

SYNOPSIS
	   use WebService::ISBNDB::API::Subjects;

	   $net_prog = WebService::ISBNDB::API::Subjects->
			   find('internet_programming');

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

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($SUBJECT_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 subject'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::Subjects->
		   new({ id => "internet_programming" });

	       $book = WebService::ISBNDB::API::Subjects->new('internet_programming');

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

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

       name
	   The name of the subject.

       book_count
	   The number of books listed under this subject.

       marc_field
       marc_indicator_1
       marc_indicator_2
	   These three attributes make up the subject's	MARC (MAchine-Readable
	   Cataloging) information.

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

       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_book_count
	   Returns the number of books under this subject.

       set_book_count($COUNT)
	   Set the number of books under this subject.

       get_marc_field
	   Get the MARC	field value.

       set_marc_field($MARC)
	   Set the MARC	field value.

       get_marc_indicator_1
	   Get the value for the first MARC indicator.

       set_marc_indicator_1($MARC_1)
	   Set the value for the first MARC indicator.

       get_marc_indicator_2
	   Get the value for the second	MARC indicator.

       set_marc_indicator_2($MARC_1)
	   Set the value for the second	MARC indicator.

       get_categories
	   Return a list-reference of the categories this aubject 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.

   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|subject_id
	   The value should be a text string. The search returns the author
	   whose ID in the system matches the value.

       category|category_id
	   You can search for subjects in a given category. If the search-key
	   is "category", the value may	be either the ID or a category object.
	   If it is an object, the ID is derived from it. If the search-key is
	   "category_id", the value must be the	ID itself.

       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 subject, "perl_computer_program_language":

	   $perl = WebService::ISBNDB::API::Subjects->
		       find('perl_computer_program_language');

       Find all	subject	with "perl" in their name:

	   $allperl = WebService::ISBNDB::API::Subjects->
			  search({ name	=> 'perl' });

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

home | help