NAME

Javascript::Closure - compress your javascript code using Google online service of Closure Compiler

VERSION

0.05

SYNOPSIS

    #nothing is imported by default
    use Javascript::Closure qw(minify :CONSTANTS); 

    #open a file
    open (FILE,'<','jscript.js') or die $!;
    my @lines = <FILE>;
    close FILE;
        
    #compress the code. most of the time it will be all you need!
    my $compressed   = minify(input=>join('',@lines));
    
    #output the result in another file
    open FILE,'>','closure-jscript.js' or die $!;
    print FILE $compressed;
    close FILE;

    #further settings:
    my $compressed = minify(input            => [$string,'http://www.domain.com/my.js',$string2,'http://www.domain2.com/my2.js'],
                            output_format    => XML,
                            output_info      => [STATISTICS,WARNINGS,COMPILED_CODE],
                            compilation_level=> SIMPLE_OPTIMIZATIONS,
                            warning_level        => VERBOSE
    );

DESCRIPTION

This package allows you to compress your javascript code by using the online service of Closure Compiler offered by Google via a REST API.

The Closure compiler offers 3 different level of compression and tools to analyze the code.

You can therefore get errors, warnings about the code and some statistics about the compression.

The Closure compiler offers also some annotations to be used in your code in order to offer optimum compression.

This can come in handy once a project is finish to merge all the files, pass it through the ADVANCED_OPTIMIZATIONS algorithm

to get the most out of it.

See http://closure-compiler.appspot.com/ for further information.

MOTIVATION

Needed a package to encapsulate a coherent API for a future Javascript::Minifier::Any package

and wanted a package with as few dependencies as possible.

ADVANTAGES

Gives you access to the closure compression algo with a unified API. It also gives you access to code analyze via errors, warnings and authorizing via statistics.

SUBROUTINE

minify

    Takes an hash with the following parameters(parameters ended with * are optionals):

    input

    Specify the javascript source to be compressed/analysed. It can be either an url or a scalar.

    You can also use an array reference containing multiple urls or raw source code.

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            
        my $compressed   = minify(input=>$jscode);
        my $compressed   = minify(input=>'http://www.yourdomain.com/yourscript.js');    
        my $compressed   = minify(input=>['http://www.yourdomain.com/yourscript.js','http://www.yourdomain.com/yourscript2.js',$jscode]);     

    compilation_level

    Specifies the algorithm use to compress the javascript code. You can specify them by using one of the following constants:

        WHITESPACE_ONLY
        SIMPLE_OPTIMIZATIONS (default)
        ADVANCED_OPTIMIZATIONS

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            
        my $compressed   = minify(input=>$jscode,compilation_level=>WHITESPACE_ONLY);
    
            #if you do not import the constants:
        my $compressed   = minify(input=>$jscode,compilation_level=>Javascript::Closure::WHITESPACE_ONLY);

    See CONSTANTS section for further information about the algorithms.

    output_info

    Specify the informations you will get back from the service. it accepts either a scalar or an array reference. You can specify them by using the following constants:

         COMPILED_CODE (default)
         WARNINGS
         ERRORS
         STATISTICS

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            
            #you just want to get the code analysed before compression
        my $warnings   = minify(input=>$jscode,output_info=>WARNINGS);
    
            #only the errors in your code
        my $errors   = minify(input=>$jscode,output_info=>ERRORS);
    
            #everything was ok so you want to compressed code and some statistics about the efficiency of the compresssion
        my $errors   = minify(input=>$jscode,output_info=>[COMPILED_CODE,STATISTICS]);
         

    output_format

    Specify the format of the response. It can be one of the following constants:

         TEXT (default)
         JSON
         XML

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            
            #the default
        my $warnings   = minify(input=>$jscode,output_format=>TEXT);
    
            #get back the response as XML
        my $errors   = minify(input=>$jscode,output_format=>XML);
    
            #get back the response as JSON
        my $compress   = minify(input=>$jscode,output_format=>JSON);

    Specifying the format can be useful if you want not only the compiled code but warnings,errors or statistics. Though minify only returns the compressed version of the javascript code as a scalar,you can easily json-ify it to retrieve the information (you could do so with a corresponding XML module):

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            use JSON;
            
            #the default
        my $output     = minify(input=>$jscode,output_format=>JSON,output_info=>[COMPILED_CODE,STATISTICS]);
    
            #change the raw string into perl structure
            my $response   = from_json($output);
    
            my $statistics = $response->{statistics};
            say $statistics->{originalSize};
            say $statistics->{compressedSize};

    Javascript::Closure does not offer shortcuts access to errors,warnings or statistics for now. Might add a Javascript::Closure::Response::JSON to make thing even sweeter but access through an hash is certainly faster and the overhead of function call does not seem necessary...

    warning_level

    Specifies the amount of information you will get when you set the output_info to WARNINGS. You can specify them by using one of the following constants:

        QUIET
        DEFAULT (default)
        VERBOSE

    Example:

        use Javascript::Closure qw(minify :CONSTANTS); 
            
        my $compressed   = minify(input            => $jscode,
                                  compilation_level=> WHITESPACE_ONLY,
                                  output_info      => [COMPILE_CODE,WARNINGS],
                                  warning_level    => VERBOSE
        );

    See CONSTANTS section for further information about the algorithms.

CONSTANTS

Each optional parameter to minify can be specified via constants. If you do not import the :CONSTANTS, you will have to write Javascript::Closure::NAME_OF_THE_CONSTANT;

 - WHITESPACE_ONLY
   remove space and comments from javascript code.

 - SIMPLE_OPTIMIZATIONS
   compress the code by renaming local variables

 - ADVANCED_OPTIMIZATIONS
   compress all local variables, do some clever stripping down of the code (unused functions are removed) 
   but you need to setup external references to do it properly.

See http://code.google.com/intl/ja/closure/compiler/docs/api-tutorial3.html for further information.

 - XML
   return the output in XML format with the information set with your output_info settings

 - JSON
   return the output in JSON format with the information set with your output_info settings

 - TEXT
   return the output in raw text format with the information set with your output_info settings

See http://code.google.com/intl/ja/closure/compiler/docs/api-ref.html#out for further information.

 - COMPILED_CODE
   return only the raw compressed javascript source code.

 - WARNINGS
   return any warnings found by the Closure Compiler (ie,code after a return statement)

 - ERRORS
   return any errors in your javascript code found by the Closure Compiler

 - STATISTICS
   return some statistics about the compilation process (original file size, compressed file size, time,etc)

See http://code.google.com/intl/ja/closure/compiler/docs/api-ref.html#output_info for further information.

 - QUIET

 - DEFAULT

 - VERBOSE

See http://code.google.com/intl/ja/closure/compiler/docs/api-ref.html#warn for further information.

PACKAGE PROPERTY

TIMEOUT

    Set by default to 5s. You can modify it if you need to:

        $Javascript::Closure::Timeout=15;

DIAGNOSTICS

croak

Fail to connect to http://closure-compiler.appspot.com/compile: ...

The module could not connect and successfully compress your javascript. See the detail error to get a hint.

... is not in:...(list of possible value)

One of the optional parameter received does not contain an authorized predefined value.

carp

The following url could not be fetched::...(url that failed)

The module could not connect to the url. See the detail error to get a hint.

TODO

optional parameters

none of the following optional parameters are supported:

 - use_closure_library
 - formatting
 - output_file_name
 - exclude_default_externs
 - externs_url
 - js_externs
copyrights information

If you use the Closure Compiler annotations, you can keep the copyright notice within the comments. If you do not use them though, this package will still offer you a way to add copyright notice after the compression is done.

SEE ALSO

WebService::Google::Closure

JavaScript::Minifier

JavaScript::Packer

JavaScript::Minifier::XS

http://closure-compiler.appspot.com/

CONFIGURATION AND ENVIRONMENT

none

DEPENDENCIES

LWP::UserAgent

INCOMPATIBILITIES

none

BUGS AND LIMITATIONS

If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!

AUTHOR

shiriru <shiriru0111[arobas]hotmail.com>

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 192:

You can't have =items (as at line 196) unless the first thing after the =over is an =item

Around line 331:

'=item' outside of any '=over'

Around line 388:

You forgot a '=back' before '=head1'

You forgot a '=back' before '=head1'

Around line 455:

'=item' outside of any '=over'