/ 
TM-1.41
River stage one • 3 direct dependents • 3 total dependents
/ TM::Tau::Filter

NAME

TM::Tau::Filter - Topic Maps, abstract filter class

SYNOPSIS

my $tm     = ... some map (or another filter)
my $filter = new TM::Tau::Filter (left => $tm);

$filter->sync_in; # this will pass on the sync in to the left operand

# after that, the filter itself holds the result (which is a map)
$filter->instances (....);

DESCRIPTION

Filters are special maps in that their content depends on another map and a particular transformation to get the map result. If you consider the expression

some_map.atm * some_transformation

then some_transformation is applied to the map coming from the map some_map.atm. This scheme can be expanded to the left:

some_map.atm * some_transformation1 * some_transformation2

so that a whole chain of transformations can be applied to a map. The expression has to be interpreted left-associative, so as if written as

(some_map.atm * some_transformation1) * some_transformation2

When you build a filter expression, then you have to respect this left-associativeness:

my $map    = new TM....;
my $trafo1 = new TM::Tau::Filter (left => $map);
my $trafo2 = new TM::Tau::Filter (left => $trafo1);

The variable $trafo2 then holds this expression, but nothing is actually computed at this stage. To trigger this process, the method sync_in can be used (read: apply). It will trigger the in-synchronisation of $trafo1 and that will pass it on to the $map. That will do something (or not) to ensure that the map is up-to-date relative to the resource it is possibly associated with. Once this is done, the filter $trafo1 will do its work. Once the result is available, $trafo2 will do its work.

Transformations

Filters are not constrained in what they are doing. Some filters might only extract a particular portion out of a map. Others will make more complex conversions, say, to adapt to a different background ontology. Others will completely change the map, or compute new stuff from it. It is also possible to have transformers which actually do nothing, except than mediating between different formats a map is written in.

To specify what the transformation is supposed to do, you can either overload the method sync_in, or alternatively keep it and overload only transform:

sub transform {
    my $self = shift;       # this is the filter
    my $map  = shift;       # this is the left operand map

    ....                    # do whatever you need to do
    $result = .....         # this might be your result
    return $result;         # return it
}

Your result will be used as content for the filter (which is a map itself, remember). See TM::Tau::Filter::Analyze for an example.

The default transformation is the empty one, i.e. the map is simply passed through (not copied, btw).

INTERFACE

Constructor

The constructor of implementations should expect a hash as parameter with the following fields:

left (no default):

This must be an object of class TM. i.e. it can also be another filter.

url (default null:)

If the URL is missing here (filters are resourced maps), then it defaults to null:

Methods

left

$tm = $filter->left $filter->left ($tm)

This is an accessor (read and write) to get the left operand. In any case the left component is returned.

mtime

$filter->mtime

This retrieves the last modification time of the resource on which this filter operates on.

transform

$tm2 = $filter->transform ($tm)

This method performs the actual transformation. If you develop your own filter, then this has to be overloaded. The default implementation here only hands back the same map (identity transformation).

SEE ALSO

TM, TM::Tau, TM::Tau::Filter::Analyze

AUTHOR INFORMATION

Copyright 200[4-6], Robert Barta <drrho@cpan.org>, All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. http://www.perl.com/perl/misc/Artistic.html