Update VPIT::TestHelpers to 15e8aee3

[perl/modules/LaTeX-TikZ.git] / README

diff --git a/README b/README
index fcfafc9fd23ffc65d247bac2477575a1005db145..c1bd2e38eb46a94167b70e7e16080f2666c86b7e 100644 (file)
--- a/README
+++ b/README
@@ -2,14 +2,14 @@ NAME
     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
 
 VERSION
     LaTeX::TikZ - Perl object model for generating PGF/TikZ code.
 
 VERSION

-    Version 0.01
+    Version 0.03

 
 SYNOPSIS
         use LaTeX::TikZ;
 
         # A couple of lines
         my $hline = Tikz->line(-1 => 1);
 
 SYNOPSIS
         use LaTeX::TikZ;
 
         # A couple of lines
         my $hline = Tikz->line(-1 => 1);

-        my $vline = Tikz->line([ 0, -1 ] => [ 0, -1 ]);
+        my $vline = Tikz->line([ 0, -1 ] => [ 0, 1 ]);

 
         # Paint them in red
         $_->mod(Tikz->color('red')) for $hline, $vline;
 
         # Paint them in red
         $_->mod(Tikz->color('red')) for $hline, $vline;


@@ -27,7 +27,7 @@ SYNOPSIS
         $octo->mod(Tikz->pattern(class => 'Dots'));
 
         # Create a formatter object
         $octo->mod(Tikz->pattern(class => 'Dots'));
 
         # Create a formatter object

-        my $tikz = Tikz->formatter;
+        my $tikz = Tikz->formatter(scale => 5);

 
         # Put those objects all together and print them
         my $seq = Tikz->seq($octo, $hline, $vline);
 
         # Put those objects all together and print them
         my $seq = Tikz->seq($octo, $hline, $vline);


@@ -35,30 +35,28 @@ SYNOPSIS
         print "$_\n" for map @$_, $head, $decl, $body;
 
 DESCRIPTION
         print "$_\n" for map @$_, $head, $decl, $body;
 
 DESCRIPTION

-    This module provides an object model for TikZ, a graphical tookit for
+    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
     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 :
+    Traditionally, in TikZ, there are two ways of grouping paths together :

 
 

-    *   either as a *sequence*, where each element is drawn in its own line
-        :
+    *   either as a *sequence*, where each path is drawn in its own line :

 
             \draw (0cm,0cm) -- (0cm,1cm) ;
             \draw (0cm,0cm) -- (1cm,0cm) ;
 
 
             \draw (0cm,0cm) -- (0cm,1cm) ;
             \draw (0cm,0cm) -- (1cm,0cm) ;
 

-    *   or as a *path*, where elements are all drawn as one line :
+    *   or as an *union*, where paths are all drawn as one line :

 
             \draw (0cm,0cm) -- (0cm,1cm) (0cm,0cm) -- (1cm,0cm) ;
 
 
             \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.
+    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 ops, path or sequence *sets* assembled together in a
+    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
     tree.
 
     *Modifiers* can be applied onto any set to alter the way in which it is


@@ -67,11 +65,13 @@ CONCEPTS
 
 INTERFACE
   Containers
 
 INTERFACE
   Containers

-   "Tikz->path(@ops)"
-    Creates a LaTeX::TikZ::Set::Path object out of the ops @ops.
+   "union"
+        Tikz->union(@kids)
+
+    Creates a LaTeX::TikZ::Set::Union object out of the paths @kids.

 
         # A path made of two circles
 
         # A path made of two circles

-        Tikz->path(
+        Tikz->union(

                Tikz->circle(0, 1),
                Tikz->circle(1, 1),
               )
                Tikz->circle(0, 1),
                Tikz->circle(1, 1),
               )


@@ -80,16 +80,48 @@ INTERFACE
                'even odd rule',
               );
 
                'even odd rule',
               );
 

-   "Tikz->seq(@kids)"
-    Creates a LaTeX::TikZ::Set::Sequence object out of the sequences, paths
-    or ops @kids.
+   "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.
 
 
         my $bag = Tikz->seq($sequence, $path, $circle, $raw, $point);
 
   Elements
     Those are the building blocks of your geometrical figure.
 

-   "Tikz->point($point)"
+   "point"
+        Tikz->point($point)
+

     Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
     LaTeX::TikZ::Point. The following rules are available :
 
     Creates a LaTeX::TikZ::Set::Point object by coercing $point into a
     LaTeX::TikZ::Point. The following rules are available :
 


@@ -119,18 +151,22 @@ INTERFACE
 
     You can define automatic coercions from your user point types to
     LaTeX::TikZ::Point by writing your own
 
     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::Point::My::User::Point" class. See

     LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
     LaTeX::TikZ::Point::Math::Complex for an example.
 
     LaTeX::TikZ::Meta::TypeConstraint::Autocoerce for the rationale and
     LaTeX::TikZ::Point::Math::Complex for an example.
 

-   "Tikz->line($from => $to)"
+   "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 ]);
 
     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)"
+   "polyline"
+        Tikz->polyline(@points)
+

     Creates a LaTeX::TikZ::Set::Polyline object that links the successive
     elements of @points by segments.
 
     Creates a LaTeX::TikZ::Set::Polyline object that links the successive
     elements of @points by segments.
 


@@ -141,9 +177,11 @@ INTERFACE
          Tikz->point(1, 1),
         );
 
          Tikz->point(1, 1),
         );
 

-   "Tikz->closed_polyline(@points)"
+   "closed_polyline"
+        Tikz->closed_polyline(@points)
+

     Creates a LaTeX::TikZ::Set::Polyline object that cycles through
     Creates a LaTeX::TikZ::Set::Polyline object that cycles through

-    successive eleemnts of @points.
+    successive elements of @points.

 
         my $diamond = Tikz->closed_polyline(
          Tikz->point(0, 1),
 
         my $diamond = Tikz->closed_polyline(
          Tikz->point(0, 1),


@@ -152,7 +190,10 @@ INTERFACE
          Tikz->point(1, 0),
         );
 
          Tikz->point(1, 0),
         );
 

-   "Tikz->rectangle($from => $to), Tikz->rectangle($from => { width => $width, height => $height })"
+   "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.
 
     Creates a LaTeX::TikZ::Set::Rectangle object with opposite corners $from
     and $to, or with anchor point $from and dimensions $width and $height.
 


@@ -161,13 +202,17 @@ INTERFACE
          Tikz->point(2, 1),
         );
 
          Tikz->point(2, 1),
         );
 

-   "Tikz->circle($center, $radius)"
+   "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);
 
     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)"
+   "arc"
+        Tikz->arc($from => $to, $center)
+

     Creates a LaTeX::TikZ::Set structure that represents an arc going from
     $from to $to with center $center.
 
     Creates a LaTeX::TikZ::Set structure that represents an arc going from
     $from to $to with center $center.
 


@@ -177,14 +222,19 @@ INTERFACE
          [ 0, 0 ]
         );
 
          [ 0, 0 ]
         );
 

-   "Tikz->arrow($from => $to), Tikz->arrow($from => dir => $dir)"
+   "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);
 
     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)"
+   "raw"
+        Tikz->raw($content)
+

     Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
     TikZ code $content.
 
     Creates a LaTeX::TikZ::Set::Raw object that will instantiate to the raw
     TikZ code $content.
 


@@ -193,7 +243,9 @@ INTERFACE
     "$set->mod($mod)". This method returns the $set object, so it can be
     chained.
 
     "$set->mod($mod)". This method returns the $set object, so it can be
     chained.
 

-   "Tikz->clip($path)"
+   "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.
 
     Creates a LaTeX::TikZ::Mod::Clip object that can be used to clip a given
     sequence by the (closed) path $path.
 


@@ -206,7 +258,9 @@ INTERFACE
         my $set = Tikz->circle(0, 1.5)
                       ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
 
         my $set = Tikz->circle(0, 1.5)
                       ->clip(Tikz->rectangle([-1, -1] => [1, 1]));
 

-   "Tikz->layer($name, above => \@above, below => \@below)"
+   "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.
 
     Creates a LaTeX::TikZ::Mod::Layer object with name $name and optional
     relative positions @above and @below.
 


@@ -226,28 +280,45 @@ INTERFACE
                        ->mod(Tikz->pattern(class => 'Dots'))
                        ->layer('top');
 
                        ->mod(Tikz->pattern(class => 'Dots'))
                        ->layer('top');
 

-   "Tikz->width($line_width)"
+   "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));
 
     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"
+        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'));
 
     $color (given in the "xcolor" syntax).
 
         # Paint the previous $thick_arrow in red.
         $thick_arrow->mod(Tikz->color('red'));
 

-   "Tikz->fill($color)"
+   "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'));
 
     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)"
+   "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
     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


@@ -257,7 +328,9 @@ INTERFACE
         my $hatched_circle = Tikz->circle(0 => 1)
                                  ->mod(Tikz->pattern(class => 'Lines'));
 
         my $hatched_circle = Tikz->circle(0 => 1)
                                  ->mod(Tikz->pattern(class => 'Lines'));
 

-   "Tikz->raw_mod($content)"
+   "raw_mod"
+        Tikz->raw_mod($content)
+

     Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
     TikZ mod code $content.
 
     Creates a LaTeX::TikZ::Mod::Raw object that will instantiate to the raw
     TikZ mod code $content.
 


@@ -265,18 +338,23 @@ INTERFACE
                                  ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
 
   Helpers
                                  ->mod(Tikz->raw_mod('->')) # or just ->mod('->')
 
   Helpers

-   "Tikz->formatter(%args)"
+   "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);
 
     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)"
+   "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
     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.
+    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;
 
         # The default is a clone method
         my $clone = Tikz->functor;


@@ -301,17 +379,15 @@ INTERFACE
 
         # A mod stripper
         my $strip = Tikz->functor(
 
         # A mod stripper
         my $strip = Tikz->functor(

-         'LaTeX::TikZ::Mod' => sub { return },
+         '+LaTeX::TikZ::Mod' => sub { return },

         );
         my $naked = $set->$strip;
 
 DEPENDENCIES
         );
         my $naked = $set->$strip;
 
 DEPENDENCIES

-    Any::Moose with Mouse 0.63 or greater.
+    Mouse 0.80 or greater.

 
     Sub::Name.
 
 
     Sub::Name.
 

-    Scope::Guard.
-

     Math::Complex, Math::Trig.
 
     Scalar::Util, List::Util, Task::Weaken.
     Math::Complex, Math::Trig.
 
     Scalar::Util, List::Util, Task::Weaken.


@@ -337,7 +413,8 @@ SUPPORT
         perldoc LaTeX::TikZ
 
 COPYRIGHT & LICENSE
         perldoc LaTeX::TikZ
 
 COPYRIGHT & LICENSE

-    Copyright 2010 Vincent Pit, all rights reserved.
+    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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.