Perl::Critic::Document - Caching wrapper around a PPI::Document.
use PPI::Document; use Perl::Critic::Document; my $doc = PPI::Document->new('Foo.pm'); $doc = Perl::Critic::Document->new(-source => $doc); ## Then use the instance just like a PPI::Document
Perl::Critic does a lot of iterations over the PPI document tree via the
PPI::Document::find() method. To save some time, this class pre-caches a lot of the common
find() calls in a single traversal. Then, on subsequent requests we return the cached data.
This is implemented as a facade, where method calls are handed to the stored
This facade does not implement the overloaded operators from PPI::Document (that is, the
use overload ... work). Therefore, users of this facade must not rely on that syntactic sugar. So, for example, instead of
my $source = "$doc"; you should write
my $source = $doc->content();
Perhaps there is a CPAN module out there which implements a facade better than we do here?
This is considered to be a public class. Any changes to its interface will go through a deprecation cycle.
new(-source => $source_code, '-filename-override' => $filename, '-program-extensions' => [program_extensions])
Create a new instance referencing a PPI::Document instance. The
$source_code can be the name of a file, a reference to a scalar containing actual source code, or a PPI::Document or PPI::Document::File.
In the event that
$source_code is a reference to a scalar containing actual source code or a PPI::Document, the resulting Perl::Critic::Document will not have a filename. This may cause Perl::Critic::Document to incorrectly classify the source code as a module or script. To avoid this problem, you can optionally set the
-filename-override to force the Perl::Critic::Document to have a particular
$filename. Do not use this option if
$source_code is already the name of a file, or is a reference to a PPI::Document::File.
The '-program-extensions' argument is optional, and is a reference to a list of strings and/or regular expressions. The strings will be made into regular expressions matching the end of a file name, and any document whose file name matches one of the regular expressions will be considered a program.
If -program-extensions is not specified, or if it does not determine the document type, the document will be considered to be a program if the source has a shebang line or its file name (if any) matches
m/ [.] PL \z /smx.
Accessor for the wrapped PPI::Document instance. Note that altering this instance in any way can cause unpredictable failures in Perl::Critic's subsequent analysis because some caches may fall out of date.
Caching wrappers around the PPI methods. If
$wanted is a simple PPI class name, then the cache is employed. Otherwise we forward the call to the corresponding method of the
Returns a list of the namespaces (package names) in the document.
Returns a list of sub-documents containing the elements in the given namespace. For example, given that the current document is for the source
foo(); package Foo; package Bar; package Foo;
this method will return two Perl::Critic::Documents for a parameter of
"Foo". For more, see "split_ppi_node_by_namespace" in PPIx::Utilities::Node.
Caching wrapper around
$element is a
PPI::Element the cache is employed, otherwise it just returns the results of
PPIx::Regexp->new(). In either case, it returns
undef unless the argument is something that PPIx::Regexp actually understands.
element_is_in_lexical_scope_after_statement_containing( $inner, $outer )
$inner element in lexical scope after the statement containing the
In the case where
$outer is itself a scope-defining element, returns true if
$inner. In any other case,
$inner must be after the last element of the statement containing
$outer, and the innermost scope for
$outer also contains
This is not the same as asking whether
$inner is visible from
Returns the filename for the source code if applicable (PPI::Document::File) or
undef otherwise (PPI::Document).
isa( $classname )
To be compatible with other modules that expect to get a PPI::Document, the Perl::Critic::Document class masquerades as the PPI::Document class.
Returns a version object for the highest Perl version requirement declared in the document via a
require statement. Returns nothing if there is no version statement.
Answers whether there is a
no of the given name in this document. Note that there is no differentiation of modules vs. pragmata here.
Causes this Document to scan itself and mark which lines & policies are disabled by the
"## no critic" annotations.
Returns true if the given
$policy_name has been disabled for at
$line in this Document. Otherwise, returns false.
add_annotation( $annotation )
$annotation object to this Document.
Returns a list containing all the Perl::Critic::Annotations that were found in this Document.
Informs this Document that a
$violation was found but not reported because it fell on a line that had been suppressed by a
"## no critic" annotation. Returns
Returns a list of references to all the Perl::Critic::Violations that were found in this Document but were suppressed.
Returns whether this document is considered to be a program.
Returns whether this document is considered to be a Perl module.
Chris Dolan <email@example.com>
Copyright (c) 2006-2011 Chris Dolan.
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.