From: Vincent Pit Date: Fri, 23 Jul 2010 11:33:09 +0000 (+0200) Subject: This is 0.01 X-Git-Tag: v0.01 X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=1f0f6560bbd191f88c8f68cb663203d9c9bf7938;p=perl%2Fmodules%2FLaTeX-TikZ.git This is 0.01 --- diff --git a/Changes b/Changes index 9593a84..e6a93d3 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,5 @@ Revision history for LaTeX-TikZ -0.01 2010-01-02 21:10 UTC +0.01 2010-07-03 11:40 UTC First version, released on an unsuspecting world. diff --git a/MANIFEST b/MANIFEST index bb50009..23bd0e6 100644 --- a/MANIFEST +++ b/MANIFEST @@ -35,6 +35,7 @@ lib/LaTeX/TikZ/Set/Polyline.pm lib/LaTeX/TikZ/Set/Raw.pm lib/LaTeX/TikZ/Set/Rectangle.pm lib/LaTeX/TikZ/Set/Sequence.pm +lib/LaTeX/TikZ/Tools.pm samples/synopsis.pl t/00-load.t t/01-api.t diff --git a/META.yml b/META.yml index e69de29..f89de76 100644 --- a/META.yml +++ b/META.yml @@ -0,0 +1,51 @@ +--- #YAML:1.0 +name: LaTeX-TikZ +version: 0.01 +abstract: Perl object model for generating PGF/TikZ code. +author: + - Vincent Pit +license: perl +distribution_type: module +configure_requires: + ExtUtils::MakeMaker: 0 +build_requires: + Any::Moose: 0 + Carp: 0 + constant: 0 + ExtUtils::MakeMaker: 0 + List::Util: 0 + Math::Complex: 0 + Math::Trig: 0 + Mouse: 0.63 + Scalar::Util: 0 + Scope::Guard: 0 + Sub::Name: 0 + Task::Weaken: 0 + Test::More: 0 +requires: + Any::Moose: 0 + Carp: 0 + constant: 0 + List::Util: 0 + Math::Complex: 0 + Math::Trig: 0 + Mouse: 0.63 + perl: 5.006 + Scalar::Util: 0 + Scope::Guard: 0 + Sub::Name: 0 + Task::Weaken: 0 +resources: + bugtracker: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LaTeX-TikZ + homepage: http://search.cpan.org/dist/LaTeX-TikZ/ + license: http://dev.perl.org/licenses/ + repository: http://git.profvince.com/?p=perl%2Fmodules%2FLaTeX-TikZ.git +no_index: + directory: + - t + - inc +generated_by: ExtUtils::MakeMaker version 6.56 +meta-spec: + url: http://module-build.sourceforge.net/META-spec-v1.4.html + version: 1.4 +dynamic_config: 0 diff --git a/README b/README index e69de29..fcfafc9 100644 --- a/README +++ b/README @@ -0,0 +1,344 @@ +NAME + LaTeX::TikZ - Perl object model for generating PGF/TikZ code. + +VERSION + Version 0.01 + +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; + + # 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 tookit 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 + Traditionnaly, in TikZ, there are two ways of grouping elements, or + *ops*, together : + + * either as a *sequence*, where each element is drawn in its own line + : + + \draw (0cm,0cm) -- (0cm,1cm) ; + \draw (0cm,0cm) -- (1cm,0cm) ; + + * or as a *path*, where elements are all drawn as one line : + + \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ; + + This distinction is important because there are some primitves that only + apply to paths but not to sequences, and vice versa. + + Figures are made of ops, 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 + "Tikz->path(@ops)" + Creates a LaTeX::TikZ::Set::Path object out of the ops @ops. + + # A path made of two circles + Tikz->path( + Tikz->circle(0, 1), + Tikz->circle(1, 1), + ) + ->mod( + Tikz->fill('red'), + 'even odd rule', + ); + + "Tikz->seq(@kids)" + Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths + or ops @kids. + + my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point); + + Elements + Those are the building blocks of your geometrical figure. + + "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. + + "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 ]); + + "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), + ); + + "Tikz->closed_polyline(@points)" + Creates a LaTeX::TikZ::Set::Polyline object that cycles through + successive eleemnts of @points. + + my $diamond = Tikz->closed_polyline( + Tikz->point(0, 1), + Tikz->point(-1, 0), + Tikz->point(0, -2), + Tikz->point(1, 0), + ); + + "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), + ); + + "Tikz->circle($center, $radius)" + Creates a LaTeX::TikZ::Set::Circle object of center $center and radius + $radius. + + my $unit_circle = Tikz->circle(0, 1); + + "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 ] + ); + + "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); + + "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. + + "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])); + + "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'); + + "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)); + + "Tikz->color($color)" + Creates a LaTeX::TikZ::Mod::Colorobject 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')); + + "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')); + + "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')); + + "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 + "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); + + "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 made of array references whose first element is + the class/role to match against and the second the handler to run. + + # 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 + Any::Moose with Mouse 0.63 or greater. + + Sub::Name. + + Scope::Guard. + + 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 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. +