Eric Lease Morgan > MyLibrary > MyLibrary::Librarian

Download:
MyLibrary-3.0.4.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

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.

syntax highlighting: