class Nokogiri::XML::SAX::Parser

This parser is a SAX style parser that reads its input as it deems necessary. The parser takes a Nokogiri::XML::SAX::Document, an optional encoding, then given an XML input, sends messages to the Nokogiri::XML::SAX::Document.

Here is an example of using this parser:

# Create a subclass of Nokogiri::XML::SAX::Document and implement
# the events we care about:
class MyHandler < Nokogiri::XML::SAX::Document
  def start_element name, attrs = []
    puts "starting: #{name}"
  end

  def end_element name
    puts "ending: #{name}"
  end
end

parser = Nokogiri::XML::SAX::Parser.new(MyHandler.new)

# Hand an IO object to the parser, which will read the XML from the IO.
File.open(path_to_xml) do |f|
  parser.parse(f)
end

For more information about SAX parsers, see Nokogiri::XML::SAX.

Also see Nokogiri::XML::SAX::Document for the available events.

For HTML documents, use the subclass Nokogiri::HTML4::SAX::Parser.

Attributes

document[RW]

The Nokogiri::XML::SAX::Document where events will be sent.

encoding[RW]

The encoding beings used for this document.

Public Class Methods

new ⇒ SAX::Parser click to toggle source

new(handler) ⇒ SAX::Parser

new(handler, encoding) ⇒ SAX::Parser

Create a new Parser.

Parameters

handler (optional Nokogiri::XML::SAX::Document) The document that will receive events. Will create a new Nokogiri::XML::SAX::Document if not given, which is accessible through the document attribute.
encoding (optional Encoding, String, nil) An Encoding or encoding name to use when parsing the input. (default nil for auto-detection)

# File lib/nokogiri/xml/sax/parser.rb, line 95
def initialize(doc = Nokogiri::XML::SAX::Document.new, encoding = nil)
  @encoding = encoding
  @document = doc
  @warned   = false

  initialize_native unless Nokogiri.jruby?
end

Public Instance Methods

parse(input) { |parser_context| ... } click to toggle source

Parse the input, sending events to the SAX::Document at document.

Parameters

input (String, IO) The input to parse.

If input quacks like a readable IO object, this method forwards to Parser.parse_io, otherwise it forwards to Parser.parse_memory.

Yields: If a block is given, the underlying ParserContext object will be yielded. This can be used to set options on the parser context before parsing begins.

# File lib/nokogiri/xml/sax/parser.rb, line 119
def parse(input, &block)
  if input.respond_to?(:read) && input.respond_to?(:close)
    parse_io(input, &block)
  else
    parse_memory(input, &block)
  end
end

parse_file(filename) { |parser_context| ... } click to toggle source

parse_file(filename, encoding) { |parser_context| ... }

Parse a file.

Parameters

filename (String) The path to the file to be parsed.
encoding (optional Encoding, String, nil) An Encoding or encoding name to use when parsing the input, or nil for auto-detection. (default encoding)

Yields: If a block is given, the underlying ParserContext object will be yielded. This can be used to set options on the parser context before parsing begins.

# File lib/nokogiri/xml/sax/parser.rb, line 187
def parse_file(filename, encoding = @encoding)
  raise ArgumentError, "no filename provided" unless filename
  raise Errno::ENOENT unless File.exist?(filename)
  raise Errno::EISDIR if File.directory?(filename)

  ctx = related_class("ParserContext").file(filename, encoding)
  yield ctx if block_given?
  ctx.parse_with(self)
end

parse_io(io) { |parser_context| ... } click to toggle source

parse_io(io, encoding) { |parser_context| ... }

Parse an input stream.

Parameters

io (IO) The readable IO object from which to read input
encoding (optional Encoding, String, nil) An Encoding or encoding name to use when parsing the input, or nil for auto-detection. (default encoding)

Yields: If a block is given, the underlying ParserContext object will be yielded. This can be used to set options on the parser context before parsing begins.

# File lib/nokogiri/xml/sax/parser.rb, line 143
def parse_io(io, encoding = @encoding)
  ctx = related_class("ParserContext").io(io, encoding)
  yield ctx if block_given?
  ctx.parse_with(self)
end

parse_memory(input) { |parser_context| ... } click to toggle source

parse_memory(input, encoding) { |parser_context| ... }

Parse an input string.

Parameters

input (String) The input string to be parsed.
encoding (optional Encoding, String, nil) An Encoding or encoding name to use when parsing the input, or nil for auto-detection. (default encoding)

Yields: If a block is given, the underlying ParserContext object will be yielded. This can be used to set options on the parser context before parsing begins.

# File lib/nokogiri/xml/sax/parser.rb, line 165
def parse_memory(input, encoding = @encoding)
  ctx = related_class("ParserContext").memory(input, encoding)
  yield ctx if block_given?
  ctx.parse_with(self)
end

Private Instance Methods

initialize_native() click to toggle source

static VALUE
noko_xml_sax_parser__initialize_native(VALUE self)
{
  xmlSAXHandlerPtr handler = noko_xml_sax_parser_unwrap(self);

  handler->startDocument = noko_xml_sax_parser_start_document_callback;
  handler->endDocument = noko_xml_sax_parser_end_document_callback;
  handler->startElement = noko_xml_sax_parser_start_element_callback;
  handler->endElement = noko_xml_sax_parser_end_element_callback;
  handler->startElementNs = noko_xml_sax_parser_start_element_ns_callback;
  handler->endElementNs = noko_xml_sax_parser_end_element_ns_callback;
  handler->characters = noko_xml_sax_parser_characters_callback;
  handler->comment = noko_xml_sax_parser_comment_callback;
  handler->warning = noko_xml_sax_parser_warning_callback;
  handler->error = noko_xml_sax_parser_error_callback;
  handler->cdataBlock = noko_xml_sax_parser_cdata_block_callback;
  handler->processingInstruction = noko_xml_sax_parser_processing_instruction_callback;
  handler->reference = noko_xml_sax_parser_reference_callback;

  /* use some of libxml2's default callbacks to managed DTDs and entities */
  handler->getEntity = xmlSAX2GetEntity;
  handler->internalSubset = xmlSAX2InternalSubset;
  handler->externalSubset = xmlSAX2ExternalSubset;
  handler->isStandalone = xmlSAX2IsStandalone;
  handler->hasInternalSubset = xmlSAX2HasInternalSubset;
  handler->hasExternalSubset = xmlSAX2HasExternalSubset;
  handler->resolveEntity = xmlSAX2ResolveEntity;
  handler->getParameterEntity = xmlSAX2GetParameterEntity;
  handler->entityDecl = xmlSAX2EntityDecl;
  handler->unparsedEntityDecl = xmlSAX2UnparsedEntityDecl;

  handler->initialized = XML_SAX2_MAGIC;

  return self;
}