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

NAME

6       Config::MVP::Slicer - Extract embedded plugin config from parent config
7

VERSION

9       version 0.303
10

SYNOPSIS

12         my $slicer = Config::MVP::Slicer->new({
13           config => $parent->config,
14         });
15
16         # extract a hashref from the parent config without modifying the plugin
17         my $plugin_config = $slicer->slice($plugin);
18
19         # from plugin bundles:
20         my $plugin_spec = ['Name', 'Package::Name', {default => 'config'}];
21         # update the hashref
22         $slicer->merge($plugin_spec);
23
24         # with object instances:
25         my $plugger = App::Plugin::Plugger->new({some => 'config'});
26         # update 'rw' attributes
27         $slicer->merge($plugger);
28

DESCRIPTION

30       This can be used to extract embedded configurations for other plugins
31       out of larger (parent) configurations.
32
33       A example where this can be useful is plugin bundles (see
34       Config::MVP::Assembler::WithBundles).
35
36       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
41         # mvp config file
42         [@MyBundle]
43         Other::Plugin.setting = new value
44
45       Now you can accept customizations to plugins into your bundle config
46       and separate them out using this module.
47

ATTRIBUTES

49   config
50       This is the main/parent configuration hashref that contains embedded
51       plugin configurations.
52
53   match_name
54       This is coderef that determines if a configuration line matches a
55       plugin's name.
56
57       It can be customized by passing an alternate subroutine reference to
58       the constructor.
59
60       The sub will receive two arguments:
61
62       ·   The plugin name portion of the configuration line
63
64       ·   The name of the plugin being worked on (provided to "slice", for
65           instance).
66
67       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
71       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
75         # configuration line: "Foo.attr = value"
76
77         $slicer->match_name("Foo", "Foo");            # true
78         $slicer->match_name("Foo", "@Bar/Foo");       # true
79         $slicer->match_name("Foo", "Bar");            # false
80
81         # configuration line: "@Bar/Foo.attr = value"
82
83         $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
88       Subclasses can define "_build_match_name" (which should return a "sub")
89       to overwrite the default.
90
91   match_package
92       This works like "match_name" except that the configuration line is
93       compared to the plugin's package (class).
94
95       The default returns true if the two values are equal and false
96       otherwise.
97
98       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
102         match_package => sub { rewrite_prefix($_[0]) eq $_[1] }
103
104       Subclasses can define "_build_match_package" (which should return a
105       "sub") to overwrite the default.
106
107   prefix
108       Regular expression that should match at the beginning of a key before
109       the module name and attribute:
110
111         # prefix => 'dynamic\.'
112         # { 'dynamic.Module::Name.attr' => 'value' }
113
114       This can be a string or a compiled regular expression ("qr//").
115
116       The default is no prefix (empty string '').
117
118   separator
119       A regular expression that will capture the package name in $1 and the
120       attribute name in $2.
121
122       The default ("(.+?)\.(.+?)")  separates plugin name from attribute name
123       with a dot:
124
125         'Module::Name.attribute'
126         '-Plugin.attr'
127
128       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

METHODS

135   separator_regexp
136       Returns a compiled regular expression ("qr//") combining "prefix",
137       "separator", and the possible trailing array specification ("\[.*?\]").
138
139   slice
140         $slicer->slice($plugin);
141
142       Return a hashref of the config arguments for the plugin determined by
143       $plugin.
144
145       This is a slice of the "config" attribute appropriate for the plugin
146       passed to the method.
147
148       Starting with a config hashref of:
149
150         {
151           'APlug:attr1'   => 'value1',
152           'APlug:second'  => '2nd',
153           'OtherPlug:attr => '0'
154         }
155
156       Passing a plugin instance of 'APlug' (or an arrayref of "['APlug',
157       'Full::Package::APlug', {}]") would return:
158
159         {
160           'attr1'   => 'value1',
161           'second'  => '2nd'
162         }
163
164   merge
165         $slicer->merge($plugin, \%opts);
166
167       Get the config slice (see "slice"), then attempt to merge it into the
168       plugin.
169
170       If $plugin is an arrayref the hashref will be modified.  If it is an
171       object it's attributes should be writable ('rw').
172
173       This will append to array references if it was specified as an array or
174       if a preexisting value is an arrayref.
175
176       Returns the modified $plugin for convenience.
177
178       Possible options:
179
180       ·   "slice" - A hashref like that returned from "slice".  If not
181           present, "slice" will be called.
182
183   plugin_info
184         $slicer->plugin_info($plugin);
185
186       Used by other methods to normalize the information about a plugin.
187       Returns a list of "($name, $package, \%config)".
188
189       If $plugin is an arrayref it will simply dereference it.  This can be
190       useful for processing the results of plugin bundles.
191
192       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

CONFIGURATION SYNTAX

197       Often configurations come from an "ini" file and look like this:
198
199         [PluginName]
200         option = value
201
202       This gets converted to a hashref:
203
204         PluginName->new({ option => 'value' });
205
206       To embed configuration for other plugins:
207
208         [@BigBundle]
209         bundle_option = value
210         Bundled::Plugin.option = other value
211
212       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
216       Prefixes can be used (see "prefix").  In this example the prefix is set
217       as "plug.".
218
219         [@Foo]
220         plug.Bundled::Plugin.attr = value
221
222       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
227         [@Bar]
228         Baz.quux[0] = part 1
229         Baz.quux[1] = part 2
230
231       This is required because each line will end up in a hashref:
232
233         { "quux[0]" => "part 1", "quxx[1]" => "part 2" }
234
235       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
239         { quux => ["part 1", "part 2"] }
240
241       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
245         [@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

SUPPORT

256   Perldoc
257       You can find documentation for this module with the perldoc command.
258
259         perldoc Config::MVP::Slicer
260
261   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
266       ·   MetaCPAN
267
268           A modern, open-source CPAN search engine, useful to view POD in
269           HTML format.
270
271           <http://metacpan.org/release/Config-MVP-Slicer>
272
273   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
280   Source Code
281       <https://github.com/rwstauner/Config-MVP-Slicer>
282
283         git clone https://github.com/rwstauner/Config-MVP-Slicer.git
284

AUTHOR

286       Randy Stauner <rwstauner@cpan.org>
287
289       This software is copyright (c) 2011 by Randy Stauner.
290
291       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.
293
294
295
296perl v5.30.1                      2020-01-29            Config::MVP::Slicer(3)
Impressum