File Coverage

blib/lib/App/Info/Request.pm
Criterion Covered Total %
statement 21 36 58.3
branch 7 14 50.0
condition 7 12 58.3
subroutine 5 11 45.5
pod 7 7 100.0
total 47 80 58.8


line stmt bran cond sub pod time code
1             package App::Info::Request;
2              
3             # $Id: Request.pm 3176 2006-09-25 16:00:28Z theory $
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 2     2   27 use strict;
  2         20  
  2         24  
46 2     2   29 use vars qw($VERSION);
  2         18  
  2         26  
47 2     2   30 use Carp;
  2         19  
  2         37  
48             $VERSION = '0.51';
49              
50             ##############################################################################
51              
52             =head1 INTERFACE
53            
54             The following sections document the App::Info::Request interface.
55            
56             =head2 Constructor
57            
58             =head3 new
59            
60             my $req = App::Info::Request->new(%params);
61            
62             This method is used internally by App::Info to construct new
63             App::Info::Request objects to pass to event handler objects. Generally, you
64             won't need to use it, other than perhaps for testing custom App::Info::Handler
65             classes.
66            
67             The parameters to C<new()> are passed as a hash of named parameters that
68             correspond to their like-named methods. The supported parameters are:
69            
70             =over 4
71            
72             =item type
73            
74             =item message
75            
76             =item error
77            
78             =item value
79            
80             =item callback
81            
82             =back
83            
84             See the object methods documentation below for details on these object
85             attributes.
86            
87             =cut
88              
89             sub new {
90 24     24 1 357     my $pkg = shift;
91              
92             # Make sure we've got a hash of arguments.
93 24 50       558     Carp::croak("Odd number of parameters in call to " . __PACKAGE__ .
94                             "->new() when named parameters expected" ) if @_ % 2;
95 24         425     my %params = @_;
96              
97             # Validate the callback.
98 24 100       329     if ($params{callback}) {
99 4 50       54         Carp::croak("Callback parameter '$params{callback}' is not a code ",
100                                 "reference")
101                         unless UNIVERSAL::isa($params{callback}, 'CODE');
102                 } else {
103             # Otherwise just assign a default approve callback.
104 20     0   312         $params{callback} = sub { 1 };
  0         0  
105                 }
106              
107             # Validate type parameter.
108 24 50       771     if (my $t = $params{type}) {
109 24 50 66     936         Carp::croak("Invalid handler type '$t'")
      66        
      66        
110                       unless $t eq 'error' or $t eq 'info' or $t eq 'unknown'
111                       or $t eq 'confirm';
112                 } else {
113 0         0         $params{type} = 'info';
114                 }
115              
116             # Return the request object.
117 24   33     850     bless \%params, ref $pkg || $pkg;
118             }
119              
120             ##############################################################################
121              
122             =head2 Object Methods
123            
124             =head3 key
125            
126             my $key = $req->key;
127            
128             Returns the key stored in the App::Info::Request object. The key is used by
129             the App::Info subclass to uniquely identify the information it is harvesting,
130             such as the path to an executable. It might be used by request handlers,
131             for example, to see if an option was passed on the command-line.
132            
133             =cut
134              
135 0     0 1 0 sub key { $_[0]->{key} }
136              
137             ##############################################################################
138              
139             =head3 message
140            
141             my $message = $req->message;
142            
143             Returns the message stored in the App::Info::Request object. The message is
144             typically informational, or an error message, or a prompt message.
145            
146             =cut
147              
148 0     0 1 0 sub message { $_[0]->{message} }
149              
150             ##############################################################################
151              
152             =head3 error
153            
154             my $error = $req->error;
155            
156             Returns any error message associated with the App::Info::Request object. The
157             error message is typically there to display for users when C<callback()>
158             returns false.
159            
160             =cut
161              
162 0     0 1 0 sub error { $_[0]->{error} }
163              
164             ##############################################################################
165              
166             =head3 type
167            
168             my $type = $req->type;
169            
170             Returns a string representing the type of event that triggered this request.
171             The types are the same as the event triggering methods defined in App::Info.
172             As of this writing, the supported types are:
173            
174             =over
175            
176             =item info
177            
178             =item error
179            
180             =item unknown
181            
182             =item confirm
183            
184             =back
185            
186             Be sure to consult the App::Info documentation for more details on the event
187             types.
188            
189             =cut
190              
191 0     0 1 0 sub type { $_[0]->{type} }
192              
193             ##############################################################################
194              
195             =head3 callback
196            
197             if ($req->callback($value)) {
198             print "Value '$value' is valid.\n";
199             } else {
200             print "Value '$value' is not valid.\n";
201             }
202            
203             Executes the callback anonymous subroutine supplied by the App::Info concrete
204             base class that triggered the event. If the callback returns false, then
205             C<$value> is invalid. If the callback returns true, then C<$value> is valid
206             and can be assigned via the C<value()> method.
207            
208             Note that the C<value()> method itself calls C<callback()> if it was passed a
209             value to assign. See its documentation below for more information.
210            
211             =cut
212              
213             sub callback {
214 0     0 1 0     my $self = shift;
215 0         0     my $code = $self->{callback};
216 0         0     local $_ = $_[0];
217 0         0     $code->(@_);
218             }
219              
220             ##############################################################################
221              
222             =head3 value
223            
224             my $value = $req->value;
225             if ($req->value($value)) {
226             print "Value '$value' successfully assigned.\n";
227             } else {
228             print "Value '$value' not successfully assigned.\n";
229             }
230            
231             When called without an argument, C<value()> simply returns the value currently
232             stored by the App::Info::Request object. Typically, the value is the default
233             value for a confirm event, or a value assigned to an unknown event.
234            
235             When passed an argument, C<value()> attempts to store the the argument as a
236             new value. However, C<value()> calls C<callback()> on the new value, and if
237             C<callback()> returns false, then C<value()> returns false and does not store
238             the new value. If C<callback()> returns true, on the other hand, then
239             C<value()> goes ahead and stores the new value and returns true.
240            
241             =cut
242              
243             sub value {
244 4     4 1 457     my $self = shift;
245 4 50       165     if ($#_ >= 0) {
246             # grab the value.
247 0         0         my $value = shift;
248             # Validate the value.
249 0 0       0         if ($self->callback($value)) {
250             # The value is good. Assign it and return true.
251 0         0             $self->{value} = $value;
252 0         0             return 1;
253                     } else {
254             # Invalid value. Return false.
255 0         0             return;
256                     }
257                 }
258             # Just return the value.
259 4         149     return $self->{value};
260             }
261              
262             1;
263             __END__
264            
265             =head1 BUGS
266            
267             Please send bug reports to <bug-app-info@rt.cpan.org> or file them at
268             L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Info>.
269            
270             =head1 AUTHOR
271            
272             David Wheeler <david@justatheory.com>
273            
274             =head1 SEE ALSO
275            
276             L<App::Info|App::Info> documents the event triggering methods and how they
277             construct App::Info::Request objects to pass to event handlers.
278            
279             L<App::Info::Handler:|App::Info::Handler> documents how to create custom event
280             handlers, which must make use of the App::Info::Request object passed to their
281             C<handler()> object methods.
282            
283             The following classes subclass App::Info::Handler, and thus offer good
284             exemplars for using App::Info::Request objects when handling events.
285            
286             =over 4
287            
288             =item L<App::Info::Handler::Carp|App::Info::Handler::Carp>
289            
290             =item L<App::Info::Handler::Print|App::Info::Handler::Print>
291            
292             =item L<App::Info::Handler::Prompt|App::Info::Handler::Prompt>
293            
294             =back
295            
296             =head1 COPYRIGHT AND LICENSE
297            
298             Copyright (c) 2002-2006, David Wheeler. All Rights Reserved.
299            
300             This module is free software; you can redistribute it and/or modify it under the
301             same terms as Perl itself.
302            
303             =cut
304