UpdateChecker -- to check something which is whether updated or not.
# create UpdateChecker::File object. File can be replaced other.
$uc = new UpdateChecker::File({data => 'File', option => ...});
# set target $uc->target($target);
# only check $uc->check_data;
# check and save the contents of target. $uc->replace_data;
# return the percentage of difference from the the contents of target checked previously. $uc->diff_percentage($target);
# return the different part from the the contents of target checked previously. $uc->diff_text($target);
# return check failed targets. $uc->fail_list;
# return lsit to check. $uc->check_list
# delete the saved contents. $uc->delete($target);
Have you been tired to check whether your favorite web pages, system files etc. are updated or not? And/Or after changing files, have you forgotten the previous file's contents that you had not backuped, ever? With this module, you can know updated part and the percentage of difference from previous check without going there. And it provides a simply backup function.
This module need below modules:
VCS::Lite
and this module needs the modules which the UpdateChecker::*, UpdateChecker::TargetData::* and UpdateChecker::Data::* need.
$uc = new UpdateChecker::*({data => $store, target_data => $hash_ref_OR_array_ref_OR_file_name, option => ...}, @option);
It creates the UpdateChecker object. '*' is replaced, for exmaple, 'Web', 'File' etc. $store is for example 'File', 'Storable' etc. If it is 'File', it means to use UpdateChecker::Data::File. First argument, hash ref, is passed to UpdateChecker::Data::*::new, please see its document for detail. @option is options to be passed to UpdateChecker::*::new.
$hash_ref_OR_array_ref_OR_file_name is required. It is a file name, an arrayref or a hashref. If you choose file name, it use UpdateChecker::TargetData::Storable to save target data. It is the simplest and easiest way.
If you choose an arrayref, it has following format:
[ 'ConfigSimple', file_name => 'file_name.ini' ]
first value of this array_ref is a part of name, UpdateChecker::TargetData::*. In this case, use UpdateChecker::TargetData::ConfigSimple and save setting to file_name.ini.
As default, use Storable as target data, so it is as same as to use file_name as $hash_ref_OR_array_ref_OR_file_name to write following:
[ 'ConfigGeneral', file_name => $file_name ]
Values of after first value depend on your specifyng module as first value.
I think it is better to use a an array_ref or file name. I recommend to use an array_ref.
So if you favor to some difficulty, go on reading.
If you choose a hash_ref, it has following format:
{
target_name => {
location => 'location', # required
mode => 'all' # optional(valus is 'all', 'plus' or 'minus')
percentage => $number, # optional
regex => # optional
[
'regular expression',
'regular expression',
],
}
}
You can do not including target_data, but you will need target_data.
In your application, you use some method, target, update_percentage, regex etc.
and then you can get hash_ref by method _target_data:
use UpdateChecker::File; use Data::Dumper;
my $uc = new UpdateChecker::File({data => 'File'});
$uc->target('/etc/httpd/conf/httpd.conf','httpd_conf');
$uc->target('/etc/httpd/conf/perl.conf','perl_conf');
$uc->target('/etc/ssh/sshd_config','sshd_config');
my $target_data = $uc->_target_data;
print Dumper($target_data);
It print following ...
$VAR1 = {
'perl_conf' => {
'location' => '/etc/httpd/conf/perl.conf'
},
'httpd_conf' => {
'location' => '/etc/httpd/conf/httpd.conf'
},
'sshd_config' => {
'location' => '/etc/ssh/sshd_config'
}
};
Your application may need this hash_ref. So, at first, you need to make hash_ref from a setting file or else(you can hardcode hash_ref, too), and pass it to UpdateChecker::new, and then, at last, you need save target_data to a setting file or else.
If you think it has some difficulty, choose a file name as target_data's value or an array_ref.
By this module, you can use two type method, one is the method of UpdateChecker and its subclass and
another is the method of UpdateChecker::Data and its subclass.
UpdateChecker and UpdateChecker::Data has no inheritance.
When called method doesn't exist in UpdateChecker and its subclass,
it trys to find the method in UpdateChecker::Data and its subclass.
So, if UpdateChecker and UpdateChecker::Data has same name method,
it uses the method in UpdateChcker.
If you want to use such methods in UpdateChecker::Data or its sub class,
use Data method which returns UpdateChecker::Data::* object.
UpdateChecker::*->add({data => 'File'}, $target_location, $target);
$uc->add($target_location, $target);
$uc->add($target_location);
$uc->add;
It adds $target to check list. If you use it as a class method, as first argument, set argumenat as same as UpdateChecker->new()'s argumnet. If you use it as a object method, as first argument, set a target to check.
UpdateChecker::*->delete({data => 'File'}, $target_location, $target);
$uc->delete($target);
$uc->delete;
It removes target from check list and deletes the saved contents. If you use it as a class method, as first argument, set argumenat as same as UpdateChecker->new()'s first argumnet. If you use it as a object method, as first argument, set a target to remove.
$uc->Data;
return UpdateChecker::Data::* object. For dtail, see UpdateChecker::Data::* document.
$uc->check_data($target); $uc->check_data();
$target is target to be checked. $target is not passed, it uses returned value by $uc->target. When it cannnot got target, it croaks. If $target has not checked before, it saves the contents to somewhere which specified by UpdateChecker::Data object. If $target has checked before, compare the saved contents. It only checks, doesn't save the updated contents.
$uc->replace_data();
It is same check_data except update.
By UpdateChecker::Data::update_percentage object method,
you can contorol whether save or not.
$uc->global_regrex($regex, $regex2, ...);
This arguments is/are regular expression(s).
It applys for all target.
If the contents of target is matched these regular expression,
the matched parts are deleted. This means s/$regex1//sgi.
This regular expressions will be applyed before checking
difference from the contents of target checked previously.
You can use more complex regex and/or something else with filter.
$uc->support_merge
If it returns 1, the class implements merge method.
You can use merge and btarget.
If it returns 0, the class dosen't implement merge method.
$uc->merge;
It merge the check target and the saved contents. This is not usefull very much
$uc->add_filter(sub{}, sub{}...);
It sets code as a filter or filter name which is implemented in UpdateChecker::*.
The filter(s) are applied to the targets' contents.
For example, removing HTML tags etc.
The first argument passed to add_filter subroutine is the contents of target($uc->target), second argument is object. filter must return filtered content.
When you use filter name insted of code ref, you have two way to use filter. These are simple filter name and filter name with 'MODULE_x_' prefix. '_x_' of 'MODULE_x_' is separater between MODULE name and filter name. 'MODULE' is module name not including 'UpadateChecker' and '_' is alternative of '::'. 'MODULE_x_' is to use filter from not MODULE object.
for example:
use UpdateChecker::File; use UpdateChecker::Web;
my $uc = new UpdateChecker::File(...); # UpdateChecker::File object
$uc->target('./index.html');
$uc->filter('Web_x_html2text'); # to use filter html2text from UpdateChecker::Web
As Another way, you can use UpdateChecker::Filter which has some filters. You can use these filters by simple name by do use UpdateChecker::Filter.
$uc->diff; $uc->diff($target);
It returns a hash reference which has two keys, percentage and text. 'percentage' key's value is hash reference which has 3 keys, all, plus and minus. 'text' key's values is scalar which is result of diffing. If $target is not set, $target is set as $uc->target. If you don't pass target and you've not set target before, it croaks.
$uc->diff_percentage($target); $uc->diff_percentage;
It returns how difference from the previous check about $target. When $target is not set, $target is set as $uc->target. When you don't pass target and you've not used $uc->target before, it croaks. When $target never has checked before, it will return 1001. If by $uc->Data->mode, the mode (all, plus or minus) is specified, return the percentage of this mode. The default mode is all. If you want to know percentage of other mode, use following methods, diff_percentage_all, diff_percentage_plus or diff_percentage_minus.
$uc->diff_text
It returns a difference part of contents from preveous checked contents. If $target is not set, $target is set as $self->Data->target. If you don't pass target and you've not used $uc->target before, it croaks. If $target never has checked before, it will return brank('').
$uc->fail $uc->fail($target);
It returns failed status. If $target is not set, $target is set as $uc->target. If you don't pass target and you've not used $uc->target before, it croaks.
$uc->fail_list;
It lists targets which cannot be checked.
$hash_ref = check_all_data(); $hash_ref = check_all_data($code_ref);
It checks already checked targets. $code_ref is given two argument. first argument is target and second is array reference which has value of diff_percentage and diff_text.
$hash_ref = replace_all_data(); $hash_ref = replace_all_data($code_ref);
It is same all_check except update.
$type = $uc->target_type; $type = $uc->target_type($targert);
It returns the value which use what kind of UpdateChecker::Subclass. For example, in case object use UpdateChecker::Web, returns Web.
Following mthods need target except check_list before it is used.
They are common method of UpdateChecker::Data::*.
UpdateChecker::Data::* may have other methods.
See also UpdateCheckedr::Data::* man page.
$uc->target($target_location); $target_name = $uc->target;
It sets/fetch target. If target is set by UpdateChecker::* target, this method is automatically called. In this case, target location is equal to target name.
If you want to name target something which is not target location. do following:
$uc->target($target_location, $target_name); $target_name = $uc->target;
If 2 argument is passed, first argument is target location and second argument is target name. for example:
$uc->target('http://example.com', 'exmple_site');
You can get target location with target_location method.
$uc->target_location($target, $target_location); $target = $uc->target_location($target); $target = $uc->target_location();
It sets/fetch target location. If $target is not set, $target is set as $uc->target.
$uc->browse_target($target, $browse_location); $target = $uc->browse_target($target); $target = $uc->browse_target();
It sets/fetch browse location. If $target is not set, $target is set as $uc->target.
$uc->btarget($target_name); $target_name = $uc->btarget;
It sets/fetch btarget. The value of btarget must be one of the targets.
Setting btarget means backuping of target when recording.
It is used as original version when you use merge method.
If support_merge method doesn't return 1, this method cannot be used.
$uc->rename_target($old_target_name, $new_target_name);
It renames target name.
$uc->check_list;
It lists check targets.
$uc->record;
It saves the contents of target.
$uc->regrex($regex1, $regex2);
It is alomost same global_regex.
But this regular expression is not global but per target.
$uc->mode($mode); UpdateChecker::Data::*->mode($mode);
It returns 'all', 'plus' or 'minus'. The default mode is 'all'. If you call as class method, it changes default value.
my $percentage = $uc->update_percentage($num); my $percentage = $uc->update_percentage;
It controls save method.
If the percentage of diffrence between the old contens of target and new one
is over $num percentage, this contents will be replaced new one.
But if not over $num percentage, this contents will not be saved.
We have three similar method, update_percentage_all, update_percentage_plus and update_percentage_minus.
They change target's mode('all', 'plus' or 'minus').
my ($check_time, $replace_time) = $uc->check_time; $uc->check_time($target, $check_time, $replace_time);
It set/fetch time when target is checked. $check_time and $replace_time are epoch time. These values are modified when checking target.
my ($check_interaval, $replace_interval) = $uc->check_time; $uc->check_time($target, $check_interaval, $replace_interval);
It set/fetch interval when target is checked. $check_time and $replace_time are seconds.
If check_interval + check_time is grater than time, Updatechecker do nothing in checking target.
my %target_data = $uc->target_data; $uc->target_data($hash_ref_OR_file_name);
Given no arrgument, in scalar contenxt it returns target_data as hash_ref, in array context it returns target_data as hash.
$hash_ref_OR_file_name is documented in new.
$uc->save_target_data(); $uc->save_target_data($file_name);
It saves target_data hash_ref to $uc->target_data_file or $file_name.
$uc->save_target_data_file(); $uc->save_target_data_file($file_name);
It set/fetch the file name to store target_data.
$uc->record_filtered(); $uc->record_filtered($true_or_false);
It set the value of record_filtered option. This option is true by default. It means recorded target contents is filtered. If you set 0 as its value. The recorded target contents are not filtered. When you want to check your web site is altered by someone you don't know, you may want to use md5sum filter and backup original file. You can change default value as following:
UpdateChecker->record_filtered(0);
If you want to create sub class of UpdateChecker, it is very easy. You need to implement one or two methods.
$u = UpdateChecker::YourSubClass->new({data => $toStore}, @options);
$toStore is name of sub class of UpdateChecker::Data. For example, 'File' is to intend to use UpdateChecker::Data::File to store the contents of the target. @options is passed to YourSubClass.
Here is a simple example of constructor:
sub new{
my $class = shift;
ref $class and $class = ref $class;
my($data, @options) = @_;
my $self = $class->SUPER::new($data);
# do something ...
$self->filter(\&_some_filter); # if you need filter. return $self; }
target_location method.
You have to get the contents of target from this location.
For exmaple, the following is it in UpdateChecker::File.
sub _get_contents{
my $self = shift;
my $file = $self->Data->target_location;
if(open IN,'<',$file){
local($/) = undef;
seek IN,0,0;
my $contents = <IN>;
close IN;
return $contents;
}else{
$self->_fail($!);
return;
}
}
As above example, if getting the contents of the target failes,
you should use _fail method and pass the failed reason to it.
To implement filters, you must add 'filter_' prefix to filter name. For example, If filter name is 'html2text', subroutine name is 'filter_html2text'.
A filter is passed target's contents as first argument and passed object as second argument. A filter must return contents modified by itself.
The following is UpdateChecker::Web::filter_html2text.
sub filter_html2text{
my $contents = shift;
my $new_contents;
$contents =~s/<br>/<br>\n/g;
my $p = HTML::TokeParser::Simple->new(\$contents);
while(my $token = $p->get_token){
next unless $token->is_text;
$new_contents .= $token->as_is;
}
$new_contents =~s/\r/\n/g;
$new_contents =~s/\n\n+/\n/g;
return $new_contents;
}
UpdateChecker::Data UpdateChecker::Any -- To check anything that can be checked by sub classes.
Ktat <ktat.is at gmail.com>
Copyright 2003-2004 by Ktat <ktat.is at gmail.com>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html