1XML::Parser::PerlSAX(3)User Contributed Perl DocumentatioXnML::Parser::PerlSAX(3)
2
3
4

NAME

6       XML::Parser::PerlSAX - Perl SAX parser using XML::Parser
7

SYNOPSIS

9        use XML::Parser::PerlSAX;
10
11        $parser = XML::Parser::PerlSAX->new( [OPTIONS] );
12        $result = $parser->parse( [OPTIONS] );
13
14        $result = $parser->parse($string);
15

DESCRIPTION

17       "XML::Parser::PerlSAX" is a PerlSAX parser using the XML::Parser
18       module.  This man page summarizes the specific options, handlers, and
19       properties supported by "XML::Parser::PerlSAX"; please refer to the
20       PerlSAX standard in `"PerlSAX.pod"' for general usage information.
21

METHODS

23       new Creates a new parser object.  Default options for parsing,
24           described below, are passed as key-value pairs or as a single hash.
25           Options may be changed directly in the parser object unless stated
26           otherwise.  Options passed to `"parse()"' override the default
27           options in the parser object for the duration of the parse.
28
29       parse
30           Parses a document.  Options, described below, are passed as key-
31           value pairs or as a single hash.  Options passed to `"parse()"'
32           override default options in the parser object.
33
34       location
35           Returns the location as a hash:
36
37             ColumnNumber    The column number of the parse.
38             LineNumber      The line number of the parse.
39             BytePosition    The current byte position of the parse.
40             PublicId        A string containing the public identifier, or undef
41                             if none is available.
42             SystemId        A string containing the system identifier, or undef
43                             if none is available.
44             Base            The current value of the base for resolving relative
45                             URIs.
46
47           ALPHA WARNING: The `"SystemId"' and `"PublicId"' properties
48           returned are the system and public identifiers of the document
49           passed to `"parse()"', not the identifiers of the currently parsing
50           external entity.  The column, line, and byte positions are of the
51           current entity being parsed.
52

OPTIONS

54       The following options are supported by "XML::Parser::PerlSAX":
55
56        Handler          default handler to receive events
57        DocumentHandler  handler to receive document events
58        DTDHandler       handler to receive DTD events
59        ErrorHandler     handler to receive error events
60        EntityResolver   handler to resolve entities
61        Locale           locale to provide localisation for errors
62        Source           hash containing the input source for parsing
63        UseAttributeOrder set to true to provide AttributeOrder and Defaulted
64                          properties in `start_element()'
65
66       If no handlers are provided then all events will be silently ignored,
67       except for `"fatal_error()"' which will cause a `"die()"' to be called
68       after calling `"end_document()"'.
69
70       If a single string argument is passed to the `"parse()"' method, it is
71       treated as if a `"Source"' option was given with a `"String"'
72       parameter.
73
74       The `"Source"' hash may contain the following parameters:
75
76        ByteStream       The raw byte stream (file handle) containing the
77                         document.
78        String           A string containing the document.
79        SystemId         The system identifier (URI) of the document.
80        PublicId         The public identifier.
81        Encoding         A string describing the character encoding.
82
83       If more than one of `"ByteStream"', `"String"', or `"SystemId"', then
84       preference is given first to `"ByteStream"', then `"String"', then
85       `"SystemId"'.
86

HANDLERS

88       The following handlers and properties are supported by
89       "XML::Parser::PerlSAX":
90
91   DocumentHandler methods
92       start_document
93           Receive notification of the beginning of a document.
94
95           No properties defined.
96
97       end_document
98           Receive notification of the end of a document.
99
100           No properties defined.
101
102       start_element
103           Receive notification of the beginning of an element.
104
105            Name             The element type name.
106            Attributes       A hash containing the attributes attached to the
107                             element, if any.
108
109           The `"Attributes"' hash contains only string values.
110
111           If the `"UseAttributeOrder"' parser option is true, the following
112           properties are also passed to `"start_element"':
113
114            AttributeOrder   An array of attribute names in the order they were
115                             specified, followed by the defaulted attribute
116                             names.
117            Defaulted        The index number of the first defaulted attribute in
118                             `AttributeOrder.  If this index is equal to the
119                             length of `AttributeOrder', there were no defaulted
120                             values.
121
122           Note to "XML::Parser" users:  `"Defaulted"' will be half the value
123           of "XML::Parser::Expat"'s `"specified_attr()"' function because
124           only attribute names are provided, not their values.
125
126       end_element
127           Receive notification of the end of an element.
128
129            Name             The element type name.
130
131       characters
132           Receive notification of character data.
133
134            Data             The characters from the XML document.
135
136       processing_instruction
137           Receive notification of a processing instruction.
138
139            Target           The processing instruction target.
140            Data             The processing instruction data, if any.
141
142       comment
143           Receive notification of a comment.
144
145            Data             The comment data, if any.
146
147       start_cdata
148           Receive notification of the start of a CDATA section.
149
150           No properties defined.
151
152       end_cdata
153           Receive notification of the end of a CDATA section.
154
155           No properties defined.
156
157       entity_reference
158           Receive notification of an internal entity reference.  If this
159           handler is defined, internal entities will not be expanded and not
160           passed to the `"characters()"' handler.  If this handler is not
161           defined, internal entities will be expanded if possible and passed
162           to the `"characters()"' handler.
163
164            Name             The entity reference name
165            Value            The entity reference value
166
167   DTDHandler methods
168       notation_decl
169           Receive notification of a notation declaration event.
170
171            Name             The notation name.
172            PublicId         The notation's public identifier, if any.
173            SystemId         The notation's system identifier, if any.
174            Base             The base for resolving a relative URI, if any.
175
176       unparsed_entity_decl
177           Receive notification of an unparsed entity declaration event.
178
179            Name             The unparsed entity's name.
180            SystemId         The entity's system identifier.
181            PublicId         The entity's public identifier, if any.
182            Base             The base for resolving a relative URI, if any.
183
184       entity_decl
185           Receive notification of an entity declaration event.
186
187            Name             The entity name.
188            Value            The entity value, if any.
189            PublicId         The notation's public identifier, if any.
190            SystemId         The notation's system identifier, if any.
191            Notation         The notation declared for this entity, if any.
192
193           For internal entities, the `"Value"' parameter will contain the
194           value and the `"PublicId"', `"SystemId"', and `"Notation"' will be
195           undefined.  For external entities, the `"Value"' parameter will be
196           undefined, the `"SystemId"' parameter will have the system id, the
197           `"PublicId"' parameter will have the public id if it was provided
198           (it will be undefined otherwise), the `"Notation"' parameter will
199           contain the notation name for unparsed entities.  If this is a
200           parameter entity declaration, then a '%' will be prefixed to the
201           entity name.
202
203           Note that `"entity_decl()"' and `"unparsed_entity_decl()"' overlap.
204           If both methods are implemented by a handler, then this handler
205           will not be called for unparsed entities.
206
207       element_decl
208           Receive notification of an element declaration event.
209
210            Name             The element type name.
211            Model            The content model as a string.
212
213       attlist_decl
214           Receive notification of an attribute list declaration event.
215
216           This handler is called for each attribute in an ATTLIST declaration
217           found in the internal subset. So an ATTLIST declaration that has
218           multiple attributes will generate multiple calls to this handler.
219
220            ElementName      The element type name.
221            AttributeName    The attribute name.
222            Type             The attribute type.
223            Fixed            True if this is a fixed attribute.
224
225           The default for `"Type"' is the default value, which will either be
226           "#REQUIRED", "#IMPLIED" or a quoted string (i.e. the returned
227           string will begin and end with a quote character).
228
229       doctype_decl
230           Receive notification of a DOCTYPE declaration event.
231
232            Name             The document type name.
233            SystemId         The document's system identifier.
234            PublicId         The document's public identifier, if any.
235            Internal         The internal subset as a string, if any.
236
237           Internal will contain all whitespace, comments, processing
238           instructions, and declarations seen in the internal subset. The
239           declarations will be there whether or not they have been processed
240           by another handler (except for unparsed entities processed by the
241           Unparsed handler).  However, comments and processing instructions
242           will not appear if they've been processed by their respective
243           handlers.
244
245       xml_decl
246           Receive notification of an XML declaration event.
247
248            Version          The version.
249            Encoding         The encoding string, if any.
250            Standalone       True, false, or undefined if not declared.
251
252   EntityResolver
253       resolve_entity
254           Allow the handler to resolve external entities.
255
256            Name             The notation name.
257            SystemId         The notation's system identifier.
258            PublicId         The notation's public identifier, if any.
259            Base             The base for resolving a relative URI, if any.
260
261           `"resolve_entity()"' should return undef to request that the parser
262           open a regular URI connection to the system identifier or a hash
263           describing the new input source.  This hash has the same properties
264           as the `"Source"' parameter to `"parse()"':
265
266             PublicId    The public identifier of the external entity being
267                         referenced, or undef if none was supplied.
268             SystemId    The system identifier of the external entity being
269                         referenced.
270             String      String containing XML text
271             ByteStream  An open file handle.
272             CharacterStream
273                         An open file handle.
274             Encoding    The character encoding, if known.
275

AUTHOR

277       Ken MacLeod, ken@bitsko.slc.ut.us
278

SEE ALSO

280       perl(1), PerlSAX.pod(3)
281
282        Extensible Markup Language (XML) <http://www.w3c.org/XML/>
283        SAX 1.0: The Simple API for XML <http://www.megginson.com/SAX/>
284

POD ERRORS

286       Hey! The above document had some coding errors, which are explained
287       below:
288
289       Around line 528:
290           You forgot a '=back' before '=head1'
291
292
293
294perl v5.26.3                      2003-10-21           XML::Parser::PerlSAX(3)
Impressum