File Coverage

blib/lib/Dist/Zilla/Plugin/Stenciller/HtmlExamples.pm

Criterion	Covered	Total	%
statement	51	51	100.0
branch			n/a
condition			n/a
subroutine	14	14	100.0
pod	0	1	0.0
total	65	66	98.4

line	stmt	sub	pod	time	code
1	1	1		1644571	use 5.10.0;
	1			3
2	1	1		4	use strict;
	1			1
	1			16
3	1	1		2	use warnings;
	1			1
	1			54
4
5					package Dist::Zilla::Plugin::Stenciller::HtmlExamples;
6
7					# ABSTRACT: Create Html example files from text files parsed with Stenciller
8					our $AUTHORITY = 'cpan:CSSON'; # AUTHORITY
9					our $VERSION = '0.0201';
10
11	1	1		4	use Moose;
	1			1
	1			7
12					with 'Dist::Zilla::Role::FileGatherer';
13	1	1		5295	use Stenciller;
	1			380033
	1			43
14	1	1		6	use Types::Standard qw/Bool Maybe Str/;
	1			1
	1			7
15	1	1		696	use Types::Path::Tiny qw/AbsFile Dir Path/;
	1			2
	1			7
16	1	1		472	use Types::Stenciller -types;
	1			1
	1			6
17	1	1		401	use Path::Tiny;
	1			2
	1			58
18	1	1		579	use Dist::Zilla::File::InMemory;
	1			62131
	1			37
19	1	1		513	use String::Stomp;
	1			263
	1			54
20	1	1		5	use syntax 'qs';
	1			1
	1			8
21	1	1		1561	use namespace::autoclean;
	1			2
	1			8
22
23					has '+zilla' => (
24					traits => ['Documented'],
25					documentation_order => 0,
26					);
27					has '+plugin_name' => (
28					traits => ['Documented'],
29					documentation_order => 0,
30					);
31					has '+logger' => (
32					traits => ['Documented'],
33					documentation_order => 0,
34					);
35
36					has source_directory => (
37					is => 'ro',
38					isa => Dir,
39					coerce => 1,
40					default => 'examples/source',
41					traits => ['Documented'],
42					documentation => 'Path to where the stencil files are.',
43					documentation_order => 1,
44					);
45					has file_pattern => (
46					is => 'ro',
47					isa => Str,
48					default => '.+\.stencil',
49					traits => ['Documented'],
50					documentation => stomp qs{
51					This is used as a part of a regular expression (so do not use start and end anchors) to find stencil files in the C<source_directory>.
52					},
53					documentation_order => 3,
54					);
55					has output_directory => (
56					is => 'ro',
57					isa => Path,
58					coerce => 1,
59					default => 'examples',
60					traits => ['Documented'],
61					documentation => stomp qs{
62					Path to where the generated files are saved. The output files
63					will have the same basename as the stencil they are based on, but with the suffix replaced by C<html>.
64					},
65					documentation_order => 2,
66					);
67					has template_file => (
68					is => 'ro',
69					isa => AbsFile,
70					lazy => 1,
71					coerce => 1,
72					default => sub { shift->source_directory->child('template.html')->absolute },
73					traits => ['Documented'],
74					documentation => stomp qs{
75					The template file should be an html file. The first occurence of C<[STENCILS]> will be replaced with the output from L<Stenciller::Plugin::ToHtmlPreBlock>
76					for each stencil.
77					},
78	1	1	0	2644	documentation_default => q{'template.html' in L</source_directory>},
79					documentation_order => 4,
80	1			38	);
81	1			211	has separator => (
	1			36
82					is => 'ro',
83	1			125	isa => Maybe[Str],
84					traits => ['Documented'],
85	1			220	documentation => q{Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.},
86	1			6	documentation_order => 5,
87					);
88					has output_also_as_html => (
89					is => 'ro',
90					isa => Bool,
91					default => 0,
92					traits => ['Documented'],
93					documentation => q{Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.},
94					documentation_order => 6,
95					);
96
97					sub gather_files {
98					my $self = shift;
99
100	1			202846	my $template = $self->template_file->slurp_utf8;
101	1			75	my @source_files = $self->source_directory->children(qr{^@{[ $self->file_pattern ]}$});
102	1			8
103	1			78	$self->log('Generating from stencils');
104
105	1			341	foreach my $file (@source_files) {
106					my $contents = Stenciller->new(filepath => $file->stringify)->transform(
107					plugin_name => 'ToHtmlPreBlock',
108					constructor_args => {
109	1			324	output_also_as_html => $self->output_also_as_html,
110					separator => $self->separator,
111					},
112					transform_args => {
113					require_in_extra => {
114					key => 'is_html_example',
115					value => 1,
116					default => 1,
117					},
118					},
119					);
120					my $all_contents = $template;
121					$all_contents =~ s{\[STENCILS\]}{$contents};
122					my $new_filename = $file->basename(qr/\.[^.]+$/) . '.html';
123					$self->log("Generated $new_filename");
124
125					my $generated_file = Dist::Zilla::File::InMemory->new(
126					name => path($self->output_directory, $new_filename)->stringify,
127					content => $all_contents,
128					);
129					$self->add_file($generated_file);
130
131					}
132					}
133
134					__PACKAGE__->meta->make_immutable;
135
136					1;
137
138					__END__
139
140					=pod
141
142					=encoding UTF-8
143
144					=head1 NAME
145
146					Dist::Zilla::Plugin::Stenciller::HtmlExamples - Create Html example files from text files parsed with Stenciller
147
148
149
150					=begin html
151
152					<p>
153					<img src="https://img.shields.io/badge/perl-5.10+-blue.svg" alt="Requires Perl 5.10+" />
154					<a href="https://travis-ci.org/Csson/p5-Dist-Zilla-Plugin-Stenciller-HtmlExamples"><img src="https://api.travis-ci.org/Csson/p5-Dist-Zilla-Plugin-Stenciller-HtmlExamples.svg?branch=master" alt="Travis status" /></a>
155					<a href="http://cpants.cpanauthors.org/dist/Dist-Zilla-Plugin-Stenciller-HtmlExamples-0.0201"><img src="https://badgedepot.code301.com/badge/kwalitee/Dist-Zilla-Plugin-Stenciller-HtmlExamples/0.0201" alt="Distribution kwalitee" /></a>
156					<a href="http://matrix.cpantesters.org/?dist=Dist-Zilla-Plugin-Stenciller-HtmlExamples%200.0201"><img src="https://badgedepot.code301.com/badge/cpantesters/Dist-Zilla-Plugin-Stenciller-HtmlExamples/0.0201" alt="CPAN Testers result" /></a>
157					<img src="https://img.shields.io/badge/coverage-98.5%-yellow.svg" alt="coverage 98.5%" />
158					</p>
159
160					=end html
161
162					=head1 VERSION
163
164					Version 0.0201, released 2016-03-23.
165
166
167
168					=head1 SYNOPSIS
169
170					; in dist.ini
171					; these are the defaults
172					[Stenciller::HtmlExamples]
173					source_directory = examples/source
174					output_directory = examples
175					template_file = examples/source/template.html
176					file_pattern = .+\.stencil
177					output_also_as_html = 0
178
179					=head1 DESCRIPTION
180
181					Dist::Zilla::Plugin::Stenciller::HtmlExamples uses L<Stenciller> and L<Stenciller::Plugin::ToHtmlPreBlock> to turn
182					stencil files in C<source_directory> (that matches the C<file_pattern>) into
183					html example files in C<output_directory> by applying the C<template_file>.
184
185					This L<Dist::Zilla> plugin does the C<FileGatherer> role.
186
187					=head1 ATTRIBUTES
188
189
190					=head2 source_directory
191
192					=begin HTML
193
194					<table cellpadding="0" cellspacing="0">
195					<tr>
196					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#Dir">Dir</a></td>
197					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>examples/source</code></td>
198					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
199					</tr>
200					</table>
201
202					<p>Path to where the stencil files are.</p>
203
204					=end HTML
205
206					=begin markdown
207
208					<table cellpadding="0" cellspacing="0">
209					<tr>
210					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#Dir">Dir</a></td>
211					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>examples/source</code></td>
212					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
213					</tr>
214					</table>
215
216					<p>Path to where the stencil files are.</p>
217
218					=end markdown
219
220					=head2 output_directory
221
222					=begin HTML
223
224					<table cellpadding="0" cellspacing="0">
225					<tr>
226					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#Path">Path</a></td>
227					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>examples</code></td>
228					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
229					</tr>
230					</table>
231
232					<p>Path to where the generated files are saved. The output files
233					will have the same basename as the stencil they are based on, but with the suffix replaced by C<html>.</p>
234
235					=end HTML
236
237					=begin markdown
238
239					<table cellpadding="0" cellspacing="0">
240					<tr>
241					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#Path">Path</a></td>
242					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>examples</code></td>
243					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
244					</tr>
245					</table>
246
247					<p>Path to where the generated files are saved. The output files
248					will have the same basename as the stencil they are based on, but with the suffix replaced by C<html>.</p>
249
250					=end markdown
251
252					=head2 file_pattern
253
254					=begin HTML
255
256					<table cellpadding="0" cellspacing="0">
257					<tr>
258					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Str">Str</a></td>
259					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>.+\.stencil</code></td>
260					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
261					</tr>
262					</table>
263
264					<p>This is used as a part of a regular expression (so do not use start and end anchors) to find stencil files in the C<source_directory>.</p>
265
266					=end HTML
267
268					=begin markdown
269
270					<table cellpadding="0" cellspacing="0">
271					<tr>
272					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Str">Str</a></td>
273					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>.+\.stencil</code></td>
274					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
275					</tr>
276					</table>
277
278					<p>This is used as a part of a regular expression (so do not use start and end anchors) to find stencil files in the C<source_directory>.</p>
279
280					=end markdown
281
282					=head2 template_file
283
284					=begin HTML
285
286					<table cellpadding="0" cellspacing="0">
287					<tr>
288					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#AbsFile">AbsFile</a></td>
289					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>'template.html' in <a href="#source_directory">"source_directory"</a></code></td>
290					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
291					</tr>
292					</table>
293
294					<p>The template file should be an html file. The first occurence of C<[STENCILS]> will be replaced with the output from L<Stenciller::Plugin::ToHtmlPreBlock>
295					for each stencil.</p>
296
297					=end HTML
298
299					=begin markdown
300
301					<table cellpadding="0" cellspacing="0">
302					<tr>
303					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Path::Tiny#AbsFile">AbsFile</a></td>
304					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>'template.html' in <a href="#source_directory">"source_directory"</a></code></td>
305					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
306					</tr>
307					</table>
308
309					<p>The template file should be an html file. The first occurence of C<[STENCILS]> will be replaced with the output from L<Stenciller::Plugin::ToHtmlPreBlock>
310					for each stencil.</p>
311
312					=end markdown
313
314					=head2 separator
315
316					=begin HTML
317
318					<table cellpadding="0" cellspacing="0">
319					<tr>
320					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Maybe">Maybe</a> [ <a href="https://metacpan.org/pod/Types::Standard#Str">Str</a> ]</td>
321					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional</td>
322					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
323					</tr>
324					</table>
325
326					<p>Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.</p>
327
328					=end HTML
329
330					=begin markdown
331
332					<table cellpadding="0" cellspacing="0">
333					<tr>
334					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Maybe">Maybe</a> [ <a href="https://metacpan.org/pod/Types::Standard#Str">Str</a> ]</td>
335					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional</td>
336					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
337					</tr>
338					</table>
339
340					<p>Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.</p>
341
342					=end markdown
343
344					=head2 output_also_as_html
345
346					=begin HTML
347
348					<table cellpadding="0" cellspacing="0">
349					<tr>
350					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Bool">Bool</a></td>
351					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>0</code></td>
352					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
353					</tr>
354					</table>
355
356					<p>Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.</p>
357
358					=end HTML
359
360					=begin markdown
361
362					<table cellpadding="0" cellspacing="0">
363					<tr>
364					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;"><a href="https://metacpan.org/pod/Types::Standard#Bool">Bool</a></td>
365					<td style="padding-right: 6px; padding-left: 6px; border-right: 1px solid #b8b8b8; white-space: nowrap;">optional, default: <code>0</code></td>
366					<td style="padding-left: 6px; padding-right: 6px; white-space: nowrap;">read-only</td>
367					</tr>
368					</table>
369
370					<p>Passed on to the L<Stenciller::Plugin::ToHtmlPreBlock> constructor.</p>
371
372					=end markdown
373
374					=head1 SEE ALSO
375
376					=over 4
377
378					=item *
379
380					L<Stenciller>
381
382					=item *
383
384					L<Stenciller::Plugin::ToHtmlPreBlock>
385
386					=back
387
388					=head1 SOURCE
389
390					L<https://github.com/Csson/p5-Dist-Zilla-Plugin-Stenciller-HtmlExamples>
391
392					=head1 HOMEPAGE
393
394					L<https://metacpan.org/release/Dist-Zilla-Plugin-Stenciller-HtmlExamples>
395
396					=head1 AUTHOR
397
398					Erik Carlsson <info@code301.com>
399
400					=head1 COPYRIGHT AND LICENSE
401
402					This software is copyright (c) 2016 by Erik Carlsson.
403
404					This is free software; you can redistribute it and/or modify it under
405					the same terms as the Perl 5 programming language system itself.
406
407					=cut