MVP.pm untested

filter: Statementstmt 0.0% 0 / 7 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 2 Podpod n/a totaltotal 0.0% 0 / 9 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
1 package Config::MVP 2.200015;
2 # ABSTRACT: multivalue-property package-oriented configuration
3  
4 use strict;
5 use warnings;
6  
7 #pod =head1 SYNOPSIS
8 #pod
9 #pod If you want a useful synopsis, consider this code which actually comes from
10 #pod L<Config::MVP::Assembler|Config::MVP::Assembler>:
11 #pod
12 #pod my $assembler = Config::MVP::Assembler->new;
13 #pod
14 #pod # Maybe you want a starting section:
15 #pod my $section = $assembler->section_class->new({ name => '_' });
16 #pod $assembler->sequence->add_section($section);
17 #pod
18 #pod # We'll add some values, which will go to the starting section:
19 #pod $assembler->add_value(x => 10);
20 #pod $assembler->add_value(y => 20);
21 #pod
22 #pod # Change to a new section...
23 #pod $assembler->change_section($moniker);
24 #pod
25 #pod # ...and add values to that section.
26 #pod $assembler->add_value(x => 100);
27 #pod $assembler->add_value(y => 200);
28 #pod
29 #pod This doesn't make sense? Well, read on.
30 #pod
31 #pod (You can also read the L<2009 RJBS Advent Calendar
32 #pod article|http://advent.rjbs.manxome.org/2009/2009-12-20.html> on Config::MVP!)
33 #pod
34 #pod =head1 DESCRIPTION
35 #pod
36 #pod MVP is a mechanism for loading configuration (or other information) for
37 #pod libraries. It doesn't read a file or a database. It's a helper for things
38 #pod that do.
39 #pod
40 #pod The idea is that you end up with a
41 #pod L<Config::MVP::Sequence|Config::MVP::Sequence> object, and that you can use
42 #pod that object to fully configure your library or application. The sequence will
43 #pod contain a bunch of L<Config::MVP::Section|Config::MVP::Section> objects, each
44 #pod of which is meant to provide configuration for a part of your program. Most of
45 #pod these sections will be directly related to a Perl library that you'll use as a
46 #pod plugin or helper. Each section will have a name, and every name in the
47 #pod sequence will be unique.
48 #pod
49 #pod This is a pretty abstract set of behaviors, so we'll provide some more concrete
50 #pod examples that should help explain how things work.
51 #pod
52 #pod =head1 EXAMPLE
53 #pod
54 #pod Imagine that we've got a program called DeliveryBoy that accepts mail and does
55 #pod stuff with it. The "stuff" is entirely up to the user's configuration. He can
56 #pod set up plugins that will be used on the message. He writes a config file that's
57 #pod read by L<Config::MVP::Reader::INI|Config::MVP::Reader::INI>, which is a thin
58 #pod wrapper around Config::MVP used to load MVP-style config from F<INI> files.
59 #pod
60 #pod Here's the user's configuration:
61 #pod
62 #pod [Whitelist]
63 #pod require_pgp = 1
64 #pod
65 #pod file = whitelist-family
66 #pod file = whitelist-friends
67 #pod file = whitelist-work
68 #pod
69 #pod [SpamFilter]
70 #pod filterset = standard
71 #pod max_score = 5
72 #pod action = bounce
73 #pod
74 #pod [SpamFilter / SpamFilter_2]
75 #pod filterset = aggressive
76 #pod max_score = 5
77 #pod action = tag
78 #pod
79 #pod [VerifyPGP]
80 #pod
81 #pod [Deliver]
82 #pod dest = Maildir
83 #pod
84 #pod The user will end up with a sequence with five sections, which we can represent
85 #pod something like this:
86 #pod
87 #pod { name => 'Whitelist',
88 #pod package => 'DeliveryBoy::Plugin::Whitelist',
89 #pod payload => {
90 #pod require_pgp => 1,
91 #pod files => [ qw(whitelist-family whitelist-friends whitelist-work) ]
92 #pod },
93 #pod },
94 #pod { name => 'SpamFilter',
95 #pod package => 'DeliveryBoy::Plugin::SpamFilter',
96 #pod payload => {
97 #pod filterset => 'standard',
98 #pod max_score => 5,
99 #pod action => 'bounce',
100 #pod }
101 #pod },
102 #pod { name => 'SpamFilter_2',
103 #pod package => 'DeliveryBoy::Plugin::SpamFilter',
104 #pod payload => {
105 #pod filterset => 'aggressive',
106 #pod max_score => 5,
107 #pod action => 'tag',
108 #pod },
109 #pod },
110 #pod { name => 'VerifyPGP',
111 #pod package => 'DeliveryBoy::Plugin::VerifyPGP',
112 #pod payload => { },
113 #pod },
114 #pod { name => 'Deliver',
115 #pod package => 'DeliveryBoy::Plugin::Deliver',
116 #pod payload => { dest => 'Maildir' },
117 #pod },
118 #pod
119 #pod The INI reader uses L<Config::MVP::Assembler|Config::MVP::Assembler> to build
120 #pod up configuration section by section as it goes, so that's how we'll talk about
121 #pod what's going on.
122 #pod
123 #pod Every section of the config file was converted into a section in the MVP
124 #pod sequence. Each section has a unique name, which defaults to the name of the
125 #pod INI section. Each section is also associated with a package, which was
126 #pod expanded from the INI section name. The way that names are expanded can be
127 #pod customized by subclassing the assembler.
128 #pod
129 #pod Every section also has a payload -- a hashref of settings. Note that every
130 #pod entry in every payload is a simple scalar except for one. The C<files> entry
131 #pod for the Whitelist section is an arrayref. Also, note that while it appears as
132 #pod C<files> in the final output, it was given as C<file> in the input.
133 #pod
134 #pod Config::MVP provides a mechanism by which packages can define aliases for
135 #pod configuration names and an indication of what names correspond to "multi-value
136 #pod parameters." (That's part of the meaning of the name "MVP.") When the MVP
137 #pod assembler is told to start a section for C<Whitelist> it expands the section
138 #pod name, loads the package, and inspects it for aliases and multivalue parameters.
139 #pod Then if multiple entries for a non-multivalue parameter are given, an exception
140 #pod can be raised. Multivalue parameters are always pushed onto arrayrefs and
141 #pod non-multivalue parameters are left as found.
142 #pod
143 #pod =head2 ...so what now?
144 #pod
145 #pod So, once our DeliveryBoy program has loaded its configuration, it needs to
146 #pod initialize its plugins. It can do something like the following:
147 #pod
148 #pod my $sequence = $deliveryboy->load_config;
149 #pod
150 #pod for my $section ($sequence->sections) {
151 #pod my $plugin = $section->package->new( $section->payload );
152 #pod $deliveryboy->add_plugin( $section->name, $plugin );
153 #pod }
154 #pod
155 #pod That's it! In fact, allowing this very, very block of code to load
156 #pod configuration and initialize plugins is the goal of Config::MVP.
157 #pod
158 #pod The one thing not depicted is the notion of a "root section" that you might
159 #pod expect to see in an INI file. This can be easily handled by starting your
160 #pod assembler off with a pre-built section where root settings will end up. For
161 #pod more information on this, look at the docs for the specific components.
162 #pod
163 #pod =head1 WHAT NEXT?
164 #pod
165 #pod =head2 Making Packages work with MVP
166 #pod
167 #pod Any package can be used as part of an MVP section. Packages can provide some
168 #pod methods to help MVP work with them. It isn't a problem if they are not defined
169 #pod
170 #pod =head3 mvp_aliases
171 #pod
172 #pod This method should return a hashref of name remappings. For example, if it
173 #pod returned this hashref:
174 #pod
175 #pod {
176 #pod file => 'files',
177 #pod path => 'files',
178 #pod }
179 #pod
180 #pod Then attempting to set either the "file" or "path" setting for the section
181 #pod would actually set the "files" setting.
182 #pod
183 #pod =head3 mvp_multivalue_args
184 #pod
185 #pod This method should return a list of setting names that may have multiple values
186 #pod and that will always be stored in an arrayref.
187 #pod
188 #pod =head2 The Assembler
189 #pod
190 #pod L<Config::MVP::Assembler|Config::MVP::Assembler> is a state machine that makes
191 #pod it easy to build up your MVP-style configuration by firing off a series of
192 #pod events: new section, new setting, etc. You might want to subclass it to change
193 #pod the class of sequence or section that's used or to change how section names are
194 #pod expanded into packages.
195 #pod
196 #pod =head2 Sequences and Sections
197 #pod
198 #pod L<Config::MVP::Sequence|Config::MVP::Sequence> and
199 #pod L<Config::MVP::Section|Config::MVP::Section> are the two most important classes
200 #pod in MVP. They represent the overall configuration and each section of the
201 #pod configuration, respectively. They're both fairly simple classes, and you
202 #pod probably won't need to subclass them, but it's easy.
203 #pod
204 #pod =head2 Examples in the World
205 #pod
206 #pod For examples of Config::MVP in use, you can look at L<Dist::Zilla|Dist::Zilla>
207 #pod or L<App::Addex|App::Addex>.
208 #pod
209 #pod =cut
210  
211 1;
212  
213 __END__