++ed by:
ADAMJS ARJONES ARPI AYOUNG AZAWAWI

38 PAUSE user(s)
22 non-PAUSE user(s).

Jeffrey Ryan Thalhammer

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, '-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.

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)

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

namespaces()

Returns a list of the namespaces (package names) in the document.

subdocuments_for_namespace($namespace)

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.

ppix_regexp_from_element($element)

Caching wrapper around PPIx::Regexp->new($element). If $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 )

Is the $inner element in lexical scope after the statement containing the $outer element?

In the case where $outer is itself a scope-defining element, returns true if $outer contains $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 $inner.

This is not the same as asking whether $inner is visible from $outer.

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.

uses_module($module_or_pragma_name)

Answers whether there is a use, require, or no of the given name in this document. Note that there is no differentiation of modules vs. pragmata here.

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




Hosting generously
sponsored by Bytemark