2 LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
11 my $hline = Tikz->line(-1 => 1);
12 my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]);
15 $_->mod(Tikz->color('red')) for $hline, $vline;
19 my $octo = Tikz->closed_polyline(
20 map Math::Complex->emake(1, ($_ * pi)/4), 0 .. 7
23 # Only keep a portion of it
24 $octo->clip(Tikz->rectangle(-0.5*(1+i), 2*(1+i)));
27 $octo->mod(Tikz->pattern(class => 'Dots'));
29 # Create a formatter object
30 my $tikz = Tikz->formatter(scale => 5);
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;
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
45 Traditionally, in TikZ, there are two ways of grouping paths together :
47 * either as a *sequence*, where each path is drawn in its own line :
49 \draw (0cm,0cm) -- (0cm,1cm) ;
50 \draw (0cm,0cm) -- (1cm,0cm) ;
52 * or as an *union*, where paths are all drawn as one line :
54 \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
56 This distinction is important because there are some primitives that
57 only apply to paths but not to sequences, and vice versa.
59 Figures are made of path or sequence *sets* assembled together in a
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.
71 Creates a LaTeX::TikZ::Set::Union object out of the paths @kids.
73 # A path made of two circles
86 A synonym for "union".
89 Tikz->join($connector, @kids)
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
97 Tikz->join('-|', map [ $_, $_ ], 0 .. 5);
100 Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn)
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.
105 # An heart-like shape
107 => '.. controls (-1, 1.5) and (-0.75, 0.25) ..' => [ 0, 0 ]
108 => '.. controls (0.75, 0.25) and (1, 1.5) ..' => [ 0, 1 ]
114 Creates a LaTeX::TikZ::Set::Sequence object out of the sequences or
117 my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
120 Those are the building blocks of your geometrical figure.
125 Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
126 LaTeX::TikZ::Point. The following rules are available :
128 * If $point isn't given, the point defaults to "(0, 0)".
130 my $origin = Tikz->point;
132 * If $point is a numish Perl scalar, it is treated as "($point, 0)".
134 my $unit = Tikz->point(1);
136 * If two numish scalars $x and $y are given, they result in the point
139 my $one_plus_i = Tikz->point(1, 1);
141 * If $point is an array reference, it is parsed as "($point->[0],
144 my $i = Tikz->point([ 0, 1 ]);
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)".
150 my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
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.
159 Tikz->line($from => $to)
161 Creates a LaTeX::TikZ::Set::Line object between the points $from and
164 my $x_axis = Tikz->line(-5 => 5);
165 my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
168 Tikz->polyline(@points)
170 Creates a LaTeX::TikZ::Set::Polyline object that links the successive
171 elements of @points by segments.
173 my $U = Tikz->polyline(
181 Tikz->closed_polyline(@points)
183 Creates a LaTeX::TikZ::Set::Polyline object that cycles through
184 successive elements of @points.
186 my $diamond = Tikz->closed_polyline(
194 Tikz->rectangle($from => $to)
195 Tikz->rectangle($from => { width => $width, height => $height })
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.
200 my $square = Tikz->rectangle(
206 Tikz->circle($center, $radius)
208 Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
211 my $unit_circle = Tikz->circle(0, 1);
214 Tikz->arc($from => $to, $center)
216 Creates a LaTeX::TikZ::Set structure that represents an arc going from
217 $from to $to with center $center.
219 # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
220 my $quarter = Tikz->arc(
221 [ 1, 0 ] => [ 0, 1 ],
226 Tikz->arrow($from => $to)
227 Tikz->arrow($from => dir => $dir)
229 Creates a LaTeX::TikZ::Set structure that represents an arrow going from
230 $from towards $to, or starting at $from in direction $dir.
232 # An horizontal arrow
233 my $arrow = Tikz->arrow(0 => 1);
238 Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
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
249 Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
250 sequence by the (closed) path $path.
252 my $box = Tikz->clip(
253 Tikz->rectangle(0 => [ 1, 1 ]),
256 Clips can also be directly applied to sets with the "->clip" method.
258 my $set = Tikz->circle(0, 1.5)
259 ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
262 Tikz->layer($name, above => \@above, below => \@below)
264 Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
265 relative positions @above and @below.
267 my $layer = Tikz->layer(
272 The default layer is "main".
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.
277 Layers can also be directly applied to sets with the "->layer" method.
279 my $dots = Tikz->rectangle(0 => [ 1, 1 ])
280 ->mod(Tikz->pattern(class => 'Dots'))
286 Creates a LaTeX::TikZ::Mod::Scale object that scales the sets onto which
287 it apply by the given $factor.
289 my $circle_of_radius_2 = Tikz->circle(0 => 1)
290 ->mod(Tikz->scale(2));
293 Tikz->width($line_width)
295 Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
296 $line_width when applied.
298 my $thick_arrow = Tikz->arrow(0 => 1)
299 ->mod(Tikz->width(5));
304 Creates a LaTeX::TikZ::Mod::Color object that sets the line color to
305 $color (given in the "xcolor" syntax).
307 # Paint the previous $thick_arrow in red.
308 $thick_arrow->mod(Tikz->color('red'));
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).
316 my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
317 ->mod(Tikz->fill('red'));
320 Tikz->pattern(class => $class, %args)
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.
328 my $hatched_circle = Tikz->circle(0 => 1)
329 ->mod(Tikz->pattern(class => 'Lines'));
332 Tikz->raw_mod($content)
334 Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
335 TikZ mod code $content.
337 my $homemade_arrow = Tikz->line(0 => 1)
338 ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
342 Tikz->formatter(%args)
344 Creates a LaTeX::TikZ::Formatter object that can render a
345 LaTeX::TikZ::Set tree.
347 my $tikz = Tikz->formatter;
348 my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
351 Tikz->functor(@rules)
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
359 # The default is a clone method
360 my $clone = Tikz->functor;
361 my $dup = $set->$clone;
364 my $translate = Tikz->functor(
365 'LaTeX::TikZ::Set::Point' => sub {
366 my ($functor, $set, $x, $y) = @_;
373 label => $set->label,
378 my $shifted = $set->$translate(1, 1);
381 my $strip = Tikz->functor(
382 '+LaTeX::TikZ::Mod' => sub { return },
384 my $naked = $set->$strip;
387 Mouse 0.80 or greater.
391 Math::Complex, Math::Trig.
393 Scalar::Util, List::Util, Task::Weaken.
396 PGF/TikZ - <http://pgf.sourceforge.net>.
399 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
401 You can contact me by mail or on "irc.perl.org" (vincent).
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.
411 You can find documentation for this module with the perldoc command.
416 Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights
419 This program is free software; you can redistribute it and/or modify it
420 under the same terms as Perl itself.