From: Karen Etheridge 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, + +# 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.