lib/LaTeX/TikZ/Formatter.pm

   1 package LaTeX::TikZ::Formatter;
   2
   3 use strict;
   4 use warnings;
   5
   6 =head1 NAME
   7
   8 LaTeX::TikZ::Formatter - LaTeX::TikZ formatter object.
   9
  10 =head1 VERSION
  11
  12 Version 0.02
  13
  14 =cut
  15
  16 our $VERSION = '0.02';
  17
  18 =head1 DESCRIPTION
  19
  20 A formatter object turns a L<LaTeX::TikZ::Set> tree into the actual TikZ code, depending on some parameters such as the scale, the unit or the origin.
  21
  22 =cut
  23
  24 use Sub::Name ();
  25
  26 use LaTeX::TikZ::Point;
  27
  28 use LaTeX::TikZ::Interface;
  29
  30 use LaTeX::TikZ::Tools;
  31
  32 use Mouse;
  33 use Mouse::Util::TypeConstraints;
  34
  35 =head1 ATTRIBUTES
  36
  37 =head2 C<unit>
  38
  39 The unit in which lengths are printed.
  40 Valid units are C<cm> for centimeters and C<pt> for points.
  41
  42 Defaults to C<cm>.
  43
  44 =cut
  45
  46 has 'unit' => (
  47  is      => 'ro',
  48  isa     => enum([ qw<cm pt> ]),
  49  default => 'cm',
  50 );
  51
  52 =head2 C<format>
  53
  54 The format used to print the numbers.
  55
  56 Defaults to C<%s>.
  57
  58 =cut
  59
  60 has 'format' => (
  61  is      => 'ro',
  62  isa     => 'Str',
  63  default => '%s',
  64 );
  65
  66 =head2 C<scale>
  67
  68 The scale of the drawing.
  69
  70 Defaults to C<1>.
  71
  72 =cut
  73
  74 has 'scale' => (
  75  is      => 'rw',
  76  isa     => 'Num',
  77  default => 1,
  78 );
  79
  80 =head2 C<width>
  81
  82 The width of the drawing area.
  83
  84 Defaults to C<undef> for none.
  85
  86 =cut
  87
  88 has 'width' => (
  89  is  => 'rw',
  90  isa => 'Maybe[Num]',
  91 );
  92
  93 =head2 C<height>
  94
  95 The height of the drawing area.
  96
  97 Defaults to C<undef> for none.
  98
  99 =cut
 100
 101 has 'height' => (
 102  is  => 'rw',
 103  isa => 'Maybe[Num]',
 104 );
 105
 106 =head2 C<origin>
 107
 108 A point coerced into a L<LaTeX::TikZ::Point> object that represents the logical origin of the printed area.
 109 If L</width> and L</height> are set, the canvas will be equivalent to a rectangle whose lower left corner at C<-$origin> and of given width and length.
 110
 111 Defaults to C<(0, 0)>, meaning that the drawing area goes from C<(0, 0)> to C<($width, $height)>.
 112
 113 =cut
 114
 115 has 'origin' => (
 116  is     => 'rw',
 117  isa    => 'LaTeX::TikZ::Point::Autocoerce',
 118  coerce => 1,
 119 );
 120
 121 =head1 METHODS
 122
 123 =head2 C<id>
 124
 125 An unique identifier of the formatter object.
 126
 127 =cut
 128
 129 sub id {
 130  my $tikz = shift;
 131
 132  my $origin = $tikz->origin;
 133  if (defined $origin) {
 134   my ($x, $y) = map $origin->$_, qw<x y>;
 135   $origin = "($x;$y)";
 136  } else {
 137   $origin = "(0;0)";
 138  }
 139
 140  join $;, map {
 141   defined() ? "$_" : '(undef)';
 142  } map($tikz->$_, qw<unit format scale width height>), $origin;
 143 }
 144
 145 =head2 C<render>
 146
 147     my ($header_lines, $mod_lines, $content_lines) = $formatter->render(@sets);
 148
 149 Processes all the L<LaTeX::TikZ::Set> objects given in C<@sets> to produce the actual TikZ code to insert in the LaTeX file.
 150 First, all the mods applied to the sets and their subsets are collected, and a declaration is emitted if needed for each of them by calling L<LaTeX::TikZ::Mod/declare>.
 151 Then, the image code is generated for each set.
 152
 153 This method returns a list of array references :
 154
 155 =over 4
 156
 157 =item *
 158
 159 The first one contains the header lines to include between the C<\documentclass> and the C<\begin{document}>.
 160
 161 =item *
 162
 163 The second one contains the mod declaration lines to put inside the document, between C<\begin{document}> and C<\end{document}>.
 164
 165 =item *
 166
 167 Finally, there's one array reference for each given TikZ set, which contain the lines for the actual TikZ pictures.
 168
 169 =back
 170
 171 The lines returned by L</render> don't end with a line feed.
 172
 173     my ($header, $declarations, $set1_body, $set2_body) = $formatter->render($set1, $set2);
 174
 175     open my $tex, '>', 'test.tex' or die "open('>test.tex'): $!";
 176
 177     print $tex "$_\n" for (
 178      "\\documentclass[12pt]{article}",
 179      @$header,
 180      "\\begin{document}",
 181       "\\pagestyle{empty}",
 182       @$declarations,
 183       "First set :"
 184       "\\begin{center}",
 185        @$set1_body,
 186       "\\end{center}",
 187       "Second set :"
 188       "\\begin{center}",
 189        @$set2_body,
 190       "\\end{center}",
 191      "\\end{document}",
 192     );
 193
 194 =cut
 195
 196 my $find_mods = do {
 197  our %seen;
 198
 199  my $find_mods_rec;
 200  $find_mods_rec = do {
 201   no warnings 'recursion';
 202
 203   Sub::Name::subname('find_mods_rec' => sub {
 204    my ($set, $layers, $others) = @_;
 205
 206    for ($set->mods) {
 207     my $tag = $_->tag;
 208     next if $seen{$tag}++;
 209
 210     if ($_->isa('LaTeX::TikZ::Mod::Layer')) {
 211      push @$layers, $_;
 212     } else {
 213      push @$others, $_;
 214     }
 215    }
 216
 217    my @subsets = $set->does('LaTeX::TikZ::Set::Container')
 218                  ? $set->kids
 219                  : ();
 220
 221    $find_mods_rec->($_, $layers, $others) for @subsets;
 222   });
 223  };
 224
 225  Sub::Name::subname('find_mods' => sub {
 226   local %seen = ();
 227
 228   $find_mods_rec->(@_);
 229  });
 230 };
 231
 232 my $translate;
 233
 234 sub render {
 235  my ($tikz, @sets) = @_;
 236
 237  unless ($translate) {
 238   require LaTeX::TikZ::Functor;
 239   $translate = LaTeX::TikZ::Functor->new(
 240    rules => [
 241     'LaTeX::TikZ::Set::Point' => sub {
 242      my ($functor, $set, $v) = @_;
 243
 244      $set->new(
 245       point => [
 246        $set->x + $v->x,
 247        $set->y + $v->y,
 248       ],
 249       label => $set->label,
 250       pos   => $set->pos,
 251      );
 252     },
 253    ],
 254   );
 255  }
 256
 257  my $origin = $tikz->origin;
 258  if (defined $origin) {
 259   @sets = map $_->$translate($origin), @sets;
 260  }
 261
 262  my (@layers, @other_mods);
 263  my $seq = LaTeX::TikZ::Set::Sequence->new(kids => \@sets);
 264  $find_mods->($seq, \@layers, \@other_mods);
 265
 266  my $w = $tikz->width;
 267  my $h = $tikz->height;
 268  my $canvas = '';
 269  if (defined $w and defined $h) {
 270   require LaTeX::TikZ::Set::Rectangle;
 271   for (@sets) {
 272    $_->clip(LaTeX::TikZ::Set::Rectangle->new(
 273     from   => 0,
 274     width  => $w,
 275     height => $h,
 276    ));
 277   }
 278   $_ = $tikz->len($_) for $w, $h;
 279   $canvas = ",papersize={$w,$h},body={$w,$h}";
 280  }
 281
 282  my @header = (
 283   "\\usepackage[pdftex,hcentering,vcentering$canvas]{geometry}",
 284   "\\usepackage{tikz}",
 285   "\\usetikzlibrary{patterns}",
 286  );
 287
 288  my @decls;
 289  push @decls, LaTeX::TikZ::Mod::Layer->declare(@layers) if  @layers;
 290  push @decls, $_->declare($tikz)                        for @other_mods;
 291
 292  my @bodies = map [
 293   "\\begin{tikzpicture}",
 294   @{ $_->draw($tikz) },
 295   "\\end{tikzpicture}",
 296  ], @sets;
 297
 298  return \@header, \@decls, @bodies;
 299 }
 300
 301 =head2 C<len>
 302
 303     my $physical_len = $formatter->len($logical_len);
 304
 305 Format the given length according to the formatter options.
 306
 307 =cut
 308
 309 sub len {
 310  my ($tikz, $len) = @_;
 311
 312  $len = 0 if LaTeX::TikZ::Tools::numeq($len, 0);
 313
 314  sprintf $tikz->format . $tikz->unit, $len * $tikz->scale;
 315 }
 316
 317 =head2 C<angle>
 318
 319     my $physical_angle = $formatter->angle($logical_angle);
 320
 321 Format the given angle (in radians) according to the formatter options.
 322
 323 =cut
 324
 325 sub angle {
 326  my ($tikz, $a) = @_;
 327
 328  $a = ($a * 180) / CORE::atan2(0, -1);
 329  $a += 360 if LaTeX::TikZ::Tools::numcmp($a, 0) < 0;
 330
 331  require POSIX;
 332  sprintf $tikz->format, POSIX::ceil($a);
 333 }
 334
 335 =head2 C<label>
 336
 337     my $label = $formatter->label($name, $pos);
 338
 339 Returns the TikZ code for a point labeled C<$name> at position C<$pos> according to the formatter options.
 340
 341 =cut
 342
 343 sub label {
 344  my ($tikz, $name, $pos) = @_;
 345
 346  my $scale = sprintf '%0.2f', $tikz->scale / 5;
 347
 348  "node[scale=$scale,$pos] {$name}";
 349 }
 350
 351 =head2 C<thickness>
 352
 353 Format the given line thickness according to the formatter options.
 354
 355 =cut
 356
 357 sub thickness {
 358  my ($tikz, $width) = @_;
 359
 360  # width=1 is 0.4 points for a scale of 2.5
 361  0.8 * $width * ($tikz->scale / 5);
 362 }
 363
 364 LaTeX::TikZ::Interface->register(
 365  formatter => sub {
 366   shift;
 367
 368   __PACKAGE__->new(@_);
 369  },
 370 );
 371
 372 __PACKAGE__->meta->make_immutable;
 373
 374 =head1 SEE ALSO
 375
 376 L<LaTeX::TikZ>.
 377
 378 =head1 AUTHOR
 379
 380 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 381
 382 You can contact me by mail or on C<irc.perl.org> (vincent).
 383
 384 =head1 BUGS
 385
 386 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>.
 387 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 388
 389 =head1 SUPPORT
 390
 391 You can find documentation for this module with the perldoc command.
 392
 393     perldoc LaTeX::TikZ
 394
 395 =head1 COPYRIGHT & LICENSE
 396
 397 Copyright 2010,2011,2012,2013,2014,2015 Vincent Pit, all rights reserved.
 398
 399 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 400
 401 =cut
 402
 403 1; # End of LaTeX::TikZ::Formatter