Reading XML into a tree of XML nodes is typically done like this:
import Orchard.XML document = Orchard.XML.load('file.xml')
XML node constructors are one way to create XML nodes in code. There will also be modules that provide convenience methods for creating nodes. This is an example of using node constructors to build an XML tree:
import Orchard.XML document = Orchard.XML.Document() element = Orchard.XML.Element( name='my_element' ) document.contents.append(element) element.attributes['an_attr'] = Orchard.XML.Attribute() characters = Orchard.XML.Characters( data='some chars' ) element.contents.append(characters)
Using Orchard.XML in event-stream mode is described below.
This module has basic functions for reading XML documents and creating trees and provides objects for accessing and working with them.
|root||The root element of the document.|
|contents||An array containing any whitespace or comment nodes coming before or after the root element.|
|name||The element type name (including prefix).|
|namespace_uri||The namespace of this element.|
|prefix||The namespace prefix used on this element.||local_name||The local name of this element.|
|attributes||A mapping containing the attributes of this element, as Attribute objects. XML Namespace declarations are included, if any. See note below on Attribute indexes.|
|contents||An array containing the contents of the element, which may be any type of node.|
The attributes mapping is indexed by both name and by (namespace_uri, local_name). When assigning to this hash, the prefix, local_name, and namespace_uri of the attribute will override the mapping index used to make the assignment.
Mixing name and (namespace_uri, local_name) accesses can produce undefined results when prefix properties are modified on Attribute objects. It is recommended only to use name for unqualified (non-namespace) attributes and to use (namespace_uri, local_name) for all namespace attributes.
Users may assign an array to the attributes property, the mapping will be created from the Attribute objects in the array.
|name||The attribute name (including prefix).|
|namespace_uri||The namespace of this attribute.|
|prefix||The namespace prefix used on this attribute.||local_name||The local name of this attribute.|
|value||The normalized value of the attribute.|
|data||The characters from the XML document.|
Orchard.Parsers.XML provides an event-stream interface to an XML parser based on SAX but using Orchard.XML nodes as event parameters.
There are two basic interfaces to using the parser: the parser interface and the handler interface. The parser interface creates new parser instances, starts parsing, and provides additional information to handlers on request. The handler interface is used to receive parse events from the parser. This pattern is also commonly called "Producer and Consumer" or "Generator and Sink".
SAX is typically used like this:
import Orchard.Parsers.SAX handler = MyHandler() parser = Orchard.Parsers.SAX.SAX(handler=handler) parser.parse(uri)
Handlers are typically written like this:
class MyHandler: def startElement(self, element): print "Starting element " + element.name def endElement(self, element): print "Ending element " + element.name def characters(self, characters): print "characters: " + characters.data
Applications may not invoke the parse() method again while a parse is in progress (they should create a new parser instead for each nested XML document). Once a parse is complete, an application may reuse the same parser object, possibly with a different input source.
During the parse, the parser will provide information about the XML document through the registered event handlers.
These methods are the most commonly used by handlers.
The parser will invoke this method only once, before any other methods (except for setDocumentLocator() in advanced SAX handlers).
The parser will invoke this method only once, and it will be the last method invoked during the parse. The parser shall not invoke this method until it has either abandoned parsing (because of an unrecoverable error) or reached the end of input.The return value of endDocument() is returned by the parser's parse() method.
The parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement() event for every startElement() event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement() event.
The parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement() event for every endElement() event (even when the element is empty).
The parser will call this method to report each chunk of character data. Parsers may return all contiguous character data in a single chunk, or they may split it into several chunks (however, all of the characters in any single event must come from the same external entity so that the Locator provides useful information).