1Config::MVP(3) User Contributed Perl Documentation Config::MVP(3)
2
6 Config::MVP - multivalue-property package-oriented configuration
7
9 version 2.200011
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 (You can also read the 2009 RJBS Advent Calendar article
35 <http://advent.rjbs.manxome.org/2009/2009-12-20.html> on Config::MVP!)
36
38 MVP is a mechanism for loading configuration (or other information) for
39 libraries. It doesn't read a file or a database. It's a helper for
40 things that do.
41 The idea is that you end up with a Config::MVP::Sequence object, and
43 that you can use that object to fully configure your library or
44 application. The sequence will contain a bunch of Config::MVP::Section
45 objects, each of which is meant to provide configuration for a part of
46 your program. Most of these sections will be directly related to a
47 Perl library that you'll use as a plugin or helper. Each section will
48 have a name, and every name in the sequence will be unique.
49 This is a pretty abstract set of behaviors, so we'll provide some more
51 concrete examples that should help explain how things work.
52
54 Imagine that we've got a program called DeliveryBoy that accepts mail
55 and does stuff with it. The "stuff" is entirely up to the user's
56 configuration. He can set up plugins that will be used on the message.
57 He writes a config file that's read by Config::MVP::Reader::INI, which
58 is a thin wrapper around Config::MVP used to load MVP-style config from
59 INI files.
60 Here's the user's configuration:
62 [Whitelist]
64 require_pgp = 1
65 file = whitelist-family
67 file = whitelist-friends
68 file = whitelist-work
69 [SpamFilter]
71 filterset = standard
72 max_score = 5
73 action = bounce
74 [SpamFilter / SpamFilter_2]
76 filterset = aggressive
77 max_score = 5
78 action = tag
79 [VerifyPGP]
81 [Deliver]
83 dest = Maildir
84 The user will end up with a sequence with five sections, which we can
86 represent something like this:
87 { name => 'Whitelist',
89 package => 'DeliveryBoy::Plugin::Whitelist',
90 payload => {
91 require_pgp => 1,
92 files => [ qw(whitelist-family whitelist-friends whitelist-work) ]
93 },
94 },
95 { name => 'SpamFilter',
96 package => 'DeliveryBoy::Plugin::SpamFilter',
97 payload => {
98 filterset => 'standard',
99 max_score => 5,
100 action => 'bounce',
101 }
102 },
103 { name => 'SpamFilter_2',
104 package => 'DeliveryBoy::Plugin::SpamFilter',
105 payload => {
106 filterset => 'aggressive',
107 max_score => 5,
108 action => 'tag',
109 },
110 },
111 { name => 'VerifyPGP',
112 package => 'DeliveryBoy::Plugin::VerifyPGP',
113 payload => { },
114 },
115 { name => 'Deliver',
116 package => 'DeliveryBoy::Plugin::Deliver',
117 payload => { dest => 'Maildir' },
118 },
119 The INI reader uses Config::MVP::Assembler to build up configuration
121 section by section as it goes, so that's how we'll talk about what's
122 going on.
123 Every section of the config file was converted into a section in the
125 MVP sequence. Each section has a unique name, which defaults to the
126 name of the INI section. Each section is also associated with a
127 package, which was expanded from the INI section name. The way that
128 names are expanded can be customized by subclassing the assembler.
129 Every section also has a payload -- a hashref of settings. Note that
131 every entry in every payload is a simple scalar except for one. The
132 "files" entry for the Whitelist section is an arrayref. Also, note
133 that while it appears as "files" in the final output, it was given as
134 "file" in the input.
135 Config::MVP provides a mechanism by which packages can define aliases
137 for configuration names and an indication of what names correspond to
138 "multi-value parameters." (That's part of the meaning of the name
139 "MVP.") When the MVP assembler is told to start a section for
140 "Whitelist" it expands the section name, loads the package, and
141 inspects it for aliases and multivalue parameters. Then if multiple
142 entries for a non-multivalue parameter are given, an exception can be
143 raised. Multivalue parameters are always pushed onto arrayrefs and
144 non-multivalue parameters are left as found.
145 ...so what now?
147 So, once our DeliveryBoy program has loaded its configuration, it needs
148 to initialize its plugins. It can do something like the following:
149 my $sequence = $deliveryboy->load_config;
151 for my $section ($sequence->sections) {
153 my $plugin = $section->package->new( $section->payload );
154 $deliveryboy->add_plugin( $section->name, $plugin );
155 }
156 That's it! In fact, allowing this very, very block of code to load
158 configuration and initialize plugins is the goal of Config::MVP.
159 The one thing not depicted is the notion of a "root section" that you
161 might expect to see in an INI file. This can be easily handled by
162 starting your assembler off with a pre-built section where root
163 settings will end up. For more information on this, look at the docs
164 for the specific components.
165
167 Making Packages work with MVP
168 Any package can be used as part of an MVP section. Packages can
169 provide some methods to help MVP work with them. It isn't a problem if
170 they are not defined
171 mvp_aliases
173 This method should return a hashref of name remappings. For example,
175 if it returned this hashref:
176 {
178 file => 'files',
179 path => 'files',
180 }
181 Then attempting to set either the "file" or "path" setting for the
183 section would actually set the "files" setting.
184 mvp_multivalue_args
186 This method should return a list of setting names that may have
188 multiple values and that will always be stored in an arrayref.
189 The Assembler
191 Config::MVP::Assembler is a state machine that makes it easy to build
192 up your MVP-style configuration by firing off a series of events: new
193 section, new setting, etc. You might want to subclass it to change the
194 class of sequence or section that's used or to change how section names
195 are expanded into packages.
196 Sequences and Sections
198 Config::MVP::Sequence and Config::MVP::Section are the two most
199 important classes in MVP. They represent the overall configuration and
200 each section of the configuration, respectively. They're both fairly
201 simple classes, and you probably won't need to subclass them, but it's
202 easy.
203 Examples in the World
205 For examples of Config::MVP in use, you can look at Dist::Zilla or
206 App::Addex.
207
209 Ricardo Signes <rjbs@cpan.org>
210
212 · Alexandr Ciornii <alexchorny@gmail.com>
213 · George Hartzell <hartzell@alerce.com>
215 · Karen Etheridge <ether@cpan.org>
217 · Kent Fredric <kentfredric@gmail.com>
219 · Philippe Bruhat (BooK) <book@cpan.org>
221
223 This software is copyright (c) 2018 by Ricardo Signes.
224 This is free software; you can redistribute it and/or modify it under
226 the same terms as the Perl 5 programming language system itself.
227perl v5.32.0 2020-07-28 Config::MVP(3)