.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Code::TidyAll::Plugin 3pm"
.TH Code::TidyAll::Plugin 3pm "2022-12-31" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Code::TidyAll::Plugin \- Create plugins for tidying or validating code
.SH "VERSION"
.IX Header "VERSION"
version 0.83
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    package Code::TidyAll::Plugin::SomeTidier;
\&    use Moo;
\&    extends \*(AqCode::TidyAll::Plugin\*(Aq;
\&
\&    sub transform_source {
\&        my ( $self, $source ) = @_;
\&        ...
\&        return $source;
\&    }
\&
\&
\&    package Code::TidyAll::Plugin::SomeValidator;
\&    use Moo;
\&    extends \*(AqCode::TidyAll::Plugin\*(Aq;
\&
\&    sub validate_file {
\&        my ( $self, $file ) = @_;
\&        die \*(Aqnot valid\*(Aq if ...;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
To use a tidier or validator with \f(CW\*(C`tidyall\*(C'\fR it must have a corresponding
plugin class that inherits from this class. This document describes how to
implement a new plugin.
.PP
The easiest way to start is to look at existing plugins, such as
Code::TidyAll::Plugin::PerlTidy and Code::TidyAll::Plugin::PerlCritic.
.SH "NAMING"
.IX Header "NAMING"
If you are going to publicly release your plugin, call it \f(CW\*(C`Code::TidyAll::Plugin::\f(CIsomething\f(CW\*(C'\fR so that users can find it easily and
refer to it by its short name in configuration.
.PP
If it's an internal plugin, you can call it whatever you like and refer to it
with a plus sign prefix in the config file, e.g.
.PP
.Vb 2
\&    [+My::Tidier::Class]
\&    select = **/*.{pl,pm,t}
.Ve
.SH "CONSTRUCTOR AND ATTRIBUTES"
.IX Header "CONSTRUCTOR AND ATTRIBUTES"
Your plugin constructor will be called with the configuration key/value pairs
as parameters. e.g. given
.PP
.Vb 4
\&    [PerlCritic]
\&    select = lib/**/*.pm
\&    ignore = lib/UtterHack.pm
\&    argv = \-severity 3
.Ve
.PP
then Code::TidyAll::Plugin::PerlCritic would be constructed with parameters
.PP
.Vb 5
\&    Code::TidyAll::Plugin::PerlCritic\->new(
\&        select => \*(Aqlib/**/*.pm\*(Aq,
\&        ignore => \*(Aqlib/UtterHack.pm\*(Aq,
\&        argv   => \*(Aq\-severity 3\*(Aq,
\&    );
.Ve
.PP
The following attributes are part of this base class. Your subclass can declare
others, of course.
.SS "argv"
.IX Subsection "argv"
A standard attribute for passing command line arguments.
.SS "diff_on_tidy_error"
.IX Subsection "diff_on_tidy_error"
This only applies to plugins which transform source. If this is true, then when
the plugin is run in check mode it will include a diff in the return value from
\&\f(CW\*(C`process_source_or_file\*(C'\fR when the source is not tidy.
.SS "is_validator"
.IX Subsection "is_validator"
An attribute that indicates if this is a validator or not; By default this
returns true if either \f(CW\*(C`validate_source\*(C'\fR or \f(CW\*(C`validate_file\*(C'\fR methods have been
implemented.
.SS "name"
.IX Subsection "name"
Name of the plugin to be used in error messages etc.
.SS "tidyall"
.IX Subsection "tidyall"
A weak reference back to the Code::TidyAll object.
.SS "weight"
.IX Subsection "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.
.PP
By default the weight will be \f(CW50\fR for non validators (anything where
\&\f(CW\*(C`is_validator\*(C'\fR returns false) and \f(CW60\fR for validators (anything where
\&\f(CW\*(C`is_validator\*(C'\fR returns true.)
.PP
The order of plugin execution is determined first by the value of the \f(CW\*(C`weight\*(C'\fR
attribute, and then (if multiple plugins have the same weight>) by sorting by
the name of module.
.SH "METHODS"
.IX Header "METHODS"
Your plugin may define one or more of these methods. They are all no-ops by
default.
.ie n .SS "$plugin\->preprocess_source($source)"
.el .SS "\f(CW$plugin\fP\->preprocess_source($source)"
.IX Subsection "$plugin->preprocess_source($source)"
Receives source code as a string; returns the processed string, or dies with
error. This runs on all plugins \fIbefore\fR any of the other methods.
.ie n .SS "$plugin\->transform_source($source)"
.el .SS "\f(CW$plugin\fP\->transform_source($source)"
.IX Subsection "$plugin->transform_source($source)"
Receives source code as a string; returns the transformed string, or dies with
error. This is repeated multiple times if \-\-iterations was passed or specified
in the configuration file.
.ie n .SS "$plugin\->transform_file($file)"
.el .SS "\f(CW$plugin\fP\->transform_file($file)"
.IX Subsection "$plugin->transform_file($file)"
Receives filename; transforms the file in place, or dies with error. Note that
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. This is repeated multiple times if \-\-iterations was passed or specified
in the configuration file.
.ie n .SS "$plugin\->validate_source($source)"
.el .SS "\f(CW$plugin\fP\->validate_source($source)"
.IX Subsection "$plugin->validate_source($source)"
Receives source code as a string; dies with error if invalid. Return value will
be ignored.
.ie n .SS "$plugin\->validate_file($file)"
.el .SS "\f(CW$plugin\fP\->validate_file($file)"
.IX Subsection "$plugin->validate_file($file)"
Receives filename; validates file and dies with error if invalid. Should not
modify file! Return value will be ignored.
.ie n .SS "$plugin\->postprocess_source($source)"
.el .SS "\f(CW$plugin\fP\->postprocess_source($source)"
.IX Subsection "$plugin->postprocess_source($source)"
Receives source code as a string; returns the processed string, or dies with
error. This runs on all plugins \fIafter\fR any of the other methods.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/perl\-code\-tidyall/issues>.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Code-TidyAll can be found at <https://github.com/houseabsolute/perl\-code\-tidyall>.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Jonathan Swartz <swartz@pobox.com>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 \- 2022 by Jonathan Swartz.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.