Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Perl::Critic::DocumentUser Contributed Perl DocumentaPerl::Critic::Document(3)

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

	   use PPI::Document;
	   use Perl::Critic::Document;
	   my $doc = PPI::Document->new('');
	   $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 =

       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

	   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

	   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".

	   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.

	   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"

	   Returns a list of the namespaces (package names) in the document.

	   Returns a list of sub-documents containing the elements in the
	   given namespace.  For example, given	that the current document is
	   for the source

	       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

	   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

	   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.

	   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.

	   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.

	   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.

	   Returns a list containing all the Perl::Critic::Annotations that
	   were	found in this Document.

	   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.

	   Returns a list of references	to all the Perl::Critic::Violations
	   that	were found in this Document but	were suppressed.

	   Returns whether this	document is considered to be a program.

	   Returns whether this	document is considered to be a Perl module.

       Chris Dolan <>

       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.24.1			  2017-07-02	     Perl::Critic::Document(3)


Want to link to this manual page? Use this URL:

home | help