class Oga::XML::PullParser

The PullParser class can be used to parse an XML document incrementally instead of parsing it as a whole. This results in lower memory usage and potentially faster parsing times. The downside is that pull parsers are typically more difficult to use compared to DOM parsers.

Basic parsing using this class works as following:

parser = Oga::XML::PullParser.new('... xml here ...')

parser.parse do |node|
  if node.is_a?(Oga::XML::PullParser)

  end
end

This parses yields proper XML instances such as {Oga::XML::Element}. Doctypes and XML declarations are ignored by this parser.

Constants

BLOCK_CALLBACKS

@return [Array]

DISABLED_CALLBACKS

@return [Array]

NODE_SHORTHANDS

Returns the shorthands that can be used for various node classes.

@return [Hash]

Attributes

nesting[R]

Array containing the names of the currently nested elements. @return [Array]

node[R]

@return [Oga::XML::Node]

Public Class Methods

new(*args) click to toggle source
Calls superclass method Oga::XML::Parser::new
# File lib/oga/xml/pull_parser.rb, line 57
def initialize(*args)
  super
  @nesting = []
end

Public Instance Methods

after_element(*args) click to toggle source

@see Oga::XML::Parser#on_element_children

# File lib/oga/xml/pull_parser.rb, line 146
def after_element(*args)
  nesting.pop

  return
end
on(type, nesting = []) { || ... } click to toggle source

Calls the supplied block if the current node type and optionally the nesting match. This method allows you to write this:

parser.parse do |node|
  parser.on(:text, %w{people person name}) do
    puts node.text
  end
end

Instead of this:

parser.parse do |node|
  if node.is_a?(Oga::XML::Text) and parser.nesting == %w{people person name}
    puts node.text
  end
end

When calling this method you can specify the following node types:

  • ‘:cdata`

  • ‘:comment`

  • ‘:element`

  • ‘:text`

@example

parser.on(:element, %w{people person name}) do

end

@param [Symbol] type The type of node to act upon. This is a symbol as

returned by {Oga::XML::Node#node_type}.

@param [Array] nesting The element name nesting to act upon.

# File lib/oga/xml/pull_parser.rb, line 106
def on(type, nesting = [])
  if node.is_a?(NODE_SHORTHANDS[type])
    if nesting.empty? or nesting == self.nesting
      yield
    end
  end
end
on_element(*args) click to toggle source

@see Oga::XML::Parser#on_element

Calls superclass method Oga::XML::Parser#on_element
# File lib/oga/xml/pull_parser.rb, line 135
def on_element(*args)
  @node = super

  nesting << @node.name

  @block.call(@node)

  return
end
parse(&block) click to toggle source

Parses the input and yields every node to the supplied block.

@yieldparam [Oga::XML::Node]

Calls superclass method
# File lib/oga/xml/pull_parser.rb, line 65
def parse(&block)
  @block = block

  super

  return
end