1XPath::XMLParser(3)   User Contributed Perl Documentation  XPath::XMLParser(3)
2
3
4

NAME

6       XML::XPath::XMLParser - The default XML parsing class that produces a
7       node tree
8

SYNOPSIS

10           my $parser = XML::XPath::XMLParser->new(
11                       filename => $self->get_filename,
12                       xml => $self->get_xml,
13                       ioref => $self->get_ioref,
14                       parser => $self->get_parser,
15                   );
16           my $root_node = $parser->parse;
17

DESCRIPTION

19       This module generates a node tree for use as the context node for XPath
20       processing.  It aims to be a quick parser, nothing fancy, and yet has
21       to store more information than most parsers. To achieve this I've used
22       array refs everywhere - no hashes.  I don't have any performance fig‐
23       ures for the speedups achieved, so I make no appologies for anyone not
24       used to using arrays instead of hashes. I think they make good sense
25       here where we know the attributes of each type of node.
26

Node Structure

28       All nodes have the same first 2 entries in the array: node_parent and
29       node_pos. The type of the node is determined using the ref() function.
30       The node_parent always contains an entry for the parent of the current
31       node - except for the root node which has undef in there. And node_pos
32       is the position of this node in the array that it is in (think: $node
33       == $node->[node_parent]->[node_children]->[$node->[node_pos]] )
34
35       Nodes are structured as follows:
36
37       Root Node
38
39       The root node is just an element node with no parent.
40
41           [
42             undef, # node_parent - check for undef to identify root node
43             undef, # node_pos
44             undef, # node_prefix
45             [ ... ], # node_children (see below)
46           ]
47
48       Element Node
49
50           [
51             $parent, # node_parent
52             <position in current array>, # node_pos
53             'xxx', # node_prefix - namespace prefix on this element
54             [ ... ], # node_children
55             'yyy', # node_name - element tag name
56             [ ... ], # node_attribs - attributes on this element
57             [ ... ], # node_namespaces - namespaces currently in scope
58           ]
59
60       Attribute Node
61
62           [
63             $parent, # node_parent - the element node
64             <position in current array>, # node_pos
65             'xxx', # node_prefix - namespace prefix on this element
66             'href', # node_key - attribute name
67             'ftp://ftp.com/', # node_value - value in the node
68           ]
69
70       Namespace Nodes
71
72       Each element has an associated set of namespace nodes that are cur‐
73       rently in scope. Each namespace node stores a prefix and the expanded
74       name (retrieved from the xmlns:prefix="..." attribute).
75
76           [
77             $parent,
78             <pos>,
79             'a', # node_prefix - the namespace as it was written as a prefix
80             'http://my.namespace.com', # node_expanded - the expanded name.
81           ]
82
83       Text Nodes
84
85           [
86             $parent,
87             <pos>,
88             'This is some text' # node_text - the text in the node
89           ]
90
91       Comment Nodes
92
93           [
94             $parent,
95             <pos>,
96             'This is a comment' # node_comment
97           ]
98
99       Processing Instruction Nodes
100
101           [
102             $parent,
103             <pos>,
104             'target', # node_target
105             'data', # node_data
106           ]
107

Usage

109       If you feel the need to use this module outside of XML::XPath (for
110       example you might use this module directly so that you can cache parsed
111       trees), you can follow the following API:
112
113       new
114
115       The new method takes either no parameters, or any of the following
116       parameters:
117
118               filename
119               xml
120               parser
121               ioref
122
123       This uses the familiar hash syntax, so an example might be:
124
125           use XML::XPath::XMLParser;
126
127           my $parser = XML::XPath::XMLParser->new(filename => 'example.xml');
128
129       The parameters represent a filename, a string containing XML, an
130       XML::Parser instance and an open filehandle ref respectively. You can
131       also set or get all of these properties using the get_ and set_ func‐
132       tions that have the same name as the property: e.g. get_filename,
133       set_ioref, etc.
134
135       parse
136
137       The parse method generally takes no parameters, however you are free to
138       pass either an open filehandle reference or an XML string if you so
139       require.  The return value is a tree that XML::XPath can use. The parse
140       method will die if there is an error in your XML, so be sure to use
141       perl's exception handling mechanism (eval{};) if you want to avoid
142       this.
143
144       parsefile
145
146       The parsefile method is identical to parse() except it expects a single
147       parameter that is a string naming a file to open and parse. Again it
148       returns a tree and also dies if there are XML errors.
149

NOTICES

151       This file is distributed as part of the XML::XPath module, and is copy‐
152       right 2000 Fastnet Software Ltd. Please see the documentation for the
153       module as a whole for licencing information.
154
155
156
157perl v5.8.8                       2001-06-12               XPath::XMLParser(3)