PerlPoint/Import/POD.pm untested

filter: Statementstmt 0.0% 0 / 28 Branchbran 0.0% 0 / 4 Conditioncond 0.0% 0 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 0.0% 0 / 4 Podpod 0.0% 0 / 1 totaltotal 0.0% 0 / 42 CC 3 SCAR 19.5
CC
3
Cov
0%
importFilter
12.0
BEGIN
2.0
BEGIN
2.0
CRAP 7.0
1
2
3
4 # = HISTORY SECTION =====================================================================
5
6 # ---------------------------------------------------------------------------------------
7 # version | date | author | changes
8 # ---------------------------------------------------------------------------------------
9 # 0.01 |09.04.2006| JSTENZEL | new.
10 # ---------------------------------------------------------------------------------------
11
12 # = POD SECTION =========================================================================
13
14 =head1 NAME
15
16 B<PerlPoint::Import::POD> - a standard PerlPoint import filter for POD
17
18 =head1 VERSION
19
20 This manual describes version B<0.01>.
21
22 =head1 SYNOPSIS
23
24 # command line: process a POD file
25 perlpoint ... IMPORT:file.pod
26
27 ...
28
29 # or, in a PerlPoint source:
30
31 // include a POD file with "pod" extension
32 \INCLUDE{import=1 file="example.pod"}
33
34 // include a POD file without "pod" extension
35 \INCLUDE{import=pod file="example"}
36
37 // import a snippet in POD,
38 // which in turn contains some PerlPoint
39 \EMBED{import=pod}
40
41 =head2 Embedded PerlPoint
42
43 A POD paragraph.
44
45 =for perlpoint It \I<works>!
46
47 \END_EMBED
48
49
50 =head1 DESCRIPTION
51
52 Standard import filters are loaded automatically by the Parser
53 when you import a POD file in one of the ways shown in the
54 I<SYNOPSIS>.
55
56
57 =head1 FUNCTION
58
59 According to the standard import filter API (see C<PerlPoint::Parser>) this
60 module provides one function, C<importFilter()>. I transforms a POD file
61 into PerlPoint.
62
63 =cut
64
65
66
67
68 # check perl version
69 require 5.00503;
70
71 # = PACKAGE SECTION ======================================================================
72
73 # declare package
74 package PerlPoint::Import::POD;
75
76 # declare package version
77 $VERSION=0.01;
78
79
80 # = PRAGMA SECTION =======================================================================
81
82 # set pragmata
83 use strict;
84
85
86 # = LIBRARY SECTION ======================================================================
87
88 # load libraries
89 use Pod::PerlPoint 0.05;
90
91 # declare the filter function
92 sub importFilter
93 {
94 # declare variables
95 my ($pod2pp, $result, $i);
96
97 # get source and sourcefile name
98 my ($pod, $sourcefile)=(join('', "\n\n\n", @main::_ifilterText), $main::_ifilterFile);
99
100 # transform it into PerlPoint
101 {
102 # build a translator object and configure it
103 ($pod2pp, $result)=(new Pod::PerlPoint());
104 $pod2pp->output_string(\$result);
105 $pod2pp->configure(parser40=>($PerlPoint::Parser::VERSION>=0.40));
106
107 # parse file
108 my $rc=$pod2pp->parse_string_document($pod);
109 $i++, $pod="\n\n=pod\n\n$pod", redo unless $result or $i;
110
111 # report errors, if any
112 if (exists $pod2pp->{errata})
113 {
114 warn "\nPOD error detected in $sourcefile:\n\n";
115 foreach (sort {$a <=> $b} keys %{$pod2pp->{errata}})
116 {warn "Line $_:\n\n", map {"$_\n"} @{$pod2pp->{errata}{$_}};}
117
118 # flag the error
119 die "\n";
120 }
121 }
122
123 # supply result (add leading newlines to let the parser detect a *new*
124 # paragraph and therefore recognize the special paragraph menaing of the
125 # dot added by Pod::PerlPoint to the first paragraph)
126 "\n\n$result";
127 }
128
129
130 # flag successful loading
131 1;
132
133
134
135
136 # = POD TRAILER SECTION =================================================================
137
138 =pod
139
140 =head1 NOTES
141
142 None that far.
143
144 =head1 SEE ALSO
145
146 =over 4
147
148 =item B<Pod::PerlPoint>
149
150 The module implementing POD to PerlPoint conversion.
151
152 =item B<Bundle::PerlPoint>
153
154 A bundle of packages to deal with PerlPoint documents.
155
156 =item B<pod2pp>
157
158 A standalone POD to PerlPoint translator, distributed
159 and installed with this module.
160
161 =back
162
163
164 =head1 SUPPORT
165
166 A PerlPoint mailing list is set up to discuss usage, ideas,
167 bugs, suggestions and translator development. To subscribe,
168 please send an empty message to perlpoint-subscribe@perl.org.
169
170 If you prefer, you can contact me via perl@jochen-stenzel.de
171 as well.
172
173
174 =head1 AUTHOR
175
176 Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2006.
177 All rights reserved.
178
179 This module is free software, you can redistribute it and/or modify it
180 under the terms of the Artistic License distributed with Perl version
181 5.003 or (at your option) any later version. Please refer to the
182 Artistic License that came with your Perl distribution for more
183 details.
184
185 The Artistic License should have been included in your distribution of
186 Perl. It resides in the file named "Artistic" at the top-level of the
187 Perl source tree (where Perl was downloaded/unpacked - ask your
188 system administrator if you dont know where this is). Alternatively,
189 the current version of the Artistic License distributed with Perl can
190 be viewed on-line on the World-Wide Web (WWW) from the following URL:
191 http://www.perl.com/perl/misc/Artistic.html
192
193
194 =head1 DISCLAIMER
195
196 This software is distributed in the hope that it will be useful, but
197 is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
198 implied, INCLUDING, without limitation, the implied warranties of
199 MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.
200
201 The ENTIRE RISK as to the quality and performance of the software
202 IS WITH YOU (the holder of the software). Should the software prove
203 defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
204 CORRECTION.
205
206 IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
207 MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
208 ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
209 if they arise from known or unknown flaws in the software).
210
211 Please refer to the Artistic License that came with your Perl
212 distribution for more details.
213