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
67
 
# 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_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;
}

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

#file=(value) ⇒ Object

:enddoc:



42
43
44
45
 
# File 'lib/libxml/sax_parser.rb', line 42

def file=(value)
  warn("XML::SaxParser#file is deprecated.  Use XML::SaxParser.file instead")
  @context = XML::Parser::Context.file(value)
end

#io=(value) ⇒ Object 



47
48
49
50
 
# File 'lib/libxml/sax_parser.rb', line 47

def io=(value)
  warn("XML::SaxParser#io is deprecated.  Use XML::SaxParser.io instead")
  @context = XML::Parser::Context.io(value)
end

#parse ⇒ Object

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



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'ext/libxml/ruby_xml_sax_parser.c', line 76

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

#string=(value) ⇒ Object 



52
53
54
55
 
# File 'lib/libxml/sax_parser.rb', line 52

def string=(value)
  warn("XML::SaxParser#string is deprecated.  Use XML::SaxParser.string instead")
  @context = XML::Parser::Context.string(value)
end