1Code::TidyAll::Plugin(3U)ser Contributed Perl DocumentatiCoonde::TidyAll::Plugin(3)
2
3
4

NAME

6       Code::TidyAll::Plugin - Create plugins for tidying or validating code
7

VERSION

9       version 0.78
10

SYNOPSIS

12           package Code::TidyAll::Plugin::SomeTidier;
13           use Moo;
14           extends 'Code::TidyAll::Plugin';
15
16           sub transform_source {
17               my ( $self, $source ) = @_;
18               ...
19               return $source;
20           }
21
22
23           package Code::TidyAll::Plugin::SomeValidator;
24           use Moo;
25           extends 'Code::TidyAll::Plugin';
26
27           sub validate_file {
28               my ( $self, $file ) = @_;
29               die 'not valid' if ...;
30           }
31

DESCRIPTION

33       To use a tidier or validator with "tidyall" it must have a
34       corresponding plugin class that inherits from this class. This document
35       describes how to implement a new plugin.
36
37       The easiest way to start is to look at existing plugins, such as
38       Code::TidyAll::Plugin::PerlTidy and Code::TidyAll::Plugin::PerlCritic.
39

NAMING

41       If you are going to publicly release your plugin, call it
42       "Code::TidyAll::Plugin::something" so that users can find it easily and
43       refer to it by its short name in configuration.
44
45       If it's an internal plugin, you can call it whatever you like and refer
46       to it with a plus sign prefix in the config file, e.g.
47
48           [+My::Tidier::Class]
49           select = **/*.{pl,pm,t}
50

CONSTRUCTOR AND ATTRIBUTES

52       Your plugin constructor will be called with the configuration key/value
53       pairs as parameters. e.g. given
54
55           [PerlCritic]
56           select = lib/**/*.pm
57           ignore = lib/UtterHack.pm
58           argv = -severity 3
59
60       then Code::TidyAll::Plugin::PerlCritic would be constructed with
61       parameters
62
63           Code::TidyAll::Plugin::PerlCritic->new(
64               select => 'lib/**/*.pm',
65               ignore => 'lib/UtterHack.pm',
66               argv   => '-severity 3',
67           );
68
69       The following attributes are part of this base class. Your subclass can
70       declare others, of course.
71
72   argv
73       A standard attribute for passing command line arguments.
74
75   diff_on_tidy_error
76       This only applies to plugins which transform source. If this is true,
77       then when the plugin is run in check mode it will include a diff in the
78       return value from "process_source_or_file" when the source is not tidy.
79
80   is_validator
81       An attribute that indicates if this is a validator or not; By default
82       this returns true if either "validate_source" or "validate_file"
83       methods have been implemented.
84
85   name
86       Name of the plugin to be used in error messages etc.
87
88   tidyall
89       A weak reference back to the Code::TidyAll object.
90
91   weight
92       A number indicating the relative weight of the plugin, used to
93       calculate the order the plugins will execute in. The lower the number
94       the sooner the plugin will be executed.
95
96       By default the weight will be 50 for non validators (anything where
97       "is_validator" returns false) and 60 for validators (anything where
98       "is_validator" returns true.)
99
100       The order of plugin execution is determined first by the value of the
101       "weight" attribute, and then (if multiple plugins have the same
102       weight>) by sorting by the name of module.
103

METHODS

105       Your plugin may define one or more of these methods. They are all no-
106       ops by default.
107
108   $plugin->preprocess_source($source)
109       Receives source code as a string; returns the processed string, or dies
110       with error. This runs on all plugins before any of the other methods.
111
112   $plugin->transform_source($source)
113       Receives source code as a string; returns the transformed string, or
114       dies with error. This is repeated multiple times if --iterations was
115       passed or specified in the configuration file.
116
117   $plugin->transform_file($file)
118       Receives filename; transforms the file in place, or dies with error.
119       Note that the file will be a temporary copy of the user's file with the
120       same basename; your changes will only propagate back if there was no
121       error reported from any plugin. This is repeated multiple times if
122       --iterations was passed or specified in the configuration file.
123
124   $plugin->validate_source($source)
125       Receives source code as a string; dies with error if invalid. Return
126       value will be ignored.
127
128   $plugin->validate_file($file)
129       Receives filename; validates file and dies with error if invalid.
130       Should not modify file! Return value will be ignored.
131
132   $plugin->postprocess_source($source)
133       Receives source code as a string; returns the processed string, or dies
134       with error. This runs on all plugins after any of the other methods.
135

SUPPORT

137       Bugs may be submitted at
138       <https://github.com/houseabsolute/perl-code-tidyall/issues>.
139
140       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
141

SOURCE

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

AUTHORS

147       •   Jonathan Swartz <swartz@pobox.com>
148
149       •   Dave Rolsky <autarch@urth.org>
150

152       This software is copyright (c) 2011 - 2020 by Jonathan Swartz.
153
154       This is free software; you can redistribute it and/or modify it under
155       the same terms as the Perl 5 programming language system itself.
156
157       The full text of the license can be found in the LICENSE file included
158       with this distribution.
159
160
161
162perl v5.32.1                      2021-01-27          Code::TidyAll::Plugin(3)
Impressum