| 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__ |