lib/MooseX/ConfigFromFile.pm

   1 package MooseX::ConfigFromFile;
   2
   3 use Moose::Role;
   4 use MooseX::Types::Path::Class qw( File );
   5
   6 our $VERSION   = '0.02';
   7
   8 use Carp qw(croak);
   9
  10 requires 'get_config_from_file';
  11
  12 has configfile => (
  13     is => 'ro',
  14     isa => File,
  15     coerce => 1,
  16     predicate => 'has_configfile',
  17 );
  18
  19 sub new_with_config {
  20     my ($class, %opts) = @_;
  21
  22     my $configfile;
  23
  24     if(defined $opts{configfile}) {
  25         $configfile = $opts{configfile}
  26     }
  27     else {
  28         my $cfmeta = $class->meta->find_attribute_by_name('configfile');
  29         $configfile = $cfmeta->default if $cfmeta->has_default;
  30     }
  31
  32     if(defined $configfile) {
  33         my $hash = $class->get_config_from_file($configfile);
  34
  35         no warnings 'uninitialized';
  36         croak "get_config_from_file($configfile) did not return a hash (got $hash)"
  37             unless ref $hash eq 'HASH';
  38
  39         %opts = (%$hash, %opts);
  40     }
  41
  42     $class->new(%opts);
  43 }
  44
  45 no Moose::Role; 1;
  46
  47 __END__
  48
  49 =pod
  50
  51 =head1 NAME
  52
  53 MooseX::ConfigFromFile - An abstract Moose role for setting attributes from a configfile
  54
  55 =head1 SYNOPSIS
  56
  57   ########
  58   ## A real role based on this abstract role:
  59   ########
  60
  61   package MooseX::SomeSpecificConfigRole;
  62   use Moose::Role;
  63
  64   with 'MooseX::ConfigFromFile';
  65
  66   use Some::ConfigFile::Loader ();
  67
  68   sub get_config_from_file {
  69     my ($class, $file) = @_;
  70
  71     my $options_hashref = Some::ConfigFile::Loader->load($file);
  72
  73     return $options_hashref;
  74   }
  75
  76
  77   ########
  78   ## A class that uses it:
  79   ########
  80   package Foo;
  81   use Moose;
  82   with 'MooseX::SomeSpecificConfigRole';
  83
  84   # optionally, default the configfile:
  85   has +configfile ( default => '/tmp/foo.yaml' );
  86
  87   # ... insert your stuff here ...
  88
  89   ########
  90   ## A script that uses the class with a configfile
  91   ########
  92
  93   my $obj = Foo->new_with_config(configfile => '/etc/foo.yaml', other_opt => 'foo');
  94
  95 =head1 DESCRIPTION
  96
  97 This is an abstract role which provides an alternate constructor for creating
  98 objects using parameters passed in from a configuration file.  The
  99 actual implementation of reading the configuration file is left to
 100 concrete subroles.
 101
 102 It declares an attribute C<configfile> and a class method C<new_with_config>,
 103 and requires that concrete roles derived from it implement the class method
 104 C<get_config_from_file>.
 105
 106 Attributes specified directly as arguments to C<new_with_config> supercede those
 107 in the configfile.
 108
 109 L<MooseX::Getopt> knows about this abstract role, and will use it if available
 110 to load attributes from the file specified by the commandline flag C<--configfile>
 111 during its normal C<new_with_options>.
 112
 113 =head1 Attributes
 114
 115 =head2 configfile
 116
 117 This is a L<Path::Class::File> object which can be coerced from a regular pathname
 118 string.  This is the file your attributes are loaded from.  You can add a default
 119 configfile in the class using the role and it will be honored at the appropriate time:
 120
 121   has +configfile ( default => '/etc/myapp.yaml' );
 122
 123 =head1 Class Methods
 124
 125 =head2 new_with_config
 126
 127 This is an alternate constructor, which knows to look for the C<configfile> option
 128 in its arguments and use that to set attributes.  It is much like L<MooseX::Getopts>'s
 129 C<new_with_options>.  Example:
 130
 131   my $foo = SomeClass->new_with_config(configfile => '/etc/foo.yaml');
 132
 133 Explicit arguments will overide anything set by the configfile.
 134
 135 =head2 get_config_from_file
 136
 137 This class method is not implemented in this role, but it is required of all subroles.
 138 Its two arguments are the classname and the configfile, and it is expected to return
 139 a hashref of arguments to pass to C<new()> which are sourced from the configfile.
 140
 141 =head2 meta
 142
 143 The Moose meta stuff, included here because otherwise pod tests fail sometimes
 144
 145 =head1 BUGS
 146
 147 =head1 AUTHOR
 148
 149 Brandon L. Black, E<lt>blblack@gmail.comE<gt>
 150
 151 =head1 LICENSE
 152
 153 This library is free software; you can redistribute it and/or modify
 154 it under the same terms as Perl itself.
 155
 156 =cut