File Coverage

blib/lib/CSS/Minifier/XS.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package CSS::Minifier::XS;
2              
3 1     1   91163 use strict;
  1         22  
  1         33  
4 1     1   5 use warnings;
  1         2  
  1         122  
5              
6             require Exporter;
7             require DynaLoader;
8             our @ISA = qw(Exporter DynaLoader);
9             our @EXPORT_OK = qw(minify);
10              
11             our $VERSION = '0.12';
12              
13             bootstrap CSS::Minifier::XS $VERSION;
14              
15             1;
16              
17             =for stopwords minifier minifies minified minification eol tokenizing
18              
19             =head1 NAME
20              
21             CSS::Minifier::XS - XS based CSS minifier
22              
23             =head1 SYNOPSIS
24              
25             use CSS::Minifier::XS qw(minify);
26             my $css = '...';
27             my $minified = minify($css);
28              
29             =head1 DESCRIPTION
30              
31             C is a CSS "minifier"; its designed to remove unnecessary
32             whitespace and comments from CSS files, while also B breaking the CSS.
33              
34             C is similar in function to C, but is
35             substantially faster as its written in XS and not just pure Perl.
36              
37             =head1 METHODS
38              
39             =over
40              
41             =item minify($css)
42              
43             Minifies the given C<$css>, returning the minified CSS back to the caller.
44              
45             =back
46              
47             =head1 HOW IT WORKS
48              
49             C minifies the CSS by removing unnecessary whitespace from
50             CSS documents. Comment blocks are also removed, I when (a) they
51             contain the word "copyright" in them, or (b) they're needed to implement the
52             "Mac/IE Comment Hack".
53              
54             Internally, the minification is done by taking multiple passes through the CSS
55             document:
56              
57             =head2 Pass 1: Tokenize
58              
59             First, we go through and parse the CSS document into a series of tokens
60             internally. The tokenizing process B check to make sure that you've
61             got syntactically valid CSS, it just breaks up the text into a stream of tokens
62             suitable for processing by the subsequent stages.
63              
64             =head2 Pass 2: Collapse
65              
66             We then march through the token list and collapse certain tokens down to their
67             smallest possible representation. I they're still included in the final
68             results we only want to include them at their shortest.
69              
70             =over
71              
72             =item Whitespace
73              
74             Runs of multiple whitespace characters are reduced down to a single whitespace
75             character. If the whitespace contains any "end of line" (EOL) characters, then
76             the end result is the I EOL character encountered. Otherwise, the
77             result is the first whitespace character in the run.
78              
79             =item Comments
80              
81             Comments implementing the "Mac/IE Comment Hack" are collapsed down to the
82             smallest possible comment that would still implement the hack ("/*\*/" to start
83             the hack, and "/**/" to end it).
84              
85             =item Zero Units
86              
87             Zero Units (e.g. C<0px>) are reduced down to just "0", as the CSS specification
88             indicates that the unit is not required when its a zero value.
89              
90             =back
91              
92             =head2 Pass 3: Pruning
93              
94             We then go back through the token list and prune and remove unnecessary
95             tokens.
96              
97             =over
98              
99             =item Whitespace
100              
101             Wherever possible, whitespace is removed; before+after comment blocks, and
102             before+after various symbols/sigils.
103              
104             =item Comments
105              
106             Comments that either (a) are needed to implement the "Mac/IE Comment Hack", or
107             that (b) contain the word "copyright" in them are preserved. B other
108             comments are removed.
109              
110             =item Symbols/Sigils
111              
112             Semi-colons that are immediately followed by a closing brace (e.g. ";}") are
113             removed; semi-colons are needed to separate multiple declarations, but aren't
114             required at the end of a group.
115              
116             =item Everything else
117              
118             We keep everything else; identifiers, quoted literal strings, symbols/sigils,
119             etc.
120              
121             =back
122              
123             =head2 Pass 4: Re-assembly
124              
125             Lastly, we go back through the token list and re-assemble it all back into a
126             single CSS string, which is then returned back to the caller.
127              
128             =head1 AUTHOR
129              
130             Graham TerMarsch (cpan@howlingfrog.com)
131              
132             =head1 COPYRIGHT
133              
134             Copyright (C) 2007-, Graham TerMarsch. All Rights Reserved.
135              
136             This is free software; you can redistribute it and/or modify it under the same
137             license as Perl itself.
138              
139             =head1 SEE ALSO
140              
141             C.
142              
143             =cut