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

FreeBSD Manual Pages

  
 
  

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

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

AUTHOR
       Chris Dolan <cdolan@cpan.org>

COPYRIGHT
       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)

NAME | SYNOPSIS | DESCRIPTION | CAVEATS | INTERFACE SUPPORT | CONSTRUCTOR | METHODS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Document&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help