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(-source => $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?

INTERFACE SUPPORT

This is considered to be a public class. Any changes to its interface will go through a deprecation cycle.

CONSTRUCTOR

new(-source => $source_code, '-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.

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.

METHODS

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.

process_annotations()

Causes this Document to scan itself and mark which lines & policies are disabled by the "## no critic" annotations.

line_is_disabled_for_policy($line, $policy_object)

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

add_annotation( $annotation )

Adds an $annotation object to this Document.

annotations()

Returns a list containing all the Perl::Critic::Annotations that were found in this Document.

add_suppressed_violation($violation)

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 $self.

suppressed_violations()

Returns a list of references to all the Perl::Critic::Violations that were found in this Document but were suppressed.

is_program()

Returns whether this document is considered to be a program.

is_module()

Returns whether this document is considered to be a Perl module.

AUTHOR

Chris Dolan <cdolan@cpan.org>

COPYRIGHT

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