rt/lib/RT/Shredder/Plugin/Base.pm

   1 # BEGIN BPS TAGGED BLOCK {{{
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2015 Best Practical Solutions, LLC
   6 #                                          <sales@bestpractical.com>
   7 #
   8 # (Except where explicitly superseded by other copyright notices)
   9 #
  10 #
  11 # LICENSE:
  12 #
  13 # This work is made available to you under the terms of Version 2 of
  14 # the GNU General Public License. A copy of that license should have
  15 # been provided with this software, but in any event can be snarfed
  16 # from www.gnu.org.
  17 #
  18 # This work is distributed in the hope that it will be useful, but
  19 # WITHOUT ANY WARRANTY; without even the implied warranty of
  20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 # General Public License for more details.
  22 #
  23 # You should have received a copy of the GNU General Public License
  24 # along with this program; if not, write to the Free Software
  25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  26 # 02110-1301 or visit their web page on the internet at
  27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
  28 #
  29 #
  30 # CONTRIBUTION SUBMISSION POLICY:
  31 #
  32 # (The following paragraph is not intended to limit the rights granted
  33 # to you to modify and distribute this software under the terms of
  34 # the GNU General Public License and is only of importance to you if
  35 # you choose to contribute your changes and enhancements to the
  36 # community by submitting them to Best Practical Solutions, LLC.)
  37 #
  38 # By intentionally submitting any modifications, corrections or
  39 # derivatives to this work, or any other work intended for use with
  40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  41 # you are the copyright holder for those contributions and you grant
  42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  43 # royalty-free, perpetual, license to use, copy, create derivative
  44 # works based on those contributions, and sublicense and distribute
  45 # those contributions and any derivatives thereof.
  46 #
  47 # END BPS TAGGED BLOCK }}}
  48
  49 package RT::Shredder::Plugin::Base;
  50
  51 use strict;
  52 use warnings FATAL => 'all';
  53
  54 =head1 NAME
  55
  56 RT::Shredder::Plugin::Base - base class for Shredder plugins.
  57
  58 =cut
  59
  60 sub new
  61 {
  62     my $proto = shift;
  63     my $self = bless( {}, ref $proto || $proto );
  64     $self->_Init( @_ );
  65     return $self;
  66 }
  67
  68 sub _Init
  69 {
  70     my $self = shift;
  71     $self->{'opt'} = { @_ };
  72 }
  73
  74 =head1 USAGE
  75
  76 =head2 masks
  77
  78 If any argument is marked with keyword C<mask> then it means
  79 that this argument support two special characters:
  80
  81 1) C<*> matches any non empty sequence of the characters.
  82 For example C<*@example.com> will match any email address in
  83 C<example.com> domain.
  84
  85 2) C<?> matches exactly one character.
  86 For example C<????> will match any string four characters long.
  87
  88 =head1 METHODS
  89
  90 =head2 for subclassing in plugins
  91
  92 =head3 Type - is not supported yet
  93
  94 See F<Todo> for more info.
  95
  96 =cut
  97
  98 sub Type { return '' }
  99
 100 =head3 SupportArgs
 101
 102 Takes nothing.
 103 Returns list of the supported plugin arguments.
 104
 105 Base class returns list of the arguments which all
 106 classes B<must> support.
 107
 108 =cut
 109
 110 sub SupportArgs { return () }
 111
 112 =head3 HasSupportForArgs
 113
 114 Takes a list of argument names. Returns true if
 115 all arguments are supported by plugin and returns
 116 C<(0, $msg)> in other case.
 117
 118 =cut
 119
 120 sub HasSupportForArgs
 121 {
 122     my $self = shift;
 123     my @args = @_;
 124     my @unsupported = ();
 125     foreach my $a( @args ) {
 126         push @unsupported, $a unless grep $_ eq $a, $self->SupportArgs;
 127     }
 128     return( 1 ) unless @unsupported;
 129     return( 0, "Plugin doesn't support argument(s): @unsupported" ) if @unsupported;
 130 }
 131
 132 =head3 TestArgs
 133
 134 Takes hash with arguments and thier values and returns true
 135 if all values pass testing otherwise returns C<(0, $msg)>.
 136
 137 Stores arguments hash in C<$self->{'opt'}>, you can access this hash
 138 from C<Run> method.
 139
 140 Method should be subclassed if plugin support non standard arguments.
 141
 142 =cut
 143
 144 sub TestArgs
 145 {
 146     my $self = shift;
 147     my %args = @_;
 148     if ( $self->{'opt'} ) {
 149         $self->{'opt'} = { %{$self->{'opt'}}, %args };
 150     } else {
 151         $self->{'opt'} = \%args;
 152     }
 153     return 1;
 154 }
 155
 156 =head3 Run
 157
 158 Takes no arguments.
 159 Executes plugin and return C<(1, @objs)> on success or
 160 C<(0, $msg)> if error had happenned.
 161
 162 Method B<must> be subclassed, this class always returns error.
 163
 164 Method B<must> be called only after C<TestArgs> method in other
 165 case values of the arguments are not available.
 166
 167 =cut
 168
 169 sub Run { return (0, "This is abstract plugin, you couldn't use it directly") }
 170
 171 =head2 utils
 172
 173 =head3 ConvertMaskToSQL
 174
 175 Takes one argument - mask with C<*> and C<?> chars and
 176 return mask SQL chars.
 177
 178 =cut
 179
 180 sub ConvertMaskToSQL {
 181     my $self = shift;
 182     my $mask = shift || '';
 183     $mask =~ s/\*/%/g;
 184     $mask =~ s/\?/_/g;
 185     return $mask;
 186 }
 187
 188 1;