README

   1 NAME
   2     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
   3
   4 VERSION
   5     Version 0.02
   6
   7 SYNOPSIS
   8         use LaTeX::TikZ;
   9
  10         # A couple of lines
  11         my $hline = Tikz->line(-1 => 1);
  12         my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]);
  13
  14         # Paint them in red
  15         $_->mod(Tikz->color('red')) for $hline, $vline;
  16
  17         # An octogon
  18         use Math::Complex;
  19         my $octo = Tikz->closed_polyline(
  20          map Math::Complex->emake(1, ($_ * pi)/4), 0 .. 7
  21         );
  22
  23         # Only keep a portion of it
  24         $octo->clip(Tikz->rectangle(-0.5*(1+i), 2*(1+i)));
  25
  26         # Fill it with dots
  27         $octo->mod(Tikz->pattern(class => 'Dots'));
  28
  29         # Create a formatter object
  30         my $tikz = Tikz->formatter(scale => 5);
  31
  32         # Put those objects all together and print them
  33         my $seq = Tikz->seq($octo, $hline, $vline);
  34         my ($head, $decl, $body) = $tikz->render($seq);
  35         print "$_\n" for map @$_, $head, $decl, $body;
  36
  37 DESCRIPTION
  38     This module provides an object model for TikZ, a graphical toolkit for
  39     LaTeX. It allows you to build structures representing geometrical
  40     figures, apply a wide set of modifiers on them, transform them globally
  41     with functors, and print them in the context of an existing TeX
  42     document.
  43
  44 CONCEPTS
  45     Traditionally, in TikZ, there are two ways of grouping elements, or
  46     *ops*, together :
  47
  48     *   either as a *sequence*, where each element is drawn in its own line
  49         :
  50
  51             \draw (0cm,0cm) -- (0cm,1cm) ;
  52             \draw (0cm,0cm) -- (1cm,0cm) ;
  53
  54     *   or as a *path*, where elements are all drawn as one line :
  55
  56             \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
  57
  58     This distinction is important because there are some primitives that
  59     only apply to paths but not to sequences, and vice versa.
  60
  61     Figures are made of ops, path or sequence *sets* assembled together in a
  62     tree.
  63
  64     *Modifiers* can be applied onto any set to alter the way in which it is
  65     generated. The two TikZ concepts of *clips* and *layers* have been
  66     unified with the modifiers.
  67
  68 INTERFACE
  69   Containers
  70    "Tikz->path(@ops)"
  71     Creates a LaTeX::TikZ::Set::Path object out of the ops @ops.
  72
  73         # A path made of two circles
  74         Tikz->path(
  75                Tikz->circle(0, 1),
  76                Tikz->circle(1, 1),
  77               )
  78             ->mod(
  79                Tikz->fill('red'),
  80                'even odd rule',
  81               );
  82
  83    "Tikz->seq(@kids)"
  84     Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths
  85     or ops @kids.
  86
  87         my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
  88
  89   Elements
  90     Those are the building blocks of your geometrical figure.
  91
  92    "Tikz->point($point)"
  93     Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
  94     LaTeX::TikZ::Point. The following rules are available :
  95
  96     *   If $point isn't given, the point defaults to "(0, 0)".
  97
  98             my $origin = Tikz->point;
  99
 100     *   If $point is a numish Perl scalar, it is treated as "($point, 0)".
 101
 102             my $unit = Tikz->point(1);
 103
 104     *   If two numish scalars $x and $y are given, they result in the point
 105         "($x, $y)".
 106
 107             my $one_plus_i = Tikz->point(1, 1);
 108
 109     *   If $point is an array reference, it is parsed as "($point->[0],
 110         $point->[1])".
 111
 112             my $i = Tikz->point([ 0, 1 ]);
 113
 114     *   If $point is a Math::Complex object, the
 115         LaTeX::TikZ::Point::Math::Complex class is automatically loaded and
 116         the point is coerced into "($point->Re, $point->Im)".
 117
 118             my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
 119
 120     You can define automatic coercions from your user point types to
 121     LaTeX::TikZ::Point by writing your own
 122     "LaTeX::TikZ::Point::My::User::Point" class. See
 123     LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
 124     LaTeX::TikZ::Point::Math::Complex for an example.
 125
 126    "Tikz->line($from => $to)"
 127     Creates a LaTeX::TikZ::Set::Line object between the points $from and
 128     $to.
 129
 130         my $x_axis = Tikz->line(-5 => 5);
 131         my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
 132
 133    "Tikz->polyline(@points)"
 134     Creates a LaTeX::TikZ::Set::Polyline object that links the successive
 135     elements of @points by segments.
 136
 137         my $U = Tikz->polyline(
 138          Tikz->point(0, 1),
 139          Tikz->point(0, 0),
 140          Tikz->point(1, 0),
 141          Tikz->point(1, 1),
 142         );
 143
 144    "Tikz->closed_polyline(@points)"
 145     Creates a LaTeX::TikZ::Set::Polyline object that cycles through
 146     successive elements of @points.
 147
 148         my $diamond = Tikz->closed_polyline(
 149          Tikz->point(0, 1),
 150          Tikz->point(-1, 0),
 151          Tikz->point(0, -2),
 152          Tikz->point(1, 0),
 153         );
 154
 155    "Tikz->rectangle($from => $to), Tikz->rectangle($from => { width => $width, height => $height })"
 156     Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from
 157     and $to, or with anchor point $from and dimensions $width and $height.
 158
 159         my $square = Tikz->rectangle(
 160          Tikz->point,
 161          Tikz->point(2, 1),
 162         );
 163
 164    "Tikz->circle($center, $radius)"
 165     Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
 166     $radius.
 167
 168         my $unit_circle = Tikz->circle(0, 1);
 169
 170    "Tikz->arc($from => $to, $center)"
 171     Creates a LaTeX::TikZ::Set structure that represents an arc going from
 172     $from to $to with center $center.
 173
 174         # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
 175         my $quarter = Tikz->arc(
 176          [ 1, 0 ] => [ 0, 1 ],
 177          [ 0, 0 ]
 178         );
 179
 180    "Tikz->arrow($from => $to), Tikz->arrow($from => dir => $dir)"
 181     Creates a LaTeX::TikZ::Set structure that represents an arrow going from
 182     $from towards $to, or starting at $from in direction $dir.
 183
 184         # An horizontal arrow
 185         my $arrow = Tikz->arrow(0 => 1);
 186
 187    "Tikz->raw($content)"
 188     Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
 189     TikZ code $content.
 190
 191   Modifiers
 192     Modifiers are applied onto sets by calling the "->mod" method, like in
 193     "$set->mod($mod)". This method returns the $set object, so it can be
 194     chained.
 195
 196    "Tikz->clip($path)"
 197     Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
 198     sequence by the (closed) path $path.
 199
 200         my $box = Tikz->clip(
 201          Tikz->rectangle(0 => [ 1, 1 ]),
 202         );
 203
 204     Clips can also be directly applied to sets with the "->clip" method.
 205
 206         my $set = Tikz->circle(0, 1.5)
 207                       ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
 208
 209    "Tikz->layer($name, above => \@above, below => \@below)"
 210     Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
 211     relative positions @above and @below.
 212
 213         my $layer = Tikz->layer(
 214          'top'
 215          above => [ 'main' ],
 216         );
 217
 218     The default layer is "main".
 219
 220     Layers are stored into a global hash, so that when you refer to them by
 221     their name, you get the existing layer object.
 222
 223     Layers can also be directly applied to sets with the "->layer" method.
 224
 225         my $dots = Tikz->rectangle(0 => [ 1, 1 ])
 226                        ->mod(Tikz->pattern(class => 'Dots'))
 227                        ->layer('top');
 228
 229    "Tikz->width($line_width)"
 230     Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
 231     $line_width when applied.
 232
 233         my $thick_arrow = Tikz->arrow(0 => 1)
 234                               ->mod(Tikz->width(5));
 235
 236    "Tikz->color($color)"
 237     Creates a LaTeX::TikZ::Mod::Colorobject that sets the line color to
 238     $color (given in the "xcolor" syntax).
 239
 240         # Paint the previous $thick_arrow in red.
 241         $thick_arrow->mod(Tikz->color('red'));
 242
 243    "Tikz->fill($color)"
 244     Creates a LaTeX::TikZ::Mod::Fill object that fills the interior of a
 245     path with the solid color $color (given in the "xcolor" syntax).
 246
 247         my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
 248                           ->mod(Tikz->fill('red'));
 249
 250    "Tikz->pattern(class => $class, %args)"
 251     Creates a LaTeX::TikZ::Mod::Pattern object of class $class and arguments
 252     %args that fills the interior of a path with the specified pattern.
 253     $class is prepended with "LaTeX::TikZ::Mod::Pattern" when it doesn't
 254     contain "::". See LaTeX::TikZ::Mod::Pattern::Dots and
 255     LaTeX::TikZ::Mod::Pattern::Lines for two examples of pattern classes.
 256
 257         my $hatched_circle = Tikz->circle(0 => 1)
 258                                  ->mod(Tikz->pattern(class => 'Lines'));
 259
 260    "Tikz->raw_mod($content)"
 261     Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
 262     TikZ mod code $content.
 263
 264         my $homemade_arrow = Tikz->line(0 => 1)
 265                                  ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
 266
 267   Helpers
 268    "Tikz->formatter(%args)"
 269     Creates a LaTeX::TikZ::Formatter object that can render a
 270     LaTeX::TikZ::Set tree.
 271
 272         my $tikz = Tikz->formatter;
 273         my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
 274
 275    "Tikz->functor(@rules)"
 276     Creates a LaTeX::TikZ::Functor anonymous subroutine that can be called
 277     against LaTeX::TikZ::Set trees to clone them according to the given
 278     rules. @rules should be a list of array references whose first element
 279     is the class/role to match against and the second the handler to
 280     execute.
 281
 282         # The default is a clone method
 283         my $clone = Tikz->functor;
 284         my $dup = $set->$clone;
 285
 286         # A translator
 287         my $translate = Tikz->functor(
 288          'LaTeX::TikZ::Set::Point' => sub {
 289           my ($functor, $set, $x, $y) = @_;
 290
 291           $set->new(
 292            point => [
 293             $set->x + $x,
 294             $set->y + $y,
 295            ],
 296            label => $set->label,
 297            pos   => $set->pos,
 298           );
 299          },
 300         );
 301         my $shifted = $set->$translate(1, 1);
 302
 303         # A mod stripper
 304         my $strip = Tikz->functor(
 305          '+LaTeX::TikZ::Mod' => sub { return },
 306         );
 307         my $naked = $set->$strip;
 308
 309 DEPENDENCIES
 310     Any::Moose with Mouse 0.63 or greater.
 311
 312     Sub::Name.
 313
 314     Scope::Guard.
 315
 316     Math::Complex, Math::Trig.
 317
 318     Scalar::Util, List::Util, Task::Weaken.
 319
 320 SEE ALSO
 321     PGF/TikZ - <http://pgf.sourceforge.net>.
 322
 323 AUTHOR
 324     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 325
 326     You can contact me by mail or on "irc.perl.org" (vincent).
 327
 328 BUGS
 329     Please report any bugs or feature requests to "bug-latex-tikz at
 330     rt.cpan.org", or through the web interface at
 331     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ>. I will be
 332     notified, and then you'll automatically be notified of progress on your
 333     bug as I make changes.
 334
 335 SUPPORT
 336     You can find documentation for this module with the perldoc command.
 337
 338         perldoc LaTeX::TikZ
 339
 340 COPYRIGHT & LICENSE
 341     Copyright 2010 Vincent Pit, all rights reserved.
 342
 343     This program is free software; you can redistribute it and/or modify it
 344     under the same terms as Perl itself.
 345