Layered.pm

filter: Statementstmt 92.1% 70 / 76 Branchbran 76.6% 23 / 30 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 12 / 12 Podpod 100% 2 / 2 totaltotal 89.1% 107 / 120 CC 21 SCAR 15.8
CC
21
Cov
88%
new
8.0
_merge
7.1
_load_source
4.4
CRAP 4.8
↑ Summary Layered/Source/ENV.pm »
1 package Config::Layered;
2 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 5 ▶use Storable qw( dclone );
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 5 our $VERSION = '0.000003'; # 0.0.3
8 5 $VERSION = eval $VERSION;
9  
10 47 ▶sub new {
Subroutine new: called CC=8 SCAR=20.8
Pod documented
11 47 my ( $class, %args ) = @_;
12 47 my $self = bless {}, $class;
13  
14 47 for ( qw( sources default merge ) ) {
15 141 ▶ $self->can($_) || $self->_build_accessor($_);
Branch: 1 branch
BranchTrueFalseTotal
$self->can($_) or $self->_build_accessor($_) 129 12 141
16 }
17  
18 47 for my $arg ( keys %args ) {
19 75 ▶ $self->_build_accessor( $arg ) unless $self->can($arg);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->can($arg) 1 74 75
20  
21 75 ▶ if ( $arg eq 'sources' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arg eq 'sources') { } 24 51 75
22 24 $self->$arg( $self->_normalize_sources($args{$arg}) );
23 } else {
24 51 $self->$arg( $args{$arg} );
25 }
26 }
27  
28 $self->default( {} )
29 47 ▶ unless $self->default;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->default 0 47 47
30  
31 47 ▶ $self->sources([
Branch: 1 branch
BranchTrueFalseTotal
unless $self->sources 23 24 47
32 [ 'ConfigAny' => {} ],
33 [ 'ENV' => {} ],
34 [ 'Getopt' => {} ],
35 ]) unless $self->sources;
36  
37 47 return $self;
38  
39 }
40  
41 94 ▶sub load_config {
Subroutine load_config: called CC=3 SCAR=11.0
Pod documented
42 94 my ( $self, @args ) = @_;
43  
44 # Allow to skip calling ->new()->load_config
45 94 ▶ return $self->new( @args )->load_config unless ref $self eq __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self eq __PACKAGE__ 47 47 94
46  
47 47 my $config = $self->default;
48  
49 47 for my $source ( @{ $self->sources } ) {
50 107 my $pkg = $self->_load_source( $source->[0] )
51 ->new( $self, $source->[1] );
52  
53 107 $config = $self->_merge( $config, dclone($pkg->get_config) );
54 }
55  
56 47 return $config;
57 }
58  
59 24 ▶sub _normalize_sources {
Subroutine _normalize_sources: called CC=3 SCAR=11.3
60 24 my ( $self, $sources ) = @_;
61  
62 24 my @new_sources;
63 24 ▶ while ( my $source = shift @{$sources} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $source = shift @{$sources;}) 38 24 62
64 38 ▶ if ( ref @{$self->{sources}}[0] eq 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref @{$$self{'sources'};}[0] eq 'HASH') { } 0 38 38
65 0 push @new_sources, [ $source, shift @{$self->{sources}} ];
66 } else {
67 38 push @new_sources, [ $source, {} ];
68 }
69 }
70 24 $self->{sources} = [@new_sources];
71 }
72  
73 13 ▶sub _build_accessor {
Subroutine _build_accessor: called CC=1 SCAR=0.0
74 13 my ( $self, $method ) = @_;
75
76 486 ▶ my $accessor = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
77 486 my $self = shift;
78 486 ▶ $self->{$method} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 98 388 486
79 486 return $self->{$method};
80 13 };
81 {
82 5 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
83 13 *$method = $accessor;
84 }
85 13 return ();
86 }
87  
88 107 ▶sub _load_source {
Subroutine _load_source: called CC=3 SCAR=14.8
89 107 my ( $self, $source ) = @_;
90
91 107 my $class = "Config::Layered::Source::$source";
92  
93 107 eval "require $class";
94 107 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 107 107
95 0 eval "require $source";
96 0 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) { } 0 0 0
97 0 die "Couldn't find $source or $class";
98 } else {
99 0 $class = $source;
100 }
101 }
102  
103 107 return $class;
104 }
105  
106 116 ▶sub _merge {
Subroutine _merge: called CC=7 SCAR=19.5
107 116 my ( $self, $content, $data ) = @_;
108  
109 # Allow this method to be replaced by a coderef.
110 116 ▶ return $self->merge->( $content, $data ) if ref $self->merge eq 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->merge eq "CODE" 0 116 116
111  
112 116 ▶ if ( ref $content eq 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content eq "HASH") 116 0 116
113 116 for my $key ( keys %$content ) {
114 279 ▶ if ( ref $content->{$key} eq 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $content->{$key} eq 'HASH') { } 9 270 279
115 9 $content->{$key} = $self->_merge($content->{$key}, $data->{$key});
116 9 delete $data->{$key};
117 } else {
118 270 ▶ $content->{$key} = delete $data->{$key} if exists $data->{$key};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$key} 92 178 270
119 }
120 }
121 # Unhandled keys (simply do injection on uneven rhs structure)
122 116 for my $key ( keys %$data ) {
123 10 $content->{$key} = delete $data->{$key};
124 }
125 }
126  
127 116 return $content;
128 }
129  
130 5 1;
131  
132 =head1 NAME
133  
134 Config::Layered - Layered config from files, command line, and other sources.
135  
136 =head1 DESCRIPTION
137  
138 Config::Layered aims to make it easy for programmers, operations teams and those
139 who run the programs to have the configuration methods they prefer with one simple
140 interface.
141  
142 By default options will be taken from the program source code itself, then
143 -- if provided -- a configuration file, and finally command-line options.
144  
145 =head1 SYNOPSIS
146  
147 By default options will be taken from the program source code itself, then
148 merged -- if provided -- with a configuration file, then environment variables
149 in the form of C<CONFIG_$OPTIONNAME> and finally command-line options.
150  
151 my $config = Config::Layered->load_config(
152 file => "/etc/myapp",
153 default => {
154 verbose => 0,
155 run => 1,
156 input => "/tmp/to_process",
157 output => "/tmp/done_processing",
158 plugins => [ qw( process ) ]
159 },
160 );
161  
162 Given the above, the data structure would look like:
163  
164
165 {
166 verbose => 0,
167 run => 1,
168 input => "/tmp/to_process",
169 output => "/tmp/done_processing",
170 plugins => [ qw( process ) ]
171 }
172  
173 Provided a file, C</etc/myapp.yml> with the line C<input: /tmp/pending_process>
174 the data structure would look like:
175  
176 {
177 verbose => 0,
178 run => 1,
179 input => "/tmp/pending_process",
180 output => "/tmp/done_processing",
181 plugins => [ qw( process ) ]
182 }
183  
184 Provided the command line arguments C<--norun --verbose --output /tmp/completed_process>
185 -- in addition to the configuration file above -- the data structure would look like:
186  
187 {
188 verbose => 1,
189 run => 0,
190 input => "/tmp/pending_process",
191 output => "/tmp/completed_process",
192 plugins => [ qw( process ) ]
193 }
194  
195 Provided the environment variable C<CONFIG_INPUT="/tmp/awaiting_process>
196 -- in addition to the configuration file above -- the data structure would look like:
197  
198 {
199 verbose => 1,
200 run => 0,
201 input => "/tmp/awaiting_process",
202 output => "/tmp/completed_process",
203 plugins => [ qw( process ) ]
204 }
205  
206 =head1 METHODS
207  
208 =head2 load_config
209  
210 =over 4
211  
212 =item * file
213  
214 By default the file given here will be loaded by Config::Any and the data
215 structure provided will be merged ontop of the default data structure.
216  
217 Example:
218  
219 file => "/etc/myapp",
220  
221 This will atempt to load C</etc/myapp> as a stem in L<Config::Any>, meanig
222 files like C</etc/myapp.yml>, C</etc/myapp.conf>, C</etc/myapp.ini> and such
223 will be checked for existence.
224  
225 =item * default
226  
227 This is the default data structure that L<Config::Layered> will load.
228  
229 Example:
230  
231 default => {
232 verbose => 1,
233 run => 0,
234 },
235  
236 The above data structure will have C<$config-E<gt>{verbose}> set to 1, and
237 C<$config-E<gt>{run}> set to 0 if there are no configuration files, and no
238 command line options used.
239  
240 =item * sources
241  
242 A source returns an instance of configuration to merge with previously loaded
243 sources. Following a source a specific configuration may be sent the to source.
244  
245 Example
246  
247 sources => [ 'ConfigAny', { file => "/etc/myapp }, 'Getopts' ]
248  
249 In the above example, L<Config::Layered::Sources::ConfigAny> will be loaded,
250 and the following hashref will be sent to the source. This allows source-specific
251 configuration to be used. For more information on creating a soure, see
252 L</CREATING A SOURCE>.
253  
254 =item * merge
255  
256 You may provide a method as a coderef that will be used to merge the data
257 structures returned from a source together. By default the method used favors
258 the newer sources that are loaded.
259  
260 Example:
261  
262 merge => sub {
263 my ( $lhs, $rhs ) = @_;
264  
265 ... Do something with the data structures ...
266  
267 return $merged_data_structure;
268 }
269  
270 =back
271  
272 =head1 INCLUDED SOURCES
273  
274 Each source provides its own documentation for source-specific options,
275 please see the POD pages for the source you're interested in learning more
276 about
277  
278 =over4
279  
280 =item * L<Config::Layered::Source::ConfigAny> is used for configuration files
281  
282 =item * L<Config::Layered::Source::ENV> is used for environment variables
283  
284 =item * L<Config::Layered::Sources::Getopt> is used for command-line options
285  
286 =back
287  
288 =head1 CREATING A SOURCE
289  
290 If you would like to create your own source to provide a configuration method,
291 the following documents the creation of a source. You can also check
292 L<Config::Layered::Source::ConfigAny> for a source that is used by default.
293  
294 =head2 WRITING THE SOURCE CLASS
295  
296 A source requires at least two methods, C<new> and C<get_config>.
297  
298 =over 4
299  
300 =item * new
301  
302 The C<new> method should take the following arguments and return an instance of itself:
303  
304 C<$layered> is the instance of L<Config::Layered> which called it. You may look at all
305 arguments given at construction of the instance.
306  
307 C<$arguments> is the source-specific configuration information. You should B<NOT> parse
308 C<$config-E<gt>sources> yourself, instead look at C<$arguments>, and optionally fall-back
309 to using information in C<$layered> to make decisions.
310  
311 sub new {
312 my ( $class, $layered, $args ) = @_;
313 my $self = bless { layered => $layered, args => $args }, $class;
314 return $self;
315 }
316  
317 =item * get_config
318  
319 The C<get_config> method is given no arguments, and expected to return a hashref that
320 is merged with previous sources, and will be merged over by future sources.
321  
322 Example:
323  
324 sub get_config {
325 my ( $self ) = @_;
326
327 # Load a specific file with Config::Any
328 if ( exists $self->{args}->{file} ) {
329 return Config::Any->load_file( { file => $self->{args}->{file} );
330 # Otherwise, load the global file with Config::Any
331 } elsif ( exists $config->{layered}->{file} )
332 return Config::Any->load_file( { file => $self->{layered}->{file} );
333 }
334 # No configuration file, our source is being ignored.
335 return {};
336 }
337  
338 =back
339  
340 =head2 GLOBAL OR SOURCE ARGUMENTS?
341  
342 Config::Layered will accept any constructor arguments and a source may
343 look at C<$layered> to check them. However, source instance specific arguments
344 are also available. Both should be supported under the following reasoning:
345  
346 Suppose that I would like to load a global file, but I would also like to merge arguments
347 from a configuration file in my home directory. With only global arguments this isn't
348 possible. With source-specific arguments, this is easily enabled:
349  
350 my $config = Config::Layered->get_config(
351 sources => [
352 'ConfigAny', { file => "/etc/myapp" },
353 'ConfigAny', { file => $ENV{"HOME"} . "/.myapp",
354 ] ,
355 );
356  
357 Global arguments are useful in the context that writing out the data structure for the
358 default use-cases and single-use sources can be tedious.
359  
360 =head1 AUTHOR
361  
362 =over 4
363  
364 =item * Kaitlyn Parkhurst (SymKat) I<E<lt>symkat@symkat.comE<gt>> (L<http://symkat.com/>)
365  
366 =back
367  
368 =head1 CONTRIBUTORS
369  
370 =head1 COPYRIGHT
371  
372 Copyright (c) 2012 the Config::Layered L</AUTHOR> and L</CONTRIBUTORS> as listed
373 above.
374  
375 =head1 LICENSE
376  
377 This library is free software and may be distributed under the same terms as
378 perl itself.
379  
380 =head1 AVAILABILITY
381  
382 The latest version of this software is available at
383 L<https://github.com/symkat/Config-Layered>
384  
↑ Summary Layered/Source/ENV.pm »