File Coverage

blib/lib/SVG.pm
Criterion Covered Total %
statement 65 66 98.4
branch 16 22 72.7
condition 10 16 62.5
subroutine 8 9 88.8
pod 3 3 100.0
total 102 116 87.9


line stmt bran cond sub pod time code
1             package SVG;
2              
3 25     25   1731420 use strict;
  25         258  
  25         792  
4 25     25   127 use warnings;
  25         44  
  25         936  
5              
6 25     25   10716 use SVG::XML;
  25         67  
  25         2350  
7 25     25   12565 use parent qw(SVG::Element SVG::Extension);
  25         8057  
  25         150  
8 25     25   1803 use Scalar::Util qw/weaken/;
  25         53  
  25         28343  
9              
10             our $VERSION = '2.86';
11              
12             =pod
13              
14             =encoding UTF-8
15              
16             =head1 NAME
17              
18             SVG - Perl extension for generating Scalable Vector Graphics (SVG) documents.
19              
20             =head1 SYNOPSIS
21              
22             #!/usr/bin/perl
23             use strict;
24             use warnings;
25             use SVG;
26              
27             # create an SVG object
28             my $svg= SVG->new( width => 200, height => 200);
29              
30             # use explicit element constructor to generate a group element
31             my $y = $svg->group(
32             id => 'group_y',
33             style => {
34             stroke => 'red',
35             fill => 'green'
36             },
37             );
38              
39             # add a circle to the group
40             $y->circle( cx => 100, cy => 100, r => 50, id => 'circle_in_group_y' );
41              
42             # or, use the generic 'tag' method to generate a group element by name
43             my $z = $svg->tag('g',
44             id => 'group_z',
45             style => {
46             stroke => 'rgb(100,200,50)',
47             fill => 'rgb(10,100,150)'
48             }
49             );
50              
51             # create and add a circle using the generic 'tag' method
52             $z->tag('circle', cx => 50, cy => 50, r => 100, id => 'circle_in_group_z');
53              
54             # create an anchor on a rectangle within a group within the group z
55             my $k = $z->anchor(
56             id => 'anchor_k',
57             -href => 'http://test.hackmare.com/',
58             target => 'new_window_0'
59             )->rectangle(
60             x => 20, y => 50,
61             width => 20, height => 30,
62             rx => 10, ry => 5,
63             id => 'rect_k_in_anchor_k_in_group_z'
64             );
65              
66             # now render the SVG object, implicitly use svg namespace
67             print $svg->xmlify;
68              
69             # or render a child node of the SVG object without rendering the entire object
70             print $k->xmlify; #renders the anchor $k above containing a rectangle, but does not
71             #render any of the ancestor nodes of $k
72              
73              
74             # or, explicitly use svg namespace and generate a document with its own DTD
75             print $svg->xmlify(-namespace=>'svg');
76              
77             # or, explicitly use svg namespace and generate an inline docunent
78             print $svg->xmlify(
79             -namespace => "svg",
80             -pubid => "-//W3C//DTD SVG 1.0//EN",
81             -inline => 1
82             );
83              
84              
85             See the other modules in this distribution:
86             L,
87             L,
88             L,
89             and L.
90              
91             See L for reading SVG files as C objects.
92              
93             =head2 Converting SVG to PNG and other raster image formats
94              
95             The B command of L (also via L ) can convert SVG files to PNG
96             and other formats.
97              
98             L can convert SVG to other format.
99              
100             =head1 EXAMPLES
101              
102             examples/circle.pl generates the following image:
103              
104            
105            
106            
107             I am a title
108            
109            
110            
111            
112            
113              
114             That you can either embed directly into HTML or can include it using:
115              
116            
117              
118             =for HTML

SVG example circle

119              
120             (The image was converted to png using L. See the svg2png.pl script in the examples directory.)
121              
122             =for HTML

SVG example circle

123              
124             See also the B directory in this distribution which contain several fully documented examples.
125              
126             =head1 DESCRIPTION
127              
128             SVG is a 100% Perl module which generates a nested data structure containing the
129             DOM representation of an SVG (Scalable Vector Graphics) image. Using SVG, you
130             can generate SVG objects, embed other SVG instances into it, access the DOM
131             object, create and access javascript, and generate SMIL animation content.
132              
133             =head2 General Steps to generating an SVG document
134              
135             Generating SVG is a simple three step process:
136              
137             =over 4
138              
139             =item 1 Construct a new SVG object with L<"new">.
140              
141             =item 2 Call element constructors such as L<"circle"> and L<"path"> to create SVG elements.
142              
143             =item 3 Render the SVG object into XML using the L<"xmlify"> method.
144              
145             =back
146              
147             The L<"xmlify"> method takes a number of optional arguments that control how SVG
148             renders the object into XML, and in particular determine whether a standalone
149             SVG document or an inline SVG document fragment is generated:
150              
151             =head2 -standalone
152              
153             A complete SVG document with its own associated DTD. A namespace for the SVG
154             elements may be optionally specified.
155              
156             =head2 -inline
157              
158             An inline SVG document fragment with no DTD that be embedded within other XML
159             content. As with standalone documents, an alternate namespace may be specified.
160              
161             No XML content is generated until the third step is reached. Up until this
162             point, all constructed element definitions reside in a DOM-like data structure
163             from which they can be accessed and modified.
164              
165             =head2 EXPORTS
166              
167             None. However, SVG permits both options and additional element methods to be
168             specified in the import list. These options and elements are then available
169             for all SVG instances that are created with the L<"new"> constructor. For example,
170             to change the indent string to two spaces per level:
171              
172             use SVG (-indent => " ");
173              
174             With the exception of -auto, all options may also be specified to the L<"new">
175             constructor. The currently supported options and their default value are:
176              
177             # processing options
178             -auto => 0, # permit arbitrary autoloading of all unrecognised elements
179             -printerror => 1, # print error messages to STDERR
180             -raiseerror => 1, # die on errors (implies -printerror)
181              
182             # rendering options
183             -indent => "\t", # what to indent with
184             -elsep => "\n", # element line (vertical) separator
185             # (note that not all agents ignor trailing blanks)
186             -nocredits => 0, # enable/disable credit note comment
187             -namespace => '', # The root element's (and it's children's) namespace prefix
188              
189             # XML and Doctype declarations
190             -inline => 0, # inline or stand alone
191             -docroot => 'svg', # The document's root element
192             -version => '1.0',
193             -extension => '',
194             -encoding => 'UTF-8',
195             -xml_svg => 'http://www.w3.org/2000/svg', # the svg xmlns attribute
196             -xml_xlink => 'http://www.w3.org/1999/xlink', # the svg tag xmlns:xlink attribute
197             -standalone => 'yes',
198             -pubid => "-//W3C//DTD SVG 1.0//EN", # formerly -identifier
199             -sysid => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd', # the system id
200              
201             SVG also allows additional element generation methods to be specified in the
202             import list. For example to generate 'star' and 'planet' element methods:
203              
204             use SVG qw(star planet);
205              
206             or:
207              
208             use SVG ("star","planet");
209              
210             This will add 'star' to the list of elements supported by SVG.pm (but not of
211             course other SVG parsers...). Alternatively the '-auto' option will allow
212             any unknown method call to generate an element of the same name:
213              
214             use SVG (-auto => 1, "star", "planet");
215              
216             Any elements specified explicitly (as 'star' and 'planet' are here) are
217             predeclared; other elements are defined as and when they are seen by Perl. Note
218             that enabling '-auto' effectively disables compile-time syntax checking for
219             valid method names.
220              
221             use SVG (
222             -auto => 0,
223             -indent => " ",
224             -raiseerror => 0,
225             -printerror => 1,
226             "star", "planet", "moon"
227             );
228              
229             =head2 Default SVG tag
230              
231             The Default SVG tag will generate the following XML:
232              
233             $svg = SVG->new;
234             print $svg->xmlify;
235              
236             Resulting XML snippet:
237              
238            
239            
240            
241            
246              
247             =head1 METHODS
248              
249             SVG provides both explicit and generic element constructor methods. Explicit
250             generators are generally (with a few exceptions) named for the element they
251             generate. If a tag method is required for a tag containing hyphens, the method
252             name replaces the hyphen with an underscore. ie: to generate tag
253             you would use method $svg->column_heading(id=>'new').
254              
255              
256             All element constructors take a hash of element attributes and options;
257             element attributes such as 'id' or 'border' are passed by name, while options for the
258             method (such as the type of an element that supports multiple alternate forms)
259             are passed preceded by a hyphen, e.g '-type'. Both types may be freely
260             intermixed; see the L<"fe"> method and code examples throughout the documentation
261             for more examples.
262              
263             =head2 new (constructor)
264              
265             $svg = SVG->new(%attributes)
266              
267             Creates a new SVG object. Attributes of the document SVG element be passed as
268             an optional list of key value pairs. Additionally, SVG options (prefixed with
269             a hyphen) may be set on a per object basis:
270              
271             my $svg1 = SVG->new;
272              
273             my $svg2 = SVG->new(id => 'document_element');
274              
275             my $svg3 = SVG->new(
276             -printerror => 1,
277             -raiseerror => 0,
278             -indent => ' ',
279             -docroot => 'svg', #default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
280             -sysid => 'abc', #optional system identifyer
281             -pubid => "-//W3C//DTD SVG 1.0//EN", #public identifyer default value is "-//W3C//DTD SVG 1.0//EN" if undefined
282             -namespace => 'mysvg',
283             -inline => 1
284             id => 'document_element',
285             width => 300,
286             height => 200,
287             );
288              
289             BsvgE> root element.>
290              
291             Default SVG options may also be set in the import list. See L<"EXPORTS"> above
292             for more on the available options.
293              
294             Furthermore, the following options:
295              
296              
297             -version
298             -encoding
299             -standalone
300             -namespace Defines the document or element level namespace. The order of assignment priority is element,document .
301             -inline
302             -identifier
303             -nostub
304             -dtd (standalone)
305              
306             may also be set in xmlify, overriding any corresponding values set in the SVG->new declaration
307              
308              
309             =head2 xmlify (alias: to_xml render serialise serialize)
310              
311             $string = $svg->xmlify(%attributes);
312              
313             Returns xml representation of svg document.
314              
315             B
316              
317             Name Default Value
318             -version '1.0'
319             -encoding 'UTF-8'
320             -standalone 'yes'
321             -namespace 'svg' - namespace for elements
322             -inline '0' - If '1', then this is an inline document.
323             -pubid '-//W3C//DTD SVG 1.0//EN';
324             -dtd (standalone) 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
325              
326              
327             =head2 tag (alias: element)
328              
329             $tag = $svg->tag($name, %attributes)
330              
331             Generic element generator. Creates the element named $name with the attributes
332             specified in %attributes. This method is the basis of most of the explicit
333             element generators.
334              
335             my $tag = $svg->tag('g', transform=>'rotate(-45)');
336              
337              
338             =head2 anchor
339              
340             $tag = $svg->anchor(%attributes)
341              
342             Generate an anchor element. Anchors are put around objects to make them
343             'live' (i.e. clickable). It therefore requires a drawn object or group element
344             as a child.
345              
346             =head3 optional anchor attributes
347              
348             the following attributes are expected for anchor tags (any any tags which use -href links):
349              
350             =head2 -href required
351              
352             =head2 -type optional
353              
354             =head2 -role optional
355              
356             =head2 -title optional
357              
358             =head2 -show optional
359              
360             =head2 -arcrole optional
361              
362             =head2 -actuate optional
363              
364             =head2 target optional
365              
366             For more information on the options, refer to the w3c XLink specification at
367             L
368              
369             B
370              
371             # generate an anchor
372             $tag = $SVG->anchor(
373             -href=>'http://here.com/some/simpler/SVG.SVG'
374             -title => 'new window 2 example title',
375             -actuate => 'onLoad',
376             -show=> 'embed',
377              
378             );
379              
380             for more information about the options above, refer to Link section in the SVG recommendation: L
381              
382             # add a circle to the anchor. The circle can be clicked on.
383             $tag->circle(cx => 10, cy => 10, r => 1);
384              
385             # more complex anchor with both URL and target
386             $tag = $SVG->anchor(
387             -href => 'http://somewhere.org/some/other/page.html',
388             target => 'new_window'
389             );
390              
391              
392             # generate an anchor
393             $tag = $svg->anchor(
394             -href=>'http://here.com/some/simpler/svg.svg'
395             );
396             # add a circle to the anchor. The circle can be clicked on.
397             $tag->circle(cx => 10, cy => 10, r => 1);
398              
399             # more complex anchor with both URL and target
400             $tag = $svg->anchor(
401             -href => 'http://somewhere.org/some/other/page.html',
402             target => 'new_window'
403             );
404              
405             =head2 circle
406              
407             $tag = $svg->circle(%attributes)
408              
409             Draw a circle at (cx,cy) with radius r.
410              
411             my $tag = $svg->circle(cx => 4, cy => 2, r => 1);
412              
413             =head2 ellipse
414              
415             $tag = $svg->ellipse(%attributes)
416              
417             Draw an ellipse at (cx,cy) with radii rx,ry.
418              
419             use SVG;
420              
421             # create an SVG object
422             my $svg= SVG->new( width => 200, height => 200);
423              
424             my $tag = $svg->ellipse(
425             cx => 10,
426             cy => 10,
427             rx => 5,
428             ry => 7,
429             id => 'ellipse',
430             style => {
431             'stroke' => 'red',
432             'fill' => 'green',
433             'stroke-width' => '4',
434             'stroke-opacity' => '0.5',
435             'fill-opacity' => '0.2',
436             }
437             );
438              
439             See The B
440              
441             =for HTML

SVG example ellipse

442              
443             =head2 rectangle (alias: rect)
444              
445             $tag = $svg->rectangle(%attributes)
446              
447             Draw a rectangle at (x,y) with width 'width' and height 'height' and side radii
448             'rx' and 'ry'.
449              
450             $tag = $svg->rectangle(
451             x => 10,
452             y => 20,
453             width => 4,
454             height => 5,
455             rx => 5.2,
456             ry => 2.4,
457             id => 'rect_1'
458             );
459              
460             =head2 image
461              
462             $tag = $svg->image(%attributes)
463              
464             Draw an image at (x,y) with width 'width' and height 'height' linked to image
465             resource '-href'. See also L<"use">.
466              
467             $tag = $svg->image(
468             x => 100,
469             y => 100,
470             width => 300,
471             height => 200,
472             '-href' => "image.png", #may also embed SVG, e.g. "image.svg"
473             id => 'image_1'
474             );
475              
476             B
477              
478            
479              
480             =head2 use
481              
482             $tag = $svg->use(%attributes)
483              
484             Retrieve the content from an entity within an SVG document and apply it at
485             (x,y) with width 'width' and height 'height' linked to image resource '-href'.
486              
487             $tag = $svg->use(
488             x => 100,
489             y => 100,
490             width => 300,
491             height => 200,
492             '-href' => "pic.svg#image_1",
493             id => 'image_1'
494             );
495              
496             B
497              
498            
499              
500             According to the SVG specification, the 'use' element in SVG can point to a
501             single element within an external SVG file.
502              
503             =head2 polygon
504              
505             $tag = $svg->polygon(%attributes)
506              
507             Draw an n-sided polygon with vertices at points defined by a string of the form
508             'x1,y1,x2,y2,x3,y3,... xy,yn'. The L<"get_path"> method is provided as a
509             convenience to generate a suitable string from coordinate data.
510              
511             # a five-sided polygon
512             my $xv = [0, 2, 4, 5, 1];
513             my $yv = [0, 0, 2, 7, 5];
514              
515             my $points = $svg->get_path(
516             x => $xv,
517             y => $yv,
518             -type =>'polygon'
519             );
520              
521             my $poly = $svg->polygon(
522             %$points,
523             id => 'pgon1',
524             style => \%polygon_style
525             );
526              
527             SEE ALSO:
528              
529             L<"polyline">, L<"path">, L<"get_path">.
530              
531             =head2 polyline
532              
533             $tag = $svg->polyline(%attributes)
534              
535             Draw an n-point polyline with points defined by a string of the form
536             'x1,y1,x2,y2,x3,y3,... xy,yn'. The L<"get_path"> method is provided as a
537             convenience to generate a suitable string from coordinate data.
538              
539             # a 10-pointsaw-tooth pattern
540             my $xv = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
541             my $yv = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1];
542              
543             my $points = $svg->get_path(
544             x => $xv,
545             y => $yv,
546             -type => 'polyline',
547             -closed => 'true' #specify that the polyline is closed.
548             );
549              
550             my $tag = $svg->polyline (
551             %$points,
552             id =>'pline_1',
553             style => {
554             'fill-opacity' => 0,
555             'stroke' => 'rgb(250,123,23)'
556             }
557             );
558              
559             =head2 line
560              
561             $tag = $svg->line(%attributes)
562              
563             Draw a straight line between two points (x1,y1) and (x2,y2).
564              
565             my $tag = $svg->line(
566             id => 'l1',
567             x1 => 0,
568             y1 => 10,
569             x2 => 10,
570             y2 => 0,
571             );
572              
573             To draw multiple connected lines, use L<"polyline">.
574              
575             =head2 text
576              
577             $text = $svg->text(%attributes)->cdata();
578              
579             $text_path = $svg->text(-type=>'path');
580             $text_span = $text_path->text(-type=>'span')->cdata('A');
581             $text_span = $text_path->text(-type=>'span')->cdata('B');
582             $text_span = $text_path->text(-type=>'span')->cdata('C');
583              
584             Define the container for a text string to be drawn in the image.
585              
586             B
587              
588             -type = path type (path | polyline | polygon)
589             -type = text element type (path | span | normal [default])
590              
591             my $text1 = $svg->text(
592             id => 'l1',
593             x => 10,
594             y => 10
595             )->cdata('hello, world');
596              
597             my $text2 = $svg->text(
598             id => 'l1',
599             x => 10,
600             y => 10,
601             -cdata => 'hello, world',
602             );
603              
604             my $text = $svg->text(
605             id => 'tp',
606             x => 10,
607             y => 10,
608             -type => path,
609             )
610             ->text(id=>'ts' -type=>'span')
611             ->cdata('hello, world');
612              
613             SEE ALSO:
614              
615             L<"desc">, L<"cdata">.
616              
617             =head2 title
618              
619             $tag = $svg->title(%attributes)
620              
621             Generate the title of the image.
622              
623             my $tag = $svg->title(id=>'document-title')->cdata('This is the title');
624              
625             =head2 desc
626              
627             $tag = $svg->desc(%attributes)
628              
629             Generate the description of the image.
630              
631             my $tag = $svg->desc(id=>'document-desc')->cdata('This is a description');
632              
633             =head2 comment
634              
635             $tag = $svg->comment(@comments)
636              
637             Generate the description of the image.
638              
639             my $tag = $svg->comment('comment 1','comment 2','comment 3');
640              
641             =head2 pi (Processing Instruction)
642              
643             $tag = $svg->pi(@pi)
644              
645             Generate a set of processing instructions
646              
647             my $tag = $svg->pi('instruction one','instruction two','instruction three');
648              
649             returns:
650             ?instruction one?
651             ?instruction two?
652             ?instruction three?
653              
654             =head2 script
655              
656             $tag = $svg->script(%attributes)
657              
658             Generate a script container for dynamic (client-side) scripting using
659             ECMAscript, Javascript or other compatible scripting language.
660              
661             my $tag = $svg->script(-type=>"text/ecmascript");
662             #or my $tag = $svg->script();
663             #note that type ecmascript is not Mozilla compliant
664              
665             # populate the script tag with cdata
666             # be careful to manage the javascript line ends.
667             # Use qq{text} or q{text} as appropriate.
668             # make sure to use the CAPITAL CDATA to poulate the script.
669             $tag->CDATA(qq{
670             function d() {
671             //simple display function
672             for(cnt = 0; cnt < d.length; cnt++)
673             document.write(d[cnt]);//end for loop
674             document.write("
");//write a line break
675             }
676             });
677              
678             =head2 path
679              
680             $tag = $svg->path(%attributes)
681              
682             Draw a path element. The path vertices may be provided as a parameter or
683             calculated using the L<"get_path"> method.
684              
685             # a 10-pointsaw-tooth pattern drawn with a path definition
686             my $xv = [0,1,2,3,4,5,6,7,8,9];
687             my $yv = [0,1,0,1,0,1,0,1,0,1];
688              
689             $points = $svg->get_path(
690             x => $xv,
691             y => $yv,
692             -type => 'path',
693             -closed => 'true' #specify that the polyline is closed
694             );
695              
696             $tag = $svg->path(
697             %$points,
698             id => 'pline_1',
699             style => {
700             'fill-opacity' => 0,
701             'fill' => 'green',
702             'stroke' => 'rgb(250,123,23)'
703             }
704             );
705              
706              
707             SEE ALSO: L<"get_path">.
708              
709             =head2 get_path
710              
711             $path = $svg->get_path(%attributes)
712              
713             Returns the text string of points correctly formatted to be incorporated into
714             the multi-point SVG drawing object definitions (path, polyline, polygon)
715              
716             B attributes including:
717              
718             -type = path type (path | polyline | polygon)
719             x = reference to array of x coordinates
720             y = reference to array of y coordinates
721              
722             B a hash reference consisting of the following key-value pair:
723              
724             points = the appropriate points-definition string
725             -type = path|polygon|polyline
726             -relative = 1 (define relative position rather than absolute position)
727             -closed = 1 (close the curve - path and polygon only)
728              
729             #generate an open path definition for a path.
730             my ($points,$p);
731             $points = $svg->get_path(x=>\@x,y=>\@y,-relative=>1,-type=>'path');
732              
733             #add the path to the SVG document
734             my $p = $svg->path(%$path, style=>\%style_definition);
735              
736             #generate an closed path definition for a a polyline.
737             $points = $svg->get_path(
738             x=>\@x,
739             y=>\@y,
740             -relative=>1,
741             -type=>'polyline',
742             -closed=>1
743             ); # generate a closed path definition for a polyline
744              
745             # add the polyline to the SVG document
746             $p = $svg->polyline(%$points, id=>'pline1');
747              
748             B get_path set_path
749              
750              
751             =head2 animate
752              
753             $tag = $svg->animate(%attributes)
754              
755             Generate an SMIL animation tag. This is allowed within any nonempty tag. Refer
756             to the W3C for detailed information on the subtleties of the animate SMIL
757             commands.
758              
759             B -method = Transform | Motion | Color
760              
761             my $an_ellipse = $svg->ellipse(
762             cx => 30,
763             cy => 150,
764             rx => 10,
765             ry => 10,
766             id => 'an_ellipse',
767             stroke => 'rgb(130,220,70)',
768             fill =>'rgb(30,20,50)'
769             );
770              
771             $an_ellipse-> animate(
772             attributeName => "cx",
773             values => "20; 200; 20",
774             dur => "10s",
775             repeatDur => 'indefinite'
776             );
777              
778             $an_ellipse-> animate(
779             attributeName => "rx",
780             values => "10;30;20;100;50",
781             dur => "10s",
782             repeatDur => 'indefinite',
783             );
784              
785             $an_ellipse-> animate(
786             attributeName => "ry",
787             values => "30;50;10;20;70;150",
788             dur => "15s",
789             repeatDur => 'indefinite',
790             );
791              
792             $an_ellipse-> animate(
793             attributeName=>"rx",values=>"30;75;10;100;20;20;150",
794             dur=>"20s", repeatDur=>'indefinite');
795              
796             $an_ellipse-> animate(
797             attributeName=>"fill",values=>"red;green;blue;cyan;yellow",
798             dur=>"5s", repeatDur=>'indefinite');
799              
800             $an_ellipse-> animate(
801             attributeName=>"fill-opacity",values=>"0;1;0.5;0.75;1",
802             dur=>"20s",repeatDur=>'indefinite');
803              
804             $an_ellipse-> animate(
805             attributeName=>"stroke-width",values=>"1;3;2;10;5",
806             dur=>"20s",repeatDur=>'indefinite');
807              
808             =head2 group
809              
810             $tag = $svg->group(%attributes)
811              
812             Define a group of objects with common properties. Groups can have style,
813             animation, filters, transformations, and mouse actions assigned to them.
814              
815             $tag = $svg->group(
816             id => 'xvs000248',
817             style => {
818             'font' => [ qw( Arial Helvetica sans ) ],
819             'font-size' => 10,
820             'fill' => 'red',
821             },
822             transform => 'rotate(-45)'
823             );
824              
825             =head2 defs
826              
827             $tag = $svg->defs(%attributes)
828              
829             define a definition segment. A Defs requires children when defined using SVG.pm
830              
831             $tag = $svg->defs(id => 'def_con_one',);
832              
833             =head2 style
834              
835             $svg->tag('style', %styledef);
836              
837             Sets/Adds style-definition for the following objects being created.
838              
839             Style definitions apply to an object and all its children for all properties for
840             which the value of the property is not redefined by the child.
841              
842             $tag = $SVG->style(%attributes)
843              
844             Generate a style container for inline or xlink:href based styling instructions
845              
846             my $tag = $SVG->style(type=>"text/css");
847              
848             # Populate the style tag with cdata.
849             # Be careful to manage the line ends.
850             # Use qq{text}, where text is the script
851              
852             $tag1->CDATA(qq{
853             rect fill:red;stroke:green;
854             circle fill:red;stroke:orange;
855             ellipse fill:none;stroke:yellow;
856             text fill:black;stroke:none;
857             });
858              
859             # Create a external CSS stylesheet reference
860             my $tag2 = $SVG->style(type=>"text/css", -href="/resources/example.css");
861              
862             =pod
863              
864              
865             =head2 mouseaction
866              
867             $svg->mouseaction(%attributes)
868              
869             Sets/Adds mouse action definitions for tag
870              
871             =head2 attrib
872              
873             $svg->attrib($name, $value)
874              
875             Sets/Adds attributes of an element.
876              
877             Retrieve an attribute:
878              
879             $svg->attrib($name);
880              
881             Set a scalar attribute:
882              
883             $SVG->attrib $name, $value
884              
885             Set a list attribute:
886              
887             $SVG->attrib $name, \@value
888              
889             Set a hash attribute (i.e. style definitions):
890              
891             $SVG->attrib $name, \%value
892              
893             Remove an attribute:
894              
895             $svg->attrib($name,undef);
896              
897             B attr attribute
898              
899             Sets/Replaces attributes for a tag.
900              
901             =head2 cdata
902              
903             $svg->cdata($text)
904              
905             Sets cdata to $text. SVG.pm allows you to set cdata for any tag. If the tag is
906             meant to be an empty tag, SVG.pm will not complain, but the rendering agent will
907             fail. In the SVG DTD, cdata is generally only meant for adding text or script
908             content.
909              
910             $svg->text(
911             style => {
912             'font' => 'Arial',
913             'font-size' => 20
914             })->cdata('SVG.pm is a perl module on CPAN!');
915              
916             my $text = $svg->text( style => { 'font' => 'Arial', 'font-size' => 20 } );
917             $text->cdata('SVG.pm is a perl module on CPAN!');
918              
919             B
920              
921             SVG.pm is a perl module on CPAN!
922              
923             SEE ALSO:
924              
925             L<"CDATA">, L<"desc">, L<"title">, L<"text">, L<"script">.
926              
927             =head2 cdata_noxmlesc
928              
929             $script = $svg->script();
930             $script->cdata_noxmlesc($text);
931              
932             Generates cdata content for text and similar tags which do not get xml-escaped.
933             In othe words, does not parse the content and inserts the exact string into the cdata location.
934              
935             =head2 CDATA
936              
937             $script = $svg->script();
938             $script->CDATA($text);
939              
940             Generates a tag with the contents of $text rendered exactly as supplied. SVG.pm allows you to set cdata for any tag. If the tag is
941             meant to be an empty tag, SVG.pm will not complain, but the rendering agent will
942             fail. In the SVG DTD, cdata is generally only meant for adding text or script
943             content.
944              
945             my $text = qq{
946             var SVGDoc;
947             var groups = new Array();
948             var last_group;
949              
950             /*****
951             *
952             * init
953             *
954             * Find this SVG's document element
955             * Define members of each group by id
956             *
957             *****/
958             function init(e) {
959             SVGDoc = e.getTarget().getOwnerDocument();
960             append_group(1, 4, 6); // group 0
961             append_group(5, 4, 3); // group 1
962             append_group(2, 3); // group 2
963             }};
964             $svg->script()->CDATA($text);
965              
966              
967             B
968              
969             Escript E
970             ![CDATA[
971             var SVGDoc;
972             var groups = new Array();
973             var last_group;
974              
975             /*****
976             *
977             * init
978             *
979             * Find this SVG's document element
980             * Define members of each group by id
981             *
982             *****/
983             function init(e) {
984             SVGDoc = e.getTarget().getOwnerDocument();
985             append_group(1, 4, 6); // group 0
986             append_group(5, 4, 3); // group 1
987             append_group(2, 3); // group 2
988             }
989             ]]E
990              
991             SEE ALSO: L<"cdata">, L<"script">.
992              
993             =head2 xmlescp and xmlescape
994              
995             $string = $svg->xmlescp($string)
996             $string = $svg->xmlesc($string)
997             $string = $svg->xmlescape($string)
998              
999             SVG module does not xml-escape characters that are incompatible with the XML specification. B and B provides this functionality. It is a helper function which generates an XML-escaped string for reserved characters such as ampersand, open and close brackets, etcetera.
1000              
1001             The behaviour of xmlesc is to apply the following transformation to the input string $s:
1002              
1003             $s=~s/&(?!#(x\w\w|\d+?);)/&/g;
1004             $s=~s/>/>/g;
1005             $s=~s/
1006             $s=~s/\"/"/g;
1007             $s=~s/\'/'/g;
1008             $s=~s/([\x00-\x08\x0b\x1f])/''/eg;
1009             $s=~s/([\200-\377])/'&#'.ord($1).';'/ge;
1010              
1011              
1012             =head2 filter
1013              
1014             $tag = $svg->filter(%attributes)
1015              
1016             Generate a filter. Filter elements contain L<"fe"> filter sub-elements.
1017              
1018             my $filter = $svg->filter(
1019             filterUnits=>"objectBoundingBox",
1020             x=>"-10%",
1021             y=>"-10%",
1022             width=>"150%",
1023             height=>"150%",
1024             filterUnits=>'objectBoundingBox'
1025             );
1026              
1027             $filter->fe();
1028              
1029             SEE ALSO: L<"fe">.
1030              
1031             =head2 fe
1032              
1033             $tag = $svg->fe(-type=>'type', %attributes)
1034              
1035             Generate a filter sub-element. Must be a child of a L<"filter"> element.
1036              
1037             my $fe = $svg->fe(
1038             -type => 'DiffuseLighting' # required - element name omitting 'fe'
1039             id => 'filter_1',
1040             style => {
1041             'font' => [ qw(Arial Helvetica sans) ],
1042             'font-size' => 10,
1043             'fill' => 'red',
1044             },
1045             transform => 'rotate(-45)'
1046             );
1047              
1048             Note that the following filter elements are currently supported:
1049             Also note that the elelemts are defined in lower case in the module, but as of version 2.441, any case combination is allowed.
1050              
1051              
1052             =head2 * feBlend
1053              
1054             =head2 * feColorMatrix
1055              
1056             =head2 * feComponentTransfer
1057              
1058             =head2 * feComposite
1059              
1060             =head2 * feConvolveMatrix
1061              
1062             =head2 * feDiffuseLighting
1063              
1064             =head2 * feDisplacementMap
1065              
1066             =head2 * feDistantLight
1067              
1068             =head2 * feFlood
1069              
1070             =head2 * feFuncA
1071              
1072             =head2 * feFuncB
1073              
1074             =head2 * feFuncG
1075              
1076             =head2 * feFuncR
1077              
1078             =head2 * feGaussianBlur
1079              
1080             =head2 * feImage
1081              
1082             =head2 * feMerge
1083              
1084             =head2 * feMergeNode
1085              
1086             =head2 * feMorphology
1087              
1088             =head2 * feOffset
1089              
1090             =head2 * fePointLight
1091              
1092             =head2 * feSpecularLighting
1093              
1094             =head2 * feSpotLight
1095              
1096             =head2 * feTile
1097              
1098             =head2 * feTurbulence
1099              
1100              
1101             SEE ALSO: L<"filter">.
1102              
1103             =head2 pattern
1104              
1105             $tag = $svg->pattern(%attributes)
1106              
1107             Define a pattern for later reference by url.
1108              
1109              
1110             my $pattern = $svg->pattern(
1111             id => "Argyle_1",
1112             width => "50",
1113             height => "50",
1114             patternUnits => "userSpaceOnUse",
1115             patternContentUnits => "userSpaceOnUse"
1116             );
1117              
1118             =head2 set
1119              
1120             $tag = $svg->set(%attributes)
1121              
1122             Set a definition for an SVG object in one section, to be referenced in other
1123             sections as needed.
1124              
1125             my $set = $svg->set(
1126             id => "Argyle_1",
1127             width => "50",
1128             height => "50",
1129             patternUnits => "userSpaceOnUse",
1130             patternContentUnits => "userSpaceOnUse"
1131             );
1132              
1133             =head2 stop
1134              
1135             $tag = $svg->stop(%attributes)
1136              
1137             Define a stop boundary for L<"gradient">
1138              
1139             my $pattern = $svg->stop(
1140             id => "Argyle_1",
1141             width => "50",
1142             height => "50",
1143             patternUnits => "userSpaceOnUse",
1144             patternContentUnits => "userSpaceOnUse"
1145             );
1146              
1147             =head2 gradient
1148              
1149             $tag = $svg->gradient(%attributes)
1150              
1151             Define a color gradient. Can be of type B or B
1152              
1153             my $gradient = $svg->gradient(
1154             -type => "linear",
1155             id => "gradient_1"
1156             );
1157              
1158             =head1 GENERIC ELEMENT METHODS
1159              
1160             The following elements are generically supported by SVG:
1161              
1162              
1163             =head2 * altGlyph
1164              
1165             =head2 * altGlyphDef
1166              
1167             =head2 * altGlyphItem
1168              
1169             =head2 * clipPath
1170              
1171             =head2 * color-profile
1172              
1173             =head2 * cursor
1174              
1175             =head2 * definition-src
1176              
1177             =head2 * font-face-format
1178              
1179             =head2 * font-face-name
1180              
1181             =head2 * font-face-src
1182              
1183             =head2 * font-face-url
1184              
1185             =head2 * foreignObject
1186              
1187             =head2 * glyph
1188              
1189             =head2 * glyphRef
1190              
1191             =head2 * hkern
1192              
1193             =head2 * marker
1194              
1195             =head2 * mask
1196              
1197             =head2 * metadata
1198              
1199             =head2 * missing-glyph
1200              
1201             =head2 * mpath
1202              
1203             =head2 * switch
1204              
1205             =head2 * symbol
1206              
1207             =head2 * tref
1208              
1209             =head2 * view
1210              
1211             =head2 * vkern
1212              
1213             See e.g. L<"pattern"> for an example of the use of these methods.
1214              
1215             =head1 METHODS IMPORTED BY SVG::DOM
1216              
1217             The following L elements are accessible through SVG:
1218              
1219             =head2 * getChildren
1220              
1221             =head2 * getFirstChild
1222              
1223             =head2 * getNextChild
1224              
1225             =head2 * getLastChild
1226              
1227             =head2 * getParent
1228              
1229             =head2 * getParentElement
1230              
1231             =head2 * getSiblings
1232              
1233             =head2 * getElementByID
1234              
1235             =head2 * getElementID
1236              
1237             =head2 * getElements
1238              
1239             =head2 * getElementName
1240              
1241             =head2 * getType
1242              
1243             =head2 * getAttributes
1244              
1245             =head2 * getAttribute
1246              
1247             =head2 * setAttributes
1248              
1249             =head2 * setAttribute
1250              
1251             =head2 * insertBefore
1252              
1253             =head2 * insertAfter
1254              
1255             =head2 * insertSiblingBefore
1256              
1257             =head2 * insertSiblingAfter
1258              
1259             =head2 * replaceChild
1260              
1261             =head2 * removeChild
1262              
1263             =head2 * cloneNode
1264              
1265              
1266             =cut
1267              
1268             #-------------------------------------------------------------------------------
1269              
1270             my %default_attrs = (
1271              
1272             # processing options
1273             -auto => 0, # permit arbitrary autoloads (only at import)
1274             -printerror => 1, # print error messages to STDERR
1275             -raiseerror => 1, # die on errors (implies -printerror)
1276              
1277             # rendering options
1278             -indent => "\t", # what to indent with
1279             -elsep => "\n", # element line (vertical) separator
1280             -nocredits => 0, # enable/disable credit note comment
1281             -namespace =>
1282             '', # The root element's (and it's children's) namespace prefix
1283              
1284             # XML and Doctype declarations
1285             -inline => 0, # inline or stand alone
1286             -docroot => 'svg', # The document's root element
1287             -version => '1.0',
1288             -extension => '',
1289             -encoding => 'UTF-8',
1290             -xml_svg => 'http://www.w3.org/2000/svg',
1291             -xml_xlink => 'http://www.w3.org/1999/xlink',
1292             -standalone => 'yes',
1293             -pubid => '-//W3C//DTD SVG 1.0//EN', # formerly -identifier
1294             -sysid => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd',
1295             );
1296              
1297             sub import {
1298 27     27   1988 my $package = shift;
1299              
1300 27         55 my $attr = undef;
1301 27         75 foreach (@_) {
1302 21 100       65 if ($attr) {
    100          
1303 7         16 $default_attrs{$attr} = $_;
1304 7         16 undef $attr;
1305             }
1306             elsif ( exists $default_attrs{$_} ) {
1307 7         14 $attr = $_;
1308             }
1309             else {
1310 7 50       22 /^-/ and die "Unknown attribute '$_' in import list\n";
1311 7         20 $SVG::Element::autosubs{$_}
1312             = 1; # add to list of autoloadable tags
1313             }
1314             }
1315              
1316             # switch on AUTOLOADer, if asked.
1317 27 100       114 if ( $default_attrs{'-auto'} ) {
1318 1         4 *SVG::Element::AUTOLOAD = \&SVG::Element::autoload;
1319             }
1320              
1321             # predeclare any additional elements asked for by the user
1322 27         235 foreach my $sub ( keys %SVG::Element::autosubs ) {
1323 1282         2556 $SVG::Element::AUTOLOAD = ("SVG::Element::$sub");
1324 1282         2182 SVG::Element::autoload();
1325             }
1326              
1327 27         132 delete $default_attrs{-auto}; # -auto is only allowed here, not in new
1328              
1329 27         38702 return ();
1330             }
1331              
1332             #-------------------------------------------------------------------------------
1333              
1334             =pod
1335              
1336             =head1 Methods
1337              
1338             SVG provides both explicit and generic element constructor methods. Explicit
1339             generators are generally (with a few exceptions) named for the element they
1340             generate. If a tag method is required for a tag containing hyphens, the method
1341             name replaces the hyphen with an underscore. ie: to generate tag
1342             you would use method $svg->column_heading(id=>'new').
1343              
1344              
1345             All element constructors take a hash of element attributes and options;
1346             element attributes such as 'id' or 'border' are passed by name, while options for the
1347             method (such as the type of an element that supports multiple alternate forms)
1348             are passed preceded by a hyphen, e.g '-type'. Both types may be freely
1349             intermixed; see the L<"fe"> method and code examples throughout the documentation
1350             for more examples.
1351              
1352             =head2 new (constructor)
1353              
1354             $svg = SVG->new(%attributes)
1355              
1356             Creates a new SVG object. Attributes of the document SVG element be passed as
1357             an optional list of key value pairs. Additionally, SVG options (prefixed with
1358             a hyphen) may be set on a per object basis:
1359              
1360             my $svg1 = SVG->new;
1361              
1362             my $svg2 = SVG->new(id => 'document_element');
1363              
1364             my $svg3 = SVG->new(
1365             -printerror => 1,
1366             -raiseerror => 0,
1367             -indent => ' ',
1368             -elsep => "\n", # element line (vertical) separator
1369             -docroot => 'svg', # default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
1370             -xml_xlink => 'http://www.w3.org/1999/xlink', # required by Mozilla's embedded SVG engine
1371             -sysid => 'abc', # optional system identifier
1372             -pubid => "-//W3C//DTD SVG 1.0//EN", # public identifier default value is "-//W3C//DTD SVG 1.0//EN" if undefined
1373             -namespace => 'mysvg',
1374             -inline => 1
1375             id => 'document_element',
1376             width => 300,
1377             height => 200,
1378             );
1379              
1380             Default SVG options may also be set in the import list. See L<"EXPORTS"> above
1381             for more on the available options.
1382              
1383             Furthermore, the following options:
1384              
1385             -version
1386             -encoding
1387             -standalone
1388             -namespace
1389             -inline
1390             -pubid (formerly -identifier)
1391             -sysid (standalone)
1392              
1393             may also be set in xmlify, overriding any corresponding values set in the SVG->new declaration
1394              
1395             =cut
1396              
1397             #-------------------------------------------------------------------------------
1398             #
1399             # constructor for the SVG data model.
1400             #
1401             # the new constructor creates a new data object with a document tag at its base.
1402             # this document tag then has either:
1403             # a child entry parent with its child svg generated (when -inline = 1)
1404             # or
1405             # a child entry svg created.
1406             #
1407             # Because the new method returns the $self reference and not the
1408             # latest child to be created, a hash key -document with the reference to the hash
1409             # entry of its already-created child. hence the document object has a -document reference
1410             # to parent or svg if inline is 1 or 0, and parent will have a -document entry
1411             # pointing to the svg child.
1412             #
1413             # This way, the next tag constructor will descend the
1414             # tree until it finds no more tags with -document, and will add
1415             # the next tag object there.
1416             # refer to the SVG::tag method
1417              
1418             sub new {
1419 33     33 1 18979 my ( $proto, %attrs ) = @_;
1420              
1421 33   33     228 my $class = ref $proto || $proto;
1422 33         60 my $self;
1423              
1424             # establish defaults for unspecified attributes
1425 33         256 foreach my $attr ( keys %default_attrs ) {
1426 533 100       1223 $attrs{$attr} = $default_attrs{$attr} unless exists $attrs{$attr};
1427             }
1428 33         309 $self = $class->SUPER::new('document');
1429 33 50       274 if ( not $self->{-docref} ) {
1430 33         81 $self->{-docref} = $self;
1431 33         160 weaken( $self->{-docref} );
1432             }
1433 33 50       112 unless ( $attrs{-namespace} ) {
1434 33   33     169 $attrs{'xmlns'} = $attrs{'xmlns'} || $attrs{'-xml_svg'};
1435             }
1436             $attrs{'xmlns:xlink'}
1437             = $attrs{'xmlns:xlink'}
1438 33   50     222 || $attrs{'-xml_xlink'}
1439             || 'http://www.w3.org/1999/xlink';
1440             $attrs{'xmlns:svg'}
1441             = $attrs{'xmlns:svg'}
1442 33   50     255 || $attrs{'-xml_svg'}
1443             || 'http://www.w3.org/2000/svg';
1444              
1445 33         81 $self->{-level} = 0;
1446 33         396 $self->{$_} = $attrs{$_} foreach keys %default_attrs;
1447              
1448             # create SVG object according to nostub attribute
1449 33         84 my $svg;
1450 33 50       101 unless ( $attrs{-nostub} ) {
1451 33         274 $svg = $self->svg(%attrs);
1452 33         108 $self->{-document} = $svg;
1453 33         141 weaken( $self->{-document} );
1454             }
1455              
1456             # add -attributes to SVG object
1457             # $self->{-elrefs}->{$self}->{name} = 'document';
1458             # $self->{-elrefs}->{$self}->{id} = '';
1459              
1460 33         203 return $self;
1461             }
1462              
1463             #-------------------------------------------------------------------------------
1464              
1465             =pod
1466              
1467             =head2 xmlify (alias: to_xml render serialize serialise )
1468              
1469             $string = $svg->xmlify(%attributes);
1470              
1471             Returns xml representation of svg document.
1472              
1473             B
1474              
1475             Name Default Value
1476             -version '1.0'
1477             -encoding 'UTF-8'
1478             -standalone 'yes'
1479             -namespace 'svg' - namespace prefix for elements.
1480             Can also be used in any element method to over-ride
1481             the current namespace prefix. Make sure to have
1482             declared the prefix before using it.
1483             -inline '0' - If '1', then this is an inline document.
1484             -pubid '-//W3C//DTD SVG 1.0//EN';
1485             -sysid 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
1486              
1487             =cut
1488              
1489             sub xmlify {
1490 23     23 1 9409 my ( $self, %attrs ) = @_;
1491              
1492 23         54 my ( $decl, $ns );
1493              
1494 23         58 my $credits = '';
1495              
1496             # Give the module and myself credit unless explicitly turned off
1497 23 100 100     178 unless ( $self->{-docref}->{-nocredits}
1498             or $self->{-docref}{-creditsinserted} )
1499             {
1500 17         176 $self->comment(
1501             "\n\tGenerated using the Perl SVG Module V$VERSION\n\tby Ronan Oger\n\tInfo: http://www.roitsystems.com/\n\t"
1502             );
1503 17         46 $self->{-docref}{-creditsinserted} = 1;
1504             }
1505              
1506 23         70 foreach my $key ( keys %attrs ) {
1507 2 50       11 next if $key !~ /^-/;
1508 2         5 $self->{$key} = $attrs{$key};
1509             }
1510              
1511 23         121 foreach my $key ( keys %$self ) {
1512 551 50       1227 next if $key !~ /^-/;
1513 551   100     1488 $attrs{$key} ||= $self->{$key};
1514             }
1515              
1516 23         218 return $self->SUPER::xmlify( $self->{-namespace} );
1517             }
1518              
1519             *render = \&xmlify;
1520             *to_xml = \&xmlify;
1521             *serialise = \&xmlify;
1522             *serialize = \&xmlify;
1523              
1524             =head2 perlify ()
1525              
1526             return the perl code which generates the SVG document as it currently exists.
1527              
1528             =cut
1529              
1530             sub perlify {
1531 0     0 1   return shift->SUPER::perlify();
1532             }
1533              
1534             =head2 toperl ()
1535              
1536             Alias for method perlify()
1537              
1538             =cut
1539              
1540             *toperl = \&perlify;
1541              
1542             1;
1543              
1544             =pod
1545              
1546             =head1 AUTHOR
1547              
1548             Ronan Oger, RO IT Systemms GmbH, cpan@roitsystems.com
1549              
1550             =head1 MAINTAINER
1551              
1552             L
1553              
1554             =head1 CREDITS
1555              
1556             I would like to thank the following people for contributing to this module with
1557             patches, testing, suggestions, and other nice tidbits:
1558              
1559             Peter Wainwright, Excellent ideas, beta-testing, writing SVG::Parser and much of SVG::DOM.
1560             Fredo, http://www.penguin.at0.net/~fredo/ - provided example code and initial feedback for early SVG.pm versions and the idea of a simplified svg generator.
1561             Adam Schneider,
1562             Brial Pilpré,
1563             Ian Hickson
1564             Steve Lihn,
1565             Allen Day
1566             Martin Owens - SVG::DOM improvements in version 3.34
1567              
1568             =head1 COPYRIGHT & LICENSE
1569              
1570             Copyright 2001- Ronan Oger
1571              
1572             The modules in the SVG distribution are distributed under the same license
1573             as Perl itself. It is provided free of warranty and may be re-used freely.
1574              
1575             =head1 ARTICLES
1576              
1577             L
1578              
1579             L
1580              
1581             L
1582              
1583             =head1 SEE ALSO
1584              
1585             L,
1586             L,
1587             L,
1588             L,
1589             L
1590              
1591             For Commercial Perl/SVG development, refer to the following sites:
1592             L.
1593              
1594             =cut