 |
|
| |
Perl::Critic::Document(3) |
User Contributed Perl Documentation |
Perl::Critic::Document(3) |
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])"
- 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".
- "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.
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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|