Login
Forgot to add PPIx::Utilities::Node to required modules in
[gknop/Perl-Critic.git] / lib / Perl / Critic / Document.pm
CommitLineData
6036a254 1##############################################################################
a73f4a71
JRT
2# $URL$
3# $Date$
4# $Author$
5# $Revision$
6036a254 6##############################################################################
5bf96118
CD
7
8package Perl::Critic::Document;
9
df6dee2b 10use 5.006001;
5bf96118 11use strict;
58a9e587 12use warnings;
267b39b4 13
d5835ca8 14use Carp qw< confess >;
2d2fd196 15
81e74a91 16use List::Util qw< reduce >;
d5835ca8 17use Scalar::Util qw< blessed weaken >;
267b39b4 18use version;
5bf96118 19
013aa3aa
ES
20use PPI::Document;
21use PPI::Document::File;
22use PPIx::Utilities::Node qw< split_ppi_node_by_namespace >;
23
d5835ca8 24use Perl::Critic::Annotation;
d533eee5 25use Perl::Critic::Exception::Parse qw< throw_parse >;
48b61139 26use Perl::Critic::Utils qw< :booleans :characters shebang_line >;
d5835ca8 27
6036a254 28#-----------------------------------------------------------------------------
58a9e587 29
c263f914 30our $VERSION = '1.108';
5bf96118 31
6036a254 32#-----------------------------------------------------------------------------
5bf96118
CD
33
34our $AUTOLOAD;
937b8de0 35sub AUTOLOAD { ## no critic (ProhibitAutoloading,ArgUnpacking)
6e7d6c9f
CD
36 my ( $function_name ) = $AUTOLOAD =~ m/ ([^:\']+) \z /xms;
37 return if $function_name eq 'DESTROY';
38 my $self = shift;
39 return $self->{_doc}->$function_name(@_);
5bf96118
CD
40}
41
6036a254 42#-----------------------------------------------------------------------------
5bf96118 43
58a9e587 44sub new {
d5835ca8 45 my ($class, @args) = @_;
013aa3aa
ES
46
47 my $self = bless {}, $class;
48
49 $self->_init_common();
50 $self->_init_from_external_source(@args);
51
52 return $self;
53}
54
55#-----------------------------------------------------------------------------
56
57sub _new_for_parent_document {
58 my ($class, $ppi_document, $parent_document) = @_;
59
937b8de0 60 my $self = bless {}, $class;
013aa3aa
ES
61
62 $self->_init_common();
63
64 $self->{_doc} = $ppi_document;
65 $self->{_is_module} = $parent_document->is_module();
66
67 return $self;
d5835ca8
JRT
68}
69
70#-----------------------------------------------------------------------------
71
013aa3aa
ES
72sub _init_common {
73 my ($self) = @_;
74 my %args;
75
76 $self->{_annotations} = [];
77 $self->{_suppressed_violations} = [];
78 $self->{_disabled_line_map} = {};
79
80 return;
81}
82
83#-----------------------------------------------------------------------------
d5835ca8 84
013aa3aa 85sub _init_from_external_source { ## no critic (Subroutines::RequireArgUnpacking)
d533eee5
ES
86 my $self = shift;
87 my %args;
013aa3aa 88
d533eee5
ES
89 if (@_ == 1) {
90 warnings::warnif(
91 'deprecated',
92 'Perl::Critic::Document->new($source) deprecated, use Perl::Critic::Document->new(-source => $source) instead.' ## no critic (ValuesAndExpressions::RequireInterpolationOfMetachars)
93 );
94 %args = ('-source' => shift);
95 } else {
96 %args = @_;
97 }
013aa3aa 98
d533eee5 99 my $source_code = $args{'-source'};
d5835ca8
JRT
100
101 # $source_code can be a file name, or a reference to a
102 # PPI::Document, or a reference to a scalar containing source
103 # code. In the last case, PPI handles the translation for us.
104
013aa3aa
ES
105 my $ppi_document =
106 _is_ppi_doc($source_code)
107 ? $source_code
108 : ref $source_code
109 ? PPI::Document->new($source_code)
110 : PPI::Document::File->new($source_code);
d5835ca8
JRT
111
112 # Bail on error
013aa3aa 113 if (not defined $ppi_document) {
d5835ca8
JRT
114 my $errstr = PPI::Document::errstr();
115 my $file = ref $source_code ? undef : $source_code;
116 throw_parse
117 message => qq<Can't parse code: $errstr>,
118 file_name => $file;
119 }
120
013aa3aa 121 $self->{_doc} = $ppi_document;
d5835ca8
JRT
122 $self->index_locations();
123 $self->_disable_shebang_fix();
48b61139 124 $self->{_is_module} = $self->_determine_is_module(\%args);
d5835ca8 125
013aa3aa 126 return;
5bf96118
CD
127}
128
6036a254 129#-----------------------------------------------------------------------------
58a9e587 130
d5835ca8
JRT
131sub _is_ppi_doc {
132 my ($ref) = @_;
133 return blessed($ref) && $ref->isa('PPI::Document');
134}
135
136#-----------------------------------------------------------------------------
137
2b6293b2
CD
138sub ppi_document {
139 my ($self) = @_;
140 return $self->{_doc};
141}
142
143#-----------------------------------------------------------------------------
144
47e1ff34 145sub isa {
6e7d6c9f
CD
146 my ($self, @args) = @_;
147 return $self->SUPER::isa(@args)
148 || ( (ref $self) && $self->{_doc} && $self->{_doc}->isa(@args) );
47e1ff34
CD
149}
150
6036a254 151#-----------------------------------------------------------------------------
47e1ff34 152
5bf96118 153sub find {
6e7d6c9f 154 my ($self, $wanted, @more_args) = @_;
5bf96118 155
58a9e587
JRT
156 # This method can only find elements by their class names. For
157 # other types of searches, delegate to the PPI::Document
5bf96118 158 if ( ( ref $wanted ) || !$wanted || $wanted !~ m/ \A PPI:: /xms ) {
6e7d6c9f 159 return $self->{_doc}->find($wanted, @more_args);
5bf96118 160 }
58a9e587
JRT
161
162 # Build the class cache if it doesn't exist. This happens at most
163 # once per Perl::Critic::Document instance. %elements of will be
164 # populated as a side-effect of calling the $finder_sub coderef
165 # that is produced by the caching_finder() closure.
5bf96118 166 if ( !$self->{_elements_of} ) {
389109ec 167
58a9e587 168 my %cache = ( 'PPI::Document' => [ $self ] );
389109ec
JRT
169
170 # The cache refers to $self, and $self refers to the cache. This
171 # creates a circular reference that leaks memory (i.e. $self is not
172 # destroyed until execution is complete). By weakening the reference,
173 # we allow perl to collect the garbage properly.
174 weaken( $cache{'PPI::Document'}->[0] );
175
58a9e587
JRT
176 my $finder_coderef = _caching_finder( \%cache );
177 $self->{_doc}->find( $finder_coderef );
178 $self->{_elements_of} = \%cache;
179 }
180
181 # find() must return false-but-defined on fail
182 return $self->{_elements_of}->{$wanted} || q{};
183}
184
6036a254 185#-----------------------------------------------------------------------------
58a9e587 186
fb21e21e 187sub find_first {
6e7d6c9f 188 my ($self, $wanted, @more_args) = @_;
fb21e21e
CD
189
190 # This method can only find elements by their class names. For
191 # other types of searches, delegate to the PPI::Document
192 if ( ( ref $wanted ) || !$wanted || $wanted !~ m/ \A PPI:: /xms ) {
6e7d6c9f 193 return $self->{_doc}->find_first($wanted, @more_args);
fb21e21e
CD
194 }
195
196 my $result = $self->find($wanted);
197 return $result ? $result->[0] : $result;
198}
199
6036a254 200#-----------------------------------------------------------------------------
fb21e21e 201
f5eeac3b 202sub find_any {
6e7d6c9f 203 my ($self, $wanted, @more_args) = @_;
f5eeac3b
CD
204
205 # This method can only find elements by their class names. For
206 # other types of searches, delegate to the PPI::Document
207 if ( ( ref $wanted ) || !$wanted || $wanted !~ m/ \A PPI:: /xms ) {
6e7d6c9f 208 return $self->{_doc}->find_any($wanted, @more_args);
f5eeac3b
CD
209 }
210
211 my $result = $self->find($wanted);
212 return $result ? 1 : $result;
213}
214
6036a254 215#-----------------------------------------------------------------------------
f5eeac3b 216
013aa3aa
ES
217sub namespaces {
218 my ($self) = @_;
219
220 return keys %{ $self->_nodes_by_namespace() };
221}
222
223#-----------------------------------------------------------------------------
224
225sub subdocuments_for_namespace {
226 my ($self, $namespace) = @_;
227
228 my $subdocuments = $self->_nodes_by_namespace()->{$namespace};
229
230 return $subdocuments ? @{$subdocuments} : ();
231}
232
233#-----------------------------------------------------------------------------
234
60108aef
CD
235sub filename {
236 my ($self) = @_;
013aa3aa 237
c73ba7f3 238 my $doc = $self->{_doc};
013aa3aa 239
c73ba7f3 240 return $doc->can('filename') ? $doc->filename() : undef;
60108aef
CD
241}
242
6036a254 243#-----------------------------------------------------------------------------
60108aef 244
267b39b4
ES
245sub highest_explicit_perl_version {
246 my ($self) = @_;
247
248 my $highest_explicit_perl_version =
249 $self->{_highest_explicit_perl_version};
250
251 if ( not exists $self->{_highest_explicit_perl_version} ) {
252 my $includes = $self->find( \&_is_a_version_statement );
253
254 if ($includes) {
81e74a91
ES
255 # Note: this doesn't use List::Util::max() because that function
256 # doesn't use the overloaded ">=" etc of a version object. The
257 # reduce() style lets version.pm take care of all comparing.
df9f8d80
ES
258 #
259 # For reference, max() ends up looking at the string converted to
260 # an NV, or something like that. An underscore like "5.005_04"
261 # provokes a warning and is chopped off at "5.005" thus losing the
262 # minor part from the comparison.
263 #
264 # An underscore "5.005_04" is supposed to mean an alpha release
81e74a91
ES
265 # and shouldn't be used in a perl version. But it's shown in
266 # perlfunc under "use" (as a number separator), and appears in
267 # several modules supplied with perl 5.10.0 (like version.pm
268 # itself!). At any rate if version.pm can understand it then
269 # that's enough for here.
267b39b4 270 $highest_explicit_perl_version =
81e74a91 271 reduce { $a >= $b ? $a : $b }
901273dd
ES
272 map { version->new( $_->version() ) }
273 @{$includes};
267b39b4
ES
274 }
275 else {
276 $highest_explicit_perl_version = undef;
277 }
278
279 $self->{_highest_explicit_perl_version} =
280 $highest_explicit_perl_version;
281 }
282
283 return $highest_explicit_perl_version if $highest_explicit_perl_version;
284 return;
285}
286
937b8de0
JRT
287#-----------------------------------------------------------------------------
288
d5835ca8
JRT
289sub process_annotations {
290 my ($self) = @_;
937b8de0 291
d5835ca8
JRT
292 my @annotations = Perl::Critic::Annotation->create_annotations($self);
293 $self->add_annotation(@annotations);
937b8de0
JRT
294 return $self;
295}
296
297#-----------------------------------------------------------------------------
298
d5835ca8
JRT
299sub line_is_disabled_for_policy {
300 my ($self, $line, $policy) = @_;
301 my $policy_name = ref $policy || $policy;
2d2fd196
JRT
302
303 # HACK: This Policy is special. If it is active, it cannot be
d1237298 304 # disabled by a "## no critic" annotation. Rather than create a general
2d2fd196 305 # hook in Policy.pm for enabling this behavior, we chose to hack
d5835ca8 306 # it here, since this isn't the kind of thing that most policies do
2f4b6b33
JRT
307
308 return 0 if $policy_name eq
2d2fd196
JRT
309 'Perl::Critic::Policy::Miscellanea::ProhibitUnrestrictedNoCritic';
310
d5835ca8
JRT
311 return 1 if $self->{_disabled_line_map}->{$line}->{$policy_name};
312 return 1 if $self->{_disabled_line_map}->{$line}->{ALL};
937b8de0
JRT
313 return 0;
314}
315
316#-----------------------------------------------------------------------------
317
d5835ca8
JRT
318sub add_annotation {
319 my ($self, @annotations) = @_;
320
321 # Add annotation to our private map for quick lookup
322 for my $annotation (@annotations) {
323
324 my ($start, $end) = $annotation->effective_range();
325 my @affected_policies = $annotation->disables_all_policies ?
326 qw(ALL) : $annotation->disabled_policies();
327
328 # TODO: Find clever way to do this with hash slices
329 for my $line ($start .. $end) {
330 for my $policy (@affected_policies) {
331 $self->{_disabled_line_map}->{$line}->{$policy} = 1;
332 }
333 }
334 }
335
336 push @{ $self->{_annotations} }, @annotations;
2d2fd196
JRT
337 return $self;
338}
4880392e 339
2d2fd196 340#-----------------------------------------------------------------------------
4880392e 341
d5835ca8 342sub annotations {
2d2fd196 343 my ($self) = @_;
d5835ca8
JRT
344 return @{ $self->{_annotations} };
345}
4880392e 346
d5835ca8 347#-----------------------------------------------------------------------------
4880392e 348
d5835ca8
JRT
349sub add_suppressed_violation {
350 my ($self, $violation) = @_;
351 push @{$self->{_suppressed_violations}}, $violation;
352 return $self;
353}
4880392e 354
d5835ca8 355#-----------------------------------------------------------------------------
2d2fd196 356
d5835ca8
JRT
357sub suppressed_violations {
358 my ($self) = @_;
359 return @{ $self->{_suppressed_violations} };
95ebf9b0
JRT
360}
361
362#-----------------------------------------------------------------------------
d533eee5 363
1b936936 364sub is_program {
d533eee5 365 my ($self) = @_;
48b61139
ES
366
367 return not $self->is_module();
d533eee5
ES
368}
369
370#-----------------------------------------------------------------------------
371
372sub is_module {
373 my ($self) = @_;
48b61139
ES
374
375 return $self->{_is_module};
d533eee5
ES
376}
377
378#-----------------------------------------------------------------------------
d5835ca8 379# PRIVATE functions & methods
95ebf9b0 380
267b39b4
ES
381sub _is_a_version_statement {
382 my (undef, $element) = @_;
383
384 return 0 if not $element->isa('PPI::Statement::Include');
385 return 1 if $element->version();
386 return 0;
387}
388
389#-----------------------------------------------------------------------------
390
58a9e587 391sub _caching_finder {
58a9e587
JRT
392 my $cache_ref = shift; # These vars will persist for the life
393 my %isa_cache = (); # of the code ref that this sub returns
394
395
396 # Gather up all the PPI elements and sort by @ISA. Note: if any
397 # instances used multiple inheritance, this implementation would
398 # lead to multiple copies of $element in the $elements_of lists.
399 # However, PPI::* doesn't do multiple inheritance, so we are safe
400
401 return sub {
6e7d6c9f 402 my (undef, $element) = @_;
58a9e587
JRT
403 my $classes = $isa_cache{ref $element};
404 if ( !$classes ) {
405 $classes = [ ref $element ];
406 # Use a C-style loop because we append to the classes array inside
407 for ( my $i = 0; $i < @{$classes}; $i++ ) { ## no critic(ProhibitCStyleForLoops)
408 no strict 'refs'; ## no critic(ProhibitNoStrict)
409 push @{$classes}, @{"$classes->[$i]::ISA"};
410 $cache_ref->{$classes->[$i]} ||= [];
5bf96118 411 }
58a9e587
JRT
412 $isa_cache{$classes->[0]} = $classes;
413 }
5bf96118 414
58a9e587
JRT
415 for my $class ( @{$classes} ) {
416 push @{$cache_ref->{$class}}, $element;
417 }
5bf96118 418
58a9e587
JRT
419 return 0; # 0 tells find() to keep traversing, but not to store this $element
420 };
5bf96118
CD
421}
422
6036a254 423#-----------------------------------------------------------------------------
58a9e587 424
d5835ca8 425sub _disable_shebang_fix {
2d2fd196
JRT
426 my ($self) = @_;
427
1b936936 428 # When you install a program using ExtUtils::MakeMaker or Module::Build, it
937b8de0 429 # inserts some magical code into the top of the file (just after the
1b936936 430 # shebang). This code allows people to call your program using a shell,
937b8de0 431 # like `sh my_script`. Unfortunately, this code causes several Policy
d1237298 432 # violations, so we disable them as if they had "## no critic" annotations.
937b8de0 433
d5835ca8 434 my $first_stmnt = $self->schild(0) || return;
937b8de0
JRT
435
436 # Different versions of MakeMaker and Build use slightly different shebang
437 # fixing strings. This matches most of the ones I've found in my own Perl
438 # distribution, but it may not be bullet-proof.
439
5d6f7fbc 440 my $fixin_rx = qr<^eval 'exec .* \$0 \${1[+]"\$@"}'\s*[\r\n]\s*if.+;>ms; ## no critic (ExtendedFormatting)
937b8de0 441 if ( $first_stmnt =~ $fixin_rx ) {
d5835ca8
JRT
442 my $line = $first_stmnt->location->[0];
443 $self->{_disabled_line_map}->{$line}->{ALL} = 1;
444 $self->{_disabled_line_map}->{$line + 1}->{ALL} = 1;
937b8de0
JRT
445 }
446
2d2fd196 447 return $self;
937b8de0
JRT
448}
449
450#-----------------------------------------------------------------------------
451
48b61139 452sub _determine_is_module {
d533eee5
ES
453 my ($self, $args) = @_;
454
455 my $file_name = $self->filename();
1b936936
ES
456 if (
457 defined $file_name
458 and ref $args->{'-program-extensions'} eq 'ARRAY'
459 ) {
460 foreach my $ext ( @{ $args->{'-program-extensions'} } ) {
461 my $regex =
462 ref $ext eq 'Regexp'
463 ? $ext
464 : qr< @{ [ quotemeta $ext ] } \z >xms;
465
48b61139 466 return $FALSE if $file_name =~ m/$regex/smx;
d533eee5
ES
467 }
468 }
469
48b61139
ES
470 return $FALSE if shebang_line($self);
471 return $FALSE if defined $file_name && $file_name =~ m/ [.] PL \z /smx;
d533eee5 472
48b61139 473 return $TRUE;
d533eee5
ES
474}
475
476#-----------------------------------------------------------------------------
477
013aa3aa
ES
478sub _nodes_by_namespace {
479 my ($self) = @_;
480
481 my $nodes = $self->{_nodes_by_namespace};
482
483 return $nodes if $nodes;
484
485 my $ppi_document = $self->ppi_document();
486 if (not $ppi_document) {
487 return $self->{_nodes_by_namespace} = {};
488 }
489
490 my $raw_nodes_map = split_ppi_node_by_namespace($ppi_document);
491
492 my %wrapped_nodes;
493 while ( my ($namespace, $raw_nodes) = each %{$raw_nodes_map} ) {
494 $wrapped_nodes{$namespace} =
495 map { __PACKAGE__->_new_for_parent_document($_, $self) }
496 @{$raw_nodes};
497 }
498
499 return $self->{_nodes_by_namespace} = \%wrapped_nodes;
500}
501
502#-----------------------------------------------------------------------------
503
5bf96118 5041;
58a9e587 505
5bf96118
CD
506__END__
507
a73f4a71
JRT
508=pod
509
510=for stopwords pre-caches
511
5bf96118
CD
512=head1 NAME
513
c728943a 514Perl::Critic::Document - Caching wrapper around a PPI::Document.
5bf96118 515
267b39b4 516
5bf96118
CD
517=head1 SYNOPSIS
518
519 use PPI::Document;
520 use Perl::Critic::Document;
521 my $doc = PPI::Document->new('Foo.pm');
d533eee5 522 $doc = Perl::Critic::Document->new(-source => $doc);
5bf96118
CD
523 ## Then use the instance just like a PPI::Document
524
267b39b4 525
5bf96118
CD
526=head1 DESCRIPTION
527
528Perl::Critic does a lot of iterations over the PPI document tree via
529the C<PPI::Document::find()> method. To save some time, this class
530pre-caches a lot of the common C<find()> calls in a single traversal.
531Then, on subsequent requests we return the cached data.
532
533This is implemented as a facade, where method calls are handed to the
534stored C<PPI::Document> instance.
535
267b39b4 536
5bf96118
CD
537=head1 CAVEATS
538
539This facade does not implement the overloaded operators from
11f53956
ES
540L<PPI::Document|PPI::Document> (that is, the C<use overload ...>
541work). Therefore, users of this facade must not rely on that syntactic
542sugar. So, for example, instead of C<my $source = "$doc";> you should
543write C<my $source = $doc->content();>
5bf96118
CD
544
545Perhaps there is a CPAN module out there which implements a facade
546better than we do here?
547
267b39b4 548
4444d94d
ES
549=head1 INTERFACE SUPPORT
550
551This is considered to be a public class. Any changes to its interface
552will go through a deprecation cycle.
553
554
267b39b4
ES
555=head1 CONSTRUCTOR
556
557=over
558
1b936936 559=item C<< new(-source => $source_code, '-program-extensions' => [program_extensions]) >>
267b39b4 560
d5835ca8
JRT
561Create a new instance referencing a PPI::Document instance. The
562C<$source_code> can be the name of a file, a reference to a scalar
0e4a0ae1
TW
563containing actual source code, or a L<PPI::Document|PPI::Document> or
564L<PPI::Document::File|PPI::Document::File>.
267b39b4 565
48b61139
ES
566The '-program-extensions' argument is optional, and is a reference to a list
567of strings and/or regular expressions. The strings will be made into regular
568expressions matching the end of a file name, and any document whose file name
569matches one of the regular expressions will be considered a program.
d533eee5 570
1b936936 571If -program-extensions is not specified, or if it does not determine the
48b61139
ES
572document type, the document will be considered to be a program if the source
573has a shebang line or its file name (if any) matches C<< m/ [.] PL \z /smx >>.
d533eee5 574
267b39b4
ES
575=back
576
5bf96118
CD
577=head1 METHODS
578
579=over
580
267b39b4 581=item C<< ppi_document() >>
2b6293b2 582
11f53956
ES
583Accessor for the wrapped PPI::Document instance. Note that altering
584this instance in any way can cause unpredictable failures in
585Perl::Critic's subsequent analysis because some caches may fall out of
586date.
2b6293b2 587
5bf96118 588
267b39b4
ES
589=item C<< find($wanted) >>
590
591=item C<< find_first($wanted) >>
fb21e21e 592
267b39b4 593=item C<< find_any($wanted) >>
f5eeac3b 594
fb21e21e 595If C<$wanted> is a simple PPI class name, then the cache is employed.
f5eeac3b
CD
596Otherwise we forward the call to the corresponding method of the
597C<PPI::Document> instance.
5bf96118 598
267b39b4 599
013aa3aa
ES
600=item C<< namespaces() >>
601
602Returns a list of the namespaces (package names) in the document.
603
604
605=item C<< subdocuments_for_namespace($namespace) >>
606
607Returns a list of sub-documents containing the elements in the given
608namespace. For example, given that the current document is for the source
609
610 foo();
611 package Foo;
612 package Bar;
613 package Foo;
614
615this method will return two L<Perl::Critic::Document|Perl::Critic::Document>s
616for a parameter of C<"Foo">. For more, see
617L<PPIx::Utilities::Node/split_ppi_node_by_namespace>.
618
619
267b39b4 620=item C<< filename() >>
e7f2d995
CD
621
622Returns the filename for the source code if applicable
623(PPI::Document::File) or C<undef> otherwise (PPI::Document).
624
267b39b4
ES
625
626=item C<< isa( $classname ) >>
242f7b08 627
11f53956
ES
628To be compatible with other modules that expect to get a
629PPI::Document, the Perl::Critic::Document class masquerades as the
630PPI::Document class.
242f7b08 631
267b39b4
ES
632
633=item C<< highest_explicit_perl_version() >>
634
11f53956
ES
635Returns a L<version|version> object for the highest Perl version
636requirement declared in the document via a C<use> or C<require>
637statement. Returns nothing if there is no version statement.
267b39b4 638
013aa3aa 639
d5835ca8 640=item C<< process_annotations() >>
267b39b4 641
d5835ca8
JRT
642Causes this Document to scan itself and mark which lines &
643policies are disabled by the C<"## no critic"> annotations.
937b8de0 644
013aa3aa 645
d5835ca8 646=item C<< line_is_disabled_for_policy($line, $policy_object) >>
937b8de0 647
fcb2381b 648Returns true if the given C<$policy_object> or C<$policy_name> has
d5835ca8 649been disabled for at C<$line> in this Document. Otherwise, returns false.
937b8de0 650
013aa3aa 651
d5835ca8 652=item C<< add_annotation( $annotation ) >>
937b8de0 653
d5835ca8 654Adds an C<$annotation> object to this Document.
2d2fd196 655
013aa3aa 656
d5835ca8 657=item C<< annotations() >>
2d2fd196 658
0e4a0ae1
TW
659Returns a list containing all the
660L<Perl::Critic::Annotation|Perl::Critic::Annotation>s that
d5835ca8 661were found in this Document.
2d2fd196 662
013aa3aa 663
d5835ca8 664=item C<< add_suppressed_violation($violation) >>
2d2fd196 665
fcb2381b 666Informs this Document that a C<$violation> was found but not reported
d5835ca8
JRT
667because it fell on a line that had been suppressed by a C<"## no critic">
668annotation. Returns C<$self>.
95ebf9b0 669
013aa3aa 670
d5835ca8 671=item C<< suppressed_violations() >>
95ebf9b0 672
0e4a0ae1
TW
673Returns a list of references to all the
674L<Perl::Critic::Violation|Perl::Critic::Violation>s
d5835ca8 675that were found in this Document but were suppressed.
937b8de0 676
d533eee5 677
1b936936
ES
678=item C<< is_program() >>
679
680Returns whether this document is considered to be a program.
d533eee5 681
d533eee5
ES
682
683=item C<< is_module() >>
684
1b936936 685Returns whether this document is considered to be a Perl module.
d533eee5 686
5bf96118
CD
687=back
688
689=head1 AUTHOR
690
2f4b6b33 691Chris Dolan <cdolan@cpan.org>
5bf96118
CD
692
693=head1 COPYRIGHT
694
072692c8 695Copyright (c) 2006-2010 Chris Dolan.
5bf96118
CD
696
697This program is free software; you can redistribute it and/or modify
698it under the same terms as Perl itself. The full text of this license
699can be found in the LICENSE file included with this module.
700
701=cut
737d3b65 702
d5835ca8 703##############################################################################
737d3b65
CD
704# Local Variables:
705# mode: cperl
706# cperl-indent-level: 4
707# fill-column: 78
708# indent-tabs-mode: nil
709# c-indentation-style: bsd
710# End:
96fed375 711# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :