.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TM::Tau::Filter 3pm"
.TH TM::Tau::Filter 3pm "2008-04-10" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
TM::Tau::Filter \- Topic Maps, abstract filter class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   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 (....);
.Ve
.SH "DESCRIPTION"
.IX Header "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
.PP
.Vb 1
\&   some_map.atm * some_transformation
.Ve
.PP
then \f(CW\*(C`some_transformation\*(C'\fR is applied to the map coming from the map \f(CW\*(C`some_map.atm\*(C'\fR.
This scheme can be expanded to the left:
.PP
.Vb 1
\&   some_map.atm * some_transformation1 * some_transformation2
.Ve
.PP
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
.PP
.Vb 1
\&   (some_map.atm * some_transformation1) * some_transformation2
.Ve
.PP
When you build a filter expression, then you have to respect this left-associativeness:
.PP
.Vb 3
\&   my $map    = new TM....;
\&   my $trafo1 = new TM::Tau::Filter (left => $map);
\&   my $trafo2 = new TM::Tau::Filter (left => $trafo1);
.Ve
.PP
The variable \f(CW$trafo2\fR then holds this expression, but nothing is actually computed at this
stage. To trigger this process, the method \f(CW\*(C`sync_in\*(C'\fR can be used (read: apply). It will trigger the
in-synchronisation of \f(CW$trafo1\fR and that will pass it on to the \f(CW$map\fR. 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 \f(CW$trafo1\fR will do its work. Once the result is available, \f(CW$trafo2\fR
will do its work.
.SS "Transformations"
.IX Subsection "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.
.PP
To specify \fBwhat\fR the transformation is supposed to do, you can either overload the method
\&\f(CW\*(C`sync_in\*(C'\fR, or alternatively keep it and overload only \f(CW\*(C`transform\*(C'\fR:
.PP
.Vb 3
\&   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
\&   }
.Ve
.PP
Your result will be used as content for the filter (which is a map itself, remember). See
TM::Tau::Filter::Analyze for an example.
.PP
The default transformation is the empty one, i.e. the map is simply passed through (not copied,
btw).
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Constructor"
.IX Subsection "Constructor"
The constructor of implementations should expect a hash as parameter with the following fields:
.IP "\fIleft\fR (no default):" 4
.IX Item "left (no default):"
This must be an object of class \s-1TM\s0. i.e. it can also be another filter.
.ie n .IP "\fIurl\fR (default ""null:"")" 4
.el .IP "\fIurl\fR (default \f(CWnull:\fR)" 4
.IX Item "url (default null:)"
If the \s-1URL\s0 is missing here (filters are resourced maps), then it defaults to \f(CW\*(C`null:\*(C'\fR
.SS "Methods"
.IX Subsection "Methods"
.IP "\fBleft\fR" 4
.IX Item "left"
\&\fI\f(CI$tm\fI\fR = \fI\f(CI$filter\fI\fR\->left
\&\fI\f(CI$filter\fI\fR\->left (\fI\f(CI$tm\fI\fR)
.Sp
This is an accessor (read and write) to get the left operand. In any case the left component is
returned.
.IP "\fBmtime\fR" 4
.IX Item "mtime"
\&\fI\f(CI$filter\fI\fR\->mtime
.Sp
This retrieves the last modification time of the resource on which this filter operates on.
.IP "\fBtransform\fR" 4
.IX Item "transform"
\&\fI\f(CI$tm2\fI\fR = \fI\f(CI$filter\fI\fR\->transform (\fI\f(CI$tm\fI\fR)
.Sp
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 (\fIidentity\fR transformation).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1TM\s0, TM::Tau, TM::Tau::Filter::Analyze
.SH "AUTHOR INFORMATION"
.IX Header "AUTHOR INFORMATION"
Copyright 200[4\-6], Robert Barta <drrho@cpan.org>, All rights reserved.
.PP
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