1Perl::Critic::Document(U3spemr)Contributed Perl DocumentPaetrilo:n:Critic::Document(3pm)
2
3
4

NAME

6       Perl::Critic::Document - Caching wrapper around a PPI::Document.
7

SYNOPSIS

9           use PPI::Document;
10           use Perl::Critic::Document;
11           my $doc = PPI::Document->new('Foo.pm');
12           $doc = Perl::Critic::Document->new(-source => $doc);
13           ## Then use the instance just like a PPI::Document
14

DESCRIPTION

16       Perl::Critic does a lot of iterations over the PPI document tree via
17       the PPI::Document::find() method.  To save some time, this class pre-
18       caches a lot of the common find() calls in a single traversal.  Then,
19       on subsequent requests we return the cached data.
20
21       This is implemented as a facade, where method calls are handed to the
22       stored "PPI::Document" instance.
23

CAVEATS

25       This facade does not implement the overloaded operators from
26       PPI::Document (that is, the "use overload ..."  work). Therefore, users
27       of this facade must not rely on that syntactic sugar.  So, for example,
28       instead of "my $source = "$doc";" you should write "my $source =
29       $doc->content();"
30
31       Perhaps there is a CPAN module out there which implements a facade
32       better than we do here?
33

INTERFACE SUPPORT

35       This is considered to be a public class.  Any changes to its interface
36       will go through a deprecation cycle.
37

CONSTRUCTOR

39       "new(-source => $source_code, '-filename-override' => $filename,
40       '-program-extensions' => [program_extensions])"
41           Create a new instance referencing a PPI::Document instance.  The
42           $source_code can be the name of a file, a reference to a scalar
43           containing actual source code, or a PPI::Document or
44           PPI::Document::File.
45
46           In the event that $source_code is a reference to a scalar
47           containing actual source code or a PPI::Document, the resulting
48           Perl::Critic::Document will not have a filename.  This may cause
49           Perl::Critic::Document to incorrectly classify the source code as a
50           module or script.  To avoid this problem, you can optionally set
51           the "-filename-override" to force the Perl::Critic::Document to
52           have a particular $filename.  Do not use this option if
53           $source_code is already the name of a file, or is a reference to a
54           PPI::Document::File.
55
56           The '-program-extensions' argument is optional, and is a reference
57           to a list of strings and/or regular expressions. The strings will
58           be made into regular expressions matching the end of a file name,
59           and any document whose file name matches one of the regular
60           expressions will be considered a program.
61
62           If -program-extensions is not specified, or if it does not
63           determine the document type, the document will be considered to be
64           a program if the source has a shebang line or its file name (if
65           any) matches "m/ [.] PL \z /smx".
66

METHODS

68       ppi_document()
69           Accessor for the wrapped PPI::Document instance.  Note that
70           altering this instance in any way can cause unpredictable failures
71           in Perl::Critic's subsequent analysis because some caches may fall
72           out of date.
73
74       find($wanted)
75       find_first($wanted)
76       find_any($wanted)
77           Caching wrappers around the PPI methods.  If $wanted is a simple
78           PPI class name, then the cache is employed. Otherwise we forward
79           the call to the corresponding method of the "PPI::Document"
80           instance.
81
82       namespaces()
83           Returns a list of the namespaces (package names) in the document.
84
85       subdocuments_for_namespace($namespace)
86           Returns a list of sub-documents containing the elements in the
87           given namespace.  For example, given that the current document is
88           for the source
89
90               foo();
91               package Foo;
92               package Bar;
93               package Foo;
94
95           this method will return two Perl::Critic::Documents for a parameter
96           of "Foo".  For more, see "split_ppi_node_by_namespace" in
97           PPIx::Utils::Traversal.
98
99       ppix_regexp_from_element($element)
100           Caching wrapper around "PPIx::Regexp->new($element)".  If $element
101           is a "PPI::Element" the cache is employed, otherwise it just
102           returns the results of "PPIx::Regexp->new()".  In either case, it
103           returns "undef" unless the argument is something that PPIx::Regexp
104           actually understands.
105
106       "element_is_in_lexical_scope_after_statement_containing( $inner, $outer
107       )"
108           Is the $inner element in lexical scope after the statement
109           containing the $outer element?
110
111           In the case where $outer is itself a scope-defining element,
112           returns true if $outer contains $inner. In any other case, $inner
113           must be after the last element of the statement containing $outer,
114           and the innermost scope for $outer also contains $inner.
115
116           This is not the same as asking whether $inner is visible from
117           $outer.
118
119       filename()
120           Returns the filename for the source code if applicable
121           (PPI::Document::File) or "undef" otherwise (PPI::Document).
122
123       isa( $classname )
124           To be compatible with other modules that expect to get a
125           PPI::Document, the Perl::Critic::Document class masquerades as the
126           PPI::Document class.
127
128       highest_explicit_perl_version()
129           Returns a version object for the highest Perl version requirement
130           declared in the document via a "use" or "require" statement.
131           Returns nothing if there is no version statement.
132
133       uses_module($module_or_pragma_name)
134           Answers whether there is a "use", "require", or "no" of the given
135           name in this document.  Note that there is no differentiation of
136           modules vs. pragmata here.
137
138       process_annotations()
139           Causes this Document to scan itself and mark which lines & policies
140           are disabled by the "## no critic" annotations.
141
142       "line_is_disabled_for_policy($line, $policy_object)"
143           Returns true if the given $policy_object or $policy_name has been
144           disabled for at $line in this Document.  Otherwise, returns false.
145
146       add_annotation( $annotation )
147           Adds an $annotation object to this Document.
148
149       annotations()
150           Returns a list containing all the Perl::Critic::Annotations that
151           were found in this Document.
152
153       add_suppressed_violation($violation)
154           Informs this Document that a $violation was found but not reported
155           because it fell on a line that had been suppressed by a "## no
156           critic" annotation. Returns $self.
157
158       suppressed_violations()
159           Returns a list of references to all the Perl::Critic::Violations
160           that were found in this Document but were suppressed.
161
162       is_program()
163           Returns whether this document is considered to be a program.
164
165       is_module()
166           Returns whether this document is considered to be a Perl module.
167

AUTHOR

169       Chris Dolan <cdolan@cpan.org>
170
172       Copyright (c) 2006-2023 Chris Dolan.
173
174       This program is free software; you can redistribute it and/or modify it
175       under the same terms as Perl itself.  The full text of this license can
176       be found in the LICENSE file included with this module.
177
178
179
180perl v5.38.0                      2023-09-25       Perl::Critic::Document(3pm)
Impressum