/ 
UWO-Student
/ UWO::Student

NAME

UWO::Student - Provides Perl object representation of a University of Western Ontario student.

SYNOPSIS

This module provides a Perl object interface representing students of the University of Western Ontario. It performs basic input validation on given data and will throw an exception for suspicious information.

Additional validation is recommended since, at present, the module does not perform "deep" verification -- it does not use regular expressions and cannot "untaint" data, if you are running Perl under taintmode (Perl flag -T).

You will probably not need to use this module directly, but its accessors may be useful since collections of these objects are returned from the UWO::* class of modules.

Example code:

use UWO::Student;

# Create Perl interface to a student record
my $stu = UWO::Student->new({
  given_name => 'John',
  last_name  => 'Doe',
});

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 Email::Handle and Carp. If you encounter any problems on a different version or architecture, please contact the maintainer.

METHODS

new(\%params)

Creates a UWO::Student object, which either stores given parameters or throws an exception if it fails the simplistic validation rules. (See the email and number methods for further details.)

The parameters available are:

my $stu = UWO::Student->new({
  given_name  => 'John',
  last_name   => 'Doe',
  faculty     => 'Faculty of Arts and Humanities',
  email       => 'jdoe@uwo.ca',
  number      => 327323372,
});

Which instantiates a UWO::Student instance representing the data as Perl datastructures.

email([$address])

Without parameters, this method returns an Email::Handle object (if available.) Otherwise, it returns a SCALAR containing the e-mail address associated with the current UWO::Student object. If you wish to force the module to always return an Email::Handle object, make sure to add use Email::Handle to your code.

Example code:

# Retrieve the e-mail (as a SCALAR). This works even while Email::Handle is
# in use since the stringify operation is overloaded by that module.
print $stu->email;

# Retrieve the e-mail username (requires Email::Handle)
print $stu->email->user;

If $address is provided, it will store the given parameter as the Student's e-mail address.

Example code:

# Set the student's e-mail address
$stu->email('jdoe@uwo.ca');

This method is not guaranteed to return results. The e-mail address could very well be undef if none has been specified yet and it is not guaranteed to even "look" valid by any account. It does parsing, but not validation.

number([$number])

If $number is given, it will store the given integer as the Student's unique university identification number. Student numbers MUST consist of numbers 0 through 9 (of length 1-9 digits). Since this is just a SCALAR, you may also pass an underscore-delimited integer if you wish to improve readability:

Example code:

# Set the student's unique identification number
$stu->number(327_323_372);
# Is equivalent to
$stu->number(327323372);

Without parameters, this method simply returns the stored student number (or undef if it is unavailable).

Example code:

# Retrieve the student number
print $stu->number;

This method is not guaranteed to return results. The student number could be undef if none has been specified yet.

name()

This method intelligently concatenates the given and last names of the student.

Example code:

# Retrieve the student's full name
print $stu->name;

This method is not guaranteed to return results. The name may be null.

given_name([$name]) =head2 last_name([$name]) =head2 faculty([$name])

These mutator methods simply set the appropriate fields if parameters are provided. Currently, it does not perform any input validation at all, although this behaviour may change in the future. Namely, the module may begin to validate faculty names (as they appear in the database), since they are of a limited size and do not change frequently.

Example code:

# Change the student's given name
print $stu->given_name('Joe');

# Retrieve the student's last name
print $stu->last_name('Blow');

# Retrieve the faculty the student is registered in
print $stu->faculty('Faculty of Social Science');

Without parameters, these methods act as accessors and simply return SCALARs containing the data.

Example code:

# Retrieve the student's given name
print $stu->given_name;

# Retrieve the student's last name
print $stu->last_name;

# Retrieve the faculty the student is registered in
print $stu->faculty;

These methods are not guaranteed to return results. While given and last names are always defined, the faculty name can be undef. Given and last names may be empty and defined, so check for a true value and not just defined.

as_string()

This method, which is also executed upon stringification, intelligently composes a string representation of the given user for display. Namely, it provides a first and last name with e-mail address, as:

John Doe <jdoe@uwo.ca>

or, when an e-mail address is unavailable:

John Doe

or, when we only have a first name:

John

or, a first name and e-mail address:

John <jdoe@uwo.ca>

or, when neither are available:

<unknown>

Example code:

# Stringify the student information
print $stu->as_string;

# Or the overloaded version
print $stu;

This method will always return a non-null string result, however, it may not be particularly useful. Your mileage may vary.

CONTRIBUTORS

MAINTAINER

Jonathan Yu <frequency@cpan.org>

FEEDBACK

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

BUGS

There are no known bugs as of this release. Please send any bug reports to the maintainer directly via e-mail.

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Jonathan Yu <frequency@cpan.org>

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.