8 LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
16 our $VERSION = '0.02';
23 my $hline = Tikz->line(-1 => 1);
24 my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]);
27 $_->mod(Tikz->color('red')) for $hline, $vline;
31 my $octo = Tikz->closed_polyline(
32 map Math::Complex->emake(1, ($_ * pi)/4), 0 .. 7
35 # Only keep a portion of it
36 $octo->clip(Tikz->rectangle(-0.5*(1+i), 2*(1+i)));
39 $octo->mod(Tikz->pattern(class => 'Dots'));
41 # Create a formatter object
42 my $tikz = Tikz->formatter(scale => 5);
44 # Put those objects all together and print them
45 my $seq = Tikz->seq($octo, $hline, $vline);
46 my ($head, $decl, $body) = $tikz->render($seq);
47 print "$_\n" for map @$_, $head, $decl, $body;
51 This module provides an object model for TikZ, a graphical toolkit for LaTeX.
52 It allows you to build structures representing geometrical figures, apply a wide set of modifiers on them, transform them globally with functors, and print them in the context of an existing TeX document.
56 Traditionally, in TikZ, there are two ways of grouping paths together :
62 either as a I<sequence>, where each path is drawn in its own line :
64 \draw (0cm,0cm) -- (0cm,1cm) ;
65 \draw (0cm,0cm) -- (1cm,0cm) ;
69 or as an I<union>, where paths are all drawn as one line :
71 \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
75 This distinction is important because there are some primitives that only apply to paths but not to sequences, and vice versa.
77 Figures are made of path or sequence I<sets> assembled together in a tree.
79 I<Modifiers> can be applied onto any set to alter the way in which it is generated.
80 The two TikZ concepts of I<clips> and I<layers> have been unified with the modifiers.
90 Creates a L<LaTeX::TikZ::Set::Union> object out of the paths C<@kids>.
92 # A path made of two circles
104 Tikz->join($connector, @kids)
106 Creates a L<LaTeX::TikZ::Set::Chain> object that joins the paths C<@kinds> with the given C<$connector> which can be, according to L<LaTeX::TikZ::Set::Chain/connector>, a string, an array reference or a code reference.
109 Tikz->join('-|', map [ $_, $_ ], 0 .. 5);
113 Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn)
115 Creates a L<LaTeX::TikZ::Set::Chain> object that chains C<$kid0> to C<$kid1> with the string C<$link0>, C<$kid1> to C<$kid2> with C<$link1>, and so on.
117 # An heart-like shape
119 => '.. controls (-1, 1.5) and (-0.75, 0.25) ..' => [ 0, 0 ]
120 => '.. controls (0.75, 0.25) and (1, 1.5) ..' => [ 0, 1 ]
127 Creates a L<LaTeX::TikZ::Set::Sequence> object out of the sequences or paths C<@kids>.
129 my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
133 Those are the building blocks of your geometrical figure.
139 Creates a L<LaTeX::TikZ::Set::Point> object by coercing C<$point> into a L<LaTeX::TikZ::Point>.
140 The following rules are available :
146 If C<$point> isn't given, the point defaults to C<(0, 0)>.
148 my $origin = Tikz->point;
152 If C<$point> is a numish Perl scalar, it is treated as C<($point, 0)>.
154 my $unit = Tikz->point(1);
158 If two numish scalars C<$x> and C<$y> are given, they result in the point C<($x, $y)>.
160 my $one_plus_i = Tikz->point(1, 1);
164 If C<$point> is an array reference, it is parsed as C<< ($point->[0], $point->[1]) >>.
166 my $i = Tikz->point([ 0, 1 ]);
170 If C<$point> is a L<Math::Complex> object, the L<LaTeX::TikZ::Point::Math::Complex> class is automatically loaded and the point is coerced into C<< ($point->Re, $point->Im) >>.
172 my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
176 You can define automatic coercions from your user point types to L<LaTeX::TikZ::Point> by writing your own C<LaTeX::TikZ::Point::My::User::Point> class.
177 See L<LaTeX::TikZ::Meta::TypeConstraint::Autocoerce> for the rationale and L<LaTeX::TikZ::Point::Math::Complex> for an example.
181 Tikz->line($from => $to)
183 Creates a L<LaTeX::TikZ::Set::Line> object between the points C<$from> and C<$to>.
185 my $x_axis = Tikz->line(-5 => 5);
186 my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
190 Tikz->polyline(@points)
192 Creates a L<LaTeX::TikZ::Set::Polyline> object that links the successive elements of C<@points> by segments.
194 my $U = Tikz->polyline(
201 =head3 C<closed_polyline>
203 Tikz->closed_polyline(@points)
205 Creates a L<LaTeX::TikZ::Set::Polyline> object that cycles through successive elements of C<@points>.
207 my $diamond = Tikz->closed_polyline(
216 Tikz->rectangle($from => $to)
217 Tikz->rectangle($from => { width => $width, height => $height })
219 Creates a L<LaTeX::TikZ::Set::Rectangle> object with opposite corners C<$from> and C<$to>, or with anchor point C<$from> and dimensions C<$width> and C<$height>.
221 my $square = Tikz->rectangle(
228 Tikz->circle($center, $radius)
230 Creates a L<LaTeX::TikZ::Set::Circle> object of center C<$center> and radius C<$radius>.
232 my $unit_circle = Tikz->circle(0, 1);
236 Tikz->arc($from => $to, $center)
238 Creates a L<LaTeX::TikZ::Set> structure that represents an arc going from C<$from> to C<$to> with center C<$center>.
240 # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
241 my $quarter = Tikz->arc(
242 [ 1, 0 ] => [ 0, 1 ],
248 Tikz->arrow($from => $to)
249 Tikz->arrow($from => dir => $dir)
251 Creates a L<LaTeX::TikZ::Set> structure that represents an arrow going from C<$from> towards C<$to>, or starting at C<$from> in direction C<$dir>.
253 # An horizontal arrow
254 my $arrow = Tikz->arrow(0 => 1);
260 Creates a L<LaTeX::TikZ::Set::Raw> object that will instantiate to the raw TikZ code C<$content>.
264 Modifiers are applied onto sets by calling the C<< ->mod >> method, like in C<< $set->mod($mod) >>.
265 This method returns the C<$set> object, so it can be chained.
271 Creates a L<LaTeX::TikZ::Mod::Clip> object that can be used to clip a given sequence by the (closed) path C<$path>.
273 my $box = Tikz->clip(
274 Tikz->rectangle(0 => [ 1, 1 ]),
277 Clips can also be directly applied to sets with the C<< ->clip >> method.
279 my $set = Tikz->circle(0, 1.5)
280 ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
284 Tikz->layer($name, above => \@above, below => \@below)
286 Creates a L<LaTeX::TikZ::Mod::Layer> object with name C<$name> and optional relative positions C<@above> and C<@below>.
288 my $layer = Tikz->layer(
293 The default layer is C<main>.
295 Layers are stored into a global hash, so that when you refer to them by their name, you get the existing layer object.
297 Layers can also be directly applied to sets with the C<< ->layer >> method.
299 my $dots = Tikz->rectangle(0 => [ 1, 1 ])
300 ->mod(Tikz->pattern(class => 'Dots'))
307 Creates a L<LaTeX::TikZ::Mod::Scale> object that scales the sets onto which it apply by the given C<$factor>.
309 my $circle_of_radius_2 = Tikz->circle(0 => 1)
310 ->mod(Tikz->scale(2));
314 Tikz->width($line_width)
316 Creates a L<LaTeX::TikZ::Mod::Width> object that sets the line width to C<$line_width> when applied.
318 my $thick_arrow = Tikz->arrow(0 => 1)
319 ->mod(Tikz->width(5));
325 Creates a L<LaTeX::TikZ::Mod::Color> object that sets the line color to C<$color> (given in the C<xcolor> syntax).
327 # Paint the previous $thick_arrow in red.
328 $thick_arrow->mod(Tikz->color('red'));
334 Creates a L<LaTeX::TikZ::Mod::Fill> object that fills the interior of a path with the solid color C<$color> (given in the C<xcolor> syntax).
336 my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
337 ->mod(Tikz->fill('red'));
341 Tikz->pattern(class => $class, %args)
343 Creates a L<LaTeX::TikZ::Mod::Pattern> object of class C<$class> and arguments C<%args> that fills the interior of a path with the specified pattern.
344 C<$class> is prepended with C<LaTeX::TikZ::Mod::Pattern> when it doesn't contain C<::>.
345 See L<LaTeX::TikZ::Mod::Pattern::Dots> and L<LaTeX::TikZ::Mod::Pattern::Lines> for two examples of pattern classes.
347 my $hatched_circle = Tikz->circle(0 => 1)
348 ->mod(Tikz->pattern(class => 'Lines'));
352 Tikz->raw_mod($content)
354 Creates a L<LaTeX::TikZ::Mod::Raw> object that will instantiate to the raw TikZ mod code C<$content>.
356 my $homemade_arrow = Tikz->line(0 => 1)
357 ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
363 Tikz->formatter(%args)
365 Creates a L<LaTeX::TikZ::Formatter> object that can render a L<LaTeX::TikZ::Set> tree.
367 my $tikz = Tikz->formatter;
368 my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
372 Tikz->functor(@rules)
374 Creates a L<LaTeX::TikZ::Functor> anonymous subroutine that can be called against L<LaTeX::TikZ::Set> trees to clone them according to the given rules.
375 C<@rules> should be a list of array references whose first element is the class/role to match against and the second the handler to execute.
377 # The default is a clone method
378 my $clone = Tikz->functor;
379 my $dup = $set->$clone;
382 my $translate = Tikz->functor(
383 'LaTeX::TikZ::Set::Point' => sub {
384 my ($functor, $set, $x, $y) = @_;
391 label => $set->label,
396 my $shifted = $set->$translate(1, 1);
399 my $strip = Tikz->functor(
400 '+LaTeX::TikZ::Mod' => sub { return },
402 my $naked = $set->$strip;
406 use LaTeX::TikZ::Interface;
412 my $name = $args{as};
413 $name = 'Tikz' unless defined $name;
414 unless ($name =~ /^[a-z_][a-z0-9_]*$/i) {
416 Carp::confess('Invalid name');
420 my $const = sub () { 'LaTeX::TikZ::Interface' };
423 *{$pkg . '::' . $name} = $const;
426 LaTeX::TikZ::Interface->load;
433 L<Mouse> 0.80 or greater.
437 L<Math::Complex>, L<Math::Trig>.
439 L<Scalar::Util>, L<List::Util>, L<Task::Weaken>.
443 PGF/TikZ - L<http://pgf.sourceforge.net>.
447 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
449 You can contact me by mail or on C<irc.perl.org> (vincent).
453 Please report any bugs or feature requests to C<bug-latex-tikz at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ>.
454 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
458 You can find documentation for this module with the perldoc command.
462 =head1 COPYRIGHT & LICENSE
464 Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights reserved.
466 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
470 1; # End of LaTeX::TikZ