install/5.005/DBD-Pg-1.22-fixvercmp/t/lib/App/Info/Request.pm

   1 package App::Info::Request;
   2
   3 # $Id: Request.pm,v 1.1 2004-04-29 09:21:28 ivan Exp $
   4
   5 =head1 NAME
   6
   7 App::Info::Request - App::Info event handler request object
   8
   9 =head1 SYNOPSIS
  10
  11   # In an App::Info::Handler subclass:
  12   sub handler {
  13       my ($self, $req) = @_;
  14       print "Event Type:  ", $req->type;
  15       print "Message:     ", $req->message;
  16       print "Error:       ", $req->error;
  17       print "Value:       ", $req->value;
  18   }
  19
  20 =head1 DESCRIPTION
  21
  22 Objects of this class are passed to the C<handler()> method of App::Info event
  23 handlers. Generally, this class will be of most interest to App::Info::Handler
  24 subclass implementers.
  25
  26 The L<event triggering methods|App::Info/"Events"> in App::Info each construct
  27 a new App::Info::Request object and initialize it with their arguments. The
  28 App::Info::Request object is then the sole argument passed to the C<handler()>
  29 method of any and all App::Info::Handler objects in the event handling chain.
  30 Thus, if you'd like to create your own App::Info event handler, this is the
  31 object you need to be familiar with. Consult the
  32 L<App::Info::Handler|App::Info::Handler> documentation for details on creating
  33 custom event handlers.
  34
  35 Each of the App::Info event triggering methods constructs an
  36 App::Info::Request object with different attribute values. Be sure to consult
  37 the documentation for the L<event triggering methods|App::Info/"Events"> in
  38 App::Info, where the values assigned to the App::Info::Request object are
  39 documented. Then, in your event handler subclass, check the value returned by
  40 the C<type()> method to determine what type of event request you're handling
  41 to handle the request appropriately.
  42
  43 =cut
  44
  45 use strict;
  46 use vars qw($VERSION);
  47 $VERSION = '0.23';
  48
  49 ##############################################################################
  50
  51 =head1 INTERFACE
  52
  53 The following sections document the App::Info::Request interface.
  54
  55 =head2 Constructor
  56
  57 =head3 new
  58
  59   my $req = App::Info::Request->new(%params);
  60
  61 This method is used internally by App::Info to construct new
  62 App::Info::Request objects to pass to event handler objects. Generally, you
  63 won't need to use it, other than perhaps for testing custom App::Info::Handler
  64 classes.
  65
  66 The parameters to C<new()> are passed as a hash of named parameters that
  67 correspond to their like-named methods. The supported parameters are:
  68
  69 =over 4
  70
  71 =item type
  72
  73 =item message
  74
  75 =item error
  76
  77 =item value
  78
  79 =item callback
  80
  81 =back
  82
  83 See the object methods documentation below for details on these object
  84 attributes.
  85
  86 =cut
  87
  88 sub new {
  89     my $pkg = shift;
  90
  91     # Make sure we've got a hash of arguments.
  92     Carp::croak("Odd number of parameters in call to " . __PACKAGE__ .
  93                 "->new() when named parameters expected" ) if @_ % 2;
  94     my %params = @_;
  95
  96     # Validate the callback.
  97     if ($params{callback}) {
  98         Carp::croak("Callback parameter '$params{callback}' is not a code ",
  99                     "reference")
 100             unless UNIVERSAL::isa($params{callback}, 'CODE');
 101     } else {
 102         # Otherwise just assign a default approve callback.
 103         $params{callback} = sub { 1 };
 104     }
 105
 106     # Validate type parameter.
 107     if (my $t = $params{type}) {
 108         Carp::croak("Invalid handler type '$t'")
 109           unless $t eq 'error' or $t eq 'info' or $t eq 'unknown'
 110           or $t eq 'confirm';
 111     } else {
 112         $params{type} = 'info';
 113     }
 114
 115     # Return the request object.
 116     bless \%params, ref $pkg || $pkg;
 117 }
 118
 119 ##############################################################################
 120
 121 =head2 Object Methods
 122
 123 =head3 message
 124
 125   my $message = $req->message;
 126
 127 Returns the message stored in the App::Info::Request object. The message is
 128 typically informational, or an error message, or a prompt message.
 129
 130 =cut
 131
 132 sub message { $_[0]->{message} }
 133
 134 ##############################################################################
 135
 136 =head3 error
 137
 138   my $error = $req->error;
 139
 140 Returns any error message associated with the App::Info::Request object. The
 141 error message is typically there to display for users when C<callback()>
 142 returns false.
 143
 144 =cut
 145
 146 sub error { $_[0]->{error} }
 147
 148 ##############################################################################
 149
 150 =head3 type
 151
 152   my $type = $req->type;
 153
 154 Returns a string representing the type of event that triggered this request.
 155 The types are the same as the event triggering methods defined in App::Info.
 156 As of this writing, the supported types are:
 157
 158 =over
 159
 160 =item info
 161
 162 =item error
 163
 164 =item unknown
 165
 166 =item confirm
 167
 168 =back
 169
 170 Be sure to consult the App::Info documentation for more details on the event
 171 types.
 172
 173 =cut
 174
 175 sub type { $_[0]->{type} }
 176
 177 ##############################################################################
 178
 179 =head3 callback
 180
 181   if ($req->callback($value)) {
 182       print "Value '$value' is valid.\n";
 183   } else {
 184       print "Value '$value' is not valid.\n";
 185   }
 186
 187 Executes the callback anonymous subroutine supplied by the App::Info concrete
 188 base class that triggered the event. If the callback returns false, then
 189 C<$value> is invalid. If the callback returns true, then C<$value> is valid
 190 and can be assigned via the C<value()> method.
 191
 192 Note that the C<value()> method itself calls C<callback()> if it was passed a
 193 value to assign. See its documentation below for more information.
 194
 195 =cut
 196
 197 sub callback {
 198     my $self = shift;
 199     my $code = $self->{callback};
 200     local $_ = $_[0];
 201     $code->(@_);
 202 }
 203
 204 ##############################################################################
 205
 206 =head3 value
 207
 208   my $value = $req->value;
 209   if ($req->value($value)) {
 210       print "Value '$value' successfully assigned.\n";
 211   } else {
 212       print "Value '$value' not successfully assigned.\n";
 213   }
 214
 215 When called without an argument, C<value()> simply returns the value currently
 216 stored by the App::Info::Request object. Typically, the value is the default
 217 value for a confirm event, or a value assigned to an unknown event.
 218
 219 When passed an argument, C<value()> attempts to store the the argument as a
 220 new value. However, C<value()> calls C<callback()> on the new value, and if
 221 C<callback()> returns false, then C<value()> returns false and does not store
 222 the new value. If C<callback()> returns true, on the other hand, then
 223 C<value()> goes ahead and stores the new value and returns true.
 224
 225 =cut
 226
 227 sub value {
 228     my $self = shift;
 229     if ($#_ >= 0) {
 230         # grab the value.
 231         my $value = shift;
 232         # Validate the value.
 233         if ($self->callback($value)) {
 234             # The value is good. Assign it and return true.
 235             $self->{value} = $value;
 236             return 1;
 237         } else {
 238             # Invalid value. Return false.
 239             return;
 240         }
 241     }
 242     # Just return the value.
 243     return $self->{value};
 244 }
 245
 246 1;
 247 __END__
 248
 249 =head1 BUGS
 250
 251 Report all bugs via the CPAN Request Tracker at
 252 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Info>.
 253
 254 =head1 AUTHOR
 255
 256 David Wheeler <L<david@wheeler.net|"david@wheeler.net">>
 257
 258 =head1 SEE ALSO
 259
 260 L<App::Info|App::Info> documents the event triggering methods and how they
 261 construct App::Info::Request objects to pass to event handlers.
 262
 263 L<App::Info::Handler:|App::Info::Handler> documents how to create custom event
 264 handlers, which must make use of the App::Info::Request object passed to their
 265 C<handler()> object methods.
 266
 267 The following classes subclass App::Info::Handler, and thus offer good
 268 exemplars for using App::Info::Request objects when handling events.
 269
 270 =over 4
 271
 272 =item L<App::Info::Handler::Carp|App::Info::Handler::Carp>
 273
 274 =item L<App::Info::Handler::Print|App::Info::Handler::Print>
 275
 276 =item L<App::Info::Handler::Prompt|App::Info::Handler::Prompt>
 277
 278 =back
 279
 280 =head1 COPYRIGHT AND LICENSE
 281
 282 Copyright (c) 2002, David Wheeler. All Rights Reserved.
 283
 284 This module is free software; you can redistribute it and/or modify it under the
 285 same terms as Perl itself.
 286
 287 =cut