1 package App::Info::Request;
3 # $Id: Request.pm,v 1.1 2004-04-29 09:21:28 ivan Exp $
7 App::Info::Request - App::Info event handler request object
11 # In an App::Info::Handler subclass:
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;
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.
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.
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.
46 use vars qw($VERSION);
49 ##############################################################################
53 The following sections document the App::Info::Request interface.
59 my $req = App::Info::Request->new(%params);
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
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:
83 See the object methods documentation below for details on these object
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;
96 # Validate the callback.
97 if ($params{callback}) {
98 Carp::croak("Callback parameter '$params{callback}' is not a code ",
100 unless UNIVERSAL::isa($params{callback}, 'CODE');
102 # Otherwise just assign a default approve callback.
103 $params{callback} = sub { 1 };
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'
112 $params{type} = 'info';
115 # Return the request object.
116 bless \%params, ref $pkg || $pkg;
119 ##############################################################################
121 =head2 Object Methods
125 my $message = $req->message;
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.
132 sub message { $_[0]->{message} }
134 ##############################################################################
138 my $error = $req->error;
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()>
146 sub error { $_[0]->{error} }
148 ##############################################################################
152 my $type = $req->type;
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:
170 Be sure to consult the App::Info documentation for more details on the event
175 sub type { $_[0]->{type} }
177 ##############################################################################
181 if ($req->callback($value)) {
182 print "Value '$value' is valid.\n";
184 print "Value '$value' is not valid.\n";
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.
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.
199 my $code = $self->{callback};
204 ##############################################################################
208 my $value = $req->value;
209 if ($req->value($value)) {
210 print "Value '$value' successfully assigned.\n";
212 print "Value '$value' not successfully assigned.\n";
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.
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.
232 # Validate the value.
233 if ($self->callback($value)) {
234 # The value is good. Assign it and return true.
235 $self->{value} = $value;
238 # Invalid value. Return false.
242 # Just return the value.
243 return $self->{value};
251 Report all bugs via the CPAN Request Tracker at
252 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Info>.
256 David Wheeler <L<david@wheeler.net|"david@wheeler.net">>
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.
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.
267 The following classes subclass App::Info::Handler, and thus offer good
268 exemplars for using App::Info::Request objects when handling events.
272 =item L<App::Info::Handler::Carp|App::Info::Handler::Carp>
274 =item L<App::Info::Handler::Print|App::Info::Handler::Print>
276 =item L<App::Info::Handler::Prompt|App::Info::Handler::Prompt>
280 =head1 COPYRIGHT AND LICENSE
282 Copyright (c) 2002, David Wheeler. All Rights Reserved.
284 This module is free software; you can redistribute it and/or modify it under the
285 same terms as Perl itself.