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