Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SVG - Perl extension for generating Scalable Vector Graphics (SVG) documents | |
6 | ||
7 | =cut | |
8 | ||
9 | package SVG; | |
10 | ||
11 | use strict; | |
12 | use vars qw($VERSION @ISA $AUTOLOAD); | |
13 | use Exporter; | |
14 | use SVG::XML; | |
15 | use SVG::Element; | |
16 | use SVG::Extension; | |
17 | ||
18 | @ISA = qw(SVG::Element SVG::Extension); | |
19 | ||
20 | $VERSION = "2.28"; | |
21 | ||
22 | #------------------------------------------------------------------------------- | |
23 | ||
24 | =pod | |
25 | ||
26 | =head2 VERSION | |
27 | ||
28 | Version 2.26, 12.01.03 | |
29 | ||
30 | Refer to L<SVG::Manual> for the complete manual | |
31 | ||
32 | =head1 DESCRIPTION | |
33 | ||
34 | SVG is a 100% Perl module which generates a nested data structure containing the | |
35 | DOM representation of an SVG (Scalable Vector Graphics) image. Using SVG, you | |
36 | can generate SVG objects, embed other SVG instances into it, access the DOM | |
37 | object, create and access javascript, and generate SMIL animation content. | |
38 | ||
39 | Refer to L<SVG::Manual> for the complete manual. | |
40 | ||
41 | =head1 AUTHOR | |
42 | ||
43 | Ronan Oger, RO IT Systemms GmbH, ronan@roasp.com | |
44 | ||
45 | =head1 CREDITS | |
46 | ||
47 | Peter Wainwright, peter@roasp.com Excellent ideas, beta-testing, SVG::Parser | |
48 | ||
49 | ||
50 | =head1 EXAMPLES | |
51 | ||
52 | http://www.roasp.com/index.shtml?svg.pod | |
53 | ||
54 | =head1 SEE ALSO | |
55 | ||
56 | perl(1),L<SVG>,L<SVG::DOM>,L<SVG::XML>,L<SVG::Element>,L<SVG::Parser>, L<SVG::Manual> | |
57 | http://www.roasp.com/ | |
58 | http://www.perlsvg.com/ | |
59 | http://www.roitsystems.com/ | |
60 | http://www.w3c.org/Graphics/SVG/ | |
61 | ||
62 | =cut | |
63 | ||
64 | ||
65 | #------------------------------------------------------------------------------- | |
66 | ||
67 | my %default_attrs = ( | |
68 | # processing options | |
69 | -auto => 0, # permit arbitrary autoloads (only at import) | |
70 | -printerror => 1, # print error messages to STDERR | |
71 | -raiseerror => 1, # die on errors (implies -printerror) | |
72 | ||
73 | # rendering options | |
74 | -indent => "\t", # what to indent with | |
75 | -elsep => "\n", # element line (vertical) separator | |
76 | -nocredits => 0, # enable/disable credit note comment | |
77 | -namespace => '', # The root element's (and it's children's) namespace | |
78 | ||
79 | # XML and Doctype declarations | |
80 | -inline => 0, # inline or stand alone | |
81 | -docroot => 'svg', # The document's root element | |
82 | -version => '1.0', | |
83 | -extension => '', | |
84 | -encoding => 'UTF-8', | |
85 | -standalone => 'yes', | |
86 | -pubid => "-//W3C//DTD SVG 1.0//EN", # formerly -identifier | |
87 | -sysid => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd', | |
88 | ); | |
89 | ||
90 | sub import { | |
91 | my $package=shift; | |
92 | ||
93 | my $attr=undef; | |
94 | foreach (@_) { | |
95 | if ($attr) { | |
96 | $default_attrs{$attr}=$_; | |
97 | undef $attr; | |
98 | } elsif (exists $default_attrs{$_}) { | |
99 | $attr=$_; | |
100 | } else { | |
101 | /^-/ and die "Unknown attribute '$_' in import list\n"; | |
102 | $SVG::Element::autosubs{$_}=1; # add to list of autoloadable tags | |
103 | } | |
104 | } | |
105 | ||
106 | # switch on AUTOLOADer, if asked. | |
107 | if ($default_attrs{'-auto'}) { | |
108 | *SVG::Element::AUTOLOAD=\&SVG::Element::autoload; | |
109 | } | |
110 | ||
111 | # predeclare any additional elements asked for by the user | |
112 | foreach my $sub (keys %SVG::Element::autosubs) { | |
113 | $SVG::Element::AUTOLOAD=("SVG::Element::$sub"); | |
114 | SVG::Element::autoload(); | |
115 | } | |
116 | ||
117 | delete $default_attrs{-auto}; # -auto is only allowed here, not in new | |
118 | ||
119 | return (); | |
120 | } | |
121 | ||
122 | #------------------------------------------------------------------------------- | |
123 | ||
124 | =pod | |
125 | ||
126 | =head1 Methods | |
127 | ||
128 | SVG provides both explicit and generic element constructor methods. Explicit | |
129 | generators are generally (with a few exceptions) named for the element they | |
130 | generate. If a tag method is required for a tag containing hyphens, the method | |
131 | name replaces the hyphen with an underscore. ie: to generate tag <column-heading id="new"> | |
132 | you would use method $svg->column_heading(id=>'new'). | |
133 | ||
134 | ||
135 | All element constructors take a hash of element attributes and options; | |
136 | element attributes such as 'id' or 'border' are passed by name, while options for the | |
137 | method (such as the type of an element that supports multiple alternate forms) | |
138 | are passed preceded by a hyphen, e.g '-type'. Both types may be freely | |
139 | intermixed; see the L<"fe"> method and code examples througout the documentation | |
140 | for more examples. | |
141 | ||
142 | =head2 new (constructor) | |
143 | ||
144 | $svg = SVG->new(%attributes) | |
145 | ||
146 | Creates a new SVG object. Attributes of the document SVG element be passed as | |
147 | an optional list of key value pairs. Additionally, SVG options (prefixed with | |
148 | a hyphen) may be set on a per object basis: | |
149 | ||
150 | B<Example:> | |
151 | ||
152 | my $svg1=new SVG; | |
153 | ||
154 | my $svg2=new SVG(id => 'document_element'); | |
155 | ||
156 | my $svg3=new SVG( | |
157 | -printerror => 1, | |
158 | -raiseerror => 0, | |
159 | -indent => ' ', | |
160 | -elsep =>"\n", # element line (vertical) separator | |
161 | -docroot => 'svg', #default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined | |
162 | -sysid => 'abc', #optional system identifyer | |
163 | -pubid => "-//W3C//DTD SVG 1.0//EN", #public identifyer default value is "-//W3C//DTD SVG 1.0//EN" if undefined | |
164 | -namespace => 'mysvg', | |
165 | -inline => 1 | |
166 | id => 'document_element', | |
167 | width => 300, | |
168 | height => 200, | |
169 | ); | |
170 | ||
171 | Default SVG options may also be set in the import list. See L<"EXPORTS"> above | |
172 | for more on the available options. | |
173 | ||
174 | Furthermore, the following options: | |
175 | ||
176 | -version | |
177 | -encoding | |
178 | -standalone | |
179 | -namespace | |
180 | -inline | |
181 | -pubid (formerly -identifier) | |
182 | -sysid (standalone) | |
183 | ||
184 | may also be set in xmlify, overriding any corresponding values set in the SVG->new declaration | |
185 | ||
186 | =cut | |
187 | ||
188 | #------------------------------------------------------------------------------- | |
189 | # | |
190 | # constructor for the SVG data model. | |
191 | # | |
192 | # the new constructor creates a new data object with a document tag at its base. | |
193 | # this document tag then has either: | |
194 | # a child entry parent with its child svg generated (when -inline = 1) | |
195 | # or | |
196 | # a child entry svg created. | |
197 | # | |
198 | # Because the new method returns the $self reference and not the | |
199 | # latest child to be created, a hash key -document with the reference to the hash | |
200 | # entry of its already-created child. hence the document object has a -document reference | |
201 | # to parent or svg if inline is 1 or 0, and parent will have a -document entry | |
202 | # pointing to the svg child. | |
203 | # | |
204 | # This way, the next tag constructor will descend the | |
205 | # tree until it finds no more tags with -document, and will add | |
206 | # the next tag object there. | |
207 | # refer to the SVG::tag method | |
208 | ||
209 | sub new ($;@) { | |
210 | my ($proto,%attrs)=@_; | |
211 | my $class=ref $proto || $proto; | |
212 | my $self; | |
213 | ||
214 | # establish defaults for unspecified attributes | |
215 | foreach my $attr (keys %default_attrs) { | |
216 | $attrs{$attr}=$default_attrs{$attr} unless exists $attrs{$attr} | |
217 | } | |
218 | $self = $class->SUPER::new('document'); | |
219 | $self->{-docref} = $self unless ($self->{-docref}); | |
220 | $self->{-level} = 0; | |
221 | $self->{$_} = $attrs{$_} foreach keys %default_attrs; | |
222 | ||
223 | # create SVG object according to nostub attribute | |
224 | my $svg; | |
225 | unless ($attrs{-nostub}) { | |
226 | $svg = $self->svg(%attrs); | |
227 | $self->{-document} = $svg; | |
228 | } | |
229 | ||
230 | # add -attributes to SVG object | |
231 | # $self->{-elrefs}->{$self}->{name} = 'document'; | |
232 | # $self->{-elrefs}->{$self}->{id} = ''; | |
233 | ||
234 | return $self; | |
235 | } | |
236 | ||
237 | #------------------------------------------------------------------------------- | |
238 | ||
239 | =pod | |
240 | ||
241 | =head2 xmlify (alias: to_xml render) | |
242 | ||
243 | $string = $svg->xmlify(%attributes); | |
244 | ||
245 | Returns xml representation of svg document. | |
246 | ||
247 | B<XML Declaration> | |
248 | ||
249 | Name Default Value | |
250 | -version '1.0' | |
251 | -encoding 'UTF-8' | |
252 | -standalone 'yes' | |
253 | -namespace 'svg' - namespace for elements. | |
254 | Can also be used in any element method to over-ride | |
255 | the current namespace | |
256 | -inline '0' - If '1', then this is an inline document. | |
257 | -pubid '-//W3C//DTD SVG 1.0//EN'; | |
258 | -sysid 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd' | |
259 | ||
260 | =cut | |
261 | ||
262 | sub xmlify ($;@) { | |
263 | ||
264 | my ($self,%attrs) = @_; | |
265 | my ($decl,$ns); | |
266 | ||
267 | my $credits = ''; | |
268 | ||
269 | # Give the module and myself credit unless explicitly turned off | |
270 | unless ($self->{-docref}->{-nocredits}) { | |
271 | $self->comment("\n\tGenerated using the Perl SVG Module V$VERSION\n\tby Ronan Oger\n\tInfo: http://www.roasp.com/\n" ); | |
272 | } | |
273 | ||
274 | foreach my $key (keys %attrs) { | |
275 | next unless ($key =~ /^\-/); | |
276 | $self->{$key} = $attrs{$key}; | |
277 | } | |
278 | ||
279 | foreach my $key (keys %$self) { | |
280 | next unless ($key =~ /^\-/); | |
281 | $attrs{$key} ||= $self->{$key}; | |
282 | } | |
283 | ||
284 | return $self->SUPER::xmlify($self->{-namespace}); | |
285 | } | |
286 | *render=\&xmlify; | |
287 | *to_xml=\&xmlify; | |
288 | ||
289 | sub perlify ($;@) { | |
290 | return shift->SUPER::perlify(); | |
291 | } | |
292 | *toperl=\&perlify; | |
293 | ||
294 | #------------------------------------------------------------------------------- | |
295 | ||
296 | 1; |