.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "CSS::Squish 3pm" .TH CSS::Squish 3pm "2018-03-31" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CSS::Squish \- Compact many CSS files into one big file .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use CSS::Squish; \& my $concatenated = CSS::Squish\->concatenate(@files); \& \& my $squisher = CSS::Squish\->new( roots => [\*(Aq/root1\*(Aq, \*(Aq/root2\*(Aq] ); \& my $concatenated = $squisher\->concatenate(@files); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module takes a list of \s-1CSS\s0 files and concatenates them, making sure to honor any valid \f(CW@import\fR statements included in the files. .PP The benefit of this is that you get to keep your \s-1CSS\s0 as individual files, but can serve it to users in one big file, saving the overhead of possibly dozens of \s-1HTTP\s0 requests. .PP Following the \s-1CSS 2.1\s0 spec, \f(CW@import\fR statements must be the first rules in a \s-1CSS\s0 file. Media-specific \f(CW@import\fR statements will be honored by enclosing the included file in an \f(CW@media\fR rule. This has the side effect of actually \&\fIimproving\fR compatibility in Internet Explorer, which ignores media-specific \f(CW@import\fR rules but understands \f(CW@media\fR rules. .PP It is possible that future versions will include methods to compact whitespace and other parts of the \s-1CSS\s0 itself, but this functionality is not supported at the current time. .SH "COMMON METHODS" .IX Header "COMMON METHODS" .SS "new( [roots=>[...]] )" .IX Subsection "new( [roots=>[...]] )" A constructor. For backward compatibility with versions prior to 0.06 you can still call everything as a class method, but should remember that roots are shared between all callers in this case. .PP if you're using persistent environment (like mod_perl) then it's very recomended to use objects. .ie n .SS "concatenate( @files )" .el .SS "concatenate( \f(CW@files\fP )" .IX Subsection "concatenate( @files )" Takes a list of files to concatenate and returns the results as one big scalar. .ie n .SS "concatenate_to( $dest, @files )" .el .SS "concatenate_to( \f(CW$dest\fP, \f(CW@files\fP )" .IX Subsection "concatenate_to( $dest, @files )" Takes a filehandle to print to and a list of files to concatenate. \&\f(CW\*(C`concatenate\*(C'\fR uses this method with an \f(CW\*(C`open\*(C'\fRed scalar. .SH "RESOLVING METHODS" .IX Header "RESOLVING METHODS" The following methods help map URIs to files and find them on the disk. .PP In common situation you control \s-1CSS\s0 and can adopt it to use imports with relative URIs and most probably only have to set root(s). .PP However, you can subclass these methods to parse css files before submitting, implement advanced mapping of URIs to file system and other things. .PP Mapping works in the following way. When you call concatenate method we get content of file using file_handle method which as well lookup files in roots. If roots are not defined then files are treated as absolute paths or relative to the current directory. Using of absolute paths is not recommended as unhide server dirrectory layout to clients in css comments and as well don't allow to handle \f(CW@import\fR commands with absolute URIs. When files is found we parse its content for \f(CW@import\fR commands. On each \s-1URI\s0 we call resolve_uri method that convert absolute and relative URIs into file paths. .PP Here is example of processing: .PP .Vb 1 \& roots: /www/overlay/, /www/shared/ \& \& $squisher\->concatenate(\*(Aq/css/main.css\*(Aq); \& \& \->file_handle(\*(Aq/css/main.css\*(Aq); \& \->resolve_file(\*(Aq/css/main.css\*(Aq); \& <\- \*(Aq/www/shared/css/main.css\*(Aq; \& <\- handle; \& \& content parsing \& find \*(Aq@import url(nav.css)\*(Aq \& \-> resolve_uri(\*(Aqnav.css\*(Aq, \*(Aq/css/main.css\*(Aq); \& <\- \*(Aq/css/nav.css\*(Aq; \& ... recursivly process file \& find \*(Aq@import url(/css/another.css)\*(Aq \& \-> resolve_uri(\*(Aq/css/another.css\*(Aq, \*(Aq/css/main.css\*(Aq); \& <\- \*(Aq/css/another.css\*(Aq \& ... .Ve .ie n .SS "roots( @dirs )" .el .SS "roots( \f(CW@dirs\fP )" .IX Subsection "roots( @dirs )" A getter/setter for paths to search when looking for files. .PP The paths specified here are searched for files. This is useful if your server has multiple document roots or document root doesn't match the current dir. .PP See also 'resolve_file' below. .ie n .SS "file_handle( $file )" .el .SS "file_handle( \f(CW$file\fP )" .IX Subsection "file_handle( $file )" Takes a path to a file, resolves (see resolve_file) it and returns a handle. .PP Returns undef if file couldn't be resolved or it's impossible to open file. .PP You can subclass it to filter content, process it with templating system or generate it on the fly: .PP .Vb 2 \& package My::CSS::Squish; \& use base qw(CSS::Squish); \& \& sub file_handle { \& my $self = shift; \& my $file = shift; \& \& my $content = $self\->my_prepare_content($file); \& return undef unless defined $content; \& \& open my $fh, "<", \e$content or warn "Couldn\*(Aqt open handle: $!"; \& return $fh; \& } .Ve .PP \&\fBNote\fR that the file is not resolved yet and is relative to the root(s), so you have to resolve it yourself or call resolve_file method. .ie n .SS "resolve_file( $file )" .el .SS "resolve_file( \f(CW$file\fP )" .IX Subsection "resolve_file( $file )" Lookup file in the root(s) and returns first path it found or undef. .PP When roots are not set just checks if file exists. .ie n .SS "_resolve_file( $file, @roots )" .el .SS "_resolve_file( \f(CW$file\fP, \f(CW@roots\fP )" .IX Subsection "_resolve_file( $file, @roots )" \&\s-1DEPRECATED.\s0 This private method is deprecated and do nothing useful except maintaining backwards compatibility. If you were using it then most probably to find files in roots before submitting them into concatenate method. Now, it's not required and this method returns back file path without changes. .ie n .SS "resolve_uri( $uri_string, $base_file )" .el .SS "resolve_uri( \f(CW$uri_string\fP, \f(CW$base_file\fP )" .IX Subsection "resolve_uri( $uri_string, $base_file )" Takes an \s-1URI\s0 and base file path and transforms it into new file path. .SH "BUGS AND SHORTCOMINGS" .IX Header "BUGS AND SHORTCOMINGS" At the current time, comments are not skipped. This means comments happening before \f(CW@import\fR statements at the top of a file will cause the \f(CW@import\fR rules to not be parsed. Make sure the \f(CW@import\fR rules are the very first thing in the file (and only one per line). Processing of \f(CW@import\fR rules stops as soon as the first line that doesn't match an \f(CW@import\fR rule is encountered. .PP All other bugs should be reported via or bug\-CSS\-Squish@rt.cpan.org. .SH "AUTHOR" .IX Header "AUTHOR" Thomas Sibley , Ruslan Zakirov .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2006. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.