more code updates, before i look in depth at the _load() routine
[p5sagit/Config-Any.git] / lib / Config / Any.pm
index 7eaae8a..07f7a9c 100644 (file)
@@ -1,12 +1,12 @@
 package Config::Any;
-# $Id: $
-use warnings;
+
 use strict;
+use warnings;
+
 use Carp;
 use Module::Pluggable::Object ();
-use English qw(-no_match_vars);
 
-our $VERSION = '0.05';
+our $VERSION = '0.09';
 
 =head1 NAME
 
@@ -14,21 +14,21 @@ Config::Any - Load configuration from different file formats, transparently
 
 =head1 VERSION
 
-This document describes Config::Any version 0.0.5
+This document describes Config::Any version 0.09
 
 =head1 SYNOPSIS
 
     use Config::Any;
 
-       my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... });
-       # or
-       my $cfg = Config::Any->load_files({files => \@filepaths, ... });
+    my $cfg = Config::Any->load_stems({stems => \@filepath_stems, ... });
+    # or
+    my $cfg = Config::Any->load_files({files => \@filepaths, ... });
 
-       for (@$cfg) {
-               my ($filename, $config) = each %$_;
-               $class->config($config);
-               warn "loaded config from file: $filename";
-       }
+    for (@$cfg) {
+        my ($filename, $config) = each %$_;
+        $class->config($config);
+        warn "loaded config from file: $filename";
+    }
 
 =head1 DESCRIPTION
 
@@ -48,11 +48,11 @@ configuration formats.
 
 =cut
 
-=head2 load_files( )
+=head2 load_files( \%args )
 
-    Config::Any->load_files({files => \@files]});
-    Config::Any->load_files({files => \@files, filter  => \&filter});
-    Config::Any->load_files({files => \@files, use_ext => 1});
+    Config::Any->load_files( { files => \@files } );
+    Config::Any->load_files( { files => \@files, filter  => \&filter } );
+    Config::Any->load_files( { files => \@files, use_ext => 1 } );
 
 C<load_files()> attempts to load configuration from the list of files passed in
 the C<files> parameter, if the file exists.
@@ -74,27 +74,31 @@ arrayref of plugin names like C<Config::Any::INI>. Its intended use is to allow
 of a non-standard file extension while forcing it to be offered to a particular parser.
 It is not compatible with 'use_ext'. 
 
+You can supply a C<driver_args> hashref to pass special options to a particular
+parser object. Example:
+
+    Config::Any->load_files( { files => \@files, driver_args => {
+        General => { -LowerCaseNames => 1 }
+    } )
+
 =cut
 
 sub load_files {
-    my ($class, $args) = @_;
-    return unless defined $args;
-    unless (exists $args->{files}) {
-        warn "no files specified";
+    my ( $class, $args ) = @_;
+
+    unless ( $args && exists $args->{ files } ) {
+        warn "No files specified!";
         return;
     }
 
-    my %load_args = map { $_ => defined $args->{$_} ? $args->{$_} : undef } 
-        qw(filter use_ext force_plugins);
-    $load_args{files} = [ grep { -f $_ } @{$args->{files}} ];
-    return $class->_load(\%load_args);
+    return $class->_load( $args );
 }
 
-=head2 load_stems( )
+=head2 load_stems( \%args )
 
-    Config::Any->load_stems({stems => \@stems]});
-    Config::Any->load_stems({stems => \@stems, filter  => \&filter});
-    Config::Any->load_stems({stems => \@stems, use_ext => 1});
+    Config::Any->load_stems( { stems => \@stems } );
+    Config::Any->load_stems( { stems => \@stems, filter  => \&filter } );
+    Config::Any->load_stems( { stems => \@stems, use_ext => 1 } );
 
 C<load_stems()> attempts to load configuration from a list of files which it generates
 by combining the filename stems list passed in the C<stems> parameter with the 
@@ -106,87 +110,74 @@ parameters. Please read the C<load_files()> documentation before using this meth
 =cut
 
 sub load_stems {
-    my ($class, $args) = @_;
-    return unless defined $args;
-    unless (exists $args->{stems}) {
-        warn "no stems specified";
+    my ( $class, $args ) = @_;
+
+    unless ( $args && exists $args->{ stems } ) {
+        warn "No stems specified!";
         return;
     }
-        
-    my %load_args = map { $_ => defined $args->{$_} ? $args->{$_} : undef } 
-        qw(filter use_ext force_plugins);
-
-    my $filenames = $class->_stems_to_files($args->{stems});
-    $load_args{files} = [ grep { -f $_ } @{$filenames} ];
-    return $class->_load(\%load_args);
-}
-
-sub _stems_to_files {
-    my ($class, $stems) = @_;
-    return unless defined $stems;
 
+    my $stems = delete $args->{ stems };
     my @files;
-    STEM:
-    for my $s (@$stems) {
-        EXT:
-        for my $ext ($class->extensions) {
-            my $file = "$s.$ext";
-            next EXT unless -f $file;
-            push @files, $file;
-            last EXT;
+    for my $s ( @$stems ) {
+        for my $ext ( $class->extensions ) {
+            push @files, "$s.$ext";
         }
     }
-    \@files;
-}
 
-sub _maphash (@) { map { $_ => 1 } @_ } # sugar
+    $args->{ files } = \@files;
+    return $class->_load( $args );
+}
 
 # this is where we do the real work
 # it's a private class-method because users should use the interface described
 # in the POD.
 sub _load {
-    my ($class, $args) = @_;
-    my ($files_ref, $filter_cb, $use_ext, $force_plugins_ref) = 
-        @{$args}{qw(files filter use_ext force_plugins)};
+    my ( $class, $args ) = @_;
+    my ( $files_ref, $filter_cb, $use_ext, $force_plugins_ref )
+        = @{ $args }{ qw(files filter use_ext force_plugins) };
     croak "_load requires a arrayref of file paths" unless defined $files_ref;
 
-       my %files           = _maphash @$files_ref;
-    my %force_plugins   = _maphash @$force_plugins_ref;
-    my $enforcing       = keys %force_plugins ? 1 : 0;
+    my %files         = map { $_ => 1 } @$files_ref;
+    my %force_plugins = map { $_ => 1 } @$force_plugins_ref;
+    my $enforcing = keys %force_plugins ? 1 : 0;
 
-    my $final_configs       = [];
-    my $originally_loaded   = {};
+    my $final_configs     = [];
+    my $originally_loaded = {};
 
     # perform a separate file loop for each loader
     for my $loader ( $class->plugins ) {
-        next if $enforcing && not defined $force_plugins{$loader};
-               last unless keys %files;
-        my %ext = _maphash $loader->extensions;
-
-        FILE:
-        for my $filename (keys %files) {
-            # use file extension to decide whether this loader should try this file
-            # use_ext => 1 hits this block
-            if (defined $use_ext && !$enforcing) {
-                               my $matched_ext = 0;
-                EXT:
-                for my $e (keys %ext) {
-                    next EXT  unless $filename =~ m{ \. $e \z }xms; 
-                    next FILE unless exists $ext{$e};
-                                       $matched_ext = 1;
+        next if $enforcing && not defined $force_plugins{ $loader };
+        last unless keys %files;
+        my %ext = map { $_ => 1 } $loader->extensions;
+
+        my ( $loader_class ) = $loader =~ /::([^:]+)$/;
+        my $driver_args = $args->{ driver_args }{ $loader_class } || {};
+
+    FILE:
+        for my $filename ( keys %files ) {
+            next unless -f $filename;
+
+       # use file extension to decide whether this loader should try this file
+       # use_ext => 1 hits this block
+            if ( defined $use_ext && !$enforcing ) {
+                my $matched_ext = 0;
+            EXT:
+                for my $e ( keys %ext ) {
+                    next EXT unless $filename =~ m{ \. $e \z }xms;
+                    next FILE unless exists $ext{ $e };
+                    $matched_ext = 1;
                 }
 
-                               next FILE unless $matched_ext;
+                next FILE unless $matched_ext;
             }
 
             my $config;
-                       eval {
-                               $config = $loader->load( $filename );
-                       };
+            eval { $config = $loader->load( $filename, $driver_args ); };
 
-                       next if $EVAL_ERROR; # if it croaked or warned, we can't use it
+            next if $@;         # if it croaked or warned, we can't use it
             next if !$config;
-                       delete $files{$filename};
+            delete $files{ $filename };
 
             # post-process config with a filter callback, if we got one
             $filter_cb->( $config ) if defined $filter_cb;
@@ -194,7 +185,8 @@ sub _load {
             push @$final_configs, { $filename => $config };
         }
     }
-    $final_configs;
+
+    return $final_configs;
 }
 
 =head2 finder( )
@@ -207,12 +199,12 @@ more information.
 =cut
 
 sub finder {
-    my $class = shift;
+    my $class  = shift;
     my $finder = Module::Pluggable::Object->new(
         search_path => [ __PACKAGE__ ],
         require     => 1
     );
-    $finder;
+    return $finder;
 }
 
 =head2 plugins( )
@@ -238,14 +230,14 @@ parameter to those methods.
 sub extensions {
     my $class = shift;
     my @ext = map { $_->extensions } $class->plugins;
-       return wantarray ? @ext : [@ext];
+    return wantarray ? @ext : \@ext;
 }
 
 =head1 DIAGNOSTICS
 
 =over
 
-=item C<no files specified> or C<no stems specified>
+=item C<No files specified!> or C<No stems specified!>
 
 The C<load_files()> and C<load_stems()> methods will issue this warning if
 called with an empty list of files/stems to load.
@@ -289,7 +281,7 @@ L<http://rt.cpan.org>.
 
 =head1 AUTHOR
 
-Joel Bernstein  C<< <rataxis@cpan.org> >>
+Joel Bernstein  E<lt>rataxis@cpan.orgE<gt>
 
 =head1 CONTRIBUTORS