1 require 'forwardable'
2
3 require 'rexml/parseexception'
4 require 'rexml/parsers/baseparser'
5 require 'rexml/xmltokens'
6
7 module REXML
8 module Parsers
9 # = Using the Pull Parser
10 # <em>This API is experimental, and subject to change.</em>
11 # parser = PullParser.new( "<a>text<b att='val'/>txet</a>" )
12 # while parser.has_next?
13 # res = parser.next
14 # puts res[1]['att'] if res.start_tag? and res[0] == 'b'
15 # end
16 # See the PullEvent class for information on the content of the results.
17 # The data is identical to the arguments passed for the various events to
18 # the StreamListener API.
19 #
20 # Notice that:
21 # parser = PullParser.new( "<a>BAD DOCUMENT" )
22 # while parser.has_next?
23 # res = parser.next
24 # raise res[1] if res.error?
25 # end
26 #
27 # Nat Price gave me some good ideas for the API.
28 class PullParser
29 include XMLTokens
30 extend Forwardable
31
32 def_delegators( :@parser, :has_next? )
33 def_delegators( :@parser, :entity )
34 def_delegators( :@parser, :empty? )
35 def_delegators( :@parser, :source )
36
37 def initialize stream
38 @entities = {}
39 @listeners = nil
40 @parser = BaseParser.new( stream )
41 @my_stack = []
42 end
43
44 def add_listener( listener )
45 @listeners = [] unless @listeners
46 @listeners << listener
47 end
48
49 def each
50 while has_next?
51 yield self.pull
52 end
53 end
54
55 def peek depth=0
56 if @my_stack.length <= depth
57 (depth - @my_stack.length + 1).times {
58 e = PullEvent.new(@parser.pull)
59 @my_stack.push(e)
60 }
61 end
62 @my_stack[depth]
63 end
64
65 def pull
66 return @my_stack.shift if @my_stack.length > 0
67
68 event = @parser.pull
69 case event[0]
70 when :entitydecl
71 @entities[ event[1] ] =
72 event[2] unless event[2] =~ /PUBLIC|SYSTEM/
73 when :text
74 unnormalized = @parser.unnormalize( event[1], @entities )
75 event << unnormalized
76 end
77 PullEvent.new( event )
78 end
79
80 def unshift token
81 @my_stack.unshift token
82 end
83 end
84
85 # A parsing event. The contents of the event are accessed as an +Array?,
86 # and the type is given either by the ...? methods, or by accessing the
87 # +type+ accessor. The contents of this object vary from event to event,
88 # but are identical to the arguments passed to +StreamListener+s for each
89 # event.
90 class PullEvent
91 # The type of this event. Will be one of :tag_start, :tag_end, :text,
92 # :processing_instruction, :comment, :doctype, :attlistdecl, :entitydecl,
93 # :notationdecl, :entity, :cdata, :xmldecl, or :error.
94 def initialize(arg)
95 @contents = arg
96 end
97
98 def []( start, endd=nil)
99 if start.kind_of? Range
100 @contents.slice( start.begin+1 .. start.end )
101 elsif start.kind_of? Numeric
102 if endd.nil?
103 @contents.slice( start+1 )
104 else
105 @contents.slice( start+1, endd )
106 end
107 else
108 raise "Illegal argument #{start.inspect} (#{start.class})"
109 end
110 end
111
112 def event_type
113 @contents[0]
114 end
115
116 # Content: [ String tag_name, Hash attributes ]
117 def start_element?
118 @contents[0] == :start_element
119 end
120
121 # Content: [ String tag_name ]
122 def end_element?
123 @contents[0] == :end_element
124 end
125
126 # Content: [ String raw_text, String unnormalized_text ]
127 def text?
128 @contents[0] == :text
129 end
130
131 # Content: [ String text ]
132 def instruction?
133 @contents[0] == :processing_instruction
134 end
135
136 # Content: [ String text ]
137 def comment?
138 @contents[0] == :comment
139 end
140
141 # Content: [ String name, String pub_sys, String long_name, String uri ]
142 def doctype?
143 @contents[0] == :start_doctype
144 end
145
146 # Content: [ String text ]
147 def attlistdecl?
148 @contents[0] == :attlistdecl
149 end
150
151 # Content: [ String text ]
152 def elementdecl?
153 @contents[0] == :elementdecl
154 end
155
156 # Due to the wonders of DTDs, an entity declaration can be just about
157 # anything. There's no way to normalize it; you'll have to interpret the
158 # content yourself. However, the following is true:
159 #
160 # * If the entity declaration is an internal entity:
161 # [ String name, String value ]
162 # Content: [ String text ]
163 def entitydecl?
164 @contents[0] == :entitydecl
165 end
166
167 # Content: [ String text ]
168 def notationdecl?
169 @contents[0] == :notationdecl
170 end
171
172 # Content: [ String text ]
173 def entity?
174 @contents[0] == :entity
175 end
176
177 # Content: [ String text ]
178 def cdata?
179 @contents[0] == :cdata
180 end
181
182 # Content: [ String version, String encoding, String standalone ]
183 def xmldecl?
184 @contents[0] == :xmldecl
185 end
186
187 def error?
188 @contents[0] == :error
189 end
190
191 def inspect
192 @contents[0].to_s + ": " + @contents[1..-1].inspect
193 end
194 end
195 end
196 end