1Perl::Critic::Document(U3spemr)Contributed Perl DocumentPaetrilo:n:Critic::Document(3pm)
2
6 Perl::Critic::Document - Caching wrapper around a PPI::Document.
7
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
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 This is implemented as a facade, where method calls are handed to the
22 stored "PPI::Document" instance.
23
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 Perhaps there is a CPAN module out there which implements a facade
32 better than we do here?
33
35 This is considered to be a public class. Any changes to its interface
36 will go through a deprecation cycle.
37
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 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 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 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
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 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 namespaces()
83 Returns a list of the namespaces (package names) in the document.
84 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 foo();
91 package Foo;
92 package Bar;
93 package Foo;
94 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 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 "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 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 This is not the same as asking whether $inner is visible from
117 $outer.
118 filename()
120 Returns the filename for the source code if applicable
121 (PPI::Document::File) or "undef" otherwise (PPI::Document).
122 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 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 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 process_annotations()
139 Causes this Document to scan itself and mark which lines & policies
140 are disabled by the "## no critic" annotations.
141 "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 add_annotation( $annotation )
147 Adds an $annotation object to this Document.
148 annotations()
150 Returns a list containing all the Perl::Critic::Annotations that
151 were found in this Document.
152 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 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 is_program()
163 Returns whether this document is considered to be a program.
164 is_module()
166 Returns whether this document is considered to be a Perl module.
167
169 Chris Dolan <cdolan@cpan.org>
170
172 Copyright (c) 2006-2023 Chris Dolan.
173 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.
177perl v5.38.0 2023-09-25 Perl::Critic::Document(3pm)