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