blib/lib/Pod/Weaver/Section/Collect/FromOther.pm

filter: Statementstmt 96.6% 87 / 90 Branchbran 81.2% 13 / 16 Conditioncond 60.0% 3 / 5 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 19 / 19 Podpod 100% 2 / 2 totaltotal 92.5% 125 / 135 CC 13 SCAR 9.5
CC
13
Cov
93%
__ANON__
5.0
copy_sections_from_other
4.0
__ANON__
3.8
CRAP 2.6
↑ Summary
1 #
2 # This file is part of Pod-Weaver-Section-Collect-FromOther
3 #
4 # This software is Copyright (c) 2011 by Chris Weyl.
5 #
6 # This is free software, licensed under:
7 #
8 # The GNU Lesser General Public License, Version 2.1, February 1999
9 #
10 package Pod::Weaver::Section::Collect::FromOther;
11 {
12 2 $Pod::Weaver::Section::Collect::FromOther::VERSION = '0.002';
13 }
14  
15 # ABSTRACT: Import sections from other POD
16  
17 2 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 2 ▶use namespace::autoclean;
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 2 ▶use Moose::Autobox;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 2 ▶use Path::Class;
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 2 ▶use PPI;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 2 ▶use Pod::Elemental::Selectors -all;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 2 ▶use Pod::Elemental;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 2 ▶use Pod::Elemental::Document;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 2 ▶use Pod::Elemental::Element::Pod5::Command;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 2 ▶use Pod::Elemental::Transformer::Gatherer;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 2 ▶use Pod::Elemental::Transformer::List::Converter;
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 2 ▶use Pod::Weaver::Plugin::EnsurePod5;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 2 ▶use Pod::Weaver::Section::Collect;
Subroutine BEGIN: called CC=1 SCAR=0.0
34  
35 # debugging...
36 #use Smart::Comments '###';
37  
38 2 with
39 'Pod::Weaver::Role::Preparer',
40 ;
41  
42 2 has command => (is => 'ro', isa => 'Str', default => 'from_other', required => 1);
43  
44 has header => (
45 is => 'ro',
46 isa => 'Str',
47 lazy => 1,
48 required => 1,
49 1 ▶ default => sub { shift->plugin_name },
Subroutine __ANON__: called CC=1 SCAR=0.0
50 2 );
51  
52  
53 6 ▶sub prepare_input {
Subroutine prepare_input: called CC=2 SCAR=7.4
Pod documented
54 6 my ($self, $input) = @_;
55  
56 6 my $our_doc = $input->{pod_document};
57  
58 ### our command: $self->command
59 6 my $selector = s_command($self->command);
60 6 ▶ return unless $our_doc->children->grep($selector)->length;
Branch: 1 branch
BranchTrueFalseTotal
unless $our_doc->children->grep($selector)->length 0 6 6
61  
62 # find our commands
63 6 my @elts;
64 6 ▶ $our_doc->children->each_value(sub {
Subroutine __ANON__: called CC=3 SCAR=13.5
65  
66 0 ▶ do { push @elts, $_; return }
Branch: 1 branch
BranchTrueFalseTotal
unless ($_->does("Pod::Elemental::Command") and $_->command eq $self->command) 0 6 6
Condition33%1/3
$_->does("Pod::Elemental::Command") and $_->command eq $self->command
!ll&&!rl&&r
006
MC/DC0%0/2
$_->does("Pod::Elemental::Command") and $_->command eq $self->command
$_->does("Pod::Elemental::Command") $_->command eq $self->command
Truth table33%1/3
A and B
A= $_->does("Pod::Elemental::Command")B= $_->command eq $self->command
ABresult
0X0
100
111
67 unless $_->does('Pod::Elemental::Command') && $_->command eq $self->command;
68  
69 # run against other file and stash
70 6 my ($module, $header_text, $command) = split / \/ /, $_->content;
71 6 my @other_nodes = $self->copy_sections_from_other($module, $header_text, $command);
72  
73 ### @other_nodes
74 ### @elts
75 6 push @elts, @other_nodes; #$self->copy_sections_from_other($module, $header_text, $command);
76 6 });
77  
78 6 $our_doc->children( [ @elts ] );
79  
80 ### $our_doc
81 6 return;
82 }
83  
84 6 ▶sub _find_module {
Subroutine _find_module: called CC=3 SCAR=11.3
85 6 my ($self, $module) = @_;
86  
87 6 my @module_as_fn = split /::/, $module . '.pm';
88  
89 ### looking for: $module
90 6 for my $dir (map { dir $_ } @INC) {
91  
92 6 my $fn = file $dir, @module_as_fn;
93 6 ▶ return $fn if $fn->stat;
Branch: 1 branch
BranchTrueFalseTotal
if $fn->stat 6 0 6
94 }
95  
96 # XXX native logging?
97 0 die "Cannot find $module in \@INC?!";
98 }
99  
100  
101 6 ▶sub copy_sections_from_other {
Subroutine copy_sections_from_other: called CC=4 SCAR=13.9
Pod documented
102 6 my ($self, $module, $header_text, $command) = @_;
103  
104 ### find our remote nodes to copy...
105 6 my $selector = s_command('head1');
106 6 my $fn = $self->_find_module($module);
107  
108 ### $fn
109 6 my $other_doc = Pod::Elemental->read_file($fn);
110 6 Pod::Elemental::Transformer::Pod5->new->transform_node($other_doc);
111  
112 6 my $list_transform = Pod::Elemental::Transformer::List::Converter->new;
113 6 my $nester = Pod::Elemental::Transformer::Nester->new({
114 top_selector => s_command('head1'),
115 content_selectors => [
116 s_command([ qw(head2 head3 head4 over item back) ]),
117 s_flat,
118 ],
119 });
120  
121 6 my $container = Pod::Elemental::Element::Nested->new({
122 command => 'head1',
123 content => $self->header,
124 });
125  
126 ### attack \$other_doc!...
127 6 my @newbies;
128 6 ▶ my $found_command = ($command || q{}) eq 'all' ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
($command || '') eq 'all' ? : 3 3 6
Condition100%2/2
$command || ''
l!l
33
MC/DC100%1/1
$command || ''
$command
Truth table100%2/2
A
A= $command
Aresult
11
00
129  
130 6 $list_transform->transform_node($other_doc);
131 6 $nester->transform_node($other_doc);
132 30 ▶ $other_doc->children->each_value(sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
133  
134 30 ▶ return unless $_->content eq $header_text;
Branch: 1 branch
BranchTrueFalseTotal
unless $_->content eq $header_text 24 6 30
135  
136 6 my @children = @{ $_->children };
137  
138 6 for my $child (@children) {
139  
140 # XXX we likely want to make this optional
141 12 ▶ do { $found_command++ } if $child->does('Pod::Elemental::Command');
Branch: 1 branch
BranchTrueFalseTotal
if ($child->does("Pod::Elemental::Command")) 4 8 12
142 12 ▶ next unless $found_command;
Branch: 1 branch
BranchTrueFalseTotal
unless $found_command 2 10 12
143 10 push @newbies, $child;
144 }
145 6 });
146  
147 ### @newbies
148 6 ▶ return (scalar @newbies ? (@newbies) : ());
Branch: 1 branch
BranchTrueFalseTotal
scalar @newbies ? : 5 1 6
149 }
150  
151 2 __PACKAGE__->meta->make_immutable;
152  
153 2 !!42;
154  
155  
156  
157 =pod
158  
159 =encoding utf-8
160  
161 =head1 NAME
162  
163 Pod::Weaver::Section::Collect::FromOther - Import sections from other POD
164  
165 =head1 VERSION
166  
167 This document describes 0.002 of Pod::Weaver::Section::Collect::FromOther - released February 28, 2012 as part of Pod-Weaver-Section-Collect-FromOther.
168  
169 =head1 DESCRIPTION
170  
171 Copy chunks of POD from other documents, and incorporate them. Our purpose
172 here is to enable the easy documentation of packages that serve to combine
173 parts of preexisting packages (and thus preexisting documentation).
174  
175 =head1 METHODS
176  
177 =head2 prepare_input($input)
178  
179 Check the given C<$input> for any commands that would trigger us, and
180 extract/insert pod as requested.
181  
182 =head2 copy_sections_from_other($module, $header_text, $opts)
183  
184 Loads the POD from C<$module> (specified as a package name, in our
185 C<@INC>), looks for a C<=head1> section with C<$header_text>, and copies
186 everything pulls it out until the next C<=head1> section.
187  
188 We return the elements we find from the first command until the next section;
189 this is to enable preface text to be skipped. This behaviour can be altered
190 by setting C<$opts> to 'all';
191  
192 We return a series of elements suitable for inclusion directly into another
193 document. Note that if this set includes a list, that list will be converted,
194 with each C<=item> command becoming a C<=head2>.
195  
196 =head1 SEE ALSO
197  
198 Please see those modules/websites for more information related to this module.
199  
200 =over 4
201  
202 =item *
203  
204 L<Pod::Weaver>
205  
206 =item *
207  
208 L<Pod::Weaver::Section::Collect>
209  
210 =item *
211  
212 L<L<Reindeer> uses this package to collect documentation from various sources.|L<Reindeer> uses this package to collect documentation from various sources.>
213  
214 =back
215  
216 =head1 SOURCE
217  
218 The development version is on github at L<http://github.com/RsrchBoy/pod-weaver-section-collect-fromother>
219 and may be cloned from L<git://github.com/RsrchBoy/pod-weaver-section-collect-fromother.git>
220  
221 =head1 BUGS
222  
223 Please report any bugs or feature requests on the bugtracker website
224 https://github.com/RsrchBoy/pod-weaver-section-collect-fromother/issues
225  
226 When submitting a bug or request, please include a test-file or a
227 patch to an existing test-file that illustrates the bug or desired
228 feature.
229  
230 =head1 AUTHOR
231  
232 Chris Weyl <cweyl@alumni.drew.edu>
233  
234 =head1 COPYRIGHT AND LICENSE
235  
236 This software is Copyright (c) 2011 by Chris Weyl.
237  
238 This is free software, licensed under:
239  
240 The GNU Lesser General Public License, Version 2.1, February 1999
241  
242 =cut
243  
244  
245 __END__
↑ Summary