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.