bionic (3) TM::Tau::Filter.3pm.gz

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