/ 
UWO-Directory-Student-0.02
/ UWO::Directory::Student

NAME

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

VERSION

Version 0.02 ($Id: Student.pm 10 2007-10-08 13:03:04Z frequency $)

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/)

UWO::Directory is a module with a similar interface capable of aggregating search results from multiple directories.

Example code:

use UWO::Directory::Student;

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

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

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

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

if (defined $reverse) {
  print "Found: $reverse\n";
}

COMPATIBILITY

Though this module was only tested under Perl 5.8.8 on Linux, it should be compatible with any version of Perl that supports its prerequisite modules.

If you encounter any problems on a different version or architecture, please contact the maintainer.

METHODS

Class and Constructor Methods

UWO::Directory::Student->new
UWO::Directory::Student->new(\%params)

Creates a UWO::Directory::Student search object, which uses a given web page and server. Being that this module is developed to target UWO's in-house system, the defaults should suffice.

The parameters available are:

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

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

Object Methods

$dir->lookup(\%params)

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

The module uses the following procedure to locate users:

  1. If an e-mail address is provided:

    1. The address is deconstructed into a first initial and the portion of the last name. (According to the regular expression ^(\w)([^\d]+)([\d]*)$)

    2. The partial name is looked up in the directory.

    3. The resulting records are tested against the e-mail address. If the e-mail address matches a given record, the UWO::Student object is returned. The lookup returns a false value (0) upon failure.

  2. If first and/or last names are provided:

    1. The name is searched using the normal interface (using the query last_name,first_name) and the results are returned as an array reference. If there are no results, the method returns a false value (0).

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 UWO::Student objects.

In the case of an e-mail reverse lookup, a single UWO::Student object will be returned if a match is found. Otherwise, the result will be undef.

UNSUPPORTED API

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.

$dir->_query($query)
$dir->_query($query, $ua)

This method performs an HTTP lookup using LWP::UserAgent and returns a SCALAR reference to the returned page content. A LWP::UserAgent object may optionally be passed, which is particularly useful if a proxy is required to access the Internet.

Please note that if a LWP::UserAgent is passed, the User-Agent string will not be modified. In normal operation, this module reports its user agent as __PACKAGE__ . '/' . $VERSION.

$dir->_parse($response)
UWO::Directory::Student->_parse($response)
UWO::Directory::Student::_parse($response)

This method processes the HTML content retrieved by _query method and returns an ARRAY reference containing HASH references to the result set. Additionally, _parse can be treated as either a function or class method.

CONTRIBUTORS

MAINTAINER

Jonathan Yu <frequency@cpan.org>

ACKNOWLEDGEMENTS

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc UWO::Directory::Student

You can also look for information at:

FEEDBACK

Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer noted above.

If you have a bug report or feature request, please file them on the CPAN Request Tracker at http://rt.cpan.org

SEE ALSO

UWO::Student, UWO::Directory, http://uwo.ca/cgi-bin/dsgw/whois2html2, http://uwo.ca/westerndir/index-student.html

CAVEATS

KNOWN BUGS

There are no known bugs as of this release.

LIMITATIONS

LICENSE AND COPYRIGHT

Copyright (C) 2007 by Jonathan Yu

Redistribution and use in source/binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

DISCLAIMER OF WARRANTY

This software is provided by the copyright holders and contributors "AS IS" and ANY EXPRESS OR IMPLIED WARRANTIES, including, but not limited to, the IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.