NAME

Perl::Critic::Policy::Dynamic::ValidateAgainstSymbolTable

DESCRIPTION

This Policy warns if any subroutine call that appears in your code is not defined in the symbol table at compile-time. The intent is to detect typos in the names of packages and subroutines, and possible failures to import, declare, or include all the static subroutines that are invoked by your code..

VERY IMPORTANT: Most Perl::Critic Policies (including all the ones that ship with Perl::Critic> use pure static analysis -- they never compile nor execute any of the code that they analyze. However, this policy is very different. It actually attempts to compile your code and then compares the subroutines mentioned in your code to those found in the symbol table. Therefore you should not use this Policy on any code that you do not trust, or may have undesirable side-effects at compile-time (such as connecting to the network or mutating files).

For these reasons, this Policy (and any other Policy that inherits from Perl::Critic::DynamicPolicy) is marked as "unsafe" and usually ignored by both Perl::Critic and perlcritic. So to use this Policy, you must set the -allow-unsafe switch in the Perl::Critic contstructor or on the perlcritic command line.

For this Policy to work, all the modules included in your code must be installed locally, and must compile without error. See "CONFIGURATION" for information about controlling where this Policy searches for the included modules.

LIMITATIONS

This Policy will not detect subroutines that are declared at run-time or through direct manipulation of the symbol table, which may lead to false warnings. The most common examples of this are modules that use AUTOLOAD.

Sophisticated code often use the require function to postpone loading modules or only load modules under certain conditions. If you set the inspect_required_modules option, the Policy will attempt to load all modules that are require'd at any point in your code. However, this Policy does not know whether the module would have been loaded during normal execution of your program. This may cause the Policy to overlook potential violations.

This Policy only examines static subroutine calls -- method calls are not covered. Indirect method calls such as "my $fh = new FileHandle" also tend to trigger false warnings.

This Policy compiles your code into the same symbol table as Perl::Critic itself. So to maintain integrity in the symbol table, this Policy forks itself before analyzing each file. On some systems, this may be slow and consume a lot of resources.

CONFIGURATION

This Policy supports the following configuration parameters. See below for example of how to set these parameters in you f<.perlcriticrc> file.

at_inc_prefix

Prepends an arrayref of directories to the front of the current @INC list. This affects where the Policy will find dependent modules when it compiles your code.

at_inc_suffix

Appends an arrayref of directories to the end of the current @INC list. This affects where the Policy will find dependent modules when it compiles your code.

at_inc

Sets the @INC list outright. This affects where the Policy will find dependent modules when it compiles your code.

inspect_required_modules

By default, this Policy only examines modules that are loaded by your code at compile-time. If inspect_required_modules is set to a true value, this Policy will also compile all the modules that are require'd in your code at runtime. Note that this Policy does not know if these modules will actually be loaded when your program runs, nor does it try to invoke the import method on those modules.

inspect_autoloaders

By default, this Policy does not attempt to validate a function call into a package that has an AUTOLOAD method. Such packages usually define functions at run-time, so this Policy has no chance of knowing what functions that package might have. But if inspect_autoloaders is set to a true value, the Policy will check to see if a function exists in such packages.

max_recursion

By default, this Policy only looks at the symbol tables for the namespaces that are directly use'd (or require'd) by your code. However, some modules contain multiple namespaces which may lead to false violations. But if you set max_recursion to a positive integer, this Policy will recurse into those other namespaces. Beware, however, that using a deep recursion can mask other violations. Setting max_recursion to 1 or 2 is usually sufficient.

You can set these configuration parameters but putting any or all of the following in your .perlcriticrc file.

[Dynamic::ValidateAgainstSymbolTable]

at_inc_prefix = some/directory/path | another/directory/path
at_inc_suffix = some/directory/path | another/directory/path
at_inc = some/directory/path | another/directory/path

inspect_required_modules = 1
inspect_autoloaders   = 1

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2007 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.