Class: LibXML::XML::SaxParser

Inherits:
Object
  • Object
show all
Defined in:
ext/libxml/ruby_xml_sax_parser.c,
lib/libxml/sax_parser.rb,
lib/libxml/sax_callbacks.rb,
ext/libxml/ruby_xml_sax_parser.c

Overview

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).

Defined Under Namespace

Modules: Callbacks, VerboseCallbacks

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context) ⇒ XML::Parser

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



53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'ext/libxml/ruby_xml_sax_parser.c', line 53

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;
}

Instance Attribute Details

#callbacks ⇒ Object

Class Method Details

.file(path) ⇒ Object

call-seq:

XML::SaxParser.file(path) -> XML::SaxParser

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



10
11
12
13
 
# File 'lib/libxml/sax_parser.rb', line 10

def self.file(path)
  context = XML::Parser::Context.file(path)
  self.new(context)
end

.io(io, options = {}) ⇒ Object

call-seq:

XML::SaxParser.io(io) -> XML::SaxParser
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.



25
26
27
28
29
 
# File 'lib/libxml/sax_parser.rb', line 25

def self.io(io, options = {})
  context = XML::Parser::Context.io(io)
  context.encoding = options[:encoding] if options[:encoding]
  self.new(context)
end

.string(string) ⇒ Object

call-seq:

XML::SaxParser.string(string)

Creates a new parser by parsing the specified string.



35
36
37
38
 
# File 'lib/libxml/sax_parser.rb', line 35

def self.string(string)
  context = XML::Parser::Context.string(string)
  self.new(context)
end

Instance Method Details

#parse ⇒ Object

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



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'ext/libxml/ruby_xml_sax_parser.c', line 75

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;
}