class LibXML::XML::SaxParser

XML::SaxParser provides a callback based API for parsing documents, in contrast to XML::Parser's tree based API and XML::Reader's stream based API.

The XML::SaxParser API is fairly complex, not well standardized, and does not directly support validation making entity, namespace and base processing relatively hard.

To use the XML::SaxParser, register a callback class via the #callbacks. It is easiest to include the XML::SaxParser::Callbacks module in your class and override the methods as needed.

Basic example:

class MyCallbacks
  include XML::SaxParser::Callbacks
  def on_start_element(element, attributes)
    puts #Element started: #{element}"
  end
end

parser = XML::SaxParser.string(my_string)
parser.callbacks = MyCallbacks.new
parser.parse

You can also parse strings (see ::string) and io objects (see ::io).

Attributes

callbacks[RW]

Public Class Methods

XML::SaxParser.file(path) → XML::SaxParser click to toggle source

Creates a new parser by parsing the specified file or uri.

# File lib/libxml/sax_parser.rb, line 9
def self.file(path)
  context = XML::Parser::Context.file(path)
  self.new(context)
end
XML::SaxParser.io(io) → XML::SaxParser click to toggle source
XML::SaxParser.io(io, :encoding => XML::Encoding::UTF_8) → XML::SaxParser

Creates a new reader by parsing the specified io object.

Parameters:

encoding - The document encoding, defaults to nil. Valid values
           are the encoding constants defined on XML::Encoding.
# File lib/libxml/sax_parser.rb, line 24
def self.io(io, options = {})
  context = XML::Parser::Context.io(io)
  context.encoding = options[:encoding] if options[:encoding]
  self.new(context)
end
initialize(context) → XML::Parser click to toggle source

Creates a new XML::Parser from the specified XML::Parser::Context.

static VALUE rxml_sax_parser_initialize(int argc, VALUE *argv, VALUE self)
{
  VALUE context = Qnil;

  rb_scan_args(argc, argv, "01", &context);

  if (context == Qnil)
  {
    rb_warn("Passing no parameters to XML::SaxParser.new is deprecated.  Pass an instance of XML::Parser::Context instead.");
    context = rb_class_new_instance(0, NULL, cXMLParserContext);
  }

  rb_ivar_set(self, CONTEXT_ATTR, context);
  return self;
}
XML::SaxParser.string(string) click to toggle source

Creates a new parser by parsing the specified string.

# File lib/libxml/sax_parser.rb, line 34
def self.string(string)
  context = XML::Parser::Context.string(string)
  self.new(context)
end

Public Instance Methods

parse → (true|false) click to toggle source

Parse the input XML, generating callbacks to the object registered via the callbacks attributesibute.

static VALUE rxml_sax_parser_parse(VALUE self)
{
  int status;
  VALUE context = rb_ivar_get(self, CONTEXT_ATTR);
  xmlParserCtxtPtr ctxt;
  Data_Get_Struct(context, xmlParserCtxt, ctxt);

  ctxt->sax2 = 1;
        ctxt->userData = (void*)rb_ivar_get(self, CALLBACKS_ATTR);

  if (ctxt->sax != (xmlSAXHandlerPtr) &xmlDefaultSAXHandler)
    xmlFree(ctxt->sax);
    
  ctxt->sax = (xmlSAXHandlerPtr) xmlMalloc(sizeof(rxml_sax_handler));
  if (ctxt->sax == NULL)
    rb_fatal("Not enough memory.");
  memcpy(ctxt->sax, &rxml_sax_handler, sizeof(rxml_sax_handler));
    
  status = xmlParseDocument(ctxt);

  /* Now check the parsing result*/
  if (status == -1 || !ctxt->wellFormed)
  {
    if (ctxt->myDoc)
      xmlFreeDoc(ctxt->myDoc);

    rxml_raise(&ctxt->lastError);
  }
  return Qtrue;
}