File Coverage

blib/lib/Pod/Weaver/PluginBundle/Author/ETHER.pm
Criterion Covered Total %
statement 57 57 100.0
branch 26 26 100.0
condition 11 14 78.5
subroutine 13 13 100.0
pod 0 2 0.0
total 107 112 95.5


line stmt bran cond sub pod time code
1 22     22   170685 use strict;
  22         67  
  22         688  
2 22     22   120 use warnings;
  22         47  
  22         1661  
3             package Pod::Weaver::PluginBundle::Author::ETHER;
4             # vim: set ts=8 sts=2 sw=2 tw=100 et :
5             # ABSTRACT: A plugin bundle for pod woven by ETHER
6              
7             our $VERSION = '0.161';
8              
9 22     22   142 no if "$]" >= 5.031009, feature => 'indirect';
  22         50  
  22         254  
10 22     22   994 no if "$]" >= 5.033001, feature => 'multidimensional';
  22         48  
  22         108  
11 22     22   794 no if "$]" >= 5.033006, feature => 'bareword_filehandles';
  22         51  
  22         194  
12 22     22   1275 use namespace::autoclean -also => ['_exp'];
  22         12800  
  22         238  
13 22     22   12056 use Pod::Weaver::Config::Assembler;
  22         8899661  
  22         993  
14 22     22   210 use Module::Runtime 'use_module';
  22         47  
  22         165  
15 22     22   11194 use PadWalker 'peek_sub';
  22         12546  
  22         16210  
16              
17             sub _exp { Pod::Weaver::Config::Assembler->expand_package($_[0]) }
18              
19             # This sub behaves somewhat like a Dist::Zilla pluginbundle's configure() -- it returns a list of strings or 1, 2
20             # or 3-element arrayrefs containing plugin specifications. The goal is to make this look as close to what
21             # weaver.ini looks like as possible.
22             sub configure {
23 75     75 0 340 my $self = shift;
24              
25             # I wouldn't have to do this ugliness if I could have some configuration values passed in from weaver.ini or
26             # the [PodWeaver] plugin's use of config_plugin (where I could define a 'licence' option)
27 75         189 my $podweaver_plugin = ${ peek_sub(\&Dist::Zilla::Plugin::PodWeaver::weaver)->{'$self'} };
  75         1617  
28 75   100     2523 my $licence_plugin = $podweaver_plugin && $podweaver_plugin->zilla->plugin_named('@Author::ETHER/License');
29 75 100       24789 my $licence_filename = $licence_plugin ? $licence_plugin->filename : 'LICENCE';
30              
31             return (
32             # equivalent to [@CorePrep]
33 75         5296 [ '-EnsurePod5' ],
34             [ '-H1Nester' ],
35             '-SingleEncoding',
36              
37             [ '-Transformer' => List => { transformer => 'List' } ],
38             [ '-Transformer' => Verbatim => { transformer => 'Verbatim' } ],
39              
40             [ 'Region' => 'header' ],
41             'Name',
42             'Version',
43             [ 'Region' => 'prelude' ],
44             [ 'Generic' => 'SYNOPSIS' ],
45             [ 'Generic' => 'DESCRIPTION' ],
46             [ 'Generic' => 'OVERVIEW' ],
47              
48             [ 'Collect' => 'ATTRIBUTES' => { command => 'attr' } ],
49             [ 'Collect' => 'METHODS' => { command => 'method' } ],
50             [ 'Collect' => 'FUNCTIONS' => { command => 'func' } ],
51             [ 'Collect' => 'TYPES' => { command => 'type' } ],
52             'Leftovers',
53             [ 'Region' => 'postlude' ],
54              
55             [ 'GenerateSection' => 'generate SUPPORT' => {
56             title => 'SUPPORT',
57             main_module_only => 0,
58             text => [ <<'SUPPORT',
59             {{ join("\n\n",
60             ($bugtracker_email && $bugtracker_email =~ /rt\.cpan\.org/)
61             ? "Bugs may be submitted through L<the RT bug tracker|$bugtracker_web>\n(or L<$bugtracker_email|mailto:$bugtracker_email>)."
62             : $bugtracker_web
63             ? "Bugs may be submitted through L<$bugtracker_web>."
64             : (),
65              
66             $distmeta->{resources}{x_MailingList} ? 'There is also a mailing list available for users of this distribution, at' . "\nL<" . $distmeta->{resources}{x_MailingList} . '>.' : (),
67              
68             $distmeta->{resources}{x_IRC}
69             ? 'There is also an irc channel available for users of this distribution, at' . "\nL<"
70             . do {
71             # try to extract the channel
72             if (my ($network, $channel) = ($distmeta->{resources}{x_IRC} =~ m!(?:://)?(\w+(?:\.\w+)*)/?(#\w+)!)) {
73             'C<' . $channel . '> on C<' . $network . '>|' . $distmeta->{resources}{x_IRC}
74             }
75             else {
76             $distmeta->{resources}{x_IRC}
77             }
78             }
79             . '>.'
80             : (),
81              
82             ($distmeta->{x_authority} // '') eq 'cpan:ETHER'
83             ? "I am also usually active on irc, as 'ether' at C<irc.perl.org> and C<irc.libera.chat>."
84             : (),
85             ) }}
86             SUPPORT
87             ] },
88             ],
89              
90             [ 'AllowOverride' => 'allow override SUPPORT' => {
91             header_re => '^(SUPPORT|BUGS)\b',
92             action => 'prepend',
93             match_anywhere => 0,
94             },
95             ],
96              
97             'Authors',
98             [ 'AllowOverride' => 'allow override AUTHOR' => {
99             header_re => '^AUTHORS?\b',
100             action => 'replace',
101             match_anywhere => 0,
102             },
103             ],
104              
105             [ 'Contributors' => { ':version' => '0.008' } ],
106             [ 'Legal' => { ':version' => '4.011', header => 'COPYRIGHT AND ' . $licence_filename } ],
107             [ 'Region' => 'footer' ],
108             );
109             }
110              
111             sub mvp_bundle_config {
112 75   50 75 0 51283840 my $self = shift || __PACKAGE__;
113              
114 75         443 return map $self->_expand_config($_), $self->configure;
115             }
116              
117             my $prefix;
118             sub _prefix {
119 1371     1371   73496 my $self = shift;
120 1371 100       4565 return $prefix if defined $prefix;
121 14   33     237 ($prefix = (ref($self) || $self)) =~ s/^Pod::Weaver::PluginBundle:://;
122 14         74 $prefix;
123             }
124              
125             sub _expand_config {
126 1907     1907   441413 my ($self, $this_spec) = @_;
127              
128 1907 100       3798 die 'undefined config' if not $this_spec;
129 1906 100 100     6150 die 'unrecognized config format: ' . ref($this_spec) if ref($this_spec) and ref($this_spec) ne 'ARRAY';
130              
131 1905         3037 my ($name, $class, $payload);
132              
133 1905 100       5474 if (not ref $this_spec) {
    100          
    100          
134 385         777 ($name, $class, $payload) = ($this_spec, _exp($this_spec), {});
135             }
136             elsif (@$this_spec == 1) {
137 150         678 ($name, $class, $payload) = ($this_spec->[0], _exp($this_spec->[0]), {});
138             }
139             elsif (@$this_spec == 2) {
140 688 100       1702 $name = ref $this_spec->[1] ? $this_spec->[0] : $this_spec->[1];
141 688 100       1949 $class = _exp(ref $this_spec->[1] ? $this_spec->[0] : $this_spec->[0]);
142 688 100       37056 $payload = ref $this_spec->[1] ? $this_spec->[1] : {};
143             }
144             else {
145 682         1789 ($name, $class, $payload) = ($this_spec->[1], _exp($this_spec->[0]), $this_spec->[2]);
146             }
147              
148 1905         68642 $name =~ s/^[@=-]//;
149              
150             # Region plugins have the custom plugin name moved to 'region_name' parameter,
151             # because we don't want our bundle name to be part of the region name.
152 1905 100       3704 if ($class eq _exp('Region')) {
153 303         15598 $name = $this_spec->[1];
154 303         1087 $payload = { region_name => $this_spec->[1], %$payload };
155             }
156              
157 1905 100       84380 use_module($class, $payload->{':version'}) if $payload->{':version'};
158              
159             # prepend '@Author::ETHER/' to each class name,
160             # except for Generic and Collect which are left alone.
161 1904 100 100     1905785 $name = '@' . $self->_prefix . '/' . $name
162             if $class ne _exp('Generic') and $class ne _exp('Collect');
163              
164 1904         33560 return [ $name => $class => $payload ];
165             }
166              
167             1;
168              
169             __END__
170              
171             =pod
172              
173             =encoding UTF-8
174              
175             =head1 NAME
176              
177             Pod::Weaver::PluginBundle::Author::ETHER - A plugin bundle for pod woven by ETHER
178              
179             =head1 VERSION
180              
181             version 0.161
182              
183             =head1 SYNOPSIS
184              
185             In your F<weaver.ini>:
186              
187             [@Author::ETHER]
188              
189             Or in your F<dist.ini>
190              
191             [PodWeaver]
192             config_plugin = @Author::ETHER
193              
194             It is also used automatically when your F<dist.ini> contains:
195              
196             [@Author::ETHER]
197             :version = 0.094 ; or any higher version
198              
199             =head1 DESCRIPTION
200              
201             =for stopwords optimizations
202              
203             This is a L<Pod::Weaver> plugin bundle. It is I<approximately> equal to the
204             following F<weaver.ini>, minus some optimizations:
205              
206             [-EnsurePod5]
207             [-H1Nester]
208             [-SingleEncoding]
209              
210             [-Transformer / List]
211             transformer = List
212              
213             [-Transformer / Verbatim]
214             transformer = Verbatim
215              
216             [Region / header]
217             [Name]
218             [Version]
219              
220             [Region / prelude]
221              
222             [Generic / SYNOPSIS]
223             [Generic / DESCRIPTION]
224             [Generic / OVERVIEW]
225              
226             [Collect / ATTRIBUTES]
227             command = attr
228              
229             [Collect / METHODS]
230             command = method
231              
232             [Collect / FUNCTIONS]
233             command = func
234              
235             [Collect / TYPES]
236             command = type
237              
238             [Leftovers]
239              
240             [Region / postlude]
241              
242             [GenerateSection / generate SUPPORT]
243             title = SUPPORT
244             main_module_only = 0
245             text = <template>
246             [AllowOverride / allow override SUPPORT]
247             header_re = ^(SUPPORT|BUGS)\b
248             action = prepend
249             match_anywhere = 0
250              
251             [Authors]
252             [AllowOverride / allow override AUTHOR]
253             header_re = ^AUTHORS?\b
254             action = replace
255             match_anywhere = 0
256              
257             [Contributors]
258             :version = 0.008
259              
260             [Legal]
261             :version = 4.011
262             header = COPYRIGHT AND <licence filename>
263              
264             [Region / footer]
265              
266             This is also equivalent (other than section ordering) to:
267              
268             [-Transformer / List]
269             transformer = List
270             [-Transformer / Verbatim]
271             transformer = Verbatim
272              
273             [Region / header]
274             [@Default]
275              
276             [Collect / TYPES]
277             command = type
278              
279             [GenerateSection / generate SUPPORT]
280             title = SUPPORT
281             main_module_only = 0
282             text = <template>
283             [AllowOverride / allow override SUPPORT]
284             header_re = ^(SUPPORT|BUGS)
285             action = prepend
286             match_anywhere = 0
287              
288             [Authors]
289             [Contributors]
290             :version = 0.008
291              
292             [Region / footer]
293              
294             =head1 OPTIONS
295              
296             None at this time. (The bundle is never instantiated, so this doesn't seem to
297             be possible without updates to L<Pod::Weaver>.)
298              
299             =head1 OVERRIDING A SPECIFIC SECTION
300              
301             This F<weaver.ini> will let you use a custom C<COPYRIGHT AND LICENCE> section and still use the plugin bundle:
302              
303             [@Author::ETHER]
304             [AllowOverride / OverrideLegal]
305             header_re = ^COPYRIGHT
306             match_anywhere = 1
307              
308             =head1 ADDING STOPWORDS FOR SPELLING TESTS
309              
310             As noted in L<Dist::Zilla::PluginBundle::Author::ETHER>, stopwords for
311             spelling tests can be added by adding a directive to pod:
312              
313             =for stopwords foo bar baz
314              
315             However, if the stopword appears in the module's abstract, it is moved to the
316             C<NAME> section, which will be above your stopword directive. You can handle
317             this by declaring the stopword in the special C<header> section, which will be
318             woven ahead of everything else:
319              
320             =for :header
321             =for stopwords foo bar baz
322              
323             =head1 SEE ALSO
324              
325             =over 4
326              
327             =item *
328              
329             L<Pod::Weaver>
330              
331             =item *
332              
333             L<Pod::Weaver::PluginBundle::Default>
334              
335             =item *
336              
337             L<Dist::Zilla::Plugin::PodWeaver>
338              
339             =item *
340              
341             L<Dist::Zilla::PluginBundle::Author::ETHER>
342              
343             =item *
344              
345             L<Dist::Zilla::MintingProfile::Author::ETHER>
346              
347             =back
348              
349             =head1 NAMING SCHEME
350              
351             =for stopwords KENTNL
352              
353             This distribution follows best practices for author-oriented plugin bundles; for more information,
354             see L<KENTNL's distribution|Dist::Zilla::PluginBundle::Author::KENTNL/NAMING-SCHEME>.
355              
356             =head1 SUPPORT
357              
358             Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-PluginBundle-Author-ETHER>
359             (or L<bug-Dist-Zilla-PluginBundle-Author-ETHER@rt.cpan.org|mailto:bug-Dist-Zilla-PluginBundle-Author-ETHER@rt.cpan.org>).
360              
361             There is also a mailing list available for users of this distribution, at
362             L<http://dzil.org/#mailing-list>.
363              
364             There is also an irc channel available for users of this distribution, at
365             L<C<#distzilla> on C<irc.perl.org>|irc://irc.perl.org/#distzilla>.
366              
367             I am also usually active on irc, as 'ether' at C<irc.perl.org> and C<irc.libera.chat>.
368              
369             =head1 AUTHOR
370              
371             Karen Etheridge <ether@cpan.org>
372              
373             =head1 COPYRIGHT AND LICENCE
374              
375             This software is copyright (c) 2013 by Karen Etheridge.
376              
377             This is free software; you can redistribute it and/or modify it under
378             the same terms as the Perl 5 programming language system itself.
379              
380             =cut