Perl::...tation(3pm)

🌸 NAME 🌸

Okay bestie, this is the Perl::Critic::Annotation page — the header shows it as Perl::...tation(3pm), and it's served up by User Contributed Perl Documentation. The actual NAME line is:

Perl::Critic::Annotation — A ## no critic annotation in a document. That's the whole assignment, and it ate. 💅

✨ SYNOPSIS ✨

Bestie, here's the whole shape of it, no cap:

use Perl::Critic::Annotation;
$annotation = Perl::Critic::Annotation->new( -element => $no_critic_ppi_element );

$bool = $annotation->disables_line( $number );
$bool = $annotation->disables_policy( $policy_object );
$bool = $annotation->disables_all_policies();

($start, $end) = $annotation->effective_range();
@disabled_policy_names = $annotation->disabled_policies();

💖 DESCRIPTION 💖

Perl::Critic::Annotation represents a single ## no critic annotation in a PPI::Document. The Annotation takes care of parsing the annotation and keeps track of which lines and Policies it affects. It is intended to encapsulate the details of the no-critic annotations, and to provide a way for Policy objects to interact with the annotations (via a Perl::Critic::Document).

So it's literally the annotation's whole little handler situation, and it lets Policy objects talk to the annotations through the Document. Fr fr. 🫶

🚨 INTERFACE SUPPORT 🚨

⚠️ Warning, bestie: this is considered to be a non-public class. Its interface is subject to change without notice. So don't get too attached to the exact shape, okay? 😭

🧚 CLASS METHODS 🧚

create_annotations( -doc => $doc )

Given a Perl::Critic::Document, finds all the ## no critic annotations and constructs a new Perl::Critic::Annotation for each one and returns them. The order of the returned objects is not defined. It is generally expected that clients will use this interface rather than calling the Perl::Critic::Annotation constructor directly.

That last bit is the key, bestie: use this interface, not the constructor. Periodt. 💅

🎀 CONSTRUCTOR 🎀

new( -element => $ppi_annotation_element )

Returns a reference to a new Annotation object. The -element argument is required and should be a PPI::Token::Comment that conforms to the ## no critic syntax.

Required required, no skipping. ✨

💅 METHODS 💅

disables_line( $line )

Returns true if this Annotation disables $line for any (or all) Policies.

Any or all, she's flexible like that. 🦋

disables_policy( $policy_object ) / disables_policy( $policy_name )

Returns true if this Annotation disables $polciy_object or $policy_name at any (or all) lines.

Yes, $polciy_object — that's literally the spelling here, bestie, I'm not fixing it. 😭

disables_all_policies()

Returns true if this Annotation disables all Policies at any (or all) lines. If this method returns true, disabled_policies will return an empty list.

Empty list = all-policies situation, iykyk. 👑

effective_range()

Returns a two-element list, representing the first and last line numbers where this Annotation has effect.

Two-element list: start and end, the range of the annotation's effect. Slay. ✨

disabled_policies()

Returns a list of the names of the Policies that are affected by this Annotation. If this list is empty, then it means that all Policies are affected by this Annotation, and disables_all_policies() should return true.

So empty list is not "no policies" — it's "all the Policies", bestie. Important vibe check. 💀

element()

Returns the PPI::Element where this annotation started. This is typically an instance of PPI::Token::Comment.

Where it all began — usually a PPI::Token::Comment. Main character energy. 🎀

💌 AUTHOR 💌

Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

The author, the legend, the icon. 🌈

©️ COPYRIGHT ©️

Copyright (c) 2005-2023 Imaginative Software Systems

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.

That's the legal bit, bestie — same terms as Perl itself, and the full text lives in the LICENSE file with the module. 💜

---

Okay bestie, that's the whole page 💖 go forth and annotate iconically. This was Perl::...tation(3pm) from perl v5.42.0, dated 2024-10-23. 🫶