This is 0.02

[perl/modules/LaTeX-TikZ.git] / lib / LaTeX / TikZ / Functor.pm

diff --git a/lib/LaTeX/TikZ/Functor.pm b/lib/LaTeX/TikZ/Functor.pm
index efa66a095283d48de76a5c120eded45e40946d40..4aa811211b1d8d7fe94d5827b9b7894263a2d26b 100644 (file)
--- a/lib/LaTeX/TikZ/Functor.pm
+++ b/lib/LaTeX/TikZ/Functor.pm
@@ -9,16 +9,41 @@ LaTeX::TikZ::Functor - Build functor methods that recursively visit nodes of a L
 
 =head1 VERSION
 
-Version 0.01
+Version 0.02
 
 =cut
 
-our $VERSION = '0.01';
+our $VERSION = '0.02';
 
 =head1 DESCRIPTION
 
 A functor takes a L<LaTeX::TikZ::Set> tree and clones it according to certain rules.
-Rules can apply not only to L<LaTeX::TikZ::Set> objects, but also to the L<LaTeX::TikZ::Mod> objects they contain.
+
+Rules can apply not only to L<LaTeX::TikZ::Set> consumer objects, but also to the L<LaTeX::TikZ::Mod> consumer objects they contain.
+The are stored as L<LaTeX::TikZ::Functor::Rule> objects.
+
+When the functor is called onto a set object, all its associated rules are tried successively, and the handler of the first matching rule is executed with :
+
+=over 4
+
+=item *
+
+the functor object as its first argument ;
+
+=item *
+
+the current set object as its second argument ;
+
+=item *
+
+the arguments passed to the functor itself starting at the third argument.
+
+=back
+
+The handler is expected to return the new set/mod that will in the resulting set tree.
+If the new set is different from the original, then the functor is applied to all the mods of the set, and their cloned version are added to the new set.
+
+If no matching rule is found, the object is returned as-is.
 
 =cut
 
@@ -144,9 +169,10 @@ sub new {
     }
    }
   }
-  my $new_set = $rule ? $rule->handler->($self, $set, @_)
-                      : $set;
-  my $is_new  = $new_set ne $set;
+  return $set unless $rule;
+
+  my $new_set = $rule->handler->($self, $set, @_);
+  return $set if $new_set == $set;
 
   my @new_mods;
 MOD:
@@ -163,8 +189,7 @@ MOD:
    push @new_mods, $rule ? $rule->handler->($self, $mod, @_)
                          : $mod;
   }
-
-  $new_set->mod(@new_mods) if $is_new;
+  $new_set->mod(@new_mods);
 
   return $new_set;
  }, $class;
@@ -209,7 +234,7 @@ sub default_rule {
 
 =head1 SEE ALSO
 
-L<LaTeX::TikZ>.
+L<LaTeX::TikZ>, L<LaTeX::TikZ::Functor::Rule>.
 
 =head1 AUTHOR