From: Karen Etheridge <ether@cpan.org>
Date: Sun, 10 Feb 2013 00:25:04 +0000 (-0800)
Subject: MooseX-ConfigFromFile-0.08
X-Git-Tag: v0.08^0
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=7b24ed16bbfca5ed2dc3f3dd706352766cb661f0;p=gitmo%2FMooseX-ConfigFromFile.git

MooseX-ConfigFromFile-0.08

          - allow configfiles called "0"
          - configfile value now passed through to new()
          - new _get_default_configfile method added, which consumers can
            override to provide a default value without having to redefine the
            attribute itself (via RT#79746) -- PLEASE READ THE DOCUMENTATION
            if you override the configfile attribute!
---

diff --git a/Changes b/Changes
index 1701b13..8b08c65 100644
--- a/Changes
+++ b/Changes
@@ -1,6 +1,8 @@
 Revision history for {{$dist->name}}
 
 {{$NEXT}}
+
+0.08      2013-02-09 16:24:27 PST-0800 (Karen Etheridge)
           - allow configfiles called "0"
           - configfile value now passed through to new()
           - new _get_default_configfile method added, which consumers can
diff --git a/README.md b/README.md
index e69de29..65e7d8d 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,121 @@
+# NAME
+
+MooseX::ConfigFromFile - An abstract Moose role for setting attributes from a configfile
+
+# SYNOPSIS
+
+    ########
+    ## A real role based on this abstract role:
+    ########
+
+    package MooseX::SomeSpecificConfigRole;
+    use Moose::Role;
+
+    with 'MooseX::ConfigFromFile';
+
+    use Some::ConfigFile::Loader ();
+
+    sub get_config_from_file {
+      my ($class, $file) = @_;
+
+    my $options_hashref = Some::ConfigFile::Loader->load($file);
+
+      return $options_hashref;
+    }
+
+
+
+    ########
+    ## A class that uses it:
+    ########
+    package Foo;
+    use Moose;
+    with 'MooseX::SomeSpecificConfigRole';
+
+    # optionally, default the configfile:
+    sub _get_default_configfile { '/tmp/foo.yaml' }
+
+    # ... insert your stuff here ...
+
+    ########
+    ## A script that uses the class with a configfile
+    ########
+
+    my $obj = Foo->new_with_config(configfile => '/etc/foo.yaml', other_opt => 'foo');
+
+# DESCRIPTION
+
+This is an abstract role which provides an alternate constructor for creating
+objects using parameters passed in from a configuration file.  The
+actual implementation of reading the configuration file is left to
+concrete sub-roles.
+
+It declares an attribute `configfile` and a class method `new_with_config`,
+and requires that concrete roles derived from it implement the class method
+`get_config_from_file`.
+
+Attributes specified directly as arguments to `new_with_config` supersede those
+in the configfile.
+
+[MooseX::Getopt](http://search.cpan.org/perldoc?MooseX::Getopt) knows about this abstract role, and will use it if available
+to load attributes from the file specified by the command line flag `--configfile`
+during its normal `new_with_options`.
+
+# Attributes
+
+## configfile
+
+This is a [Path::Tiny](http://search.cpan.org/perldoc?Path::Tiny) object which can be coerced from a regular path
+string or any object that supports stringification.
+This is the file your attributes are loaded from.  You can add a default
+configfile in the consuming class and it will be honored at the appropriate
+time; see below at ["\_get\_default\_configfile"](#\_get\_default\_configfile).
+
+If you have [MooseX::Getopt](http://search.cpan.org/perldoc?MooseX::Getopt) installed, this attribute will also have the
+`Getopt` trait supplied, so you can also set the configfile from the
+command line.
+
+# Class Methods
+
+## new\_with\_config
+
+This is an alternate constructor, which knows to look for the `configfile` option
+in its arguments and use that to set attributes.  It is much like [MooseX::Getopts](http://search.cpan.org/perldoc?MooseX::Getopts)'s
+`new_with_options`.  Example:
+
+    my $foo = SomeClass->new_with_config(configfile => '/etc/foo.yaml');
+
+Explicit arguments will override anything set by the configfile.
+
+## get\_config\_from\_file
+
+This class method is not implemented in this role, but it is required of all
+classes or roles that consume this role.
+Its two arguments are the class name and the configfile, and it is expected to return
+a hashref of arguments to pass to `new()` which are sourced from the configfile.
+
+## \_get\_default\_configfile
+
+This class method returns nothing by default, but can and should be redefined
+in a consuming class to return the default value of the configfile (if not
+passed into the constructor explicitly).
+
+# COPYRIGHT
+
+Copyright (c) - the MooseX::ConfigFromFile "AUTHOR" and "CONTRIBUTORS" as listed below.
+
+# AUTHOR
+
+Brandon L. Black, <blblack@gmail.com>
+
+# CONTRIBUTORS
+
+- Tomas Doran
+- Karen Etheridge
+- Chris Prather
+- Zbigniew Lukasiak
+
+# LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.