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 XML::SaxParser#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 XML::SaxParser.string) and io objects (see XML::SaxParser.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
10 def self.file(path)
11   context = XML::Parser::Context.file(path)
12   self.new(context)
13 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
25 def self.io(io, options = {})
26   context = XML::Parser::Context.io(io)
27   context.encoding = options[:encoding] if options[:encoding]
28   self.new(context)
29 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_raise(rb_eArgError, "An instance of a XML::Parser::Context must be passed to XML::SaxParser.new");
  }

  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
35 def self.string(string)
36   context = XML::Parser::Context.string(string)
37   self.new(context)
38 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)
{
  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);
  memcpy(ctxt->sax, &rxml_sax_handler, sizeof(rxml_sax_handler));
    
  int status = xmlParseDocument(ctxt);

  /* Now check the parsing result*/
  if (status == -1 || !ctxt->wellFormed)
  {
    rxml_raise(&ctxt->lastError);
  }
  return Qtrue;
}