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 elements, or
48 * either as a *sequence*, where each element is drawn in its own line
51 \draw (0cm,0cm) -- (0cm,1cm) ;
52 \draw (0cm,0cm) -- (1cm,0cm) ;
54 * or as a *path*, where elements are all drawn as one line :
56 \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
58 This distinction is important because there are some primitives that
59 only apply to paths but not to sequences, and vice versa.
61 Figures are made of ops, path or sequence *sets* assembled together in a
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.
71 Creates a LaTeX::TikZ::Set::Path object out of the ops @ops.
73 # A path made of two circles
84 Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths
87 my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
90 Those are the building blocks of your geometrical figure.
93 Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
94 LaTeX::TikZ::Point. The following rules are available :
96 * If $point isn't given, the point defaults to "(0, 0)".
98 my $origin = Tikz->point;
100 * If $point is a numish Perl scalar, it is treated as "($point, 0)".
102 my $unit = Tikz->point(1);
104 * If two numish scalars $x and $y are given, they result in the point
107 my $one_plus_i = Tikz->point(1, 1);
109 * If $point is an array reference, it is parsed as "($point->[0],
112 my $i = Tikz->point([ 0, 1 ]);
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)".
118 my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
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.
126 "Tikz->line($from => $to)"
127 Creates a LaTeX::TikZ::Set::Line object between the points $from and
130 my $x_axis = Tikz->line(-5 => 5);
131 my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
133 "Tikz->polyline(@points)"
134 Creates a LaTeX::TikZ::Set::Polyline object that links the successive
135 elements of @points by segments.
137 my $U = Tikz->polyline(
144 "Tikz->closed_polyline(@points)"
145 Creates a LaTeX::TikZ::Set::Polyline object that cycles through
146 successive elements of @points.
148 my $diamond = Tikz->closed_polyline(
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.
159 my $square = Tikz->rectangle(
164 "Tikz->circle($center, $radius)"
165 Creates a LaTeX::TikZ::Set::Circle object of center $center and radius
168 my $unit_circle = Tikz->circle(0, 1);
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.
174 # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
175 my $quarter = Tikz->arc(
176 [ 1, 0 ] => [ 0, 1 ],
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.
184 # An horizontal arrow
185 my $arrow = Tikz->arrow(0 => 1);
187 "Tikz->raw($content)"
188 Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
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
197 Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
198 sequence by the (closed) path $path.
200 my $box = Tikz->clip(
201 Tikz->rectangle(0 => [ 1, 1 ]),
204 Clips can also be directly applied to sets with the "->clip" method.
206 my $set = Tikz->circle(0, 1.5)
207 ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
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.
213 my $layer = Tikz->layer(
218 The default layer is "main".
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.
223 Layers can also be directly applied to sets with the "->layer" method.
225 my $dots = Tikz->rectangle(0 => [ 1, 1 ])
226 ->mod(Tikz->pattern(class => 'Dots'))
229 "Tikz->width($line_width)"
230 Creates a LaTeX::TikZ::Mod::Width object that sets the line width to
231 $line_width when applied.
233 my $thick_arrow = Tikz->arrow(0 => 1)
234 ->mod(Tikz->width(5));
236 "Tikz->color($color)"
237 Creates a LaTeX::TikZ::Mod::Colorobject that sets the line color to
238 $color (given in the "xcolor" syntax).
240 # Paint the previous $thick_arrow in red.
241 $thick_arrow->mod(Tikz->color('red'));
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).
247 my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
248 ->mod(Tikz->fill('red'));
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.
257 my $hatched_circle = Tikz->circle(0 => 1)
258 ->mod(Tikz->pattern(class => 'Lines'));
260 "Tikz->raw_mod($content)"
261 Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
262 TikZ mod code $content.
264 my $homemade_arrow = Tikz->line(0 => 1)
265 ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
268 "Tikz->formatter(%args)"
269 Creates a LaTeX::TikZ::Formatter object that can render a
270 LaTeX::TikZ::Set tree.
272 my $tikz = Tikz->formatter;
273 my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
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
282 # The default is a clone method
283 my $clone = Tikz->functor;
284 my $dup = $set->$clone;
287 my $translate = Tikz->functor(
288 'LaTeX::TikZ::Set::Point' => sub {
289 my ($functor, $set, $x, $y) = @_;
296 label => $set->label,
301 my $shifted = $set->$translate(1, 1);
304 my $strip = Tikz->functor(
305 '+LaTeX::TikZ::Mod' => sub { return },
307 my $naked = $set->$strip;
310 Any::Moose with Mouse 0.63 or greater.
316 Math::Complex, Math::Trig.
318 Scalar::Util, List::Util, Task::Weaken.
321 PGF/TikZ - <http://pgf.sourceforge.net>.
324 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
326 You can contact me by mail or on "irc.perl.org" (vincent).
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.
336 You can find documentation for this module with the perldoc command.
341 Copyright 2010 Vincent Pit, all rights reserved.
343 This program is free software; you can redistribute it and/or modify it
344 under the same terms as Perl itself.