NAME

       App::Info::Request - App::Info event handler request object

SYNOPSIS

         # In an App::Info::Handler subclass:
         sub handler {
             my ($self, $req) = @_;
             print "Event Type:  ", $req->type;
             print "Message:     ", $req->message;
             print "Error:       ", $req->error;
             print "Value:       ", $req->value;
         }

DESCRIPTION

       Objects of this class are passed to the "handler()" method of App::Info event handlers.
       Generally, this class will be of most interest to App::Info::Handler subclass
       implementers.

       The event triggering methods in App::Info each construct a new App::Info::Request object
       and initialize it with their arguments. The App::Info::Request object is then the sole
       argument passed to the "handler()" method of any and all App::Info::Handler objects in the
       event handling chain.  Thus, if you'd like to create your own App::Info event handler,
       this is the object you need to be familiar with. Consult the App::Info::Handler
       documentation for details on creating custom event handlers.

       Each of the App::Info event triggering methods constructs an App::Info::Request object
       with different attribute values. Be sure to consult the documentation for the event
       triggering methods in App::Info, where the values assigned to the App::Info::Request
       object are documented. Then, in your event handler subclass, check the value returned by
       the "type()" method to determine what type of event request you're handling to handle the
       request appropriately.

INTERFACE

       The following sections document the App::Info::Request interface.

   Constructor
       new

         my $req = App::Info::Request->new(%params);

       This method is used internally by App::Info to construct new App::Info::Request objects to
       pass to event handler objects. Generally, you won't need to use it, other than perhaps for
       testing custom App::Info::Handler classes.

       The parameters to "new()" are passed as a hash of named parameters that correspond to
       their like-named methods. The supported parameters are:

       type
       message
       error
       value
       callback

       See the object methods documentation below for details on these object attributes.

   Object Methods
       key

         my $key = $req->key;

       Returns the key stored in the App::Info::Request object. The key is used by the App::Info
       subclass to uniquely identify the information it is harvesting, such as the path to an
       executable. It might be used by request handlers, for example, to see if an option was
       passed on the command-line.

       message

         my $message = $req->message;

       Returns the message stored in the App::Info::Request object. The message is typically
       informational, or an error message, or a prompt message.

       error

         my $error = $req->error;

       Returns any error message associated with the App::Info::Request object. The error message
       is typically there to display for users when "callback()" returns false.

       type

         my $type = $req->type;

       Returns a string representing the type of event that triggered this request.  The types
       are the same as the event triggering methods defined in App::Info.  As of this writing,
       the supported types are:

       info
       error
       unknown
       confirm

       Be sure to consult the App::Info documentation for more details on the event types.

       callback

         if ($req->callback($value)) {
             print "Value '$value' is valid.\n";
         } else {
             print "Value '$value' is not valid.\n";
         }

       Executes the callback anonymous subroutine supplied by the App::Info concrete base class
       that triggered the event. If the callback returns false, then $value is invalid. If the
       callback returns true, then $value is valid and can be assigned via the "value()" method.

       Note that the "value()" method itself calls "callback()" if it was passed a value to
       assign. See its documentation below for more information.

       value

         my $value = $req->value;
         if ($req->value($value)) {
             print "Value '$value' successfully assigned.\n";
         } else {
             print "Value '$value' not successfully assigned.\n";
         }

       When called without an argument, "value()" simply returns the value currently stored by
       the App::Info::Request object. Typically, the value is the default value for a confirm
       event, or a value assigned to an unknown event.

       When passed an argument, "value()" attempts to store the the argument as a new value.
       However, "value()" calls "callback()" on the new value, and if "callback()" returns false,
       then "value()" returns false and does not store the new value. If "callback()" returns
       true, on the other hand, then "value()" goes ahead and stores the new value and returns
       true.

SUPPORT

       This module is stored in an open GitHub repository <http://github.com/theory/app-info/>.
       Feel free to fork and contribute!

       Please file bug reports via GitHub Issues <http://github.com/theory/app-info/issues/> or
       by sending mail to bug-App-Info@rt.cpan.org <mailto:bug-App-Info@rt.cpan.org>.

AUTHOR

       David E. Wheeler <david@justatheory.com>

SEE ALSO

       App::Info documents the event triggering methods and how they construct App::Info::Request
       objects to pass to event handlers.

       App::Info::Handler: documents how to create custom event handlers, which must make use of
       the App::Info::Request object passed to their "handler()" object methods.

       The following classes subclass App::Info::Handler, and thus offer good exemplars for using
       App::Info::Request objects when handling events.

       App::Info::Handler::Carp
       App::Info::Handler::Print
       App::Info::Handler::Prompt

COPYRIGHT AND LICENSE

       Copyright (c) 2002-2011, David E. Wheeler. Some Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.