1XML::Parser::PerlSAX(3)User Contributed Perl DocumentatioXnML::Parser::PerlSAX(3)
2
6 XML::Parser::PerlSAX - Perl SAX parser using XML::Parser
7
9 use XML::Parser::PerlSAX;
10 $parser = XML::Parser::PerlSAX->new( [OPTIONS] );
12 $result = $parser->parse( [OPTIONS] );
13 $result = $parser->parse($string);
15
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
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 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 location
35 Returns the location as a hash:
36 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 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
54 The following options are supported by "XML::Parser::PerlSAX":
55 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 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 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 The `"Source"' hash may contain the following parameters:
75 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 If more than one of `"ByteStream"', `"String"', or `"SystemId"', then
84 preference is given first to `"ByteStream"', then `"String"', then
85 `"SystemId"'.
86
88 The following handlers and properties are supported by
89 "XML::Parser::PerlSAX":
90 DocumentHandler methods
92 start_document
93 Receive notification of the beginning of a document.
94 No properties defined.
96 end_document
98 Receive notification of the end of a document.
99 No properties defined.
101 start_element
103 Receive notification of the beginning of an element.
104 Name The element type name.
106 Attributes A hash containing the attributes attached to the
107 element, if any.
108 The `"Attributes"' hash contains only string values.
110 If the `"UseAttributeOrder"' parser option is true, the following
112 properties are also passed to `"start_element"':
113 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 Note to "XML::Parser" users: `"Defaulted"' will be half the value
123 of "XML::Parser::Expat"'s `specified_attr()' function because only
124 attribute names are provided, not their values.
125 end_element
127 Receive notification of the end of an element.
128 Name The element type name.
130 characters
132 Receive notification of character data.
133 Data The characters from the XML document.
135 processing_instruction
137 Receive notification of a processing instruction.
138 Target The processing instruction target.
140 Data The processing instruction data, if any.
141 comment
143 Receive notification of a comment.
144 Data The comment data, if any.
146 start_cdata
148 Receive notification of the start of a CDATA section.
149 No properties defined.
151 end_cdata
153 Receive notification of the end of a CDATA section.
154 No properties defined.
156 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 Name The entity reference name
165 Value The entity reference value
166 DTDHandler methods
168 notation_decl
169 Receive notification of a notation declaration event.
170 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 unparsed_entity_decl
177 Receive notification of an unparsed entity declaration event.
178 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 entity_decl
185 Receive notification of an entity declaration event.
186 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 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 Note that `entity_decl()' and `unparsed_entity_decl()' overlap. If
204 both methods are implemented by a handler, then this handler will
205 not be called for unparsed entities.
206 element_decl
208 Receive notification of an element declaration event.
209 Name The element type name.
211 Model The content model as a string.
212 attlist_decl
214 Receive notification of an attribute list declaration event.
215 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 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 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 doctype_decl
230 Receive notification of a DOCTYPE declaration event.
231 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 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 xml_decl
246 Receive notification of an XML declaration event.
247 Version The version.
249 Encoding The encoding string, if any.
250 Standalone True, false, or undefined if not declared.
251 EntityResolver
253 resolve_entity
254 Allow the handler to resolve external entities.
255 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 `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 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
277 Ken MacLeod, ken@bitsko.slc.ut.us
278
280 perl(1), PerlSAX.pod(3)
281 Extensible Markup Language (XML) <http://www.w3c.org/XML/>
283 SAX 1.0: The Simple API for XML <http://www.megginson.com/SAX/>
284
286 Hey! The above document had some coding errors, which are explained
287 below:
288 Around line 528:
290 You forgot a '=back' before '=head1'
291perl v5.36.0 2023-01-20 XML::Parser::PerlSAX(3)