Modules required for authortest¶

The authortest requires a bunch of modules above and beyond those required to run "Perl::Critic". The list probably depends on which "Perl::Critic" you are testing, so the following should not be considered definitive. You need the following in addition to all optional modules for Perl::Critic itself.

    Devel::EnforceEncapsulation
    Perl::Critic::More
    Test::Kwalitee
    Test::Memory::Cycle
    Test::Perl::Critic
    Test::Pod
    Test::Pod::Coverage
    Test::Without::Module

You can find out what the optional modules are by looking at recommended_module_versions() in inc/Perl/Critic/BuildUtilities.pm.

In the absence of "Test::Memory::Cycle", the relevant tests are simply skipped. In the absence of the other modules, the tests die horribly. Of course, either way they do not get run, so the difference is mainly one of aesthetics.

Under Perl 5.12 and above, Devel::Cycle 1.11 needs to be patched to handle a "Regexp" as a first-class Perl object. See <https://rt.cpan.org/Public/Bug/Display.html?id=56681> for the details.

Naming Conventions¶

All names are lower-case, except for the names of constants (if any), which are upper-case. When a name contains multiple words, dashes will be used to separate the words in the configuration item name and the command line option, and underscores will be used in the accessor and attribute value names, and constant names if any.

For example, if "new item" is being added, the configuration item is "new-item", the command option is "--new-item", the accessors are new_item(), and the value of the attribute will be stored in "$self->{_new_item}". If there are constants involved, their names will start with "NEW_ITEM_". These names will be used in the following discussion.

Implementation¶

There are several files that must be modified to get your new configuration item and/or command line option.

lib/Perl/Critic/Utils/Constants.pm

If there are manifest constants connected with your implementation they go here. You may well at least have a

    $NEW_ITEM_DEFAULT

to define. All the constants for your new item must be exported, and should be exported not only individually but all together with export tag

    new_item

lib/Perl/Critic/Command.pm

If your new item is a command option, its Getopt::Long specification must be defined in _get_option_specification(). If your new configuration item does not have a corresponding command option, you do not need to make any changes to this file.

lib/Perl/Critic/OptionsProcessor.pm

If your new item is a global configuration item, you need to add the code to handle it here. Specifically:

You must add code to the _init() method to store the value of your item as an attribute value, defaulting it if necessary. Using our naming convention, a single-valued item would be stored like this:

    $self->{_new_item} = delete $args{'new-item'} //
        $NEW_ITEM_DEFAULT;

If the item has synonyms (e.g. both 'color' and 'colour' meaning the same thing), you must check for all of them. If the item took a list of values, they would be parsed apart and stored as an array reference.

You must also add and document an accessor for your new item. This would look something like this:

    sub new_item {
        my ($self) = @_;
        return $self->{_new_item};
    }

In the case of multi-valued items, the accessor must return the array reference, so the above specimen code works in that case also.

Note that no validation is done here -- this class is simply a bridge between the physical .perlcriticrc file and Perl::Critic::Config, which is where the action is.

If your new item is a command option without a corresponding global configuration item, you do not need to modify this file.

lib/Perl/Critic/Config.pm

You must write a _validate_and_store_new_item() method to validate and store the value of the new item. The signature of this method depends on the details of your new item, but it must include at least the value of the item, even if there is no corresponding global configuration item. If it is possible to get validation failures, it will also need an errors object to add the validation exception to. Because the details vary, the best way to proceed is probably to find a method similar to the one you want to write, and implement from there. The _validate_and_store_top() method is a reasonable starting point for an item having a single value. The validated value needs to be stored in "$self->{_new_item}".

You must call _validate_and_store_new_item() in the _init() method.

You must write and document an accessor method for the value of the new item. The typical accessor method for a single-valued item is

    sub new_item {
        my ($self) = @_;
        return $self->{_new_item};
    }

but the accessor for a multi-valued item must return a list:

    sub new_item {
        my ($self) = @_;
        return @{ $self->{_new_item} };
    }

Last, you must document the item itself.

lib/Perl/Critic/ProfilePrototype.pm

If your new item has a corresponding global configuration item, you must update the to_string() method to include the item in the string. Your implementation of the item must be such that the generated string is the same as the input string for the item, except for whitespace.

If your new item has no corresponding global configuration item, you do not need to change this file.

bin/perlcriticrc

If your new item has a corresponding command option, you must document it here. If it does not, you do not need to change this file.

examples/perlcriticrc

If your new item has a corresponding global configuration item, you must add it here. If it does not, you do not need to change this file.

Testing¶

The following test files must be considered for modification:

    t/00_modules.t
    t/01_config.t
    t/01_config_bad_perlcritic.t
    t/04_options_processor.t
    t/07_command.t
    t/10_user_profile.t
    t/16_roundtrip_defaults.t

Depending on your new item, you may not need to change all of these, but you should at least review them. Depending on what your new item actually does, other test files may need to be modified as well.