.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "App::Info::Request 3pm"
.TH App::Info::Request 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::Info::Request \- App::Info event handler request object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\& # 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;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Objects of this class are passed to the \f(CW\*(C`handler()\*(C'\fR method of App::Info event
handlers. Generally, this class will be of most interest to App::Info::Handler
subclass implementers.
.PP
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 \f(CW\*(C`handler()\*(C'\fR
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.
.PP
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 \f(CW\*(C`type()\*(C'\fR method to determine what type of event request you're handling
to handle the request appropriately.
.SH "INTERFACE"
.IX Header "INTERFACE"
The following sections document the App::Info::Request interface.
.SS "Constructor"
.IX Subsection "Constructor"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\& my $req = App::Info::Request\->new(%params);
.Ve
.PP
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.
.PP
The parameters to \f(CW\*(C`new()\*(C'\fR are passed as a hash of named parameters that
correspond to their like-named methods. The supported parameters are:
.IP "type" 4
.IX Item "type"
.PD 0
.IP "message" 4
.IX Item "message"
.IP "error" 4
.IX Item "error"
.IP "value" 4
.IX Item "value"
.IP "callback" 4
.IX Item "callback"
.PD
.PP
See the object methods documentation below for details on these object
attributes.
.SS "Object Methods"
.IX Subsection "Object Methods"
\fIkey\fR
.IX Subsection "key"
.PP
.Vb 1
\& my $key = $req\->key;
.Ve
.PP
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.
.PP
\fImessage\fR
.IX Subsection "message"
.PP
.Vb 1
\& my $message = $req\->message;
.Ve
.PP
Returns the message stored in the App::Info::Request object. The message is
typically informational, or an error message, or a prompt message.
.PP
\fIerror\fR
.IX Subsection "error"
.PP
.Vb 1
\& my $error = $req\->error;
.Ve
.PP
Returns any error message associated with the App::Info::Request object. The
error message is typically there to display for users when \f(CW\*(C`callback()\*(C'\fR
returns false.
.PP
\fItype\fR
.IX Subsection "type"
.PP
.Vb 1
\& my $type = $req\->type;
.Ve
.PP
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:
.IP "info" 4
.IX Item "info"
.PD 0
.IP "error" 4
.IX Item "error"
.IP "unknown" 4
.IX Item "unknown"
.IP "confirm" 4
.IX Item "confirm"
.PD
.PP
Be sure to consult the App::Info documentation for more details on the event
types.
.PP
\fIcallback\fR
.IX Subsection "callback"
.PP
.Vb 5
\& if ($req\->callback($value)) {
\& print "Value \*(Aq$value\*(Aq is valid.\en";
\& } else {
\& print "Value \*(Aq$value\*(Aq is not valid.\en";
\& }
.Ve
.PP
Executes the callback anonymous subroutine supplied by the App::Info concrete
base class that triggered the event. If the callback returns false, then
\&\f(CW$value\fR is invalid. If the callback returns true, then \f(CW$value\fR is valid
and can be assigned via the \f(CW\*(C`value()\*(C'\fR method.
.PP
Note that the \f(CW\*(C`value()\*(C'\fR method itself calls \f(CW\*(C`callback()\*(C'\fR if it was passed a
value to assign. See its documentation below for more information.
.PP
\fIvalue\fR
.IX Subsection "value"
.PP
.Vb 6
\& my $value = $req\->value;
\& if ($req\->value($value)) {
\& print "Value \*(Aq$value\*(Aq successfully assigned.\en";
\& } else {
\& print "Value \*(Aq$value\*(Aq not successfully assigned.\en";
\& }
.Ve
.PP
When called without an argument, \f(CW\*(C`value()\*(C'\fR 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.
.PP
When passed an argument, \f(CW\*(C`value()\*(C'\fR attempts to store the the argument as a
new value. However, \f(CW\*(C`value()\*(C'\fR calls \f(CW\*(C`callback()\*(C'\fR on the new value, and if
\&\f(CW\*(C`callback()\*(C'\fR returns false, then \f(CW\*(C`value()\*(C'\fR returns false and does not store
the new value. If \f(CW\*(C`callback()\*(C'\fR returns true, on the other hand, then
\&\f(CW\*(C`value()\*(C'\fR goes ahead and stores the new value and returns true.
.SH "SUPPORT"
.IX Header "SUPPORT"
This module is stored in an open GitHub
repository . Feel free to fork and
contribute!
.PP
Please file bug reports via GitHub
Issues or by sending mail to
bug\-App\-Info@rt.cpan.org .
.SH "AUTHOR"
.IX Header "AUTHOR"
David E. Wheeler
.SH "SEE ALSO"
.IX Header "SEE ALSO"
App::Info documents the event triggering methods and how they
construct App::Info::Request objects to pass to event handlers.
.PP
App::Info::Handler: documents how to create custom event
handlers, which must make use of the App::Info::Request object passed to their
\&\f(CW\*(C`handler()\*(C'\fR object methods.
.PP
The following classes subclass App::Info::Handler, and thus offer good
exemplars for using App::Info::Request objects when handling events.
.IP "App::Info::Handler::Carp" 4
.IX Item "App::Info::Handler::Carp"
.PD 0
.IP "App::Info::Handler::Print" 4
.IX Item "App::Info::Handler::Print"
.IP "App::Info::Handler::Prompt" 4
.IX Item "App::Info::Handler::Prompt"
.PD
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2002\-2011, David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.