File Coverage

blib/lib/Pod/Weaver/Section/GenerateSection.pm
Criterion Covered Total %
statement 49 52 94.2
branch 10 16 62.5
condition n/a
subroutine 13 14 92.8
pod 0 3 0.0
total 72 85 84.7


line stmt bran cond sub pod time code
1             package Pod::Weaver::Section::GenerateSection 4.018;
2             # ABSTRACT: add pod section from an interpolated piece of text
3              
4 1     1   2407 use Moose;
  1         2  
  1         6  
5             with 'Pod::Weaver::Role::Section';
6              
7             # BEGIN BOILERPLATE
8 1     1   6154 use v5.20.0;
  1         2  
9 1     1   4 use warnings;
  1         2  
  1         63  
10 1     1   5 use utf8;
  1         2  
  1         5  
11 1     1   22 no feature 'switch';
  1         1  
  1         100  
12 1     1   27 use experimental qw(postderef postderef_qq); # This experiment gets mainlined.
  1         15  
  1         7  
13             # END BOILERPLATE
14              
15 1     1   576 use Pod::Elemental::Element::Nested;
  1         49408  
  1         38  
16 1     1   7 use Pod::Elemental::Element::Pod5::Ordinary;
  1         2  
  1         29  
17 1     1   765 use Text::Template;
  1         3287  
  1         49  
18              
19 1     1   21 use namespace::autoclean;
  1         2  
  1         10  
20              
21             #pod =head1 SYNOPSIS
22             #pod
23             #pod In your F<weaver.ini>
24             #pod
25             #pod [GenerateSection]
26             #pod title = HOMEPAGE
27             #pod text = This is the POD for distribution {{$name}}. Check out what we have
28             #pod text = been up to at {{$homepage}}
29             #pod
30             #pod The title value can be omited if passed as the plugin name:
31             #pod
32             #pod [GenerateSection / HOMEPAGE]
33             #pod
34             #pod =head1 DESCRIPTION
35             #pod
36             #pod This plugin allows the creation of simple text sections, with or without the
37             #pod use of Text::Template for templated text.
38             #pod
39             #pod The C<text> parameters become the lines of the template.
40             #pod
41             #pod The values of text are concatenated and variable names with matching values on
42             #pod the distribution are interpolated. Specifying the heading level allows one to
43             #pod write down a rather long section of POD text without need for extra files. For
44             #pod example:
45             #pod
46             #pod [GenerateSection / FEEDBACK]
47             #pod head = 1
48             #pod [GenerateSection / Reporting bugs]
49             #pod head = 2
50             #pod text = Please report bugs when you find them. While we do have a mailing
51             #pod text = list, please use the bug tracker at {{$bugtracker_web}}
52             #pod text = to report bugs
53             #pod [GenerateSection / Homegape]
54             #pod head = 2
55             #pod text = Also, come check out our other projects at
56             #pod text = {{$homepage}}
57             #pod
58             #pod =head1 TEMPLATE RENDERING
59             #pod
60             #pod When rendering as a template, the variables C<$plugin>, C<$dist>, and
61             #pod C<$distmeta> will be provided, set to the GenerateSection plugin,
62             #pod C<Dist::Zilla> object, and the distribution metadata hash respectively. For
63             #pod convenience, the following variables are also set:
64             #pod
65             #pod =for :list
66             #pod * C<< $name >>
67             #pod * C<< $version >>
68             #pod * C<< $homepage >>
69             #pod * C<< $repository_web >>
70             #pod * C<< $repository_url >>
71             #pod * C<< $bugtracker_web >>
72             #pod * C<< $bugtracker_email >>
73             #pod
74             #pod =attr text
75             #pod
76             #pod The text to be added to the section. Multiple values are allowed and will be
77             #pod concatenated. Certain sequences on the text will be replaced (see below).
78             #pod
79             #pod =cut
80              
81 7     7 0 12598 sub mvp_multivalue_args { return qw(text) }
82             has text => (
83             is => 'ro',
84             isa => 'ArrayRef',
85             lazy => 1,
86             default => sub { [] },
87             );
88              
89             #pod =attr head
90             #pod
91             #pod This is the I<X> to use in the C<=headX> that's created. If it's C<0> then no
92             #pod heading is added. It defaults to C<1>.
93             #pod
94             #pod =cut
95              
96             has head => (
97             is => 'ro',
98             isa => 'Int',
99             lazy => 1,
100             default => 1,
101             );
102              
103             #pod =attr title
104             #pod
105             #pod The title for this section. If none is given, the plugin's name is used.
106             #pod
107             #pod =cut
108              
109             has title => (
110             is => 'ro',
111             isa => 'Str',
112             lazy => 1,
113             default => sub { $_[0]->plugin_name },
114             );
115              
116             #pod =attr main_module_only
117             #pod
118             #pod If true, this attribute indicates that only the main module's Pod should be
119             #pod altered. By default, it is false.
120             #pod
121             #pod =cut
122              
123             has main_module_only => (
124             is => 'ro',
125             isa => 'Bool',
126             lazy => 1,
127             default => 0,
128             );
129              
130             #pod =attr
131             #pod
132             #pod If true, the text is treated as a L<Text::Template> template and rendered.
133             #pod This attribute B<is true by default>.
134             #pod
135             #pod =cut
136              
137             has is_template => (
138             is => 'ro',
139             isa => 'Bool',
140             lazy => 1,
141             default => 1,
142             );
143              
144             sub weave_section {
145 7     7 0 13 my ($self, $document, $input) = @_;
146              
147 7 50       234 if ($self->main_module_only) {
148 0 0       0 return if $input->{zilla}->main_module->name ne $input->{filename};
149             }
150              
151 7         188 my $text = join ("\n", $self->text->@*);
152              
153 7 100       183 if ($self->is_template) {
154 6         9 my %stash;
155              
156 6 100       11 if ($input->{zilla}) {
157             %stash = (
158             dist => \($input->{zilla}),
159             distmeta => \($input->{distmeta}),
160             plugin => \($self),
161              
162             name => $input->{distmeta}{name},
163             version => $input->{distmeta}{version},
164             homepage => $input->{distmeta}{resources}{homepage},
165             repository_web => $input->{distmeta}{resources}{repository}{web},
166             repository_url => $input->{distmeta}{resources}{repository}{url},
167             bugtracker_web => $input->{distmeta}{resources}{bugtracker}{web},
168             bugtracker_email => $input->{distmeta}{resources}{bugtracker}{mailto},
169 2         23 );
170             }
171              
172 6         15 $text = $self->fill_in_string($text, \%stash);
173             }
174              
175 7         245 my $element = Pod::Elemental::Element::Pod5::Ordinary->new({ content => $text });
176              
177 7 100       1086 if ($self->head) {
178 6         151 $element = Pod::Elemental::Element::Nested->new({
179             command => "head" . $self->head,
180             content => $self->title,
181             children => [ $element ],
182             });
183             }
184              
185 7         2203 push $document->children->@*, $element;
186             }
187              
188             # BEGIN CODE IMPORTED FROM Dist::Zilla::Role::TextTemplate
189             #pod =attr delim
190             #pod
191             #pod If given, this must be an arrayref with two elements. These will be the
192             #pod opening and closing delimiters of template variable sections. By default they
193             #pod are C<{{> and C<}}>.
194             #pod
195             #pod =cut
196              
197             has delim => (
198             is => 'ro',
199             isa => 'ArrayRef',
200             lazy => 1,
201             init_arg => undef,
202             default => sub { [ qw( {{ }} ) ] },
203             );
204              
205             sub fill_in_string {
206 6     6 0 13 my ($self, $string, $stash, $arg) = @_;
207              
208 6 50       13 $self->log_fatal("Cannot use undef as a template string")
209             unless defined $string;
210              
211             my $tmpl = Text::Template->new(
212             TYPE => 'STRING',
213             SOURCE => $string,
214             DELIMITERS => $self->delim,
215 0     0   0 BROKEN => sub { my %hash = @_; die $hash{error}; },
  0         0  
216 6         166 %$arg,
217             );
218              
219 6 50       700 $self->log_fatal("Could not create a Text::Template object from:\n$string")
220             unless $tmpl;
221              
222 6         19 my $content = $tmpl->fill_in(%$arg, HASH => $stash);
223              
224 6 50       2834 $self->log_fatal("Filling in the template returned undef for:\n$string")
225             unless defined $content;
226              
227 6         59 return $content;
228             }
229             # END CODE IMPORTED FROM Dist::Zilla::Role::TextTemplate
230              
231             __PACKAGE__->meta->make_immutable;
232             1;
233              
234             __END__
235              
236             =pod
237              
238             =encoding UTF-8
239              
240             =head1 NAME
241              
242             Pod::Weaver::Section::GenerateSection - add pod section from an interpolated piece of text
243              
244             =head1 VERSION
245              
246             version 4.018
247              
248             =head1 SYNOPSIS
249              
250             In your F<weaver.ini>
251              
252             [GenerateSection]
253             title = HOMEPAGE
254             text = This is the POD for distribution {{$name}}. Check out what we have
255             text = been up to at {{$homepage}}
256              
257             The title value can be omited if passed as the plugin name:
258              
259             [GenerateSection / HOMEPAGE]
260              
261             =head1 DESCRIPTION
262              
263             This plugin allows the creation of simple text sections, with or without the
264             use of Text::Template for templated text.
265              
266             The C<text> parameters become the lines of the template.
267              
268             The values of text are concatenated and variable names with matching values on
269             the distribution are interpolated. Specifying the heading level allows one to
270             write down a rather long section of POD text without need for extra files. For
271             example:
272              
273             [GenerateSection / FEEDBACK]
274             head = 1
275             [GenerateSection / Reporting bugs]
276             head = 2
277             text = Please report bugs when you find them. While we do have a mailing
278             text = list, please use the bug tracker at {{$bugtracker_web}}
279             text = to report bugs
280             [GenerateSection / Homegape]
281             head = 2
282             text = Also, come check out our other projects at
283             text = {{$homepage}}
284              
285             =head1 PERL VERSION SUPPORT
286              
287             This module has the same support period as perl itself: it supports the two
288             most recent versions of perl. (That is, if the most recently released version
289             is v5.40, then this module should work on both v5.40 and v5.38.)
290              
291             Although it may work on older versions of perl, no guarantee is made that the
292             minimum required version will not be increased. The version may be increased
293             for any reason, and there is no promise that patches will be accepted to lower
294             the minimum required perl.
295              
296             =head1 ATTRIBUTES
297              
298             =head2 text
299              
300             The text to be added to the section. Multiple values are allowed and will be
301             concatenated. Certain sequences on the text will be replaced (see below).
302              
303             =head2 head
304              
305             This is the I<X> to use in the C<=headX> that's created. If it's C<0> then no
306             heading is added. It defaults to C<1>.
307              
308             =head2 title
309              
310             The title for this section. If none is given, the plugin's name is used.
311              
312             =head2 main_module_only
313              
314             If true, this attribute indicates that only the main module's Pod should be
315             altered. By default, it is false.
316              
317             =head2
318              
319             If true, the text is treated as a L<Text::Template> template and rendered.
320             This attribute B<is true by default>.
321              
322             =head2 delim
323              
324             If given, this must be an arrayref with two elements. These will be the
325             opening and closing delimiters of template variable sections. By default they
326             are C<{{> and C<}}>.
327              
328             =head1 TEMPLATE RENDERING
329              
330             When rendering as a template, the variables C<$plugin>, C<$dist>, and
331             C<$distmeta> will be provided, set to the GenerateSection plugin,
332             C<Dist::Zilla> object, and the distribution metadata hash respectively. For
333             convenience, the following variables are also set:
334              
335             =over 4
336              
337             =item *
338              
339             C<< $name >>
340              
341             =item *
342              
343             C<< $version >>
344              
345             =item *
346              
347             C<< $homepage >>
348              
349             =item *
350              
351             C<< $repository_web >>
352              
353             =item *
354              
355             C<< $repository_url >>
356              
357             =item *
358              
359             C<< $bugtracker_web >>
360              
361             =item *
362              
363             C<< $bugtracker_email >>
364              
365             =back
366              
367             =head1 AUTHOR
368              
369             Ricardo SIGNES <rjbs@semiotic.systems>
370              
371             =head1 COPYRIGHT AND LICENSE
372              
373             This software is copyright (c) 2021 by Ricardo SIGNES.
374              
375             This is free software; you can redistribute it and/or modify it under
376             the same terms as the Perl 5 programming language system itself.
377              
378             =cut