Code::T...::Plugin(3)

📦
version 0.840.0 · 8 versions
, in opensuse-leap 16.0

💅 Code::TidyAll::Plugin — the manual, but make it group chat

okay so bestie, you're looking at the User Contributed Perl Documentation for Code::TidyAll::Plugin, and it's literally the blueprint for writing your own tidy/validate plugins. version 0.84, babes. let's get into it 🎀

✨ NAME ✨

Code::TidyAll::Plugin — the whole point is create plugins for tidying or validating code. that's the gig. that's the assignment. 💖

🌸 VERSION 🌸

version 0.84 — yes, that's the number, don't @ me.

🦋 SYNOPSIS 🦋

here's the vibe, two flavors, both extending the base class:

package Code::TidyAll::Plugin::SomeTidier;
use Moo;
extends 'Code::TidyAll::Plugin';

sub transform_source {
    my ( $self, $source ) = @_;
    ...
    return $source;
}

package Code::TidyAll::Plugin::SomeValidator;
use Moo;
extends 'Code::TidyAll::Plugin';

sub validate_file {
    my ( $self, $file ) = @_;
    die 'not valid' if ...;
}

see? one does the tidying thing, one does the validating thing. both iconic, both valid. 👑

💜 DESCRIPTION 💜

so like — if you want tidyall to actually use a tidier or a validator, that thing needs a corresponding plugin class that inherits from this class. that's not optional, that's the whole system. this doc is literally "how do I implement a new plugin", step by step, no gatekeeping. 🫶

and the easiest way to start? lowkey just go look at existing plugins. seriously. the doc itself points you at Code::TidyAll::Plugin::PerlTidy and Code::TidyAll::Plugin::PerlCritic. read those, copy the energy, you're golden. ✨

🔥 NAMING 🔥

if you're gonna publicly release your plugin, do the polite thing and call it Code::TidyAll::Plugin::something — that way users can actually find it, and they can refer to it by its short name in the config. easy. considerate. slay. 💅

if it's an internal plugin though? call it whatever you want, genuinely no rules, and refer to it in the config file with a plus sign prefix, like this:

[+My::Tidier::Class]
select = **/*.{pl,pm,t}

the + is doing the heavy lifting there, iykyk. ⭐

🧚 CONSTRUCTOR AND ATTRIBUTES 🧚

okay so here's the important bit: your plugin constructor gets called with the configuration key/value pairs as parameters. so if your config has:

[PerlCritic]
select = lib/**/*.pm
ignore = lib/UtterHack.pm
argv = -severity 3

then Code::TidyAll::Plugin::PerlCritic gets constructed with these parameters:

Code::TidyAll::Plugin::PerlCritic->new(
    select => 'lib/**/*.pm',
    ignore => 'lib/UtterHack.pm',
    argv   => '-severity 3',
);

match made in heaven, no cap. 💖

the following attributes are part of this base class. your subclass can declare others, of course — go off, add your own, we love a custom attribute. 🌈

🎀 argv

a standard attribute for passing command line arguments. that's it, that's the attribute. 🍓

🎀 diff_on_tidy_error

this one only applies to plugins that transform source. if this is true, then when the plugin runs in check mode it'll include a diff in the return value from process_source_or_file when the source is not tidy. very "here's exactly what's wrong" of it. 🙈

🎀 is_validator

an attribute that indicates if this is a validator or not. by default it returns true if either the validate_source or validate_file methods have been implemented. so it just knows. 🔍

🎀 name

name of the plugin, used in error messages etc. the little name tag. 🏷️

🎀 tidyall

a weak reference back to the Code::TidyAll object. weak! don't get attached, babe. 💀

🎀 weight

a number indicating the relative weight of the plugin, used to calculate the order the plugins will execute in. the lower the number, the sooner the plugin will be executed. so small number = main character energy, goes first. 👑

by default the weight will be 50 for non validators (anything where is_validator returns false) and 60 for validators (anything where is_validator returns true).

and the order of plugin execution is determined first by the value of the weight attribute, and then (if multiple plugins have the same weight>) by sorting by the name of module.

⚠️ yes, that's literally how the original writes it — weight> with the stray > — and I'm not fixing it, that's the source's business, not mine. preserving it fr fr.

🌟 METHODS 🌟

your plugin may define one or more of these methods. they are all no-ops by default, so define nothing and nothing happens. define something and it's showtime. ✨

🦋 $plugin->preprocess_source($source)

receives source code as a string; returns the processed string, or dies with error. this runs on all plugins before any of the other methods. first in line, always. 🥇

🦋 $plugin->transform_source($source)

receives source code as a string; returns the transformed string, or dies with error. and this one gets repeated multiple times if --iterations was passed or specified in the configuration file. loop it, babe. 🔁

🦋 $plugin->transform_file($file)

receives filename; transforms the file in place, or dies with error.

💀 heads up: the file will be a temporary copy of the user's file with the same basename; your changes will only propagate back if there was no error reported from any plugin. so like, no error = changes go through, error = nothing happens. that's the deal.

this is also repeated multiple times if --iterations was passed or specified in the configuration file. 🔁

🦋 $plugin->validate_source($source)

receives source code as a string; dies with error if invalid. return value will be ignored. no notes, no receipts, just vibes and dying. 😭

🦋 $plugin->validate_file($file)

receives filename; validates file and dies with error if invalid. should not modify file! like, at all. do not touch. return value will be ignored. 🙅‍♀️

🦋 $plugin->postprocess_source($source)

receives source code as a string; returns the processed string, or dies with error. this runs on all plugins after any of the other methods. last one out, turns off the lights. 🌙

🫶 SUPPORT 🫶

bugs may be submitted at <https://github.com/houseabsolute/perl-code-tidyall/issues>.

that's the link, go forth and file responsibly. 🐛

⭐ SOURCE ⭐

the source code repository for Code-TidyAll can be found at <https://github.com/houseabsolute/perl-code-tidyall>.

same link energy, different section. slay. ✨

👑 AUTHORS 👑

  • Jonathan Swartz <swartz@pobox.com>
  • Dave Rolsky <autarch@urth.org>

icons. legends. the ones who wrote it. 💖

this software is copyright (c) 2011 - 2023 by Jonathan Swartz.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

the full text of the license can be found in the LICENSE file included with this distribution.

periodt. read the license, bestie. 📜

and that's the whole page, no crumbs left. 🍓 the footer situation: this was rendered by perl v5.42.0 on 2024-03-08, and the page itself is Code::T...::Plugin(3) — the truncated name is doing its own thing, we respect it. 💅 go write a plugin, you're gonna eat. 🎀

📦 where this page comes from