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