File Coverage

blib/lib/Config/MVP/Reader/Finder.pm

Criterion	Covered	Total	%
statement	37	41	90.2
branch	9	18	50.0
condition	2	5	40.0
subroutine	9	12	75.0
pod	4	4	100.0
total	61	80	76.2

package Config::MVP::Reader::Finder 2.200013;
# ABSTRACT: a reader that finds an appropriate file

use Moose;
extends 'Config::MVP::Reader';

#pod =head1 DESCRIPTION
#pod
#pod The Finder reader multiplexes many other readers that implement the
#pod L<Config::MVP::Reader::Findable> role.  It uses L<Module::Pluggable> to search
#pod for modules, limits them to objects implementing the Findable role, and then
#pod selects the those which report that they are able to read a configuration file
#pod found in the config root directory.  If exactly one findable configuration
#pod reader finds a file, it is used to read the file and the configuration sequence
#pod is returned.  Otherwise, an exception is raised.
#pod
#pod Config::MVP::Reader::Finder's C<build_assembler> method will decline a new
#pod assembler, so if none was passed to C<read_config>, the Findable reader to
#pod which reading is delegated will be responsible for building the assembler,
#pod unless a Finder subclass overrides C<build_assembler> to set a default across
#pod all possible delegates.
#pod
#pod =cut

use Config::MVP::Error;
use Module::Pluggable::Object;
use Try::Tiny;

#pod =method default_search_path
#pod
#pod This is the default search path used to find configuration readers.  This
#pod method should return a list, and by default returns:
#pod
#pod   qw( Config::MVP::Reader )
#pod
#pod =cut

sub default_search_path {
  return qw(Config::MVP::Reader)
}

our @DONT_FIND;

has _module_pluggable_object => (
  is => 'ro',
  init_arg => undef,
  default  => sub {
    my ($self) = @_;
    Module::Pluggable::Object->new(
      search_path => [ $self->default_search_path ],
      inner       => 0,
      require     => 1,

      # This facility here entirely for testing. -- rjbs, 2014-07-02
      except      => \@DONT_FIND,
    );
  },
);

sub _which_reader {
  my ($self, $location) = @_;

  my @options;

  for my $pkg ($self->_module_pluggable_object->plugins) {
    next unless $pkg->isa('Moose::Object');
    next unless $pkg->does('Config::MVP::Reader::Findable');

    my $location = $pkg->refined_location($location);

    next unless defined $location;

    push @options, [ $pkg, $location ];
  }

  Config::MVP::Error->throw("no viable configuration could be found")
    unless @options;

  # XXX: Improve this error message -- rjbs, 2010-05-24
  Config::MVP::Error->throw("multiple possible config plugins found")
    if @options > 1;

  return {
    'package'  => $options[0][0],
    'location' => $options[0][1],
  };
}

has if_none => (
  is  => 'ro',
  isa => 'Maybe[Str|CodeRef]',
);

sub read_config {
  my ($self, $location, $arg) = @_;
  $self = $self->new unless blessed($self);
  $arg ||= {};

  local $arg->{assembler} = $arg->{assembler} || $self->build_assembler;

  my $which;
  my $instead;
  try {
    $which = $self->_which_reader($location);
  } catch {
    die $_ unless $_ =~ /^no viable configuration/;
    die $_ unless defined (my $handler = $self->if_none);
    $instead = $self->$handler($location, $arg);
  };

  return $instead unless $which;

  my $reader = $which->{package}->new({
    add_cwd_to_lib => $self->add_cwd_to_lib,
  });

  return $reader->read_config( $which->{location}, $arg );
}

sub build_assembler { }

sub read_into_assembler {
  confess "This method should never be called or reachable";
}

no Moose;
__PACKAGE__->meta->make_immutable;
1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Config::MVP::Reader::Finder - a reader that finds an appropriate file

=head1 VERSION

version 2.200013

=head1 DESCRIPTION

The Finder reader multiplexes many other readers that implement the
L<Config::MVP::Reader::Findable> role.  It uses L<Module::Pluggable> to search
for modules, limits them to objects implementing the Findable role, and then
selects the those which report that they are able to read a configuration file
found in the config root directory.  If exactly one findable configuration
reader finds a file, it is used to read the file and the configuration sequence
is returned.  Otherwise, an exception is raised.

Config::MVP::Reader::Finder's C<build_assembler> method will decline a new
assembler, so if none was passed to C<read_config>, the Findable reader to
which reading is delegated will be responsible for building the assembler,
unless a Finder subclass overrides C<build_assembler> to set a default across
all possible delegates.

=head1 PERL VERSION

This module should work on any version of perl still receiving updates from
the Perl 5 Porters.  This means it should work on any version of perl released
in the last two to three years.  (That is, if the most recently released
version is v5.40, then this module should work on both v5.40 and v5.38.)

Although it may work on older versions of perl, no guarantee is made that the
minimum required version will not be increased.  The version may be increased
for any reason, and there is no promise that patches will be accepted to lower
the minimum required perl.

=head1 METHODS

=head2 default_search_path

This is the default search path used to find configuration readers.  This
method should return a list, and by default returns:

  qw( Config::MVP::Reader )

=head1 AUTHOR

Ricardo Signes <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Ricardo Signes.

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

=cut