/ 
Perl-Critic-1.093_02
/ Perl::Critic::Document

NAME

Perl::Critic::Document - Caching wrapper around a PPI::Document.

SYNOPSIS

use PPI::Document;
use Perl::Critic::Document;
my $doc = PPI::Document->new('Foo.pm');
$doc = Perl::Critic::Document->new($doc);
## Then use the instance just like a PPI::Document

DESCRIPTION

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 PPI::Document instance.

CAVEATS

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?

CONSTRUCTOR

new($doc)

Create a new instance referencing a PPI::Document instance.

METHODS

new($doc)

Create a new instance referencing a PPI::Document instance.

ppi_document()

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.

find($wanted)
find_first($wanted)
find_any($wanted)

If $wanted is a simple PPI class name, then the cache is employed. Otherwise we forward the call to the corresponding method of the PPI::Document instance.

filename()

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.

highest_explicit_perl_version()

Returns a version object for the highest Perl version requirement declared in the document via a use or require statement. Returns nothing if there is no version statement.

mark_disabled_regions( @policy_names )

Scans the document for "## no critic" pseudo-pragmas and builds an internal table of which of the listed @policy_names have been disabled at each line. Unless you want to ignore the "## no critic" markers, you should call this method before critiquing the document. Returns $self.

line_is_disabled($line, $policy_name)

Returns true if the given $policy_name has been disabled for at $line in this document. Otherwise, returns false.

mark_supressed_violation($line, $policy_name)

Indicates to this Document that a violation of policy $policy_name was found at line c<$line>, but was not reported because it fell on a line that had been disabled by a "## no critic" marker. This is how the Document figures out if there are any useless "## no critic" markers in the file. Returns $self.

useless_no_critic_warnings(@violations)

Given a list of violation objects that are assumed to have been found in this Document, returns a warning message for each line where a policy was disabled using a "##no critic" pseudo-pragma, but no violation was actually found on that line. If multiple policies are disabled on a given line, then you'll get a warning message for each policy.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

Copyright (c) 2006-2008 Chris Dolan. 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.