README.md

   1 # NAME
   2
   3 MooseX::ConfigFromFile - An abstract Moose role for setting attributes from a configfile
   4
   5 # SYNOPSIS
   6
   7     ########
   8     ## A real role based on this abstract role:
   9     ########
  10
  11     package MooseX::SomeSpecificConfigRole;
  12     use Moose::Role;
  13
  14     with 'MooseX::ConfigFromFile';
  15
  16     use Some::ConfigFile::Loader ();
  17
  18     sub get_config_from_file {
  19       my ($class, $file) = @_;
  20
  21     my $options_hashref = Some::ConfigFile::Loader->load($file);
  22
  23       return $options_hashref;
  24     }
  25
  26
  27
  28     ########
  29     ## A class that uses it:
  30     ########
  31     package Foo;
  32     use Moose;
  33     with 'MooseX::SomeSpecificConfigRole';
  34
  35     # optionally, default the configfile:
  36     sub _get_default_configfile { '/tmp/foo.yaml' }
  37
  38     # ... insert your stuff here ...
  39
  40     ########
  41     ## A script that uses the class with a configfile
  42     ########
  43
  44     my $obj = Foo->new_with_config(configfile => '/etc/foo.yaml', other_opt => 'foo');
  45
  46 # DESCRIPTION
  47
  48 This is an abstract role which provides an alternate constructor for creating
  49 objects using parameters passed in from a configuration file.  The
  50 actual implementation of reading the configuration file is left to
  51 concrete sub-roles.
  52
  53 It declares an attribute `configfile` and a class method `new_with_config`,
  54 and requires that concrete roles derived from it implement the class method
  55 `get_config_from_file`.
  56
  57 Attributes specified directly as arguments to `new_with_config` supersede those
  58 in the configfile.
  59
  60 [MooseX::Getopt](http://search.cpan.org/perldoc?MooseX::Getopt) knows about this abstract role, and will use it if available
  61 to load attributes from the file specified by the command line flag `--configfile`
  62 during its normal `new_with_options`.
  63
  64 # Attributes
  65
  66 ## configfile
  67
  68 This is a [Path::Tiny](http://search.cpan.org/perldoc?Path::Tiny) object which can be coerced from a regular path
  69 string or any object that supports stringification.
  70 This is the file your attributes are loaded from.  You can add a default
  71 configfile in the consuming class and it will be honored at the appropriate
  72 time; see below at ["\_get\_default\_configfile"](#\_get\_default\_configfile).
  73
  74 If you have [MooseX::Getopt](http://search.cpan.org/perldoc?MooseX::Getopt) installed, this attribute will also have the
  75 `Getopt` trait supplied, so you can also set the configfile from the
  76 command line.
  77
  78 # Class Methods
  79
  80 ## new\_with\_config
  81
  82 This is an alternate constructor, which knows to look for the `configfile` option
  83 in its arguments and use that to set attributes.  It is much like [MooseX::Getopts](http://search.cpan.org/perldoc?MooseX::Getopts)'s
  84 `new_with_options`.  Example:
  85
  86     my $foo = SomeClass->new_with_config(configfile => '/etc/foo.yaml');
  87
  88 Explicit arguments will override anything set by the configfile.
  89
  90 ## get\_config\_from\_file
  91
  92 This class method is not implemented in this role, but it is required of all
  93 classes or roles that consume this role.
  94 Its two arguments are the class name and the configfile, and it is expected to return
  95 a hashref of arguments to pass to `new()` which are sourced from the configfile.
  96
  97 ## \_get\_default\_configfile
  98
  99 This class method is not implemented in this role, but can and should be defined
 100 in a consuming class or role to return the default value of the configfile (if not
 101 passed into the constructor explicitly).
 102
 103 # COPYRIGHT
 104
 105 Copyright (c) - the MooseX::ConfigFromFile "AUTHOR" and "CONTRIBUTORS" as listed below.
 106
 107 # AUTHOR
 108
 109 Brandon L. Black, <blblack@gmail.com>
 110
 111 # CONTRIBUTORS
 112
 113 - Tomas Doran
 114 - Karen Etheridge
 115 - Chris Prather
 116 - Zbigniew Lukasiak
 117
 118 # LICENSE
 119
 120 This library is free software; you can redistribute it and/or modify
 121 it under the same terms as Perl itself.