1#!/usr/local/bin/perl -sw
2##
3## Razor2::Errorhandler -- Base class that provides error
4##                         handling functionality.
5##
6## Copyright (c) 2001, Vipul Ved Prakash.  All rights reserved.
7## This code is free software; you can redistribute it and/or modify
8## it under the same terms as Perl itself.
9##
10## $Id: Errorhandler.pm,v 1.5 2005/08/03 21:43:09 rsoderberg Exp $
11
12package Razor2::Errorhandler;
13use strict;
14
15sub new {
16    bless {}, shift
17}
18
19
20sub error {
21    no strict;
22    my ($self, $errstr, $construction_error) = @_;
23    if ($construction_error) {
24        my ($package, @undef) = caller();
25        my $location = "$package\::errstr";
26        my $spot = *{$location}{SCALAR};
27        $$spot = "$errstr\n";
28    } else {
29        $$self{errstr} = "$errstr\n";
30    }
31    $self->log($self->{logerrors},"Error: $errstr\n") if $self->{logerrors};
32    use strict;
33    return;
34}
35
36
37sub errstr {
38    my $self = shift;
39    return $$self{errstr};
40}
41
42sub errprefix {
43    my ($self, $prefix) = @_;
44    $$self{errstr} = $prefix .": ". $$self{errstr};
45    return;
46}
47
48sub errstrrst {
49    my $self = shift;
50    $$self{errstr} = "";
51}
52
531;
54
55
56=head1 NAME
57
58Razor::Errorhandler - Error handling mechanism for Razor.
59
60=head1 SYNOPSIS
61
62    package Foo;
63
64    use Razor::Errorhandler;
65    @ISA = qw(Razor::Errorhandler);
66
67    sub alive {
68        ..
69        ..
70        return
71        $self->error ("Awake, awake! Ring the alarum bell. \
72                       Murther and treason!", $dagger)
73            if $self->murdered($king);
74    }
75
76
77    package main;
78
79    use Foo;
80    my $foo = new Foo;
81    $foo->alive($king) or print $foo->errstr();
82    # prints "Awake, awake! ... "
83
84=head1 DESCRIPTION
85
86Razor::Errorhandler encapsulates the error handling mechanism used by the
87modules in Razor bundle. Razor::Errorhandler doesn't have a constructor
88and is meant to be inherited. The derived modules use its two methods,
89error() and errstr(), to communicate error messages to the caller.
90
91When a method of the derived module fails, it calls $self->error() and
92returns  to the caller. The error message passed to error() is made
93available to the caller through the errstr() accessor. error() also
94accepts a list of sensitive data that it wipes out (undef'es) before
95returning.
96
97The caller should B<never> call errstr() to check for errors. errstr()
98should be called only when a method indicates (usually through an undef
99return value) that an error has occured. This is because errstr() is
100never overwritten and will always contain a value after the occurance of
101first error.
102
103=head1 METHODS
104
105=over 4
106
107=item B<error($mesage, ($wipeme, $wipemetoo))>
108
109The first argument to error() is $message which is placed in
110$self->{errstr} and the remaining arguments are interpretted as variables
111containing sensitive data that are wiped out from the memory. error()
112always returns undef.
113
114=item B<errstr()>
115
116errstr() is an accessor method for $self->{errstr}.
117
118=back
119
120=head1 AUTHOR
121
122Vipul Ved Prakash, E<lt>mail@vipul.netE<gt>
123
124=head1 SEE ALSO
125
126Razor::Client(3)
127
128=cut
129
130
131