NAME

Graphics::Potrace::Vectorial::Exporter - vectorial exporter base class for Graphics::Potrace

VERSION

version 0.76

DESCRIPTION

This is a base class for building up vector exporters. One example of using this base class is shipped directly in the distribution as Graphics::Potrace::Vectorial::Svg.

You only need override one of two methods in order to implement your exporter: either "render" or "save". Both receive a list of vectors to be rendered, but are expected to behave differently: the former should return a textual representation of the exported stuff (e.g. text containing the full contents of a SVG document), the latter is supposed to print it to the internal filehandle (collected via "fh").

In this class these two methods are both defined in terms of the other, so that you can really override only one of them and get the other one for free.

One additional method that you can find useful is "boundaries": it will return the maximum width and height across the full list of vectors, so that you can size the dimensions of your output representation properly (e.g. set the width and height attributes in the svg outer element).

Exporters deriving from this base class accept two different parameters for setting where the export can be performed: "fh" and "file". So you will always be able to call "create_exporter" in Graphics::Potrace::Vectorial like this:

   my $e1 = $vector->create_exporter($type, file => $filename);
   my $e2 = $vector->create_exporter($type, file => \my $text);
   my $e3 = $vector->create_exporter($type, fh   => $filehandle);

INTERFACE

boundaries

   my ($width, $height) = $exporter->boundaries(@vectors);

This function returns the maximum width and height across the list of provided vectors. These should be Graphics::Potrace::Vectorial elements, but anything providing both width and height methods will do.

clear_file

   $exporter->clear_file();

Clear the value for the file, see "file".

clear_fh

   $exporter->clear_fh();

Clear the value for the filehandle, see "fh".

clone

   my $other_exporter = $exporter->clone();

Create a replica of the exporter object. It does this by calling new passing all the parameters already present, so you can override it if your needs are more sophisticated. Used by the default provided "render" in order to avoid clobbering the main object.

file

   $exporter->file($filename);  # some file in the filesystem
   $exporter->file(\my $text);  # a variable to save to
   my $current = $exporter->file();  # getter

Accessor to get/set a file where "save" will save data. It can be whatever "open" in perlfunc accepts, e.g. a reference to a scalar.

fh

   $exporter->fh($filehandle);
   my $fh = $exporter->fh();

Accessor to get/set a filehandle where "save" will send data.

It is automatically (and lazily) populated when you call the getter, so this will change what has_fh will tell you (see "has_fh" for details).

Calling the getter will generate an exception if neither fh nor file are set (you can test it with has_fh or has_file respectively).

has_file

   $exporter->has_file() and print "has it!\n";

Returns a boolean value depending on the immediate availability of a file for "save". See also "file"

has_fh

   $exporter->has_fh() and print "has it!\n";

Returns a boolean value depending on the immediate availability of a filehandle for "save".

Note that a filehandle might be available to "save" even though the value returned is false, because it might be automatically populated in case there is a file (see "has_file" and "file"). This means that has_fh might return different values depending on the evolution:

   my $e = Graphics::Potrace::Vectorial::Exporter->new();
   print "has it!\n" if $e->has_fh(); # does NOT print
   $e->file('/dev/null');
   print "has it!\n" if $e->has_fh(); # does NOT print, again
   my $fh = $e->fh(); # opens "file" and sets the fh
   print "has it!\n" if $e->has_fh(); # does print now!

new

   my $e = Graphics::Potrace::Vectorial::Exporter->new(%args);

Constructor, input arguments can be file and fh passed in a key-value style.

render

   my $text = $exporter->render(@vectors);

Produce a rendering of the provided @vectors, e.g. the SVG document as a text in case of SVG. This method in this package uses "save" to do the heavy lifting, so you either have to override it or "save".

reset

   $exporter->reset();

Clears both "fh" and "file" by calling respective clearers (i.e. "clear_fh" and "clear_file", respectively).

save

   $exporter->save(@vectors);

Save a rendering of the provided @vectors to "fh". This method in this package uses "render" to do the heavy lifting, so you either have to override it or "render".

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011-2015 by Flavio Poletti polettix@cpan.org.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm Graphics::Potrace

perl -MCPAN -e shell
install Graphics::Potrace