Perl::Critic::Document - Caching wrapper around a PPI::Document. |
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 PPI::Document
instance.
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])
$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
.
ppi_document()
find($wanted)
find_first($wanted)
find_any($wanted)
$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()
subdocuments_for_namespace($namespace)
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 the PPIx::Utilities::Node manpage.
ppix_regexp_from_element($element)
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 )
$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()
undef
otherwise (PPI::Document).
isa( $classname )
highest_explicit_perl_version()
use
or require
statement. Returns nothing if there is no version statement.
uses_module($module_or_pragma_name)
use
, require
, or no
of the given name in
this document. Note that there is no differentiation of modules vs. pragmata
here.
process_annotations()
"## no critic"
annotations.
line_is_disabled_for_policy($line, $policy_object)
$policy_object
or $policy_name
has
been disabled for at $line
in this Document. Otherwise, returns false.
add_annotation( $annotation )
$annotation
object to this Document.
annotations()
add_suppressed_violation($violation)
$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()
is_program()
is_module()
Chris Dolan <cdolan@cpan.org>
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.
Perl::Critic::Document - Caching wrapper around a PPI::Document. |