1Config::MVP(3)        User Contributed Perl Documentation       Config::MVP(3)
2
3
4

NAME

6       Config::MVP - multivalue-property package-oriented configuration
7

VERSION

9       version 2.200011
10

SYNOPSIS

12       If you want a useful synopsis, consider this code which actually comes
13       from Config::MVP::Assembler:
14
15         my $assembler = Config::MVP::Assembler->new;
16
17         # Maybe you want a starting section:
18         my $section = $assembler->section_class->new({ name => '_' });
19         $assembler->sequence->add_section($section);
20
21         # 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
25         # Change to a new section...
26         $assembler->change_section($moniker);
27
28         # ...and add values to that section.
29         $assembler->add_value(x => 100);
30         $assembler->add_value(y => 200);
31
32       This doesn't make sense?  Well, read on.
33
34       (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

DESCRIPTION

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
42       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
50       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

EXAMPLE

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
61       Here's the user's configuration:
62
63         [Whitelist]
64         require_pgp = 1
65
66         file = whitelist-family
67         file = whitelist-friends
68         file = whitelist-work
69
70         [SpamFilter]
71         filterset = standard
72         max_score = 5
73         action    = bounce
74
75         [SpamFilter / SpamFilter_2]
76         filterset = aggressive
77         max_score = 5
78         action    = tag
79
80         [VerifyPGP]
81
82         [Deliver]
83         dest = Maildir
84
85       The user will end up with a sequence with five sections, which we can
86       represent something like this:
87
88         { 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
120       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
124       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
130       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
136       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
146   ...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
150         my $sequence = $deliveryboy->load_config;
151
152         for my $section ($sequence->sections) {
153           my $plugin = $section->package->new( $section->payload );
154           $deliveryboy->add_plugin( $section->name, $plugin );
155         }
156
157       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
160       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

WHAT NEXT?

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
172       mvp_aliases
173
174       This method should return a hashref of name remappings.  For example,
175       if it returned this hashref:
176
177         {
178           file => 'files',
179           path => 'files',
180         }
181
182       Then attempting to set either the "file" or "path" setting for the
183       section would actually set the "files" setting.
184
185       mvp_multivalue_args
186
187       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
190   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
197   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
204   Examples in the World
205       For examples of Config::MVP in use, you can look at Dist::Zilla or
206       App::Addex.
207

AUTHOR

209       Ricardo Signes <rjbs@cpan.org>
210

CONTRIBUTORS

212       ·   Alexandr Ciornii <alexchorny@gmail.com>
213
214       ·   George Hartzell <hartzell@alerce.com>
215
216       ·   Karen Etheridge <ether@cpan.org>
217
218       ·   Kent Fredric <kentfredric@gmail.com>
219
220       ·   Philippe Bruhat (BooK) <book@cpan.org>
221
223       This software is copyright (c) 2018 by Ricardo Signes.
224
225       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.
227
228
229
230perl v5.28.1                      2018-04-21                    Config::MVP(3)
Impressum