view release on metacpan or  search on metacpan

lib/App/Info.pm  view on Meta::CPAN

software categories. This approach allows the categories themselves to
function as abstract base classes that extend App::Info, so that they can
specify more methods for all of their base classes to implement. For example,
App::Info::HTTPD has specified the C<httpd_root()> abstract method that its
subclasses must implement. So as you get ready to implement your own subclass,
think about what category of software you're gathering information about.
New categories can be added as necessary.

=head2 Utility Methods

Once you've decided on the proper category, you can start implementing your
App::Info concrete subclass. As you do so, take advantage of App::Info::Util,
wherein I've tried to encapsulate common functionality to make subclassing
easier. I found that most of what I was doing repetitively was looking for
files and directories, and searching through files. Thus, App::Info::Util
subclasses L<File::Spec|File::Spec> in order to offer easy access to
commonly-used methods from that class, e.g., C<path()>. Plus, it has several
of its own methods to assist you in finding files and directories in lists of
files and directories, as well as methods for searching through files and
returning the values found in those files. See
L<App::Info::Util|App::Info::Util> for more information, and the App::Info

lib/App/Info.pm  view on Meta::CPAN

The C<key> parameter uniquely identifies the data point in your class, and is
used by App::Info to ensure that an unknown event is handled only once, no
matter how many times the method is called. The same value will be returned by
subsequent calls to C<unknown()> as was returned by the first call, and no
handlers will be activated. Typical values are "version" and "lib_dir".

=item prompt

The C<prompt> parameter is the prompt to be displayed should an event handler
decide to prompt for the appropriate value. Such a prompt might be something
like "Path to your httpd executable?". If this parameter is not provided,
App::Info will construct one for you using your class' C<key_name()> method
and the C<key> parameter. The result would be something like "Enter a valid
FooApp version". The C<prompt> parameter value will be stored in the
C<message> attribute of the App::Info::Request object passed to event
handlers.

=item callback

Assuming a handler has collected a value for your unknown data point, it might

lib/App/Info.pm  view on Meta::CPAN

can't find it, we trigger an unknown event. This allows clients of our
App::Info subclass to try to establish the value themselves by having an
App::Info::Handler subclass handle the event. If a value is found by an
App::Info::Handler subclass, it will be returned by C<unknown()> and we can
continue. But we can't assume that the unknown event will even be handled, and
thus must expect that an unknown value may remain unknown. This is why the
C<_find_version()> method above simply returns if C<_find_file()> doesn't
return a file name; there's no point in searching through a file that doesn't
exist.

Attentive readers may be left to wonder how to decide when to use C<error()>
and when to use C<unknown()>. To a large extent, this decision must be based
on one's own understanding of what's most appropriate. Nevertheless, I offer
the following simple guidelines: Use C<error()> when you expect something to
work and then it just doesn't (as when a file exists and should contain the
information you seek, but then doesn't). Use C<unknown()> when you're less
sure of your processes for finding the value, and also for any of the values
that should be returned by any of the L<meta data object methods|"Metadata
Object Methods">. And of course, C<error()> would be more appropriate when you
encounter an unexpected condition and don't think that it could be handled in
any other way.