X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FLaTeX-TikZ.git;a=blobdiff_plain;f=README;h=c1bd2e38eb46a94167b70e7e16080f2666c86b7e;hp=e69de29bb2d1d6434b8b29ae775ad8c2e48c5391;hb=HEAD;hpb=e8f0879ade07eed4f58cd52c0771f4e1ecc90b09 diff --git a/README b/README index e69de29..c1bd2e3 100644 --- a/README +++ b/README @@ -0,0 +1,421 @@ +NAME + LaTeX::TikZ - Perl object model for generating PGF/TikZ code. + +VERSION + Version 0.03 + +SYNOPSIS + use LaTeX::TikZ; + + # A couple of lines + my $hline = Tikz->line(-1 => 1); + my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]); + + # Paint them in red + $_->mod(Tikz->color('red')) for $hline, $vline; + + # An octogon + use Math::Complex; + my $octo = Tikz->closed_polyline( + map Math::Complex->emake(1, ($_ * pi)/4), 0 .. 7 + ); + + # Only keep a portion of it + $octo->clip(Tikz->rectangle(-0.5*(1+i), 2*(1+i))); + + # Fill it with dots + $octo->mod(Tikz->pattern(class => 'Dots')); + + # Create a formatter object + my $tikz = Tikz->formatter(scale => 5); + + # Put those objects all together and print them + my $seq = Tikz->seq($octo, $hline, $vline); + my ($head, $decl, $body) = $tikz->render($seq); + print "$_\n" for map @$_, $head, $decl, $body; + +DESCRIPTION + This module provides an object model for TikZ, a graphical toolkit for + LaTeX. 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. + +CONCEPTS + Traditionally, in TikZ, there are two ways of grouping paths together : + + * either as a *sequence*, where each path is drawn in its own line : + + \draw (0cm,0cm) -- (0cm,1cm) ; + \draw (0cm,0cm) -- (1cm,0cm) ; + + * or as an *union*, where paths are all drawn as one line : + + \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ; + + This distinction is important because there are some primitives that + only apply to paths but not to sequences, and vice versa. + + Figures are made of path or sequence *sets* assembled together in a + tree. + + *Modifiers* can be applied onto any set to alter the way in which it is + generated. The two TikZ concepts of *clips* and *layers* have been + unified with the modifiers. + +INTERFACE + Containers + "union" + Tikz->union(@kids) + + Creates a LaTeX::TikZ::Set::Union object out of the paths @kids. + + # A path made of two circles + Tikz->union( + Tikz->circle(0, 1), + Tikz->circle(1, 1), + ) + ->mod( + Tikz->fill('red'), + 'even odd rule', + ); + + "path" + Tikz->path(@kids) + + A synonym for "union". + + "join" + Tikz->join($connector, @kids) + + Creates a LaTeX::TikZ::Set::Chain object that joins the paths @kinds + with the given $connector which can be, according to "connector" in + LaTeX::TikZ::Set::Chain, a string, an array reference or a code + reference. + + # A stair + Tikz->join('-|', map [ $_, $_ ], 0 .. 5); + + "chain" + Tikz->chain($kid0, $link0, $kid1, $link1, ... $kidn) + + Creates a LaTeX::TikZ::Set::Chain object that chains $kid0 to $kid1 with + the string $link0, $kid1 to $kid2 with $link1, and so on. + + # An heart-like shape + Tikz->chain([ 0, 1 ] + => '.. controls (-1, 1.5) and (-0.75, 0.25) ..' => [ 0, 0 ] + => '.. controls (0.75, 0.25) and (1, 1.5) ..' => [ 0, 1 ] + ); + + "seq" + Tikz->seq(@kids) + + Creates a LaTeX::TikZ::Set::Sequence object out of the sequences or + paths @kids. + + my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point); + + Elements + Those are the building blocks of your geometrical figure. + + "point" + Tikz->point($point) + + Creates a LaTeX::TikZ::Set::Point object by coercing $point into a + LaTeX::TikZ::Point. The following rules are available : + + * If $point isn't given, the point defaults to "(0, 0)". + + my $origin = Tikz->point; + + * If $point is a numish Perl scalar, it is treated as "($point, 0)". + + my $unit = Tikz->point(1); + + * If two numish scalars $x and $y are given, they result in the point + "($x, $y)". + + my $one_plus_i = Tikz->point(1, 1); + + * If $point is an array reference, it is parsed as "($point->[0], + $point->[1])". + + my $i = Tikz->point([ 0, 1 ]); + + * If $point is a Math::Complex object, the + LaTeX::TikZ::Point::Math::Complex class is automatically loaded and + the point is coerced into "($point->Re, $point->Im)". + + my $j = Tikz->point(Math::Complex->emake(1, 2*pi/3)); + + You can define automatic coercions from your user point types to + LaTeX::TikZ::Point by writing your own + "LaTeX::TikZ::Point::My::User::Point" class. See + LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and + LaTeX::TikZ::Point::Math::Complex for an example. + + "line" + Tikz->line($from => $to) + + Creates a LaTeX::TikZ::Set::Line object between the points $from and + $to. + + my $x_axis = Tikz->line(-5 => 5); + my $y_axis = Tikz->line([ 0, -5 ] => [ 0, 5 ]); + + "polyline" + Tikz->polyline(@points) + + Creates a LaTeX::TikZ::Set::Polyline object that links the successive + elements of @points by segments. + + my $U = Tikz->polyline( + Tikz->point(0, 1), + Tikz->point(0, 0), + Tikz->point(1, 0), + Tikz->point(1, 1), + ); + + "closed_polyline" + Tikz->closed_polyline(@points) + + Creates a LaTeX::TikZ::Set::Polyline object that cycles through + successive elements of @points. + + my $diamond = Tikz->closed_polyline( + Tikz->point(0, 1), + Tikz->point(-1, 0), + Tikz->point(0, -2), + Tikz->point(1, 0), + ); + + "rectangle" + Tikz->rectangle($from => $to) + Tikz->rectangle($from => { width => $width, height => $height }) + + Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from + and $to, or with anchor point $from and dimensions $width and $height. + + my $square = Tikz->rectangle( + Tikz->point, + Tikz->point(2, 1), + ); + + "circle" + Tikz->circle($center, $radius) + + Creates a LaTeX::TikZ::Set::Circle object of center $center and radius + $radius. + + my $unit_circle = Tikz->circle(0, 1); + + "arc" + Tikz->arc($from => $to, $center) + + Creates a LaTeX::TikZ::Set structure that represents an arc going from + $from to $to with center $center. + + # An arc. The points are automatically coerced into LaTeX::TikZ::Set::Point objects + my $quarter = Tikz->arc( + [ 1, 0 ] => [ 0, 1 ], + [ 0, 0 ] + ); + + "arrow" + Tikz->arrow($from => $to) + Tikz->arrow($from => dir => $dir) + + Creates a LaTeX::TikZ::Set structure that represents an arrow going from + $from towards $to, or starting at $from in direction $dir. + + # An horizontal arrow + my $arrow = Tikz->arrow(0 => 1); + + "raw" + Tikz->raw($content) + + Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw + TikZ code $content. + + Modifiers + Modifiers are applied onto sets by calling the "->mod" method, like in + "$set->mod($mod)". This method returns the $set object, so it can be + chained. + + "clip" + Tikz->clip($path) + + Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given + sequence by the (closed) path $path. + + my $box = Tikz->clip( + Tikz->rectangle(0 => [ 1, 1 ]), + ); + + Clips can also be directly applied to sets with the "->clip" method. + + my $set = Tikz->circle(0, 1.5) + ->clip(Tikz->rectangle([-1, -1] => [1, 1])); + + "layer" + Tikz->layer($name, above => \@above, below => \@below) + + Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional + relative positions @above and @below. + + my $layer = Tikz->layer( + 'top' + above => [ 'main' ], + ); + + The default layer is "main". + + Layers are stored into a global hash, so that when you refer to them by + their name, you get the existing layer object. + + Layers can also be directly applied to sets with the "->layer" method. + + my $dots = Tikz->rectangle(0 => [ 1, 1 ]) + ->mod(Tikz->pattern(class => 'Dots')) + ->layer('top'); + + "scale" + Tikz->scale($factor) + + Creates a LaTeX::TikZ::Mod::Scale object that scales the sets onto which + it apply by the given $factor. + + my $circle_of_radius_2 = Tikz->circle(0 => 1) + ->mod(Tikz->scale(2)); + + "width" + Tikz->width($line_width) + + Creates a LaTeX::TikZ::Mod::Width object that sets the line width to + $line_width when applied. + + my $thick_arrow = Tikz->arrow(0 => 1) + ->mod(Tikz->width(5)); + + "color" + Tikz->color($color) + + Creates a LaTeX::TikZ::Mod::Color object that sets the line color to + $color (given in the "xcolor" syntax). + + # Paint the previous $thick_arrow in red. + $thick_arrow->mod(Tikz->color('red')); + + "fill" + Tikz->fill($color) + + Creates a LaTeX::TikZ::Mod::Fill object that fills the interior of a + path with the solid color $color (given in the "xcolor" syntax). + + my $red_box = Tikz->rectangle(0 => { width => 1, height => 1 }) + ->mod(Tikz->fill('red')); + + "pattern" + Tikz->pattern(class => $class, %args) + + Creates a LaTeX::TikZ::Mod::Pattern object of class $class and arguments + %args that fills the interior of a path with the specified pattern. + $class is prepended with "LaTeX::TikZ::Mod::Pattern" when it doesn't + contain "::". See LaTeX::TikZ::Mod::Pattern::Dots and + LaTeX::TikZ::Mod::Pattern::Lines for two examples of pattern classes. + + my $hatched_circle = Tikz->circle(0 => 1) + ->mod(Tikz->pattern(class => 'Lines')); + + "raw_mod" + Tikz->raw_mod($content) + + Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw + TikZ mod code $content. + + my $homemade_arrow = Tikz->line(0 => 1) + ->mod(Tikz->raw_mod('->')) # or just ->mod('->') + + Helpers + "formatter" + Tikz->formatter(%args) + + Creates a LaTeX::TikZ::Formatter object that can render a + LaTeX::TikZ::Set tree. + + my $tikz = Tikz->formatter; + my ($header, $declarations, $seq1_body, $seq2_body) = $tikz->render($set1, $set2); + + "functor" + Tikz->functor(@rules) + + Creates a LaTeX::TikZ::Functor anonymous subroutine that can be called + against LaTeX::TikZ::Set trees to clone them according to the given + rules. @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. + + # The default is a clone method + my $clone = Tikz->functor; + my $dup = $set->$clone; + + # A translator + my $translate = Tikz->functor( + 'LaTeX::TikZ::Set::Point' => sub { + my ($functor, $set, $x, $y) = @_; + + $set->new( + point => [ + $set->x + $x, + $set->y + $y, + ], + label => $set->label, + pos => $set->pos, + ); + }, + ); + my $shifted = $set->$translate(1, 1); + + # A mod stripper + my $strip = Tikz->functor( + '+LaTeX::TikZ::Mod' => sub { return }, + ); + my $naked = $set->$strip; + +DEPENDENCIES + Mouse 0.80 or greater. + + Sub::Name. + + Math::Complex, Math::Trig. + + Scalar::Util, List::Util, Task::Weaken. + +SEE ALSO + PGF/TikZ - . + +AUTHOR + Vincent Pit, "", . + + You can contact me by mail or on "irc.perl.org" (vincent). + +BUGS + Please report any bugs or feature requests to "bug-latex-tikz at + rt.cpan.org", or through the web interface at + . I will be + notified, and then you'll automatically be notified of progress on your + bug as I make changes. + +SUPPORT + You can find documentation for this module with the perldoc command. + + perldoc LaTeX::TikZ + +COPYRIGHT & LICENSE + Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights + reserved. + + This program is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. +