lib/MooseX/ConfigFromFile.pm

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