--- name: "Perl::Critic::Document" section: "3pm" platform: "linux" package: "perl-perl-critic" version: "1.156-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Perl::Critic::Document" --- # Perl::Critic::Document(3pm) Caching wrapper around a PPI::Document. ## 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::Utils::Traversal. - 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 \ ## COPYRIGHT Copyright (c) 2006-2023 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.