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