File Coverage

blib/lib/JavaScript/JSLint.pm

Criterion	Covered	Total	%
statement	10	12	83.3
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	14	16	87.5

# @(#) $Id$

package JavaScript::JSLint;

use strict;
use warnings;

use Carp;
use JavaScript;
use JSON qw(encode_json);

use base qw( Exporter );

our @EXPORT = qw( jslint );
our @EXPORT_OK = qw( jslint jslint_options );

our $VERSION = '0.07';


my %JSLINT_OPTIONS = (
    adsafe     => {type => 'bool', desc => 'ADsafe rules should be enforced'},
    bitwise    => {type => 'bool', desc => 'bitwise operators should be allowed'},
    browser    => {type => 'bool', desc => 'the standard browser globals should be predefined'},
    confusion  => {type => 'bool', desc => 'types can be used inconsistently'},
    'continue' => {type => 'bool', desc => 'the continuation statement should be tolerated'},
    debug      => {type => 'bool', desc => 'debugger statements should be allowed'},
    devel      => {type => 'bool', desc => 'logging should be allowed (console, alert, etc.)'},
    eqeq       => {type => 'bool', desc => '== should be allowed'},
    es5        => {type => 'bool', desc => 'ES5 syntax should be allowed'},
    evil       => {type => 'bool', desc => 'eval should be allowed'},
    forin      => {type => 'bool', desc => 'for in statements need not filter'},
    fragment   => {type => 'bool', desc => 'HTML fragments should be allowed'},
    indent     => {type => 'int',  desc => 'the indentation factor'},
    maxerr     => {type => 'int',  desc => 'the maximum number of errors to allow'},
    maxlen     => {type => 'int',  desc => 'the maximum length of a source line'},
    newcap     => {type => 'bool', desc => 'constructor names capitalization is ignored'},
    node       => {type => 'bool', desc => 'Node.js globals should be predefined'},
    nomen      => {type => 'bool', desc => 'names may have dangling _'},
    on         => {type => 'bool', desc => 'HTML event handlers should be allowed'},
    passfail   => {type => 'bool', desc => 'the scan should stop on first error'},
    plusplus   => {type => 'bool', desc => 'increment/decrement should be allowed'},
    properties => {type => 'bool', desc => 'all property names must be declared with /*properties*/'},
    predef     => {type => 'hash', desc => 'predefine global variables'},
    regexp     => {type => 'bool', desc => 'the . should be allowed in regexp literals'},
    rhino      => {type => 'bool', desc => 'the Rhino environment globals should be predefined'},
    'undef'    => {type => 'bool', desc => 'variables can be declared out of order'},
    unparam    => {type => 'bool', desc => 'unused parameters should be tolerated'},
    safe       => {type => 'bool', desc => 'use of some browser features should be restricted'},
    sloppy     => {type => 'bool', desc => 'the \'use strict\'; pragma is optional'},
    'sub'      => {type => 'bool', desc => 'all forms of subscript notation are tolerated'},
    vars       => {type => 'bool', desc => 'multiple var statements per function should be allowed'},
    white      => {type => 'bool', desc => 'sloppy whitespace is tolerated'},
    widget     => {type => 'bool', desc => 'the Yahoo Widgets globals should be predefined'},
    windows    => {type => 'bool', desc => 'MS Windows-specific globals should be predefined'},
);



{
    my $ctx;
    my $jslint_source = do { local $/;  };

    sub _get_context {
        unless ( $ctx ) {
            $ctx = JavaScript::Runtime->new()->create_context();
            $ctx->eval( $jslint_source, "fulljslint.js" );
        }
        return $ctx;
    }
}

sub _make_fatal_error {
    my ( $err ) = @_;
    my %newerr = %$err;
    $newerr{ id }     = '(fatal)';
    $newerr{ reason } = 'Cannot proceed.';
    return \%newerr;
}

sub jslint {
    my ( $js_source, %opt ) = @_;
    croak "usage: jslint(js_source)"
      unless defined $js_source;
    my $ctx = _get_context();

    my $js_source_str = encode_json(
        [ split(/\n/, $js_source) ]
    );

    my $predef = $opt{predef} || {};
    if ( $predef && ref $predef eq 'HASH' ) {
        %{$predef} = map {
            $_ => ( $predef->{$_} ? JSON::true : JSON::false )
        } keys %{$predef};
    }
    $opt{predef} = $predef;

    my $opt_str = encode_json( {
        map {
            $_ => (
                ($JSLINT_OPTIONS{$_} && $JSLINT_OPTIONS{$_}->{type} eq 'bool')
                    ? ( $opt{$_} ? JSON::true : JSON::false )
                    : $opt{$_}
            );
        } keys %opt
    } );

    my $ok = $ctx->eval(qq/
        JSLINT($js_source_str,$opt_str);
    /);

    die "$@" if $@;
    if ( $ok ) {
        return;
    }
    else {
        my @errors = @{ $ctx->eval( "JSLINT.errors" ) };
        # Remove the trailing undefined value, which JSLint returns if it's
        # unable to proceed.
        pop @errors if !defined $errors[-1];
        return @errors;
        # I don't think this is necessary any longer
        #return map { _fix_line_and_char_numbers( $_ ) } @errors;
    }
}

# TODO: generate this list by parsing the source below.
sub jslint_options {
    my $want_full_options = shift;
    return map {
        $_ => $want_full_options ? $JSLINT_OPTIONS{$_} : $JSLINT_OPTIONS{$_}->{desc}
    } keys %JSLINT_OPTIONS;
}


1;

=head1 NAME

JavaScript::JSLint - Check JavaScript code for problems

=head1 SYNOPSIS

  use JavaScript::JSLint;

  my @errors = jslint( $javascript, white => 1 );
  foreach my $err (@errors) {
    print "$err->{reason} at line $err->{line}\n";
  }

=head1 DESCRIPTION

JavaScript::JSLint is a tool for checking for common problems in
JavaScript code.  It's based on Douglas Crockford's jslint.  Full
documentation on the conditions that it detects is at
L.

You may be more interested in the command line interface, L.

=head2 EXPORT

=over 4

=item jslint()

This takes one mandatory parameter: a string containing JavaScript code.
It returns a list of errors. If there are no problems, an empty list will
be returned. Each error is a hash reference containing these keys:

=over 4

=item I

The category of error.

=item I

The line number of the error.

=item I

The character on the line where the error occurs.

=item I

Descriptive text of the error.

=item I

A copy of the line of code that produced the error.

=back

In addition to pure JavaScript, you can also pass in a piece of HTML
code.  This will be parsed and any JavaScript found within will be
checked in the usual manner.  The HTML code must be a full web page,
i.e. start with C<<  >>.

You can optionally pass in a second parameter to influence how JSLint works.
The following keys are used. Most take a boolean value, which is false by
default.

=over 4

=item I

true, if ADsafe rules should be enforced

=item I

true, if bitwise operators should be allowed

=item I

true, if the standard browser globals should be predefined

=item I

true, if types can be used inconsistently

=item I

true, if the continuation statement should be tolerated

=item I

true, if debugger statements should be allowed

=item I

true, if logging should be allowed (console, alert, etc.)

=item I

true, if C<==> should be allowed

=item I

true, if ES5 syntax should be allowed

=item I

true, if eval should be allowed

=item I

true, if C statements need not filter

=item I

true, if HTML fragments should be allowed

=item I

the indentation factor

=item I

the maximum number of errors to allow

=item I

the maximum length of a source line

=item I

true, if constructor names capitalization is ignored

=item I

true, if Node.js globals should be predefined

=item I

true, if names may have dangling C<_>

=item I

true, if HTML event handlers should be allowed

=item I

true, if the scan should stop on first error

=item I

true, if increment/decrement should be allowed

=item I

true, if all property names must be declared with C

=item I

predefine variables as globals. A reference to either an array or a hash. If an
arrayref, the elements of the array should be the names of the variables to be
predefined. If a hashref, the keys are the variable names to be defined and the
values indicate whether a variable is assignable (C<1>) or not (C<0>).

=item I

true, if C<.> and C<[^...]> should be allowed in regexp literals

=item I

true, if the Rhino environment globals should be predefined

=item I

true, if variables can be declared out of order

=item I

true, if unused parameters should be tolerated

=item I

true, if use of some browser features should be restricted

=item I

true, if the \'use strict\'; pragma is optional

=item I

true, if all forms of subscript notation are tolerated

=item I

true, if multiple C statements per function should be allowed

=item I

true, if sloppy whitespace is tolerated

=item I

true, if the Yahoo Widgets globals should be predefined

=item I

true, if MS Windows-specific globals should be predefined

=back

=item jslint_options ( )

Returns a hash of options and their descriptions. Each key is a valid option
to pass in to jslint().

=back

=head1 SEE ALSO

L for the original version that this is based upon.

L for more details on the Perl / JavaScript bridge.

L for the command line interface.

L is an alternative implementation of a
JavaScript lint tool.

=head1 AUTHOR

Dominic Mitchell, Ecpan (at) happygiraffe.netE

Steve Webster, Ecpan (at) statichtml.comE

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2006 by Dominic Mitchell

Portions copyright (C) 2011 by Steve Webster

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

=over 4

=item 1.

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

=item 2.

Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

=back

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

JSLint is originally Copyright (C) 2002 Douglas Crockford.

=cut

# http://www.jslint.com/fulljslint.js
__DATA__