NAME

WebService::UWO::Directory::Student - Perform lookups using the University of Western Ontario's student directory

VERSION

Version 0.01

SYNOPSIS

This module provides a Perl interface to the public directory search system which lists current students, staff and faculty at the University of Western Ontario. (http://uwo.ca/westerndir/index.html)

This module is only able to access partial student records since students must give consent for their contact information to be published on the web. (http://uwo.ca/westerndir/index-student.html).

For a more complete module able to search staff and faculty records as well, please consider using WebService::UWO::Directory.

Example code:

use WebService::UWO::Directory::Student;

# Create Perl interface to API
my $dir = WebService::UWO::Directory::Student->new;

# Look up a student by name
my $results = $dir->lookup({
                            first => 'John',
                            last  => 'S'
                           });

# Go through results
foreach my $rec (@{$results}) {
  print 'email: ' . $rec->{email} . "\n";
}

# Reverse a lookup (use e-mail to find record)
my $reverse = $dir->lookup({
                            email => 'jsmith@uwo.ca'
                           });

FUNCTIONS

new(\%params)

Creates a WebService::UWO::Directory::Student search object, which uses a given web page and server. Being that this is a specialized module, the default parameters should suffice.

The parameters available are: my $dir = WebService::UWO::Directory::Student->new({ url => 'http://uwo.ca/cgi-bin/dsgw/whois2html2', server => 'localhost', });

Which instantiates a WebService::UWO::Directory::Student instance using url as the frontend and server as the "black-box" backend.

lookup(\%params)

Uses a WebService::UWO::Directory::Student search object to locate a given person based on either their name (first and/or last) or their address (email).

Example code: # Look up "John S" in the student directory my $results = $dir->lookup({ first => 'John', last => 'S' });

# Look up jsmith@uwo.ca
my $reverse = $dir->lookup({
                            email => 'jsmith@uwo.ca'
                           });

This method is not guaranteed to return results. If no results are found, the return code will be 0.

In the case of a name-based lookup, the results will be returned as a reference pointing to an ARRAY containing HASH references. Each of these hashes represents a single user entry.

In the case of an e-mail reverse lookup, a single HASH reference will be returned.

lookup_reverse($email)

This method is a wrapper around the standard "lookup" method.

Example code: # Look up jsmith@uwo.ca my $reverse = $dir->lookup_reverse('jsmith@uwo.ca');

is equivalent to

# Look up jsmith@uwo.ca
my $reverse = $dir->lookup({
                            email => 'jsmith@uwo.ca'
                           });

This method is not guaranteed to return results. If no results are found, the return code will be 0.

WebService::UWO::Directory::Student provides access to some internal methods used to retrieve and process raw data from the directory server. Its behaviour is subject to change and may be finalized later as the need arises.

_query($query)

This method performs an HTTP lookup using LWP::UserAgent and returns a SCALAR reference to the returned page content.

_parse($response)

This method processes the HTML content retrieved by _query method and returns an ARRAY reference containing HASH references to the result set.

cpanm WebService::UWO::Directory::Student

perl -MCPAN -e shell
install WebService::UWO::Directory::Student