SVG::Parser(3pm)

1SVG::Parser(3pm)      User Contributed Perl Documentation     SVG::Parser(3pm)
2
3
4

NAME

6       SVG::Parser - XML Parser for SVG documents
7

SYNOPSIS

9         #!/usr/bin/perl -w
10         use strict;
11         use SVG::Parser;
12
13         die "Usage: $0 <file>\n" unless @ARGV;
14
15         my $xml;
16         {
17             local $/=undef;
18             $xml=<>;
19         }
20
21         my $parser=new SVG::Parser(-debug => 1);
22         my $svg=$parser->parse($xml);
23         print $svg->xmlify;
24
25         and:
26
27         #!/usr/bin/perl -w
28         use strict;
29         use SVG::Parser qw(SAX=XML::LibXML::Parser::SAX Expat SAX);
30
31         die "Usage: $0 <file>\n" unless @ARGV;
32         my $svg=SVG::Parser->new()->parsefile($ARGV[0]);
33         print $svg->xmlify;
34

DESCRIPTION

36       SVG::Parser is an XML parser for SVG Documents. It takes XML as input
37       and produces an SVG object as its output.
38
39       SVG::Parser supports both XML::SAX and XML::Parser (Expat) parsers,
40       with SAX preferred by default. Only one of these needs to be installed
41       for SVG::Parser to function.
42
43       A list of preferred parsers may be specified in the import list -
44       SVG::Parser will use the first parser that successfully loads. Some
45       basic measures are taken to provide cross-compatability. Applications
46       requiring more advanced parser features should use the relevant parser
47       module directly; see SVG::Parser::Expat and SVG::Parser::SAX.
48
49   METHODS
50       SVG::Parser provides all methods supported by its parent parser class.
51       In addition it provides the following:
52
53       •   new([%attrs])
54
55           Create a new SVG::Parser object. Optional attributes may be passed
56           as arguments; all attributes without a leading '-' prefix are
57           passed to the parent constructor. For example:
58
59              my $parser=new SVG::Parser(%parser_options);
60
61           Note that parser options are dependant on which parser type is
62           selected.
63
64           Attributes with a leading '-' are processed by SVG::Parser.
65           Currently the only recognised attribute is '-debug', which
66           generates a simple but possibly useful debug trace of the parsing
67           process to standard error. For example:
68
69              my $parser=new SVG::Parser(-debug => 1);
70
71           or:
72
73              my $parser=SVG::Parser->new(-debug => 1);
74
75           Attributes with a leading '--' are passed to the SVG constructor
76           when creating the SVG object returned as the result of the parse:
77
78              my $parser=new SVG::Parser(
79                   -debug => 1,
80                   "--indent" => "\t",
81                   "--raiseerror" => 1
82              );
83
84           The leading '-' is stripped from attribute names passed this way,
85           so this sets the '-indent' and '-raiseerror' attributes in the SVG
86           module. See SVG for a list of valid SVG options.
87
88           (The "new" constructor is provided by XML::SAX::Expat or
89           SVG::Parser::SAX, but operates identically in either case.)
90
91       •   parse($xml)
92
93           Parse an XML document and return an SVG object which may then be
94           used to manipulate the SVG content before regenerating the output
95           XML. For example:
96
97               my $svg=$parser->parse($svgxml);
98
99           Because the parse() method differs in use beteen XML::Parser and
100           XML::SAX, SVG::Parser provides its own parse() method. This calls
101           the parent parser with the correct first argument when given either
102           a filehandle or a string as input.
103
104           Additional arguments are passed to the parent parser class, but
105           since XML::Parser and XML::SAX parsers take options in different
106           formats this is of limited use. SVG::Parser does not currently
107           provide any translation of parser options.
108
109           See XML::Parser, XML::SAX, and XML::Parser::PerlSAX for other ways
110           to parse input XML.
111
112       •   parse_file($filehandle|$filename)
113
114       •   parsefile($filehandle|$filename)
115
116           Since the parse_file() method (XML::SAX) and parsefile() method
117           (XML::Parser) differ in both name and usage, SVG::Parser provides
118           its own version of both methods that determines whether the passed
119           argument is a filehandle or a file name and directs the call to the
120           appropriate parent parser method.
121
122           Both methods will work equally well whichever parent parser class
123           is in use:
124
125               my $svg=$parser->parse_file($svgxml);
126               my $svg=$parser->parsefile($svgxml);
127               my $svg=$parser->parse_file(*SVGIN);
128               my $svg=$parser->parsefile(*SVGIN);
129               ...etc...
130
131           (These methods will also work when using SVG::Parser::Expat or
132           SVG::Parser::SAX directly.)
133
134   EXPORTS
135       None. However, a list of preferred parsers can be specified by passing
136       the package name to SVG::Parser in the import list. This allows an SVG
137       parser application to use the best parser available without knowing
138       what XML parsers might be available on the target platform. SAX is
139       generally preferred to Expat, but an Expat-based parser may be
140       preferable to the slow Perl-based SAX parser XML::SAX::PurePerl. (See
141       XML::SAX::PurePerl.)
142
143       Each parser specification consists of one of the two supported SVG
144       parsers, SVG::Parser::Expat or SVG::Parser::SAX, optionally followed by
145       an '=' and an explicit parser package. For example:
146
147           use SVG::Parser qw(SVG::Parser::SAX SVG::Parser::Expat);
148
149       Instead of specifying the full SVG parser name, 'Expat' and 'SAX' may
150       be used as shorthand. For example:
151
152           use SVG::Parser qw(SAX Expat);
153
154       Both the above examples produce the default behaviour. To prefer Expat
155       over SAX use either of:
156
157           use SVG::Parser qw(SVG::Parser::Expat SVG::Parser::SAX);
158           use SVG::Parser qw(Expat SAX);
159
160       To use Expat with a specific XML::Parser subclass:
161
162           use SVG::Parser qw(SVG::Parser::Expat=My::XML::Parser::Subclass);
163
164       To use SAX with the XML::LibXML SAX parser:
165
166           use SVG::Parser qw(SVG::Parser::SAX=XML::LibXML::SAX::Parser);
167
168       A number of specifications can be listed to have SVG::Parse try a
169       number of possible parser alternatives in decreasing order of
170       preference:
171
172           use SVG::Parser qw(
173               SAX=My::SAXParser
174               Expat=My::Best::ExpatParser
175               SAX=XML::LibXML::SAX::Parser
176               Expat=My::Other::ExpatParser
177               Expat
178               SAX
179           )
180
181       You can test different scenarios from the command line. For example:
182
183           perl -MSVG::Parser=SAX mysvgapp.pl
184           perl -MSVG::Parser=Expat,SAX mysvgapp.pl
185           perl -MSVG::Parser=SAX=XML::LibXML::SAX::Parser,Expat mysvgapp.pl
186
187       To pass additional items in the import list to the parent Expat or SAX
188       parser class, use additional '=' separators in the parser
189       specification. In the case of XML::SAX a minimum version number may be
190       required this way:
191
192           # require version 1.40+ of the LibXML SAX parser, otherwise use Perl
193           use SVG::Parser qw(
194               SAX=XML::LibXML::SAX::Parser=1.40
195               SAX=XML::SAX::PurePerl
196           );
197
198       Similarly, from the command line:
199
200           perl -MSVG::Parser=SAX=XML::LibXML::SAX::Parser=1.40,SAX=XML::SAX::PurePerl mysvgapp.pl
201
202   EXAMPLES
203       See "svgparse", "svgparse2", and "svgparse3" in the examples directory
204       of the distribution, along with "svgexpatparse" and "svgsaxparse" for
205       examples of using the SVG::Parser::Expat and SVG::Parser::SAX modules
206       directly.
207

AUTHOR

209       Peter Wainwright, peter.wainwright@cybrid.net
210

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

SEE ALSO