NAME

Perl::Critic::Config - Find and load Perl::Critic user-preferences

DESCRIPTION

Perl::Critic::Config takes care of finding and processing user-preferences for Perl::Critic. The Config object defines which Policy modules will be loaded into the Perl::Critic engine and how they should be configured. You should never really need to instantiate Perl::Critic::Config directly because the Perl::Critic constructor will do it for you.

CONSTRUCTOR

new( [ -profile => $FILE, -severity => $N, -include => \@PATTERNS, -exclude => \@PATTERNS ] )

Returns a reference to a new Perl::Critic::Config object, which is basically just a blessed hash of configuration parameters. There aren't any special methods for getting and setting individual values, so just treat it like an ordinary hash. All arguments are optional key-value pairs as follows:

-profile is a path to a configuration file. If $FILE is not defined, Perl::Critic::Config attempts to find a .perlcriticrc configuration file in the current directory, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to point to a file in another location. If a configuration file can't be found, or if $FILE is an empty string, then all Policies will be loaded with their default configuration. See "CONFIGURATION" for more information.

-severity is the minimum severity level. Only Policy modules that have a severity greater than $N will be loaded into this Config. Severity values are integers ranging from 1 (least severe) to 5 (most severe). The default is 5. For a given -profile, decreasing the -severity will usually result in more Policy violations. Users can redefine the severity level for any Policy in their .perlcriticrc file. See "CONFIGURATION" for more information.

-include is a reference to a list of string @PATTERNS. Policies that match at least one m/$PATTERN/imx will be loaded into this Config, irrespective of the severity settings. You can use it in conjunction with the -exclude option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

-exclude is a reference to a list of string @PATTERNS. Polices that match at least one m/$PATTERN/imx will not be loaded into this Config, irrespective of the severity settings. You can use it in conjunction with the -include option. Note that -exclude takes precedence over -include when a Policy matches both patterns.

METHODS

add_policy( -policy => $policy_name, -config => \%config_hash )

Loads a Policy object and adds into this Config. If the object cannot be instantiated, it will throw a warning and return a false value. Otherwise, it returns a reference to this Config. Arguments are key-value pairs as follows:

-policy is the name of a Perl::Critic::Policy subclass module. The 'Perl::Critic::Policy' portion of the name can be omitted for brevity. This argument is required.

-config is an optional reference to a hash of Policy configuration parameters (Note that this is not a Perl::Critic::Config object). The contents of this hash reference will be passed into to the constructor of the Policy module. See the documentation in the relevant Policy module for a description of the arguments it supports.

policies()

Returns a list containing references to all the Policy objects that have been loaded into this Config. Objects will be in the order that they were loaded.

SUBROUTINES

Perl::Critic::Config has a few static subroutines that are used internally, but may be useful to you in some way.

find_profile_path()

Searches the PERLCRITIC environment variable, the current directory, and you home directory (in that order) for a .perlcriticrc file. If the file is found, the full path is returned. Otherwise, returns undef;

site_policies()

Returns a list of all the Policy modules that are currently installed in the Perl::Critic:Policy namespace. These will include modules that are distributed with Perl::Critic plus any third-party modules that have been installed.

native_policies()

Returns a list of all the Policy modules that have been distributed with Perl::Critic. Does not include any third-party modules.

ADVANCED USAGE

All the Policy modules that ship with Perl::Critic are in the "Perl::Critic::Policy" namespace. To load modules from an alternate namespace, import Perl::Critic::Config using the -namespace option like this:

  use Perl::Critic::Config -namespace => 'Foo::Bar'; #Loads from Foo::Bar::*

At the moment, only one alternate namespace may be specified. Unless Policy module names are fully qualified, Perl::Critic::Config assumes that all Policies are in the specified namespace. So if you want to use Policies from multiple namespaces, you will need to use the full module name in your .perlcriticrc file.

CONFIGURATION

The default configuration file is called .perlcriticrc. Perl::Critic::Config will look for this file in the current directory first, and then in your home directory. Alternatively, you can set the PERLCRITIC environment variable to explicitly point to a different file in another location. If none of these files exist, and the -profile option is not given to the constructor, then all the modules that are found in the Perl::Critic::Policy namespace will be loaded with their default configuration.

The format of the configuration file is a series of named sections that contain key-value pairs separated by '='. Comments should start with '#' and can be placed on a separate line or after the name-value pairs if you desire. The general recipe is a series of blocks like this:

    [Perl::Critic::Policy::Category::PolicyName]
    severity = 1
    arg1 = value1
    arg2 = value2

Perl::Critic::Policy::Category::PolicyName is the full name of a module that implements the policy. The Policy modules distributed with Perl::Critic have been grouped into categories according to the table of contents in Damian Conway's book Perl Best Practices. For brevity, you can omit the 'Perl::Critic::Policy' part of the module name.

severity is the level of importance you wish to assign to the Policy. All Policy modules are defined with a default severity value ranging from 1 (least severe) to 5 (most severe). However, you may disagree with the default severity and choose to give it a higher or lower severity, based on your own coding philosophy.

The remaining key-value pairs are configuration parameters that will be passed into the constructor of that Policy. The constructors for most Policy modules do not support arguments, and those that do should have reasonable defaults. See the documentation on the appropriate Policy module for more details.

Instead of redefining the severity for a given Policy, you can completely disable a Policy by prepending a '-' to the name of the module in your configuration file. In this manner, the Policy will never be loaded, regardless of the -severity given to the Perl::Critic::Config constructor.

A simple configuration might look like this:

    #--------------------------------------------------------------
    # I think these are really important, so always load them

    [TestingAndDebugging::RequireUseStrict]
    severity = 5

    [TestingAndDebugging::RequireUseWarnings]
    severity = 5

    #--------------------------------------------------------------
    # I think these are less important, so only load when asked

    [Variables::ProhibitPackageVars]
    severity = 2

    [ControlStructures::ProhibitPostfixControls]
    allow = if unless  #A policy-specific configuration
    severity = 2

    #--------------------------------------------------------------
    # I do not agree with these at all, so never load them

    [-NamingConventions::ProhibitMixedCaseVars]
    [-NamingConventions::ProhibitMixedCaseSubs]

    #--------------------------------------------------------------
    # For all other Policies, I accept the default severity,
    # so no additional configuration is required for them.

A few sample configuration files are included in this distribution under the t/samples directory. The perlcriticrc.none file demonstrates how to disable Policy modules. The perlcriticrc.levels file demonstrates how to redefine the severity level for any given Policy module. The perlcriticrc.pbp file configures Perl::Critic to load only Policies described in Damian Conway's book "Perl Best Practices."

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. 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.

cpanm Perl::Critic

perl -MCPAN -e shell
install Perl::Critic