README

   1 NAME
   2     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
   3
   4 VERSION
   5     Version 0.01
   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;
  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 tookit 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     Traditionnaly, 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 primitves that only
  59     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 eleemnts 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 made of array references whose first element is
 279     the class/role to match against and the second the handler to run.
 280
 281         # The default is a clone method
 282         my $clone = Tikz->functor;
 283         my $dup = $set->$clone;
 284
 285         # A translator
 286         my $translate = Tikz->functor(
 287          'LaTeX::TikZ::Set::Point' => sub {
 288           my ($functor, $set, $x, $y) = @_;
 289
 290           $set->new(
 291            point => [
 292             $set->x + $x,
 293             $set->y + $y,
 294            ],
 295            label => $set->label,
 296            pos   => $set->pos,
 297           );
 298          },
 299         );
 300         my $shifted = $set->$translate(1, 1);
 301
 302         # A mod stripper
 303         my $strip = Tikz->functor(
 304          'LaTeX::TikZ::Mod' => sub { return },
 305         );
 306         my $naked = $set->$strip;
 307
 308 DEPENDENCIES
 309     Any::Moose with Mouse 0.63 or greater.
 310
 311     Sub::Name.
 312
 313     Scope::Guard.
 314
 315     Math::Complex, Math::Trig.
 316
 317     Scalar::Util, List::Util, Task::Weaken.
 318
 319 SEE ALSO
 320     PGF/TikZ - <http://pgf.sourceforge.net>.
 321
 322 AUTHOR
 323     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 324
 325     You can contact me by mail or on "irc.perl.org" (vincent).
 326
 327 BUGS
 328     Please report any bugs or feature requests to "bug-latex-tikz at
 329     rt.cpan.org", or through the web interface at
 330     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ>. I will be
 331     notified, and then you'll automatically be notified of progress on your
 332     bug as I make changes.
 333
 334 SUPPORT
 335     You can find documentation for this module with the perldoc command.
 336
 337         perldoc LaTeX::TikZ
 338
 339 COPYRIGHT & LICENSE
 340     Copyright 2010 Vincent Pit, all rights reserved.
 341
 342     This program is free software; you can redistribute it and/or modify it
 343     under the same terms as Perl itself.
 344