Make sure POD headings are linkable

[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 d4ba0740b96d5abd917a18a6007bc6fc06911167..ac51ccf73d2d763331a2b6693fd1bf8050395677 100644 (file)
--- a/lib/LaTeX/TikZ/Functor.pm
+++ b/lib/LaTeX/TikZ/Functor.pm
@@ -9,16 +9,42 @@ 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.
+A functor takes a L<LaTeX::TikZ::Set> tree and returns a new, transmuted version of it according to certain rules.
+It recursively visits all the nodes of the tree, building a new set out of the result of the functor on the child sets.
+
+Rules are stored as L<LaTeX::TikZ::Functor::Rule> objects.
+They can apply not only to L<LaTeX::TikZ::Set> consumer objects, but also to the L<LaTeX::TikZ::Mod> consumer objects they contain.
+When the functor is called against a set object and that the returned set is different from the original (as told by C<==>, which defaults to object identity), then the functor is also applied to all the mods of the set, and their transformed counterparts are added to the new set.
+
+When the functor is called onto a set or mod 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 or mod 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 or mod that will replace the old one in the resulting set tree.
+
+If no matching rule is found, the object is returned as-is.
 
 =cut
 
@@ -54,9 +80,13 @@ BEGIN {
 
 =head1 METHODS
 
-=head2 C<< new rules => [ $spec1 => $handler1, $spec2 => $handler2, ... ] >>
+=head2 C<new>
 
-Creates a new functor object that will use both the default and these user-specified rules.
+    my $functor = LaTeX::TikZ::Functor->new(
+     rules => [ $spec1 => $handler1, $spec2 => $handler2, ... ],
+    );
+
+Creates a new functor object that will use both the default and the user-specified rules.
 The functor is also a code reference that expects to be called against L<LaTeX::TikZ::Set> objects.
 
 The default set and mod rules clone their relevant objects, so you get a clone functor (for the default set types) if you don't specify any user rule.
@@ -65,7 +95,7 @@ The default set and mod rules clone their relevant objects, so you get a clone f
     my $clone = Tikz->functor;
     my $dup = $set->$clone;
 
-If there is already a default rule for one of the C<$spec>s, it is replaced by the new one ; otherwise, the user rule is appended to the list of default rules.
+If there is already a default rule for one of the C<$spec>s, it is replaced by the new one ; otherwise, the user rule is inserted into the list of default rules after all its descendants' rules and before all its ancestors' rules.
 
     # A translator
     my $translate = Tikz->functor(
@@ -178,11 +208,13 @@ LaTeX::TikZ::Interface->register(
  },
 );
 
-=head2 C<< default_rule $spec => $handler >>
+=head2 C<default_rule>
+
+    LaTeX::TikZ::Functor->default_rule($spec => $handler)
 
 Adds to all subsequently created functors a default rule for the class or role C<$spec>.
 
-An exception is thrown if there is already a default rule for C<$spec> ; otherwise, the new rule is appended to the current list of rules.
+An exception is thrown if there is already a default rule for C<$spec> ; otherwise, the new rule is inserted into the current list of default rules after all its descendants' rules and before all its ancestors' rules.
 But if C<$spec> begins with C<'+'>, the rule will replace I<all> default rules that apply to subclasses or subroles of C<$spec> (including C<$spec> itself).
 
 Returns true if and only if an existent rule was replaced.
@@ -209,7 +241,7 @@ sub default_rule {
 
 =head1 SEE ALSO
 
-L<LaTeX::TikZ>.
+L<LaTeX::TikZ>, L<LaTeX::TikZ::Functor::Rule>.
 
 =head1 AUTHOR
 
@@ -230,7 +262,7 @@ You can find documentation for this module with the perldoc command.
 
 =head1 COPYRIGHT & LICENSE
 
-Copyright 2010 Vincent Pit, all rights reserved.
+Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights reserved.
 
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.