Class: XMLStreamin::XMLSpec

Inherits:
Object
  • Object
show all
Defined in:
lib/xmlstreamin.rb

Overview

XMLSpec is a base class intended to be extended as needed to handle processing for each type of expected element at each level of the XML hierarchy in the document. It has two categories of methods: those concerned with setup (which should not need to be modified) – #specs!, #default!, and #spec –, and the handler methods #start, #done, #empty and #text, that are intended to be specialized as necessary in derived classes or instances.

XMLSpec nodes are intended to be linked in a tree structure, reflecting the structure of the XML document to be read. Each node has a ‘dispatch’ (hash) table associating expected tag names with the subordinate XMLSpec nodes that should handle them; the hash table default should reference a node that will handle unexpected tags. If appropriate, you can use a single node to service several different tag names (bearing in mind that the dispatch table will be shared).

There are two predefined global XMLSpecs:

$specXMLVoid

This is a do-nothing basic XMLSpec that can be used to represent elements that you aren’t interested in. These and any subordinate elements will be skipped during parsing.

$specXMLFail

This will raise XMLError if it is invoked. It may be used if an unexpected element is a serious problem.

Instance Method Summary collapse

Constructor Details

#initialize ⇒ XMLSpec

Create an empty instance. Unless it is a non-functional leaf node, it will need to be specialized by filling the dispatch table ( #specs! ) and redefining methods as appropriate.



91
92
 
# File 'lib/xmlstreamin.rb', line 91

def initialize
@subspecs=Hash.new($specXMLVoid) end

Instance Method Details

#default!(spec) ⇒ Object

Set the XMLSpec that will be used for tag names that are not specifically referenced by the dispatch table.



96
97
 
# File 'lib/xmlstreamin.rb', line 96

def default! spec
@subspecs.default = spec end

#done(context, name) ⇒ Object

Called by XMLStreamListener when an end-tag for an element handled by this XMLSpec is read and the element was not empty. If it is actually an empty element #empty in invoked instead. If any action needs to be taken at the end of an element, this dummy method may be redefined. Arguments:

context

the context object at this level (application specific – may be nil). This is also the return value from the method, and will be passed back to XMLStreamListener (which does not keep track of context itself!). If the #start method provided a new context this must restore the one preserved at that time.

name

the actual tag name of the element. (Not normally needed, but it might be useful to have the name again here.)



155
156
157
 
# File 'lib/xmlstreamin.rb', line 155

def done context,name
		return context	# can get restored
end

#empty(context) ⇒ Object

Called by XMLStreamListener when an end-tag for an element handled by this XMLSpec is read and the element was empty. If it is not actually an empty element #done in invoked instead. If any action needs to be taken for an empty element, this dummy method may be redefined. Arguments:

context

the context object at this level (application specific – may be nil). This is also the return value from the method, and will be passed back to XMLStreamListener (which does not keep track of context itself!). If the #start method provided a new context this must restore the one preserved at that time.

name

the actual tag name of the element. (Not normally needed, but it might be useful to have the name again here.)



175
176
177
178
 
# File 'lib/xmlstreamin.rb', line 175

def empty context
	# called only if no enclosed text or elements
	return context	
end

#spec(name) ⇒ Object

Locates and returns the XMLSpec that handles name in the dispatch table.



112
113
 
# File 'lib/xmlstreamin.rb', line 112

def spec name
return @subspecs[name] end

#specs ⇒ Object

Convenience method for accessing the dispatch table; returns the hash.



108
109
 
# File 'lib/xmlstreamin.rb', line 108

def specs
return @subspecs end

#specs!(specs) ⇒ Object

Adds tagnames and their associated XMLSpecs to the dispatch table. The argument specs is a preconstructed hash that will be merged with any existing table. (There is no way of directly removing entries – except by overwriting them – as the tree is a static structure built before reading the document.)



104
105
 
# File 'lib/xmlstreamin.rb', line 104

def specs! specs
@subspecs.merge! specs end

#start(context, name, attrs) ⇒ Object

Called by XMLStreamListener when a start-tag for an element handled by this XMLSpec is read. Arguments:

context

the context object passed from the level above (application specific – may be nil). This is also the return value from the method, and will be passed on to any subordinate nodes. A derived version may actually supply a completely new context if desired, but if it does so, it must preserve the one it received (in an instance variable) for restoration later by the #done (or #empty) method. (In any normal situation the same context object – updated as required – will be used throughout. No special preservation is then needed, as long as all methods return it on exit.)

name

the actual tag name of the element. (The same node can handle several tagnames.)

attrs:: a hash of the attribute name/value pairs in the tag. The base method is a dummy that does nothing but return the context. Derived nodes will redefine the method as necessary.



135
136
137
 
# File 'lib/xmlstreamin.rb', line 135

def start context,name,attrs
		return context	# can get changed
end

#text(context, data) ⇒ Object

Called by XMLStreamListener when text is encountered within a handled element. It will be invoked separately for each text segment (separated by subordinate elements) within the element. It is a dummy method that may be redefined as desired to handle the text. It does not need to return the context.



185
186
 
# File 'lib/xmlstreamin.rb', line 185

def text context,data
end