NAME

LaTeX::TikZ::Functor - Build functor methods that recursively visit nodes of a LaTeX::TikZ::Set tree.

VERSION

Version 0.03

DESCRIPTION

A functor takes a 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 LaTeX::TikZ::Functor::Rule objects. They can apply not only to LaTeX::TikZ::Set consumer objects, but also to the 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 ==, 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 :

• the functor object as its first argument ;

• the current set or mod object as its second argument ;

• the arguments passed to the functor itself starting at the third argument.

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.

METHODS

new

    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 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.

    # The default is a clone method
    my $clone = Tikz->functor;
    my $dup = $set->$clone;

If there is already a default rule for one of the $specs, 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(
     # Only replace the way point sets are cloned
     'LaTeX::TikZ::Set::Point' => sub {
      my ($functor, $set, $x, $y) = @_;

      $set->new(
       point => [
        $set->x + $x,
        $set->y + $y,
       ],
       label => $set->label,
       pos   => $set->pos,
      );
     },
    );
    my $shifted = $set->$translate(1, 1);

But if one of the $specs begins with '+', the rule will replace all default rules that apply to subclasses or subroles of $spec (including $spec itself).

    # A mod stripper
    my $strip = Tikz->functor(
     # Replace all existent mod rules by this simple one
     '+LaTeX::TikZ::Mod' => sub { return },
    );
    my $naked = $set->$strip;

The functor will map unhandled sets and mods to themselves without cloning them, since it has no way to know how to do it. Thus, if you define your own LaTeX::TikZ::Set or LaTeX::TikZ::Mod object, be sure to register a default rule for it with the "default_rule" method.

default_rule

    LaTeX::TikZ::Functor->default_rule($spec => $handler)

Adds to all subsequently created functors a default rule for the class or role $spec.

An exception is thrown if there is already a default rule for $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 $spec begins with '+', the rule will replace all default rules that apply to subclasses or subroles of $spec (including $spec itself).

Returns true if and only if an existent rule was replaced.

SEE ALSO

LaTeX::TikZ, LaTeX::TikZ::Functor::Rule.

AUTHOR

Vincent Pit, <perl at profvince.com>, http://www.profvince.com.

You can contact me by mail or on irc.perl.org (vincent).

BUGS

Please report any bugs or feature requests to bug-latex-tikz at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc LaTeX::TikZ

COPYRIGHT & LICENSE

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.

cpanm LaTeX::TikZ

perl -MCPAN -e shell
install LaTeX::TikZ