lib/MooseX/ConfigFromFile.pm

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