File Coverage

blib/lib/MDOM/Token/Whitespace.pm
Criterion Covered Total %
statement 11 15 73.3
branch n/a
condition n/a
subroutine 5 7 71.4
pod 3 3 100.0
total 19 25 76.0


line stmt bran cond sub pod time code
1             package MDOM::Token::Whitespace;
2              
3             =pod
4              
5             =head1 NAME
6              
7             MDOM::Token::Whitespace - Tokens representing ordinary white space
8              
9             =head1 INHERITANCE
10              
11             MDOM::Token::Whitespace
12             isa MDOM::Token
13             isa MDOM::Element
14              
15             =head1 DESCRIPTION
16              
17             As a full "round-trip" parser, MDOM records every last byte in a
18             file and ensure that it is included in the L object.
19              
20             This even includes whitespace. In fact, Perl documents are seen
21             as "floating in a sea of whitespace", and thus any document will
22             contain vast quantities of C objects.
23              
24             For the most part, you shouldn't notice them. Or at least, you
25             shouldn't B to notice them.
26              
27             This means doing things like consistently using the "S for significant"
28             series of L and L methods to do things.
29              
30             If you want the nth child element, you should be using C rather
31             than C, and likewise C, C, and
32             so on and so forth.
33              
34             =head1 METHODS
35              
36             Again, for the most part you should really B need to do anything
37             very significant with whitespace.
38              
39             But there are a couple of convenience methods provided, beyond those
40             provided by the parent L and L classes.
41              
42             =cut
43              
44 17     17   84 use strict;
  17         22  
  17         651  
45 17     17   87 use base 'MDOM::Token';
  17         31  
  17         252  
46              
47 17     17   95 use vars qw{$VERSION};
  17         25  
  17         773  
48             BEGIN {
49 17     17   1978 $VERSION = '0.008';
50             }
51              
52             =pod
53              
54             =head2 null
55              
56             Because MDOM sees documents as sitting on a sort of substrate made of
57             whitespace, there are a couple of corner cases that get particularly
58             nasty if they don't find whitespace in certain places.
59              
60             Imagine walking down the beach to go into the ocean, and then quite
61             unexpectedly falling off the side of the planet. Well it's somewhat
62             equivalent to that, including the whole screaming death bit.
63              
64             The C method is a convenience provided to get some internals
65             out of some of these corner cases.
66              
67             Specifically it create a whitespace token that represents nothing,
68             or at least the null string C<''>. It's a handy way to have some
69             "whitespace" right where you need it, without having to have any
70             actual characters.
71              
72             =cut
73              
74 0     0 1 0 sub null { $_[0]->new('') }
75              
76             ### XS -> MDOM/XS.xs:_MDOM_Token_Whitespace__significant 0.900+
77 282     282 1 467 sub significant { '' }
78              
79             =pod
80              
81             =head2 tidy
82              
83             C is a convenience method for removing unneeded whitespace.
84              
85             Specifically, it removes any whitespace from the end of a line.
86              
87             Note that this B include POD, where you may well need
88             to keep certain types of whitespace. The entire POD chunk lives
89             in its own L object.
90              
91             =cut
92              
93             sub tidy {
94 0     0 1   my $self = shift;
95 0           $self->{content} =~ s/^\s+?(?>\n)//;
96 0           1;
97             }
98              
99             1;
100              
101             =pod
102              
103             =head1 SUPPORT
104              
105             See the L in the main module.
106              
107             =head1 AUTHOR
108              
109             Adam Kennedy Eadamk@cpan.orgE
110              
111             =head1 COPYRIGHT
112              
113             Copyright 2001 - 2006 Adam Kennedy.
114              
115             This program is free software; you can redistribute
116             it and/or modify it under the same terms as Perl itself.
117              
118             The full text of the license can be found in the
119             LICENSE file included with this module.
120              
121             =cut