NAME
    LaTeX::TikZ - Perl object model for generating PGF/TikZ code.

VERSION
    Version 0.01

SYNOPSIS
        use LaTeX::TikZ;

        # A couple of lines
        my $hline = Tikz->line(-1 => 1);
        my $vline = Tikz->line([ 0, -1 ] => [ 0, -1 ]);

        # Paint them in red
        $_->mod(Tikz->color('red')) for $hline, $vline;

        # An octogon
        use Math::Complex;
        my $octo = Tikz->closed_polyline(
         map Math::Complex->emake(1, ($_ * pi)/4), 0 .. 7
        );

        # Only keep a portion of it
        $octo->clip(Tikz->rectangle(-0.5*(1+i), 2*(1+i)));

        # Fill it with dots
        $octo->mod(Tikz->pattern(class => 'Dots'));

        # Create a formatter object
        my $tikz = Tikz->formatter;

        # Put those objects all together and print them
        my $seq = Tikz->seq($octo, $hline, $vline);
        my ($head, $decl, $body) = $tikz->render($seq);
        print "$_\n" for map @$_, $head, $decl, $body;

DESCRIPTION
    This module provides an object model for TikZ, a graphical tookit for
    LaTeX. It allows you to build structures representing geometrical
    figures, apply a wide set of modifiers on them, transform them globally
    with functors, and print them in the context of an existing TeX
    document.

CONCEPTS
    Traditionnaly, in TikZ, there are two ways of grouping elements, or
    *ops*, together :

    *   either as a *sequence*, where each element is drawn in its own line
        :

            \draw (0cm,0cm) -- (0cm,1cm) ;
            \draw (0cm,0cm) -- (1cm,0cm) ;

    *   or as a *path*, where elements are all drawn as one line :

            \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;

    This distinction is important because there are some primitves that only
    apply to paths but not to sequences, and vice versa.

    Figures are made of ops, path or sequence *sets* assembled together in a
    tree.

    *Modifiers* can be applied onto any set to alter the way in which it is
    generated. The two TikZ concepts of *clips* and *layers* have been
    unified with the modifiers.

INTERFACE
  Containers
   "Tikz->path(@ops)"
    Creates a LaTeX::TikZ::Set::Path object out of the ops @ops.

        # A path made of two circles
        Tikz->path(
               Tikz->circle(0, 1),
               Tikz->circle(1, 1),
              )
            ->mod(
               Tikz->fill('red'),
               'even odd rule',
              );

   "Tikz->seq(@kids)"
    Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths
    or ops @kids.

        my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);

  Elements
    Those are the building blocks of your geometrical figure.

   "Tikz->point($point)"
    Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
    LaTeX::TikZ::Point. The following rules are available :

    *   If $point isn't given, the point defaults to "(0, 0)".

            my $origin = Tikz->point;

    *   If $point is a numish Perl scalar, it is treated as "($point, 0)".

            my $unit = Tikz->point(1);

    *   If two numish scalars $x and $y are given, they result in the point
        "($x, $y)".

            my $one_plus_i = Tikz->point(1, 1);

    *   If $point is an array reference, it is parsed as "($point->[0],
        $point->[1])".

            my $i = Tikz->point([ 0, 1 ]);

    *   If $point is a Math::Complex object, the
        LaTeX::TikZ::Point::Math::Complex class is automatically loaded and
        the point is coerced into "($point->Re, $point->Im)".

            my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));

    You can define automatic coercions from your user point types to
    LaTeX::TikZ::Point by writing your own
    LaTeX::TikZ::Point::My::User::Point class. See
    LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
    LaTeX::TikZ::Point::Math::Complex for an example.

   "Tikz->line($from => $to)"
    Creates a LaTeX::TikZ::Set::Line object between the points $from and
    $to.

        my $x_axis = Tikz->line(-5 => 5);
        my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);

   "Tikz->polyline(@points)"
    Creates a LaTeX::TikZ::Set::Polyline object that links the successive
    elements of @points by segments.

        my $U = Tikz->polyline(
         Tikz->point(0, 1),
         Tikz->point(0, 0),
         Tikz->point(1, 0),
         Tikz->point(1, 1),
        );

   "Tikz->closed_polyline(@points)"
    Creates a LaTeX::TikZ::Set::Polyline object that cycles through
    successive eleemnts of @points.

        my $diamond = Tikz->closed_polyline(
         Tikz->point(0, 1),
         Tikz->point(-1, 0),
         Tikz->point(0, -2),
         Tikz->point(1, 0),
        );

   "Tikz->rectangle($from => $to), Tikz->rectangle($from => { width => $width, height => $height })"
    Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from
    and $to, or with anchor point $from and dimensions $width and $height.

        my $square = Tikz->rectangle(
         Tikz->point,
         Tikz->point(2, 1),
        );

   "Tikz->circle($center, $radius)"
    Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
    $radius.

        my $unit_circle = Tikz->circle(0, 1);

   "Tikz->arc($from => $to, $center)"
    Creates a LaTeX::TikZ::Set structure that represents an arc going from
    $from to $to with center $center.

        # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
        my $quarter = Tikz->arc(
         [ 1, 0 ] => [ 0, 1 ],
         [ 0, 0 ]
        );

   "Tikz->arrow($from => $to), Tikz->arrow($from => dir => $dir)"
    Creates a LaTeX::TikZ::Set structure that represents an arrow going from
    $from towards $to, or starting at $from in direction $dir.

        # An horizontal arrow
        my $arrow = Tikz->arrow(0 => 1);

   "Tikz->raw($content)"
    Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
    TikZ code $content.

  Modifiers
    Modifiers are applied onto sets by calling the "->mod" method, like in
    "$set->mod($mod)". This method returns the $set object, so it can be
    chained.

   "Tikz->clip($path)"
    Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
    sequence by the (closed) path $path.

        my $box = Tikz->clip(
         Tikz->rectangle(0 => [ 1, 1 ]),
        );

    Clips can also be directly applied to sets with the "->clip" method.

        my $set = Tikz->circle(0, 1.5)
                      ->clip(Tikz->rectangle([-1, -1] => [1, 1]));

   "Tikz->layer($name, above => \@above, below => \@below)"
    Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
    relative positions @above and @below.

        my $layer = Tikz->layer(
         'top'
         above => [ 'main' ],
        );

    The default layer is "main".

    Layers are stored into a global hash, so that when you refer to them by
    their name, you get the existing layer object.

    Layers can also be directly applied to sets with the "->layer" method.

        my $dots = Tikz->rectangle(0 => [ 1, 1 ])
                       ->mod(Tikz->pattern(class => 'Dots'))
                       ->layer('top');

   "Tikz->width($line_width)"
    Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
    $line_width when applied.

        my $thick_arrow = Tikz->arrow(0 => 1)
                              ->mod(Tikz->width(5));

   "Tikz->color($color)"
    Creates a LaTeX::TikZ::Mod::Colorobject that sets the line color to
    $color (given in the "xcolor" syntax).

        # Paint the previous $thick_arrow in red.
        $thick_arrow->mod(Tikz->color('red'));

   "Tikz->fill($color)"
    Creates a LaTeX::TikZ::Mod::Fill object that fills the interior of a
    path with the solid color $color (given in the "xcolor" syntax).

        my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
                          ->mod(Tikz->fill('red'));

   "Tikz->pattern(class => $class, %args)"
    Creates a LaTeX::TikZ::Mod::Pattern object of class $class and arguments
    %args that fills the interior of a path with the specified pattern.
    $class is prepended with "LaTeX::TikZ::Mod::Pattern" when it doesn't
    contain "::". See LaTeX::TikZ::Mod::Pattern::Dots and
    LaTeX::TikZ::Mod::Pattern::Lines for two examples of pattern classes.

        my $hatched_circle = Tikz->circle(0 => 1)
                                 ->mod(Tikz->pattern(class => 'Lines'));

   "Tikz->raw_mod($content)"
    Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
    TikZ mod code $content.

        my $homemade_arrow = Tikz->line(0 => 1)
                                 ->mod(Tikz->raw_mod('->')) # or just ->mod('->')

  Helpers
   "Tikz->formatter(%args)"
    Creates a LaTeX::TikZ::Formatter object that can render a
    LaTeX::TikZ::Set tree.

        my $tikz = Tikz->formatter;
        my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);

   "Tikz->functor(@rules)"
    Creates a LaTeX::TikZ::Functor anonymous subroutine that can be called
    against LaTeX::TikZ::Set trees to clone them according to the given
    rules. @rules should be made of array references whose first element is
    the class/role to match against and the second the handler to run.

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

        # A translator
        my $translate = Tikz->functor(
         '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);

        # A mod stripper
        my $strip = Tikz->functor(
         'LaTeX::TikZ::Mod' => sub { return },
        );
        my $naked = $set->$strip;

DEPENDENCIES
    Any::Moose with Mouse 0.63 or greater.

    Sub::Name.

    Scope::Guard.

    Math::Complex, Math::Trig.

    Scalar::Util, List::Util, Task::Weaken.

SEE ALSO
    PGF/TikZ - <http://pgf.sourceforge.net>.

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

