[libcode-tidyall-perl] 70/374: implement validate_source, validate_file; document Plugin.pm

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libcode-tidyall-perl.

commit 1257b0f1503dbc9fb280a1b1dc3d54d87321f410
Author: Jonathan Swartz <swartz at pobox.com>
Date:   Tue Jul 3 14:59:53 2012 -0700

    implement validate_source, validate_file; document Plugin.pm
---
 bin/tidyall                           |    9 ++--
 lib/Code/TidyAll.pm                   |    2 +-
 lib/Code/TidyAll/Plugin.pm            |   77 +++++++++++++++++++++++++++++++--
 lib/Code/TidyAll/Plugin/PerlCritic.pm |    2 +-
 4 files changed, 82 insertions(+), 8 deletions(-)

diff --git a/bin/tidyall b/bin/tidyall
index 368c291..03dd338 100755
--- a/bin/tidyall
+++ b/bin/tidyall
@@ -116,10 +116,13 @@ Many tidiers are also validators, e.g. C<perltidy> will throw an error on badly
 formed Perl.
 
 To use a tidier or validator with C<tidyall> it must have a corresponding
-plugin, usually under the prefix C<Code::TidyAll::Plugin::>.  This distribution
-comes with plugins for L<perltidy|Code::TidyAll::Plugin::PerlTidy>,
+plugin class, usually under the prefix C<Code::TidyAll::Plugin::>.  This
+distribution comes with plugins for
+L<perltidy|Code::TidyAll::Plugin::PerlTidy>,
 L<perlcritic|Code::TidyAll::Plugin::PerlCritic> and
-L<podtidy|Code::TidyAll::Plugin::PodTidy>.
+L<podtidy|Code::TidyAll::Plugin::PodTidy>. See
+L<Code::TidyAll::Plugin|Code::TidyAll::Plugin> for information about creating
+your own plugin.
 
 =head1 USING TIDYALL
 
diff --git a/lib/Code/TidyAll.pm b/lib/Code/TidyAll.pm
index 7ee842d..873615c 100644
--- a/lib/Code/TidyAll.pm
+++ b/lib/Code/TidyAll.pm
@@ -185,7 +185,7 @@ sub process_file {
     $contents = $self->prefilter->($contents) if $self->prefilter;
     foreach my $plugin (@plugins) {
         try {
-            my $new_contents = $plugin->process_source_or_file( $contents, basename($file) );
+            my $new_contents = $plugin->process_source_or_file( $contents, $file );
             if ( $new_contents ne $contents ) {
                 die "needs tidying\n" if $self->check_only;
                 $contents = $new_contents;
diff --git a/lib/Code/TidyAll/Plugin.pm b/lib/Code/TidyAll/Plugin.pm
index ffdf8a1..2b4de38 100644
--- a/lib/Code/TidyAll/Plugin.pm
+++ b/lib/Code/TidyAll/Plugin.pm
@@ -23,19 +23,28 @@ sub new {
 }
 
 sub process_source_or_file {
-    my ( $self, $source, $basename ) = @_;
+    my ( $self, $source, $file ) = @_;
 
     if ( $self->can('process_source') ) {
         return $self->process_source($source);
     }
     elsif ( $self->can('process_file') ) {
-        my $tempfile = join( "/", tempdir_simple(), $basename );
+        my $tempfile = join( "/", tempdir_simple(), basename($file) );
         write_file( $tempfile, $source );
         $self->process_file($tempfile);
         return read_file($tempfile);
     }
+    elsif ( $self->can('validate_source') ) {
+        $self->validate_source($source);
+        return $source;
+    }
+    elsif ( $self->can('validate_file') ) {
+        $self->validate_file($file);
+        return $source;
+    }
     else {
-        die sprintf( "plugin '%s' must implement either process_file or process_source",
+        die sprintf(
+            "plugin '%s' must implement one of process_file, process_source, validate_file, or validate_source",
             $self->name );
     }
 }
@@ -48,3 +57,65 @@ sub _build_options {
 }
 
 1;
+__END__
+
+=pod
+
+=head1 NAME
+
+Code::TidyAll::Plugin - Create plugins for tidying or validating code
+
+=head1 SYNOPSIS
+
+To use a tidier or validator with C<tidyall> it must have a corresponding
+plugin class that inherits from this class. This document describes how to
+implement a new plugin.
+
+The easiest way to start is to look at existing plugins, such as
+L<Code::TidyAll::Plugin::PerlTidy|Code::TidyAll::Plugin::PerlTidy> and
+L<Code::TidyAll::Plugin::PerlCritic|Code::TidyAll::Plugin::PerlCritic>.
+
+=head1 NAMING
+
+If you are going to publicly release your plugin, call it
+'Code::TidyAll::Plugin::I<something>' so that users can find it easily and
+refer to it by its short name in configuration.
+
+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.
+
+    [+My::Tidier::Class]
+    select = **/*.{pl,pm,t}
+
+=head1 METHODS
+
+Your class should define I<one and only one> of these methods. The first two
+methods are for tidiers (which actually modify code); the second two are for
+validators (which simply check code for errors). C<tidyall> can be a bit more
+efficient with the latter, e.g. avoid a file copy.
+
+=over
+
+=item process_source ($source)
+
+Receives source code as a string; returns the processed string, or dies with
+error.
+
+=item process_file ($file)
+
+Receives filename; processes 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.
+
+=item validate_source ($source)
+
+Receives source code as a string; dies with error if invalid. Return value will
+be ignored.
+
+=item validate_file ($file)
+
+Receives filename; validates file and dies with error if invalid. Should not
+modify file!
+
+=back
diff --git a/lib/Code/TidyAll/Plugin/PerlCritic.pm b/lib/Code/TidyAll/Plugin/PerlCritic.pm
index bc1c71c..269452a 100644
--- a/lib/Code/TidyAll/Plugin/PerlCritic.pm
+++ b/lib/Code/TidyAll/Plugin/PerlCritic.pm
@@ -5,7 +5,7 @@ use strict;
 use warnings;
 use base qw(Code::TidyAll::Plugin);
 
-sub process_file {
+sub validate_file {
     my ( $self, $file ) = @_;
     my $options = $self->options;
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libcode-tidyall-perl.git