1 package LaTeX::TikZ::Functor;
8 LaTeX::TikZ::Functor - Build functor methods that recursively visit nodes of a LaTeX::TikZ::Set tree.
16 our $VERSION = '0.02';
20 A functor takes a L<LaTeX::TikZ::Set> tree and returns a new, transmuted version of it according to certain rules.
21 It recursively visits all the nodes of the tree, building a new set out of the result of the functor on the child sets.
23 Rules are stored as L<LaTeX::TikZ::Functor::Rule> objects.
24 They can apply not only to L<LaTeX::TikZ::Set> consumer objects, but also to the L<LaTeX::TikZ::Mod> consumer objects they contain.
25 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.
27 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 :
33 the functor object as its first argument ;
37 the current set or mod object as its second argument ;
41 the arguments passed to the functor itself starting at the third argument.
45 The handler is expected to return the new set or mod that will replace the old one in the resulting set tree.
47 If no matching rule is found, the object is returned as-is.
55 use LaTeX::TikZ::Functor::Rule;
57 use LaTeX::TikZ::Interface;
59 use LaTeX::TikZ::Tools;
61 my $lts_tc = LaTeX::TikZ::Tools::type_constraint('LaTeX::TikZ::Set');
65 $validate_spec = Sub::Name::subname('validate_spec' => sub {
68 my ($replace, $target);
69 if (defined $spec and ref $spec eq ''
70 and $spec =~ /^(\+?)([A-Za-z][A-Za-z0-9_]*(?:::[A-Za-z][A-Za-z0-9_]*)*)$/) {
71 $replace = defined($1) && $1 eq '+';
74 Carp::confess("Invalid rule spec $spec");
77 return $target, $replace;
83 =head2 C<< new rules => [ $spec1 => $handler1, $spec2 => $handler2, ... ] >>
85 Creates a new functor object that will use both the default and the user-specified rules.
86 The functor is also a code reference that expects to be called against L<LaTeX::TikZ::Set> objects.
88 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.
90 # The default is a clone method
91 my $clone = Tikz->functor;
92 my $dup = $set->$clone;
94 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.
97 my $translate = Tikz->functor(
98 # Only replace the way point sets are cloned
99 'LaTeX::TikZ::Set::Point' => sub {
100 my ($functor, $set, $x, $y) = @_;
107 label => $set->label,
112 my $shifted = $set->$translate(1, 1);
114 But if one of the C<$spec>s begins with C<'+'>, the rule will replace I<all> default rules that apply to subclasses or subroles of C<$spec> (including C<$spec> itself).
117 my $strip = Tikz->functor(
118 # Replace all existent mod rules by this simple one
119 '+LaTeX::TikZ::Mod' => sub { return },
121 my $naked = $set->$strip;
123 The functor will map unhandled sets and mods to themselves without cloning them, since it has no way to know how to do it.
124 Thus, if you define your own L<LaTeX::TikZ::Set> or L<LaTeX::TikZ::Mod> object, be sure to register a default rule for it with the L</default_rule> method.
128 my @default_set_rules;
129 my @default_mod_rules;
132 my ($class, %args) = @_;
134 my @set_rules = @default_set_rules;
135 my @mod_rules = @default_mod_rules;
137 my @user_rules = @{$args{rules} || []};
138 while (@user_rules) {
139 my ($spec, $handler) = splice @user_rules, 0, 2;
141 my ($target, $replace) = $validate_spec->($spec);
143 my $rule = LaTeX::TikZ::Functor::Rule->new(
149 into => $rule->is_set ? \@set_rules : \@mod_rules,
155 my %dispatch = map { $_->target => $_ } @set_rules, @mod_rules;
162 $lts_tc->assert_valid($set);
164 my $rule = $dispatch{ref($set)};
167 if ($_->handles($set)) {
173 return $set unless $rule;
175 my $new_set = $rule->handler->($self, $set, @_);
176 return $set if $new_set == $set;
180 for my $mod ($set->mods) {
181 my $rule = $dispatch{ref($mod)};
184 if ($_->handles($mod)) {
190 push @new_mods, $rule ? $rule->handler->($self, $mod, @_)
193 $new_set->mod(@new_mods);
199 LaTeX::TikZ::Interface->register(
203 __PACKAGE__->new(rules => \@_);
207 =head2 C<< default_rule $spec => $handler >>
209 Adds to all subsequently created functors a default rule for the class or role C<$spec>.
211 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 default rules.
212 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).
214 Returns true if and only if an existent rule was replaced.
220 my ($spec, $handler) = @_;
222 my ($target, $replace) = $validate_spec->($spec);
224 my $rule = LaTeX::TikZ::Functor::Rule->new(
230 into => $rule->is_set ? \@default_set_rules : \@default_mod_rules,
238 L<LaTeX::TikZ>, L<LaTeX::TikZ::Functor::Rule>.
242 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
244 You can contact me by mail or on C<irc.perl.org> (vincent).
248 Please report any bugs or feature requests to C<bug-latex-tikz at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ>.
249 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
253 You can find documentation for this module with the perldoc command.
257 =head1 COPYRIGHT & LICENSE
259 Copyright 2010 Vincent Pit, all rights reserved.
261 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
265 1; # End of LaTeX::TikZ::Functor