NAME
JavaScript::Squish - Reduce/Compact JavaScript code to as few characters as possible.
SYNOPSIS
use JavaScript::Squish;
my $compacted = JavaScript::Squish->squish(
$javascript,
remove_comments_exceptions => qr/copyright/i )
or die $JavaScript::Squish::err_msg;# OR, to just do a few steps #
my $c = JavaScript::Squish->new();
$c->data( $javascript );
$c->extract_strings_and_comments();
$c->replace_white_space();
my $new = $c->data();DESCRIPTION
This module provides methods to compact javascript source down to just what is needed. It can remove all comments, put everything on one line (semi-)safely, and remove extra whitespace.
Any one of the various compacting techniques can be applied individually, or with in any group.
It also provides a means by which to extract all text literals or comments in separate arrays in the order they appear.
Since JavaScript eats up bandwidth, this can be very helpful, and you can then be free to properly comment your JavaScript without fear of burning up too much bandwidth.
EXPORT
None by default.
"squish" may be exported via "use JavaScript::Squish qw(squish);"
METHODS
JavaScript::Squish->squish($js [, %options] )
Class method. This is a wrapper around all methods in here, to allow you to do all compacting operations in one call.
my $squished = JavaScript::Squish->squish( $javascript );Current supported options:
- remove_comments_exceptions : array ref of regexp's
-
B<JavaScript::Squish-E<gt>squish($js, remove_comments_exceptions =E<gt> [ qr/copyright/i ] )>Any comment strings matching any of the supplied regexp's will not be removed. This is the recommended way to retain copyright notices, while still compacting out all other comments.
JavaScript::Squish->new()
Constructor. Currently takes no options. Returns JavaScript::Squish object.
NOTE: if you want to specify a "remove_comments_exceptions" option via one of these object, you must do so directly against the remove_comments() method (SEE BELOW).
$djc->data($js)
If the option $js is passed in, this sets the javascript that will be worked on.
If not passed in, this returns the javascript in whatever state it happens to be in (so you can step through, and pull the data out at any time).
$djc->strings()
Returns all strings extracted by either extract_literal_strings() or extract_strings_and_comments() (NOTE: be sure to call one of the aforementioned extract methods prior to strings(), or you won't get anything back).
$djc->comments()
Returns all comments extracted by either extract_comments() or extract_strings_and_comments() (NOTE: be sure to call one of the aforementioned extract methods prior to strings(), or you won't get anything back).
$djc->determine_line_ending()
Method to automatically determine the line ending character in the source data.
$djc->eol_char("\n")
Method to set/override the line ending character which will be used to parse/join lines. Set to "\r\n" if you are working on a DOS / Windows formatted file.
$djc->extract_strings_and_comments()
Finds all string literals (eg. things in quotes) and comments (// or /*...*/) and replaces them with tokens of the form "\0\0N\0\0" and "\0\0_N_\0\0" respectively, where N is the occurrance number in the file, and \0 is the null byte. The strings are stored inside the object so they may be resotred later.
After calling this, you may retrieve a list of all extracted strings or comments using the strings() or comments() methods.
$djc->extract_literal_strings()
This is a wrapper around extract_strings_and_comments(), which will restore all comments afterwards (if they had not been stripped prior to its call).
NOTE: sets $djc->strings()
$djc->extract_comments()
This is a wrapper around extract_strings_and_comments(), which will restore all literal strings afterwards (if they had not been stripped prior to its call).
NOTE: sets $djc->comments()
$djc->replace_white_space()
Per each line:
Removes all begining of line whitespace.
Removes all end of line whitespace.
Combined all series of whitespace into one space character (eg. s/\s+/ /g)
Comments and string literals (if still embeded) are untouched.
$djc->remove_blank_lines()
...does what it says.
Comments and string literals (if still embeded) are untouched.
$djc->combine_concats()
Removes any string literal concatenations. Eg.
"bob and " + "sam " + someVar;Becomes:
"bob and sam " + someVarComments (if still embeded) are untouched.
$djc->join_all()
Puts everything on one line.
Coments begining with "//", if still embeded, are the exception, as they require a new line character at the end of the comment.
$djc->replace_extra_whitespace()
This removes any excess whitespace. Eg.
if (someVar = "foo") {Becomes:
if(someVar="foo"){Comments and string literals (if still embeded) are untouched.
$djc->remove_comments(%options)
Current supported options:
- exceptions : array ref of regexp's
-
B<$djc-E<gt>remove_comments( exceptions =E<gt> [ qr/copyright/i ] )>Any comment strings matching any of the supplied regexp's will not be removed. This is the recommended way to retain copyright notices, while still compacting out all other comments.
NOTE: this is destructive (ie. you cannot restore comments after this has been called).
$djc->restore_comments()
All comments that were extracted with $djc->extract_strings_and_comments() or $djc->extract_comments() are restored. Comments retain all spacing and extra lines and such.
$djc->restore_literal_strings()
All string literals that were extracted with $djc->extract_strings_and_comments() or $djc->extract_comments() are restored. String literals retain all spacing and extra lines and such.
$djc->replace_final_eol()
Prior to this being called, the end of line may not terminated with a new line character (especially after some of the steps above). This assures the data ends in at least one of whatever is set in $djc->eol_char().
NOTES
The following should only cause an issue in rare and odd situations... If the input file is in dos format (line termination with "\r\n" (ie. CR LF / Carriage return Line feed)), we'll attempt to make the output the same. If you have a mixture of embeded "\r\n" and "\n" characters (not escaped, those are still safe) then this script may get confused and make them all conform to whatever is first seen in the file.
TODO
Function and variable renaming, and other more dangerous compating techniques.
Currently, JavaScript::Squish::err_msg never gets set, as we die on any real errors. We should look into returning proper error codes and setting this if needed.
Fix Bugs :-)
BUGS
There are a few bugs, which may rear their head in some minor situations.
- Statements not terminated by semi-colon.
-
Javascript statement that are NOT terminated by a semi-colon (";") may break once compacted, as they will be put on the same line as the following statement. In many cases, this won't be a problem, but it could cause an issue. Ex.
i = 5.4 j = 42The above would become "i=5.4 j=42", and would generate an error along the lines of "expected ':' before statement".
- Ambiguous operator precidence
-
Operator precidence may get screwed up in ambiguous statements. Eg. "x = y + ++b;" will be compacted into "x=y+++b;", which means something different.
Still looking for them. If you find some, let us know.
SEE ALSO
AUTHOR
Joshua I. Miller <jmiller@puriifeddata.net>
COPYRIGHT AND LICENSE
Copyright (c) 2005 by CallTech Communications, Inc.
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.