lib/MooseX/ConfigFromFile.pm

   1 package MooseX::ConfigFromFile;
   2
   3 use Moose::Role;
   4 use MooseX::Types::Path::Class qw( File );
   5 use Try::Tiny qw/ try /;
   6 use Carp qw(croak);
   7 use namespace::autoclean;
   8
   9 our $VERSION = '0.04';
  10
  11 requires 'get_config_from_file';
  12
  13 has configfile => (
  14     is => 'ro',
  15     isa => File,
  16     coerce => 1,
  17     predicate => 'has_configfile',
  18 );
  19
  20 sub new_with_config {
  21     my ($class, %opts) = @_;
  22
  23     my $configfile;
  24
  25     if(defined $opts{configfile}) {
  26         $configfile = $opts{configfile}
  27     }
  28     else {
  29         # This would only succeed if the consumer had defined a new configfile
  30         # sub to override the generated reader
  31         $configfile = try { $class->configfile };
  32
  33         # this is gross, but since a lot of users have swapped in their own
  34         # default subs, we have to keep calling it rather than calling a
  35         # builder sub directly - and it might not even be a coderef either
  36         my $cfmeta = $class->meta->find_attribute_by_name('configfile');
  37         $configfile ||= $cfmeta->default if $cfmeta->has_default;
  38
  39         if (ref $configfile eq 'CODE') {
  40             $configfile = $configfile->($class);
  41         }
  42     }
  43
  44     if (defined $configfile) {
  45         my $hash = $class->get_config_from_file($configfile);
  46
  47         no warnings 'uninitialized';
  48         croak "get_config_from_file($configfile) did not return a hash (got $hash)"
  49             unless ref $hash eq 'HASH';
  50
  51         %opts = (%$hash, %opts);
  52     }
  53
  54     $class->new(%opts);
  55 }
  56
  57 no Moose::Role; 1;
  58
  59 __END__
  60
  61 =pod
  62
  63 =head1 NAME
  64
  65 MooseX::ConfigFromFile - An abstract Moose role for setting attributes from a configfile
  66
  67 =head1 SYNOPSIS
  68
  69   ########
  70   ## A real role based on this abstract role:
  71   ########
  72
  73   package MooseX::SomeSpecificConfigRole;
  74   use Moose::Role;
  75
  76   with 'MooseX::ConfigFromFile';
  77
  78   use Some::ConfigFile::Loader ();
  79
  80   sub get_config_from_file {
  81     my ($class, $file) = @_;
  82
  83     my $options_hashref = Some::ConfigFile::Loader->load($file);
  84
  85     return $options_hashref;
  86   }
  87
  88
  89   ########
  90   ## A class that uses it:
  91   ########
  92   package Foo;
  93   use Moose;
  94   with 'MooseX::SomeSpecificConfigRole';
  95
  96   # optionally, default the configfile:
  97   around configfile => sub { '/tmp/foo.yaml' };
  98
  99   # ... insert your stuff here ...
 100
 101   ########
 102   ## A script that uses the class with a configfile
 103   ########
 104
 105   my $obj = Foo->new_with_config(configfile => '/etc/foo.yaml', other_opt => 'foo');
 106
 107 =head1 DESCRIPTION
 108
 109 This is an abstract role which provides an alternate constructor for creating
 110 objects using parameters passed in from a configuration file.  The
 111 actual implementation of reading the configuration file is left to
 112 concrete subroles.
 113
 114 It declares an attribute C<configfile> and a class method C<new_with_config>,
 115 and requires that concrete roles derived from it implement the class method
 116 C<get_config_from_file>.
 117
 118 Attributes specified directly as arguments to C<new_with_config> supercede those
 119 in the configfile.
 120
 121 L<MooseX::Getopt> knows about this abstract role, and will use it if available
 122 to load attributes from the file specified by the commandline flag C<--configfile>
 123 during its normal C<new_with_options>.
 124
 125 =head1 Attributes
 126
 127 =head2 configfile
 128
 129 This is a L<Path::Class::File> object which can be coerced from a regular pathname
 130 string.  This is the file your attributes are loaded from.  You can add a default
 131 configfile in the consuming class and it will be honored at the appropriate time
 132 (note that a simple sub declaration is not sufficient, as there is already a
 133 sub by that name being added by Moose as the attribute reader)
 134
 135   around configfile => sub { '/etc/myapp.yaml' };
 136
 137 Note that you can alternately just provide a C<configfile> method which returns
 138 the config file when called - this will be used in preference to the default of
 139 the attribute.
 140
 141 =head1 Class Methods
 142
 143 =head2 new_with_config
 144
 145 This is an alternate constructor, which knows to look for the C<configfile> option
 146 in its arguments and use that to set attributes.  It is much like L<MooseX::Getopts>'s
 147 C<new_with_options>.  Example:
 148
 149   my $foo = SomeClass->new_with_config(configfile => '/etc/foo.yaml');
 150
 151 Explicit arguments will overide anything set by the configfile.
 152
 153 =head2 get_config_from_file
 154
 155 This class method is not implemented in this role, but it is required of all subroles.
 156 Its two arguments are the classname and the configfile, and it is expected to return
 157 a hashref of arguments to pass to C<new()> which are sourced from the configfile.
 158
 159 =head1 COPYRIGHT
 160
 161 Copyright (c) 2007 - 2009 the MooseX::ConfigFromFile "AUTHOR" and "CONTRIBUTORS" as listed below.
 162
 163 =head1 AUTHOR
 164
 165 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
 166
 167 =head1 CONTRIBUTORS
 168
 169 =over
 170
 171 =item Tomas Doran C<< <bobtfish@bobtfish.net> >> (current maintainer).
 172
 173 =item Karen Etheridge
 174
 175 =item Chris Prather
 176
 177 =item Zbigniew Lukasiak
 178
 179 =back
 180
 181 =head1 LICENSE
 182
 183 This library is free software; you can redistribute it and/or modify
 184 it under the same terms as Perl itself.
 185
 186 =cut