Perl::Critic::Document(3)
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.
perl v5.28.2 2019-05-24 Perl::Critic::Document(3)
perl-critic 1.134.0 - Generated Sun Jun 2 12:37:35 CDT 2019