File Coverage

blib/lib/Class/ErrorHandler.pm
Criterion Covered Total %
statement 12 12 100.0
branch 4 4 100.0
condition 1 2 50.0
subroutine 4 4 100.0
pod 2 2 100.0
total 23 24 95.8


line stmt bran cond sub pod time code
1             # $Id: ErrorHandler.pm,v 1.1.1.1 2004/08/15 14:55:43 btrott Exp $
2              
3             package Class::ErrorHandler;
4 2     2   31 use strict;
  2         34  
  2         30  
5              
6 2     2   28 use vars qw( $VERSION $ERROR );
  2         18  
  2         31  
7             $VERSION = '0.01';
8              
9             sub error {
10 4   50 4 1 299     my $msg = $_[1] || '';
11 4 100       40     if (ref($_[0])) {
12 2         20         $_[0]->{_errstr} = $msg;
13                 } else {
14 2         17         $ERROR = $msg;
15                 }
16 4         39     return;
17             }
18              
19             sub errstr {
20 4 100   4 1 390     ref($_[0]) ? $_[0]->{_errstr} : $ERROR
21             }
22              
23             1;
24             __END__
25            
26             =head1 NAME
27            
28             Class::ErrorHandler - Base class for error handling
29            
30             =head1 SYNOPSIS
31            
32             package Foo;
33             use base qw( Class::ErrorHandler );
34            
35             sub class_method {
36             my $class = shift;
37             ...
38             return $class->error("Help!")
39             unless $continue;
40             }
41            
42             sub object_method {
43             my $obj = shift;
44             ...
45             return $obj->error("I am no more")
46             unless $continue;
47             }
48            
49             package main;
50             use Foo;
51            
52             Foo->class_method or die Foo->errstr;
53            
54             my $foo = Foo->new;
55             $foo->object_method or die $foo->errstr;
56            
57             =head1 DESCRIPTION
58            
59             I<Class::ErrorHandler> provides an error-handling mechanism that's generic
60             enough to be used as the base class for a variety of OO classes. Subclasses
61             inherit its two error-handling methods, I<error> and I<errstr>, to
62             communicate error messages back to the calling program.
63            
64             On failure (for whatever reason), a subclass should call I<error> and return
65             to the caller; I<error> itself sets the error message internally, then
66             returns C<undef>. This has the effect of the method that failed returning
67             C<undef> to the caller. The caller should check for errors by checking for a
68             return value of C<undef>, and calling I<errstr> to get the value of the
69             error message on an error.
70            
71             As demonstrated in the L<SYNOPSIS>, I<error> and I<errstr> work as both class
72             methods and object methods.
73            
74             =head1 USAGE
75            
76             =head2 Class->error($message)
77            
78             =head2 $object->error($message)
79            
80             Sets the error message for either the class I<Class> or the object
81             I<$object> to the message I<$message>. Returns C<undef>.
82            
83             =head2 Class->errstr
84            
85             =head2 $object->errstr
86            
87             Accesses the last error message set in the class I<Class> or the
88             object I<$object>, respectively, and returns that error message.
89            
90             =head1 LICENSE
91            
92             I<Class::ErrorHandler> is free software; you may redistribute it and/or modify
93             it under the same terms as Perl itself.
94            
95             =head1 AUTHOR & COPYRIGHT
96            
97             Except where otherwise noted, I<Class::ErrorHandler> is Copyright 2004
98             Benjamin Trott, cpan@stupidfool.org. All rights reserved.
99            
100             =cut
101