Commit | Line | Data |
7b24ed16 |
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 returns nothing by default, but can and should be redefined |
100 | in a consuming class 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. |