Perl::Critic::Policy::Modules::RequireVersionVar - Give every module a C<$VERSION> number.

Perl-Critic documentation Contained in the Perl-Critic distribution.

Index

Code Index:

NAME

Top

Perl::Critic::Policy::Modules::RequireVersionVar - Give every module a $VERSION number.

AFFILIATION

Top

This Policy is part of the core Perl::Critic distribution.

DESCRIPTION

Top

Every Perl file (modules, libraries, and programs) should have a package-scoped $VERSION variable. The $VERSION allows clients to insist on a particular revision of your file like this:

    use SomeModule 2.4;  #Only loads version 2.4

This Policy scans your file for any package variable named $VERSION. I'm assuming that you are using strict, so you'll have to declare it like one of these:

    our $VERSION = 1.0611;
    $MyPackage::VERSION = 1.061;
    use vars qw($VERSION);
    use version; our $VERSION = qv(1.0611);

Perl's version system does not recognize lexical variables such as

    my $VERSION = 1.0611;

so they are not accepted by this policy.

A common practice is to use the $Revision: 4078 $ keyword to automatically define the $VERSION variable like this:

    our ($VERSION) = '$Revision: 4078 $' =~ m{ \$Revision: \s+ (\S+) }x;

CONFIGURATION

Top

This Policy is not configurable except for the standard options.

NOTES

Top

Conway recommends using the version pragma instead of raw numbers or 'v-strings.' However, this Policy only insists that the $VERSION be defined somehow. I may try to extend this in the future.

TO DO

Top

Add check that $VERSION is independently evaluatable. In particular, prohibit this:

    our $VERSION = $Other::Module::VERSION;

This doesn't work because PAUSE and other tools literally copy your version declaration out of your module and evaluates it in isolation, at which point there's nothing in Other::Module, and so the $VERSION is undefined.

AUTHOR

Top

Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT

Top

Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.

Perl-Critic documentation Contained in the Perl-Critic distribution. 
##############################################################################
#      $URL: http://perlcritic.tigris.org/svn/perlcritic/trunk/distributions/Perl-Critic/lib/Perl/Critic/Policy/Modules/RequireVersionVar.pm $
#     $Date: 2011-05-15 16:34:46 -0500 (Sun, 15 May 2011) $
#   $Author: clonezone $
# $Revision: 4078 $
##############################################################################

package Perl::Critic::Policy::Modules::RequireVersionVar;

use 5.006001;
use strict;
use warnings;
use Readonly;

use List::MoreUtils qw(any);

use Perl::Critic::Utils qw{ :severities };
use base 'Perl::Critic::Policy';

our $VERSION = '1.116';

#-----------------------------------------------------------------------------

Readonly::Scalar my $DESC => q{No package-scoped "$VERSION" variable found}; ## no critic (RequireInterpolation)
Readonly::Scalar my $EXPL => [ 404 ];

#-----------------------------------------------------------------------------

sub supported_parameters { return ()                       }
sub default_severity     { return $SEVERITY_LOW            }
sub default_themes       { return qw(core pbp readability) }
sub applies_to           { return 'PPI::Document'          }

#-----------------------------------------------------------------------------

sub violates {
    my ( $self, $elem, $doc ) = @_;

    return if $doc->find_first( \&_is_version_declaration );

    #If we get here, then no $VERSION was found
    return $self->violation( $DESC, $EXPL, $doc );
}

#-----------------------------------------------------------------------------

sub _is_version_declaration {  ## no critic (ArgUnpacking)
    return 1 if _is_our_version(@_);
    return 1 if _is_vars_version(@_);
    return 1 if _is_package_version(@_);
    return 1 if _is_readonly_version(@_);
    return 1 if _is_package_argument_version(@_);
    return 0;
}

#-----------------------------------------------------------------------------

sub _is_our_version {
    my (undef, $elem) = @_;
    $elem->isa('PPI::Statement::Variable') || return 0;
    $elem->type() eq 'our' || return 0;
    return any { $_ eq '$VERSION' } $elem->variables(); ## no critic (RequireInterpolation)
}

#-----------------------------------------------------------------------------

sub _is_vars_version {
    my (undef, $elem) = @_;
    $elem->isa('PPI::Statement::Include') || return 0;
    $elem->pragma() eq 'vars' || return 0;
    return $elem =~ m{ \$VERSION }xms; #Crude, but usually works
}

#-----------------------------------------------------------------------------

sub _is_package_version {
    my (undef, $elem) = @_;
    $elem->isa('PPI::Token::Symbol') || return 0;
    return $elem =~ m{ \A \$ \S+ ::VERSION \z }xms;
    #TODO: ensure that it is in _this_ package!
}

#-----------------------------------------------------------------------------

sub _is_readonly_version {

    #---------------------------------------------------------------
    # Readonly VERSION statements usually come in one of two forms:
    #
    #   Readonly our $VERSION = 1.0;
    #   Readonly::Scalar our $VERSION = 1.0;
    #---------------------------------------------------------------

    my (undef, $elem) = @_;
    $elem->isa('PPI::Token::Symbol') || return 0;
    return 0 if $elem !~ m{ \A \$VERSION \z }xms;

    my $psib = $elem->sprevious_sibling() || return 0;
    return 0 if $psib ne 'our';

    my $ppsib = $psib->sprevious_sibling() || return 0;
    return $ppsib eq 'Readonly' || $ppsib eq 'Readonly::Scalar';
}

#-----------------------------------------------------------------------------

sub _is_package_argument_version {
    my (undef, $elem) = @_;
    $elem->isa( 'PPI::Statement::Package' ) or return 0;
    # Perldoc for 5.12.3 documents the statement as
    # package NAMESPACE VERSION
    # with no comma, and the compiler in fact does not accept one.
    my $ver = $elem->schild( 2 )
        or return 0;
    return $ver->isa( 'PPI::Token::Number' );
}

1;

__END__

#-----------------------------------------------------------------------------


# Local Variables:
#   mode: cperl
#   cperl-indent-level: 4
#   fill-column: 78
#   indent-tabs-mode: nil
#   c-indentation-style: bsd
# End:
# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :