README

   1 NAME
   2     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
   3
   4 VERSION
   5     Version 0.03
   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 paths together :
  46
  47     *   either as a *sequence*, where each path is drawn in its own line :
  48
  49             \draw (0cm,0cm) -- (0cm,1cm) ;
  50             \draw (0cm,0cm) -- (1cm,0cm) ;
  51
  52     *   or as an *union*, where paths are all drawn as one line :
  53
  54             \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
  55
  56     This distinction is important because there are some primitives that
  57     only apply to paths but not to sequences, and vice versa.
  58
  59     Figures are made of path or sequence *sets* assembled together in a
  60     tree.
  61
  62     *Modifiers* can be applied onto any set to alter the way in which it is
  63     generated. The two TikZ concepts of *clips* and *layers* have been
  64     unified with the modifiers.
  65
  66 INTERFACE
  67   Containers
  68    "union"
  69         Tikz->union(@kids)
  70
  71     Creates a LaTeX::TikZ::Set::Union object out of the paths @kids.
  72
  73         # A path made of two circles
  74         Tikz->union(
  75                Tikz->circle(0, 1),
  76                Tikz->circle(1, 1),
  77               )
  78             ->mod(
  79                Tikz->fill('red'),
  80                'even odd rule',
  81               );
  82
  83    "path"
  84         Tikz->path(@kids)
  85
  86     A synonym for "union".
  87
  88    "join"
  89         Tikz->join($connector, @kids)
  90
  91     Creates a LaTeX::TikZ::Set::Chain object that joins the paths @kinds
  92     with the given $connector which can be, according to "connector" in
  93     LaTeX::TikZ::Set::Chain, a string, an array reference or a code
  94     reference.
  95
  96         # A stair
  97         Tikz->join('-|', map [ $_, $_ ], 0 .. 5);
  98
  99    "chain"
 100         Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn)
 101
 102     Creates a LaTeX::TikZ::Set::Chain object that chains $kid0 to $kid1 with
 103     the string $link0, $kid1 to $kid2 with $link1, and so on.
 104
 105         # An heart-like shape
 106         Tikz->chain([ 0, 1 ]
 107          => '.. controls (-1, 1.5)    and (-0.75, 0.25) ..' => [ 0, 0 ]
 108          => '.. controls (0.75, 0.25) and (1, 1.5)      ..' => [ 0, 1 ]
 109         );
 110
 111    "seq"
 112         Tikz->seq(@kids)
 113
 114     Creates a LaTeX::TikZ::Set::Sequence object out of the sequences or
 115     paths @kids.
 116
 117         my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
 118
 119   Elements
 120     Those are the building blocks of your geometrical figure.
 121
 122    "point"
 123         Tikz->point($point)
 124
 125     Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
 126     LaTeX::TikZ::Point. The following rules are available :
 127
 128     *   If $point isn't given, the point defaults to "(0, 0)".
 129
 130             my $origin = Tikz->point;
 131
 132     *   If $point is a numish Perl scalar, it is treated as "($point, 0)".
 133
 134             my $unit = Tikz->point(1);
 135
 136     *   If two numish scalars $x and $y are given, they result in the point
 137         "($x, $y)".
 138
 139             my $one_plus_i = Tikz->point(1, 1);
 140
 141     *   If $point is an array reference, it is parsed as "($point->[0],
 142         $point->[1])".
 143
 144             my $i = Tikz->point([ 0, 1 ]);
 145
 146     *   If $point is a Math::Complex object, the
 147         LaTeX::TikZ::Point::Math::Complex class is automatically loaded and
 148         the point is coerced into "($point->Re, $point->Im)".
 149
 150             my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
 151
 152     You can define automatic coercions from your user point types to
 153     LaTeX::TikZ::Point by writing your own
 154     "LaTeX::TikZ::Point::My::User::Point" class. See
 155     LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
 156     LaTeX::TikZ::Point::Math::Complex for an example.
 157
 158    "line"
 159         Tikz->line($from => $to)
 160
 161     Creates a LaTeX::TikZ::Set::Line object between the points $from and
 162     $to.
 163
 164         my $x_axis = Tikz->line(-5 => 5);
 165         my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
 166
 167    "polyline"
 168         Tikz->polyline(@points)
 169
 170     Creates a LaTeX::TikZ::Set::Polyline object that links the successive
 171     elements of @points by segments.
 172
 173         my $U = Tikz->polyline(
 174          Tikz->point(0, 1),
 175          Tikz->point(0, 0),
 176          Tikz->point(1, 0),
 177          Tikz->point(1, 1),
 178         );
 179
 180    "closed_polyline"
 181         Tikz->closed_polyline(@points)
 182
 183     Creates a LaTeX::TikZ::Set::Polyline object that cycles through
 184     successive elements of @points.
 185
 186         my $diamond = Tikz->closed_polyline(
 187          Tikz->point(0, 1),
 188          Tikz->point(-1, 0),
 189          Tikz->point(0, -2),
 190          Tikz->point(1, 0),
 191         );
 192
 193    "rectangle"
 194         Tikz->rectangle($from => $to)
 195         Tikz->rectangle($from => { width => $width, height => $height })
 196
 197     Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from
 198     and $to, or with anchor point $from and dimensions $width and $height.
 199
 200         my $square = Tikz->rectangle(
 201          Tikz->point,
 202          Tikz->point(2, 1),
 203         );
 204
 205    "circle"
 206         Tikz->circle($center, $radius)
 207
 208     Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
 209     $radius.
 210
 211         my $unit_circle = Tikz->circle(0, 1);
 212
 213    "arc"
 214         Tikz->arc($from => $to, $center)
 215
 216     Creates a LaTeX::TikZ::Set structure that represents an arc going from
 217     $from to $to with center $center.
 218
 219         # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
 220         my $quarter = Tikz->arc(
 221          [ 1, 0 ] => [ 0, 1 ],
 222          [ 0, 0 ]
 223         );
 224
 225    "arrow"
 226         Tikz->arrow($from => $to)
 227         Tikz->arrow($from => dir => $dir)
 228
 229     Creates a LaTeX::TikZ::Set structure that represents an arrow going from
 230     $from towards $to, or starting at $from in direction $dir.
 231
 232         # An horizontal arrow
 233         my $arrow = Tikz->arrow(0 => 1);
 234
 235    "raw"
 236         Tikz->raw($content)
 237
 238     Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
 239     TikZ code $content.
 240
 241   Modifiers
 242     Modifiers are applied onto sets by calling the "->mod" method, like in
 243     "$set->mod($mod)". This method returns the $set object, so it can be
 244     chained.
 245
 246    "clip"
 247         Tikz->clip($path)
 248
 249     Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
 250     sequence by the (closed) path $path.
 251
 252         my $box = Tikz->clip(
 253          Tikz->rectangle(0 => [ 1, 1 ]),
 254         );
 255
 256     Clips can also be directly applied to sets with the "->clip" method.
 257
 258         my $set = Tikz->circle(0, 1.5)
 259                       ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
 260
 261    "layer"
 262         Tikz->layer($name, above => \@above, below => \@below)
 263
 264     Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
 265     relative positions @above and @below.
 266
 267         my $layer = Tikz->layer(
 268          'top'
 269          above => [ 'main' ],
 270         );
 271
 272     The default layer is "main".
 273
 274     Layers are stored into a global hash, so that when you refer to them by
 275     their name, you get the existing layer object.
 276
 277     Layers can also be directly applied to sets with the "->layer" method.
 278
 279         my $dots = Tikz->rectangle(0 => [ 1, 1 ])
 280                        ->mod(Tikz->pattern(class => 'Dots'))
 281                        ->layer('top');
 282
 283    "scale"
 284         Tikz->scale($factor)
 285
 286     Creates a LaTeX::TikZ::Mod::Scale object that scales the sets onto which
 287     it apply by the given $factor.
 288
 289         my $circle_of_radius_2 = Tikz->circle(0 => 1)
 290                                      ->mod(Tikz->scale(2));
 291
 292    "width"
 293         Tikz->width($line_width)
 294
 295     Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
 296     $line_width when applied.
 297
 298         my $thick_arrow = Tikz->arrow(0 => 1)
 299                               ->mod(Tikz->width(5));
 300
 301    "color"
 302         Tikz->color($color)
 303
 304     Creates a LaTeX::TikZ::Mod::Color object that sets the line color to
 305     $color (given in the "xcolor" syntax).
 306
 307         # Paint the previous $thick_arrow in red.
 308         $thick_arrow->mod(Tikz->color('red'));
 309
 310    "fill"
 311         Tikz->fill($color)
 312
 313     Creates a LaTeX::TikZ::Mod::Fill object that fills the interior of a
 314     path with the solid color $color (given in the "xcolor" syntax).
 315
 316         my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
 317                           ->mod(Tikz->fill('red'));
 318
 319    "pattern"
 320         Tikz->pattern(class => $class, %args)
 321
 322     Creates a LaTeX::TikZ::Mod::Pattern object of class $class and arguments
 323     %args that fills the interior of a path with the specified pattern.
 324     $class is prepended with "LaTeX::TikZ::Mod::Pattern" when it doesn't
 325     contain "::". See LaTeX::TikZ::Mod::Pattern::Dots and
 326     LaTeX::TikZ::Mod::Pattern::Lines for two examples of pattern classes.
 327
 328         my $hatched_circle = Tikz->circle(0 => 1)
 329                                  ->mod(Tikz->pattern(class => 'Lines'));
 330
 331    "raw_mod"
 332         Tikz->raw_mod($content)
 333
 334     Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
 335     TikZ mod code $content.
 336
 337         my $homemade_arrow = Tikz->line(0 => 1)
 338                                  ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
 339
 340   Helpers
 341    "formatter"
 342         Tikz->formatter(%args)
 343
 344     Creates a LaTeX::TikZ::Formatter object that can render a
 345     LaTeX::TikZ::Set tree.
 346
 347         my $tikz = Tikz->formatter;
 348         my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
 349
 350    "functor"
 351         Tikz->functor(@rules)
 352
 353     Creates a LaTeX::TikZ::Functor anonymous subroutine that can be called
 354     against LaTeX::TikZ::Set trees to clone them according to the given
 355     rules. @rules should be a list of array references whose first element
 356     is the class/role to match against and the second the handler to
 357     execute.
 358
 359         # The default is a clone method
 360         my $clone = Tikz->functor;
 361         my $dup = $set->$clone;
 362
 363         # A translator
 364         my $translate = Tikz->functor(
 365          'LaTeX::TikZ::Set::Point' => sub {
 366           my ($functor, $set, $x, $y) = @_;
 367
 368           $set->new(
 369            point => [
 370             $set->x + $x,
 371             $set->y + $y,
 372            ],
 373            label => $set->label,
 374            pos   => $set->pos,
 375           );
 376          },
 377         );
 378         my $shifted = $set->$translate(1, 1);
 379
 380         # A mod stripper
 381         my $strip = Tikz->functor(
 382          '+LaTeX::TikZ::Mod' => sub { return },
 383         );
 384         my $naked = $set->$strip;
 385
 386 DEPENDENCIES
 387     Mouse 0.80 or greater.
 388
 389     Sub::Name.
 390
 391     Math::Complex, Math::Trig.
 392
 393     Scalar::Util, List::Util, Task::Weaken.
 394
 395 SEE ALSO
 396     PGF/TikZ - <http://pgf.sourceforge.net>.
 397
 398 AUTHOR
 399     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 400
 401     You can contact me by mail or on "irc.perl.org" (vincent).
 402
 403 BUGS
 404     Please report any bugs or feature requests to "bug-latex-tikz at
 405     rt.cpan.org", or through the web interface at
 406     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ>. I will be
 407     notified, and then you'll automatically be notified of progress on your
 408     bug as I make changes.
 409
 410 SUPPORT
 411     You can find documentation for this module with the perldoc command.
 412
 413         perldoc LaTeX::TikZ
 414
 415 COPYRIGHT & LICENSE
 416     Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights
 417     reserved.
 418
 419     This program is free software; you can redistribute it and/or modify it
 420     under the same terms as Perl itself.
 421