8 LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
16 our $VERSION = '0.03';
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
106 A synonym for L</union>.
110 Tikz->join($connector, @kids)
112 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.
115 Tikz->join('-|', map [ $_, $_ ], 0 .. 5);
119 Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn)
121 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.
123 # An heart-like shape
125 => '.. controls (-1, 1.5) and (-0.75, 0.25) ..' => [ 0, 0 ]
126 => '.. controls (0.75, 0.25) and (1, 1.5) ..' => [ 0, 1 ]
133 Creates a L<LaTeX::TikZ::Set::Sequence> object out of the sequences or paths C<@kids>.
135 my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
139 Those are the building blocks of your geometrical figure.
145 Creates a L<LaTeX::TikZ::Set::Point> object by coercing C<$point> into a L<LaTeX::TikZ::Point>.
146 The following rules are available :
152 If C<$point> isn't given, the point defaults to C<(0, 0)>.
154 my $origin = Tikz->point;
158 If C<$point> is a numish Perl scalar, it is treated as C<($point, 0)>.
160 my $unit = Tikz->point(1);
164 If two numish scalars C<$x> and C<$y> are given, they result in the point C<($x, $y)>.
166 my $one_plus_i = Tikz->point(1, 1);
170 If C<$point> is an array reference, it is parsed as C<< ($point->[0], $point->[1]) >>.
172 my $i = Tikz->point([ 0, 1 ]);
176 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) >>.
178 my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3));
182 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.
183 See L<LaTeX::TikZ::Meta::TypeConstraint::Autocoerce> for the rationale and L<LaTeX::TikZ::Point::Math::Complex> for an example.
187 Tikz->line($from => $to)
189 Creates a L<LaTeX::TikZ::Set::Line> object between the points C<$from> and C<$to>.
191 my $x_axis = Tikz->line(-5 => 5);
192 my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]);
196 Tikz->polyline(@points)
198 Creates a L<LaTeX::TikZ::Set::Polyline> object that links the successive elements of C<@points> by segments.
200 my $U = Tikz->polyline(
207 =head3 C<closed_polyline>
209 Tikz->closed_polyline(@points)
211 Creates a L<LaTeX::TikZ::Set::Polyline> object that cycles through successive elements of C<@points>.
213 my $diamond = Tikz->closed_polyline(
222 Tikz->rectangle($from => $to)
223 Tikz->rectangle($from => { width => $width, height => $height })
225 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>.
227 my $square = Tikz->rectangle(
234 Tikz->circle($center, $radius)
236 Creates a L<LaTeX::TikZ::Set::Circle> object of center C<$center> and radius C<$radius>.
238 my $unit_circle = Tikz->circle(0, 1);
242 Tikz->arc($from => $to, $center)
244 Creates a L<LaTeX::TikZ::Set> structure that represents an arc going from C<$from> to C<$to> with center C<$center>.
246 # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects
247 my $quarter = Tikz->arc(
248 [ 1, 0 ] => [ 0, 1 ],
254 Tikz->arrow($from => $to)
255 Tikz->arrow($from => dir => $dir)
257 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>.
259 # An horizontal arrow
260 my $arrow = Tikz->arrow(0 => 1);
266 Creates a L<LaTeX::TikZ::Set::Raw> object that will instantiate to the raw TikZ code C<$content>.
270 Modifiers are applied onto sets by calling the C<< ->mod >> method, like in C<< $set->mod($mod) >>.
271 This method returns the C<$set> object, so it can be chained.
277 Creates a L<LaTeX::TikZ::Mod::Clip> object that can be used to clip a given sequence by the (closed) path C<$path>.
279 my $box = Tikz->clip(
280 Tikz->rectangle(0 => [ 1, 1 ]),
283 Clips can also be directly applied to sets with the C<< ->clip >> method.
285 my $set = Tikz->circle(0, 1.5)
286 ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
290 Tikz->layer($name, above => \@above, below => \@below)
292 Creates a L<LaTeX::TikZ::Mod::Layer> object with name C<$name> and optional relative positions C<@above> and C<@below>.
294 my $layer = Tikz->layer(
299 The default layer is C<main>.
301 Layers are stored into a global hash, so that when you refer to them by their name, you get the existing layer object.
303 Layers can also be directly applied to sets with the C<< ->layer >> method.
305 my $dots = Tikz->rectangle(0 => [ 1, 1 ])
306 ->mod(Tikz->pattern(class => 'Dots'))
313 Creates a L<LaTeX::TikZ::Mod::Scale> object that scales the sets onto which it apply by the given C<$factor>.
315 my $circle_of_radius_2 = Tikz->circle(0 => 1)
316 ->mod(Tikz->scale(2));
320 Tikz->width($line_width)
322 Creates a L<LaTeX::TikZ::Mod::Width> object that sets the line width to C<$line_width> when applied.
324 my $thick_arrow = Tikz->arrow(0 => 1)
325 ->mod(Tikz->width(5));
331 Creates a L<LaTeX::TikZ::Mod::Color> object that sets the line color to C<$color> (given in the C<xcolor> syntax).
333 # Paint the previous $thick_arrow in red.
334 $thick_arrow->mod(Tikz->color('red'));
340 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).
342 my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 })
343 ->mod(Tikz->fill('red'));
347 Tikz->pattern(class => $class, %args)
349 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.
350 C<$class> is prepended with C<LaTeX::TikZ::Mod::Pattern> when it doesn't contain C<::>.
351 See L<LaTeX::TikZ::Mod::Pattern::Dots> and L<LaTeX::TikZ::Mod::Pattern::Lines> for two examples of pattern classes.
353 my $hatched_circle = Tikz->circle(0 => 1)
354 ->mod(Tikz->pattern(class => 'Lines'));
358 Tikz->raw_mod($content)
360 Creates a L<LaTeX::TikZ::Mod::Raw> object that will instantiate to the raw TikZ mod code C<$content>.
362 my $homemade_arrow = Tikz->line(0 => 1)
363 ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
369 Tikz->formatter(%args)
371 Creates a L<LaTeX::TikZ::Formatter> object that can render a L<LaTeX::TikZ::Set> tree.
373 my $tikz = Tikz->formatter;
374 my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2);
378 Tikz->functor(@rules)
380 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.
381 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.
383 # The default is a clone method
384 my $clone = Tikz->functor;
385 my $dup = $set->$clone;
388 my $translate = Tikz->functor(
389 'LaTeX::TikZ::Set::Point' => sub {
390 my ($functor, $set, $x, $y) = @_;
397 label => $set->label,
402 my $shifted = $set->$translate(1, 1);
405 my $strip = Tikz->functor(
406 '+LaTeX::TikZ::Mod' => sub { return },
408 my $naked = $set->$strip;
412 use LaTeX::TikZ::Interface;
418 my $name = $args{as};
419 $name = 'Tikz' unless defined $name;
420 unless ($name =~ /^[a-z_][a-z0-9_]*$/i) {
422 Carp::confess('Invalid name');
426 my $const = sub () { 'LaTeX::TikZ::Interface' };
429 *{$pkg . '::' . $name} = $const;
432 LaTeX::TikZ::Interface->load;
439 L<Mouse> 0.80 or greater.
443 L<Math::Complex>, L<Math::Trig>.
445 L<Scalar::Util>, L<List::Util>, L<Task::Weaken>.
449 PGF/TikZ - L<http://pgf.sourceforge.net>.
453 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
455 You can contact me by mail or on C<irc.perl.org> (vincent).
459 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>.
460 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
464 You can find documentation for this module with the perldoc command.
468 =head1 COPYRIGHT & LICENSE
470 Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights reserved.
472 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
476 1; # End of LaTeX::TikZ