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.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'ext/libxml/ruby_xml_sax_parser.c', line 69

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.



8
9
10
11
 
# File 'lib/libxml/sax_parser.rb', line 8

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.



23
24
25
26
27
 
# File 'lib/libxml/sax_parser.rb', line 23

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.



33
34
35
36
 
# File 'lib/libxml/sax_parser.rb', line 33

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

Instance Method Details

#file=(value) ⇒ Object

:enddoc:



40
41
42
43
 
# File 'lib/libxml/sax_parser.rb', line 40

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

#io=(value) ⇒ Object 



45
46
47
48
 
# File 'lib/libxml/sax_parser.rb', line 45

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.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'ext/libxml/ruby_xml_sax_parser.c', line 92

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)&rxml_sax_handler;
    
  status = xmlParseDocument(ctxt);

  /* IMPORTANT - null the handle to our sax handler
     so libxml doesn't try to free it.*/
  ctxt->sax = NULL;
  
  /* 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 



50
51
52
53
 
# File 'lib/libxml/sax_parser.rb', line 50

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