/ 
MyLibrary-3.0.3
River stage zero No dependents
/ MyLibrary::Librarian

NAME

MyLibrary::Librarian

SYNOPSIS

# use the module
use MyLibrary::Librarian;

# create a new librarian
my $librarian = MyLibrary::Librarian->new();

# give the librarian characteristics
$librarian->name('Fred Kilgour');
$librarian->email('kilgour@oclc.org');
$librarian->telephone('1 (800) 555-1212');
$librarian->url('http://oclc.org/~kilgour/');

# associate (classify) the librarian with term ids
$librarian->term_ids(new => [3, 614, 601]);

# disassociate certain term ids from this librarian
$librarian->term_ids(del => [@del_term_ids]);

# retrieve list of term ids with sort parameter
my @term_ids = $librarian->term_ids(sort => 'name');

# save the librarian to the database; create a new record
$librarian->commit();

# get the id of the current librarian object
$id = $librarian->id();

# get a librarian based on an id
my $librarian = MyLibrary::Librarian->new(id => $id);

# display information about the librarian
print '       ID: ', $librarian->id(), "\n";
print '     Name: ', $librarian->name(), "\n";
print '    Email: ', $librarian->email(), "\n";
print 'Telephone: ', $librarian->telephone(), "\n";
print '      URL: ', $librarian->url(), "\n";

# retrieve complete, sorted list of librarian objects
my @librarians = MyLibrary::Librarian->get_librarians();

# process each librarian
foreach my $l (@librarians) {

	# print each librarian's name and email address
	print $l->name(), ' <', $l->email(), "> \n";

}

DESCRIPTION

Use this module to get and set the characteristics of librarians to a MyLibrary database. Characteristics currently include: ID (primary database key), name, email address, telephone number, home page URL, and a set of integers (primary database keys) denoting what terms the librarian has been classified under.

METHODS

This section describes the methods available in the package.

new()

Use this method to create a librarian object. Called with no options, this method creates an empty object. Called with an id option, this method uses the id as a database key and fills the librarian object with data from the underlying database.

	# create a new librarian object
	my $librarian = MyLibrary::Librarian->new();
  
	# create a librarian object based on a previously existing ID
	my $librarian = MyLibrary::Librarian->new(id => 3);

id()

This method returns an integer representing the database key of the currently created librarian object.

# get id of current librarian object
my $id = $librarian->id();

You cannot set the id attribute.

name()

This method gets and sets the name from the librarian from the current librarian object:

# get the name of the current librarian object
my $name = $librarian->name();

# set the current librarian object's name
$librarian->name('Melvile Dewey');

telephone()

Use this method to get and set the telephone number of the current librarian object:

# get the telephone number
my $phone = $librarian->telephone();

# set the current librarian object's telephone number
$librarian->telephone('1 (800) 555-1212');

email()

Like the telephone and name methods, use this method to get and set the librarian object's email attribute:

# get the email address
my $email_address = $librarian->email();

# set the current librarian object's email address
$librarian->email('info@library.org');

url()

Set or get the URL attribute of the librarian object using this method:

# get the URL attribute
my $home_page = $librarian->url();

# set the URL
$librarian->url('http://dewey.library.nd.edu/');

term_ids()

This method gets and sets the term ids with which this libraian object is associated. Given no input, it returns a list of integers or undef if no term associations exist. Any input given is expected to be a list of integers. Related terms can be added or deleted given the correct input parameter. The returned list of term ids can be sorted by name using the sort parameter.

# set the term id's
$librarian->term_ids(new => [33, 24, 83]);

# get the term id's of the current librarian object
my @ids = $librarian->term_ids();

# get the term id's of the current librarian object sorted by name
my @ids = $librarian->term_ids(sort => 'name');

# require the Term package
use MyLibrary::Term;

# process each id
foreach my $i (@ids) {

	# create a term object
	my $term->MyLibrary::Term->new(id => $i);
	
	# print the term associated with the librarian object
	print $librarian->name, ' has been classified with the term: ', $term->name, ".\n";

}

# remove term associations
$librarian->term_ids(del => [@removed_term_ids]);

commit()

Use this method to save the librarian object's attributes to the underlying database. If the object's data has never been saved before, then this method will create a new record in the database. If you used the new and passed it an id option, then this method will update the underlying database.

This method will return true upon success.

# save the current librarian object to the underlying database
$librarian->commit();

delete()

This method simply deletes the current librarian object from the underlying database.

# delete (drop) this librarian from the database
$librarian->delete();

get_librarians()

Use this method to get all the librarians from the underlying database sorted by their name. This method returns an array of objects enabling you to loop through each object in the array and subsequent characteristics of each object;

# get all librarians
my @librarians = MyLibrary::Librarian->get_librarians();

# process each librarian
foreach my $l (@librarians) {

	# print the name
	print $l->name, "\n";

}

ACKNOWLEDGEMENTS

I would like to thank the following people for providing input on how this package can be improved: Brian Cassidy and Ben Ostrowsky.

AUTHORS

Eric Lease Morgan <emorgan@nd.edu> Robert Fox <rfox2@nd.edu>

HISTORY

September 29, 2003 - first public release. April, 2004 - many modifications.