Class: Syndication::AbstractParser

Inherits:
Object
  • Object
show all
Includes:
REXML::StreamListener
Defined in:
lib/syndication/common.rb

Overview

Shared parts of parser code for Atom and RSS. This is an abstract class; Atom::Parser and RSS::Parser are the concrete classes which actually parse syndication feeds.

You don't need to know about anything below in order to use the library.

The basic parsing strategy is:

  • The parser keeps a current_object pointer which represents the object

in the parse tree that corresponds to where we are in the XML tree. To use a metaphor, it's the object where parse tree growth is occurring.

  • REXML dispatches events to the parser representing start and end tags and

text. The parser sends the events to the current_object, which replies with what the new current_object should be after the event has been dealt with.

  • The job of creating child objects when appropriate is handled by the

objects of the parse tree.

  • Reflection is used to store data in the parse tree. Accessor names are

derived from tags in a standard way once namespaces have been standardized.

Direct Known Subclasses

Syndication::Atom::Parser, RSS::Parser

Constant Summary

KNOWN_NAMESPACES =

A Hash of namespace URLs the module knows about, returning the standard prefix to remap to.

{
  'http://purl.org/dc/elements/1.1/' => 'dc',
  'http://purl.org/dc/terms/' => 'dcterms',
  'http://www.w3.org/1999/02/22-rdf-syntax-ns#' => 'rdf',
  'http://purl.org/rss/1.0/modules/content/' => 'content',
  'http://www.itunes.com/DTDs/Podcast-1.0.dtd' => 'itunes',
  'http://www.w3.org/1999/xhtml' => 'xhtml',
  'http://schemas.google.com/g/2005' => 'gd',
  'http://rssnamespace.org/feedburner/ext/1.0' => 'feedburner'
}

Instance Method Summary (collapse)

Constructor Details

- (AbstractParser) initialize(text = nil)

Create a new AbstractParser. The optional argument consists of text to parse.



146
147
148
149
150
151
152
153
# File 'lib/syndication/common.rb', line 146

def initialize(text = nil)
  reset
  # Initialize mapping from tags to classes, which only needs to be done
  # once and not reset. Concrete classes which do actual parsing will
  # fill the hash.
  @tag_to_class = Hash.new
  parse(text) if text
end

Instance Method Details

- (Object) cdata(s)

Supposed to be called when REXML finds a CDATA-encoded piece of text.



273
274
275
276
277
278
279
280
281
282
283
284
285
# File 'lib/syndication/common.rb', line 273

def cdata(s)
  # For content_encoded we re-encode, because (a) the API for RSS content 
  # module provides both encoded and decoded results to the user, and 
  # (b) REXML doesn't always seem to pass CDATA via this callback method.
  # For other elements, we keep the text decoded.
  if @textstack.last
    if @tagstack.last == 'content:encoded'
      @textstack.last << "<![CDATA[#{s}]]>"
    else
      @textstack.last << s
    end
  end
end

- (Object) define_namespace(prefix, url)

Process a namespace definition for the given prefix and namespace definition URL.

If we recongnize the URL, we set up a mapping from their prefix to our canonical choice of prefix.



209
210
211
212
213
214
# File 'lib/syndication/common.rb', line 209

def define_namespace(prefix, url)
  myprefix = KNOWN_NAMESPACES[url]
  if myprefix
    @namespacemap[prefix] = myprefix
  end
end

- (Object) end_tag(tag, current)

Catch and ignore closing tags that don't match anything open.



161
162
163
# File 'lib/syndication/common.rb', line 161

def end_tag(tag, current)
  return current
end

- (Object) handle_namespace(tag, attrs = nil)

Handle namespace translation for a raw tag.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
# File 'lib/syndication/common.rb', line 188

def handle_namespace(tag, attrs = nil)
  if attrs and tag.match(/^(rss|\w+:rdf|\w+:div)$/i)
    for key in attrs.keys
      if key.match(/xmlns:(\w+)/i)
        define_namespace($1, attrs[key])
      end
    end
  end
  if tag.match(/(\w+):(\w+)/)
    if @namespacemap[$1]
      tag = "#{@namespacemap[$1]}:#{$2}"
    end
  end
  return tag
end

- (Object) parse(text, classname = REXML::Document)

Parse the text provided. Returns a Syndication::Atom::Feed or Syndication::RSS::Feed object, according to which concrete Parser class is being used. The second argument is optional and determines the parser engine to use. The default is REXML. To use TagSoup, pass in the value Syndication::TagSoup



182
183
184
185
# File 'lib/syndication/common.rb', line 182

def parse(text, classname = REXML::Document)
  classname.parse_stream(text, self)
  return @parsetree
end

- (Object) reset

Reset the parser ready to parse a new feed.



166
167
168
169
170
171
172
173
174
# File 'lib/syndication/common.rb', line 166

def reset
  @current_object = @parsetree
  @tagstack = Array.new
  @textstack = Array.new
  @xhtml = ''
  @xhtmlmode = false
  @namespacemap = Hash.new
  # @parsetree is set up by the concrete classes
end

- (Object) store(tag, obj)

Catch any stuff that drops right through the parse tree, and simply ignore it.



157
158
# File 'lib/syndication/common.rb', line 157

def store(tag, obj)
end

- (Object) tag_end(endtag)

Called when REXML finds the end of an XML element.



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# File 'lib/syndication/common.rb', line 239

def tag_end(endtag) 
  endtag = handle_namespace(endtag, nil)
  # There are two tasks to perform: 1. store the data from the buffers, 
  # and 2. work out if we need to close out any objects in the parse 
  # tree and move the current object pointer
  begin
    # Store the top text buffer that's on the stacks by passing it to the
    # current object along with its tag. Repeat until we find a stacked
    # tag which matches the endtag, or run out of buffers.
    tag = @tagstack.pop
    text = @textstack.pop
    if text
      text.strip!
      if text.length > 0 and @current_object
        @current_object.store(tag, text)
      end
    end
  end until tag == endtag or @tagstack.length == 0
  # Pass the tag end event to the current object to find out what the
  # new current object should be.
  if @current_object
    @current_object = @current_object.tag_end(endtag, @current_object)
  end
end

- (Object) tag_start(tag, attrs)

Called when REXML finds the start of an XML element.



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
# File 'lib/syndication/common.rb', line 217

def tag_start(tag, attrs) #:nodoc:
  tag = handle_namespace(tag, attrs)
  cl = @class_for_tag[tag.downcase]
  if cl
    # If the tag requires the creation of an object, we create it as a
    # child of the current object, then ask the current object to store
    # it. It becomes the new current object.
    newobj = cl.new(@current_object, tag, attrs)
    @current_object.store(tag, newobj)
    @current_object = newobj
  else
    # Otherwise, we ask the current object to do something with the tag.
    if @current_object
      @current_object.tag_start(tag, attrs)
    end
  end
  # We also push to the stacks we use for text buffering.
  @tagstack.push(tag)
  @textstack.push('')
end

- (Object) text(s)

Called when REXML finds a text fragment. Buffers the text on the buffer stacks ready for the end tag.



266
267
268
269
270
# File 'lib/syndication/common.rb', line 266

def text(s)
  if @textstack.last
    @textstack.last << s
  end
end