view release on metacpan or  search on metacpan

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

value. This value will be stored in the C<value> attribute of the
App::Info::Request object passed to event handlers.

=item callback

Same as for C<unknown()>. Because the user can enter data to replace the
default value provided via the C<value> parameter, you might want to validate
it. Use this code reference to do so. The callback will be stored in the
C<callback> attribute of the App::Info::Request object passed to event
handlers.

=item error

Same as for C<unknown()>: an error message to display in the event that a
value entered by the user isn't validated by the C<callback> code reference.
This value will be stored in the C<error> attribute of the App::Info::Request
object passed to event handlers.

=back

Here's an example usage demonstrating all of the above arguments:

  my $exe = $self->confirm( key      => 'shell',
                            prompt   => 'Path to your shell?',
                            value    => '/bin/sh',
                            callback => sub { -x },
                            error    => 'Not an executable');


=cut

sub confirm {
    my ($self, %params) = @_;
    my $key = $params{key}
      or Carp::croak("No key parameter passed to confirm()");
    return $self->{__confirm__}{$key} if exists $self->{__confirm__}{$key};

    # Create a prompt and error message, if necessary.
    $params{message} = delete $params{prompt} ||
      "Enter a valid " . $self->key_name . " $key";
    $params{error} ||= 'Invalid value';

    # Execute the handler sequence.
    my $req = $handler->($self, "confirm", \%params);

    # Mark that we've confirmed this value.
    $self->{__confirm__}{$key} = $req->value;

    return $self->{__confirm__}{$key}
}

1;
__END__

=head2 Event Examples

Below I provide some examples demonstrating the use of the event methods.
These are meant to emphasize the contexts in which it's appropriate to use
them.

Let's start with the simplest, first. Let's say that to find the version
number for an application, you need to search a file for the relevant data.
Your App::Info concrete subclass might have a private method that handles this
work, and this method is the appropriate place to use the C<info()> and, if
necessary, C<error()> methods.

  sub _find_version {
      my $self = shift;

      # Try to find the revelant file. We cover this method below.
      # Just return if we cant' find it.
      my $file = $self->_find_file('version.conf') or return;

      # Send a status message.
      $self->info("Searching '$file' file for version");

      # Search the file. $util is an App::Info::Util object.
      my $ver = $util->search_file($file, qr/^Version\s+(.*)$/);

      # Trigger an error message, if necessary. We really think we'll have the
      # value, but we have to cover our butts in the unlikely event that we're
      # wrong.
      $self->error("Unable to find version in file '$file'") unless $ver;

      # Return the version number.
      return $ver;
  }

Here we've used the C<info()> method to display a status message to let the
user know what we're doing. Then we used the C<error()> method when something
unexpected happened, which in this case was that we weren't able to find the
version number in the file.

Note the C<_find_file()> method we've thrown in. This might be a method that
we call whenever we need to find a file that might be in one of a list of
directories. This method, too, will be an appropriate place for an C<info()>
method call. But rather than call the C<error()> method when the file can't be
found, you might want to give an event handler a chance to supply that value
for you. Use the C<unknown()> method for a case such as this:

  sub _find_file {
      my ($self, $file) = @_;

      # Send a status message.
      $self->info("Searching for '$file' file");

      # Look for the file. See App::Info:Utility for its interface.
      my @paths = qw(/usr/conf /etc/conf /foo/conf);
      my $found = $util->first_cat_path($file, @paths);

      # If we didn't find it, trigger an unknown event to
      # give a handler a chance to get the value.
      $found ||= $self->unknown( key      => "file_$file",
                                 prompt   => "Location of '$file' file?",
                                 callback => sub { -f },
                                 error    => "Not a file");

      # Now return the file name, regardless of whether we found it or not.
      return $found;
  }