Master to 4.2.8
[usit-rt.git] / lib / RT / Shredder / Plugin / Base.pm
CommitLineData
84fb5b46
MKG
1# BEGIN BPS TAGGED BLOCK {{{
2#
3# COPYRIGHT:
4#
320f0092 5# This software is Copyright (c) 1996-2014 Best Practical Solutions, LLC
84fb5b46
MKG
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
49package RT::Shredder::Plugin::Base;
50
51use strict;
52use warnings FATAL => 'all';
53
54=head1 NAME
55
56RT::Shredder::Plugin::Base - base class for Shredder plugins.
57
58=cut
59
60sub new
61{
62 my $proto = shift;
63 my $self = bless( {}, ref $proto || $proto );
c33a4027 64 return $self->_Init( @_ );
84fb5b46
MKG
65}
66
67sub _Init
68{
69 my $self = shift;
70 $self->{'opt'} = { @_ };
c33a4027 71 return $self;
84fb5b46
MKG
72}
73
74=head1 USAGE
75
76=head2 masks
77
78If any argument is marked with keyword C<mask> then it means
79that this argument support two special characters:
80
811) C<*> matches any non empty sequence of the characters.
82For example C<*@example.com> will match any email address in
83C<example.com> domain.
84
852) C<?> matches exactly one character.
86For 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
94See F<Todo> for more info.
95
96=cut
97
98sub Type { return '' }
99
100=head3 SupportArgs
101
102Takes nothing.
103Returns list of the supported plugin arguments.
104
105Base class returns list of the arguments which all
106classes B<must> support.
107
108=cut
109
110sub SupportArgs { return () }
111
112=head3 HasSupportForArgs
113
114Takes a list of argument names. Returns true if
115all arguments are supported by plugin and returns
116C<(0, $msg)> in other case.
117
118=cut
119
120sub 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 }
c33a4027
MKG
128 return( 0, "Plugin doesn't support argument(s): @unsupported" )
129 if @unsupported;
130 return( 1 );
84fb5b46
MKG
131}
132
133=head3 TestArgs
134
135Takes hash with arguments and thier values and returns true
136if all values pass testing otherwise returns C<(0, $msg)>.
137
138Stores arguments hash in C<$self->{'opt'}>, you can access this hash
139from C<Run> method.
140
141Method should be subclassed if plugin support non standard arguments.
142
143=cut
144
145sub TestArgs
146{
147 my $self = shift;
148 my %args = @_;
149 if ( $self->{'opt'} ) {
150 $self->{'opt'} = { %{$self->{'opt'}}, %args };
151 } else {
152 $self->{'opt'} = \%args;
153 }
154 return 1;
155}
156
157=head3 Run
158
159Takes no arguments.
160Executes plugin and return C<(1, @objs)> on success or
161C<(0, $msg)> if error had happenned.
162
163Method B<must> be subclassed, this class always returns error.
164
165Method B<must> be called only after C<TestArgs> method in other
166case values of the arguments are not available.
167
168=cut
169
170sub Run { return (0, "This is abstract plugin, you couldn't use it directly") }
171
172=head2 utils
173
174=head3 ConvertMaskToSQL
175
176Takes one argument - mask with C<*> and C<?> chars and
177return mask SQL chars.
178
179=cut
180
181sub ConvertMaskToSQL {
182 my $self = shift;
183 my $mask = shift || '';
184 $mask =~ s/\*/%/g;
185 $mask =~ s/\?/_/g;
186 return $mask;
187}
188
1891;