1Config::MVP::Slicer(3)User Contributed Perl DocumentationConfig::MVP::Slicer(3)
2
6 Config::MVP::Slicer - Extract embedded plugin config from parent config
7
9 version 0.303
10
12 my $slicer = Config::MVP::Slicer->new({
13 config => $parent->config,
14 });
15 # extract a hashref from the parent config without modifying the plugin
17 my $plugin_config = $slicer->slice($plugin);
18 # from plugin bundles:
20 my $plugin_spec = ['Name', 'Package::Name', {default => 'config'}];
21 # update the hashref
22 $slicer->merge($plugin_spec);
23 # with object instances:
25 my $plugger = App::Plugin::Plugger->new({some => 'config'});
26 # update 'rw' attributes
27 $slicer->merge($plugger);
28
30 This can be used to extract embedded configurations for other plugins
31 out of larger (parent) configurations.
32 A example where this can be useful is plugin bundles (see
34 Config::MVP::Assembler::WithBundles).
35 A bundle loads other plugins with a default configuration that works
37 most of the time, but sometimes you wish you could customize the
38 configuration for one of those plugins without having to remove the
39 plugin from the bundle and re-specify it separately.
40 # mvp config file
42 [@MyBundle]
43 Other::Plugin.setting = new value
44 Now you can accept customizations to plugins into your bundle config
46 and separate them out using this module.
47
49 config
50 This is the main/parent configuration hashref that contains embedded
51 plugin configurations.
52 match_name
54 This is coderef that determines if a configuration line matches a
55 plugin's name.
56 It can be customized by passing an alternate subroutine reference to
58 the constructor.
59 The sub will receive two arguments:
61 • The plugin name portion of the configuration line
63 • The name of the plugin being worked on (provided to "slice", for
65 instance).
66 The default returns true if the current plugin name matches the name
68 from the config line regardless of any leading "@Bundle/" prefixes in
69 the plugin name (as this is a common convention for bundles).
70 Obviously if the "@Bundle/" prefix is specified in the configuration
72 then it is required to be there for the default sub to match (but
73 multiple other "@Bundle/" prefixes will be allowed before it).
74 # configuration line: "Foo.attr = value"
76 $slicer->match_name("Foo", "Foo"); # true
78 $slicer->match_name("Foo", "@Bar/Foo"); # true
79 $slicer->match_name("Foo", "Bar"); # false
80 # configuration line: "@Bar/Foo.attr = value"
82 $slicer->match_name("@Bar/Foo", "Foo"); # false
84 $slicer->match_name("@Bar/Foo", "@Bar/Foo"); # true
85 $slicer->match_name("@Bar/Foo", "@Baz/@Bar/Foo"); # true
86 $slicer->match_name("@Bar/Foo", "@Baz/Foo"); # false
87 Subclasses can define "_build_match_name" (which should return a "sub")
89 to overwrite the default.
90 match_package
92 This works like "match_name" except that the configuration line is
93 compared to the plugin's package (class).
94 The default returns true if the two values are equal and false
96 otherwise.
97 If you want to match by package rather than name and you expand
99 packages with (for example) a string prefix you may need to set this to
100 something like:
101 match_package => sub { rewrite_prefix($_[0]) eq $_[1] }
103 Subclasses can define "_build_match_package" (which should return a
105 "sub") to overwrite the default.
106 prefix
108 Regular expression that should match at the beginning of a key before
109 the module name and attribute:
110 # prefix => 'dynamic\.'
112 # { 'dynamic.Module::Name.attr' => 'value' }
113 This can be a string or a compiled regular expression ("qr//").
115 The default is no prefix (empty string '').
117 separator
119 A regular expression that will capture the package name in $1 and the
120 attribute name in $2.
121 The default ("(.+?)\.(.+?)") separates plugin name from attribute name
123 with a dot:
124 'Module::Name.attribute'
126 '-Plugin.attr'
127 NOTE: The regexp should not be anchored since "separator_regexp" uses
129 it as the middle piece of a larger regexp (to add "prefix" and the
130 possible array bracket suffix). Also beware of using a regexp that
131 greedily matches the array bracket suffix as that can confuse things as
132 well.
133
135 separator_regexp
136 Returns a compiled regular expression ("qr//") combining "prefix",
137 "separator", and the possible trailing array specification ("\[.*?\]").
138 slice
140 $slicer->slice($plugin);
141 Return a hashref of the config arguments for the plugin determined by
143 $plugin.
144 This is a slice of the "config" attribute appropriate for the plugin
146 passed to the method.
147 Starting with a config hashref of:
149 {
151 'APlug:attr1' => 'value1',
152 'APlug:second' => '2nd',
153 'OtherPlug:attr => '0'
154 }
155 Passing a plugin instance of 'APlug' (or an arrayref of "['APlug',
157 'Full::Package::APlug', {}]") would return:
158 {
160 'attr1' => 'value1',
161 'second' => '2nd'
162 }
163 merge
165 $slicer->merge($plugin, \%opts);
166 Get the config slice (see "slice"), then attempt to merge it into the
168 plugin.
169 If $plugin is an arrayref the hashref will be modified. If it is an
171 object it's attributes should be writable ('rw').
172 This will append to array references if it was specified as an array or
174 if a preexisting value is an arrayref.
175 Returns the modified $plugin for convenience.
177 Possible options:
179 • "slice" - A hashref like that returned from "slice". If not
181 present, "slice" will be called.
182 plugin_info
184 $slicer->plugin_info($plugin);
185 Used by other methods to normalize the information about a plugin.
187 Returns a list of "($name, $package, \%config)".
188 If $plugin is an arrayref it will simply dereference it. This can be
190 useful for processing the results of plugin bundles.
191 If $plugin is an instance of a plugin that has a "plugin_name" method
193 it will construct the list from that method, "ref", and the instance
194 itself.
195
197 Often configurations come from an "ini" file and look like this:
198 [PluginName]
200 option = value
201 This gets converted to a hashref:
203 PluginName->new({ option => 'value' });
205 To embed configuration for other plugins:
207 [@BigBundle]
209 bundle_option = value
210 Bundled::Plugin.option = other value
211 The simple 'bundle_option' attribute is for @BigBundle, and the bundle
213 can slice out the "Bundled::Plugin" configuration and merge it in to
214 that plugin's configuration.
215 Prefixes can be used (see "prefix"). In this example the prefix is set
217 as "plug.".
218 [@Foo]
220 plug.Bundled::Plugin.attr = value
221 Due to limitations of this dynamic passing of unknown options
223 (otherwise known as a hack) values that are arrays cannot be declared
224 ahead of time by the bundle. You can help out by specifying that an
225 attribute should be an array:
226 [@Bar]
228 Baz.quux[0] = part 1
229 Baz.quux[1] = part 2
230 This is required because each line will end up in a hashref:
232 { "quux[0]" => "part 1", "quxx[1]" => "part 2" }
234 The subscripts inside the brackets are used for sorting but otherwise
236 ignored. The "slice" method will sort the keys (alphabetically) to
237 produce:
238 { quux => ["part 1", "part 2"] }
240 For simplicity the keys are sorted alphabetically because "quux[1.9]"
242 and "quux[1.10]" probably won't sort the way you intended anyway, so
243 just keep things simple:
244 [@Bundle]
246 Plug.attr[0] = part 1
247 Plug.attr[1] = part 2
248 Plug.other[09] = part 1
249 Plug.other[10] = part 2
250 Plug.alpha[a] = part 1
251 Plug.alpha[b] = part 2
252 Plug.alpha[bc] = part 3
253 Plug.single[] = subscript not required; only used for sorting
254
256 Perldoc
257 You can find documentation for this module with the perldoc command.
258 perldoc Config::MVP::Slicer
260 Websites
262 The following websites have more information about this module, and may
263 be of help to you. As always, in addition to those websites please use
264 your favorite search engine to discover more resources.
265 • MetaCPAN
267 A modern, open-source CPAN search engine, useful to view POD in
269 HTML format.
270 <http://metacpan.org/release/Config-MVP-Slicer>
272 Bugs / Feature Requests
274 Please report any bugs or feature requests by email to
275 "bug-config-mvp-slicer at rt.cpan.org", or through the web interface at
276 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Config-MVP-Slicer>.
277 You will be automatically notified of any progress on the request by
278 the system.
279 Source Code
281 <https://github.com/rwstauner/Config-MVP-Slicer>
282 git clone https://github.com/rwstauner/Config-MVP-Slicer.git
284
286 Randy Stauner <rwstauner@cpan.org>
287
289 This software is copyright (c) 2011 by Randy Stauner.
290 This is free software; you can redistribute it and/or modify it under
292 the same terms as the Perl 5 programming language system itself.
293perl v5.32.1 2021-01-27 Config::MVP::Slicer(3)