1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
package Pod::Elemental::PerlMunger;
our $VERSION = '0.093330';
use Moose::Role;
# ABSTRACT: a thing that takes a string of Perl and rewrites its documentation
use namespace::autoclean;
use PPI;
requires 'munge_perl_string';
around munge_perl_string => sub {
my ($orig, $self, $perl, $arg) = @_;
my $ppi_document = PPI::Document->new(\$perl);
confess(PPI::Document->errstr) unless $ppi_document;
my @pod_tokens = map {"$_"} @{ $ppi_document->find('PPI::Token::Pod') || [] };
$ppi_document->prune('PPI::Token::Pod');
if ($ppi_document->serialize =~ /^=[a-z]/m) {
$self->log(
sprintf "can't invoke %s on %s: there is POD inside string literals",
$self->plugin_name,
(defined $arg->{filename} ? $arg->{filename} : 'input')
);
}
# TODO: I should add a $weaver->weave_* like the Linewise methods to take the
# input, get a Document, perform the stock transformations, and then weave.
# -- rjbs, 2009-10-24
my $pod_str = join "\n", @pod_tokens;
my $pod_document = Pod::Elemental->read_string($pod_str);
my $doc = $self->$orig(
{
ppi => $ppi_document,
pod => $pod_document,
},
$arg,
);
my $new_pod = $doc->{pod}->as_pod_string;
my $end = do {
my $end_elem = $doc->{ppi}->find('PPI::Statement::Data')
|| $doc->{ppi}->find('PPI::Statement::End');
join q{}, @{ $end_elem || [] };
};
$doc->{ppi}->prune('PPI::Statement::End');
$doc->{ppi}->prune('PPI::Statement::Data');
my $new_perl = $doc->{ppi}->serialize;
return $end
? "$new_perl\n\n$new_pod\n\n$end"
: "$new_perl\n__END__\n$new_pod\n";
};
1;
__END__
=pod
=head1 NAME
Pod::Elemental::PerlMunger - a thing that takes a string of Perl and rewrites its documentation
=head1 VERSION
version 0.093330
=head1 OVERVIEW
This role is to be included in classes that rewrite the documentation of a Perl
document, stripping out all the Pod, munging it, and replacing it into the
Perl.
The only relevant method is C<munge_perl_string>, which must be implemented
with a different interface than will be exposed.
When calling the C<munge_perl_string> method, arguments should be passed like
this:
$object->munge_perl_string($perl_string, \%arg);
C<%arg> may contain any input for the underlying procedure. The only key with
associated meaning is C<filename> which may be omitted. If given, it should be
the name of the file whose contents are being munged.
The method will return a string containing the rewritten and combined document.
Classes including this role must implement a C<munge_perl_string> that expects
to be called like this:
$object->munge_perl_string(\%doc, \%arg);
C<%doc> will have two entries:
ppi - a PPI::Document of the Perl document with all its Pod removed
pod - a Pod::Document with no transformations yet performed
This C<munge_perl_string> method should return a hashref in the same format as
C<%doc>.
=head1 AUTHOR
Ricardo SIGNES <rjbs@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2009 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut
|
