View source for Lib/xml

[[Category: Library]]
== XML parsing ==

XML is used a lot these days, even by the library itself (the [[library_class:STORABLE|storable]] [[library_class:REPOSITORY|repository]] uses it, see [[lib/storage]]).

=== The parser ===

To use the XML parser, you need to proceed in two steps:
# Connect the parser to an [[library_class:OUTPUT_STREAM|output stream]], using the <tt>[[library_class:XML_PARSER|XML_PARSER]].connect_to</tt> feature;
# Parse the document by sending parsing events to the provided [[library_class:XML_CALLBACKS|events receiver]], using the <tt>[[library_class:XML_PARSER|XML_PARSER]].parse</tt> feature. Either you use a real events receiver, SAX-fashion (just inherit from [[library_class:XML_CALLBACKS|<tt>XML_CALLBACKS</tt>]]); or you can provide an [[library_class:XML_TREE|<tt>XML_TREE</tt>]], DOM-fashion (this tree implements the events receiver interface and builds its nodes when receiving events from the parser).

=== Events interface ("SAX") ===

[http://www.saxproject.org/ SAX] means "Simple API for XML". Liberty Eiffel's API is not exactly identical; nonetheless it resembles the API found in other languages.

In this case, you have to inherit from [[library_class:XML_CALLBACKS|<tt>XML_CALLBACKS</tt>]] and implement its many deferred features.

During the parsing, the [[library_class:XML_PARSER|XML parser]] calls that class to tell it, it enters a node, finds some attribute, some text, and so on. Errors are also reported.

=== Tree interface ("DOM") ===

[http://www.w3.org/DOM/ DOM] means "Document Object Model". Liberty Eiffel's DOM implementation is not endorsed by W3C but its API is equivalent.

To use an [[library_class:XML_TREE|XML tree]], you have to give it to the [[library_class:XML_PARSER|XML parser]]. The tree builds itself when called back by the parser's events.

If there were no errors, the XML tree provides a <tt>root</tt> feature that is an [[library_class:XML_NODE|<tt>XML_NODE</tt>]].

Errors can be managed by using the <tt>with_error_handler</tt> feature. The given agent will be called with the errors the parser finds.

=== Small Comparison SAX vs. DOM ===

Using one or the other is not only a matter of taste, but it also depends on where you put your priorities. In other words, you have to evaluate performance against simplicity.

{| cellspacing="10px" width="100%"
|- style="background-color: #fff3f3"
|valign="top" align="center"| Topic
|valign="top" align="center"| '''DOM'''
|valign="top" align="center"| '''SAX'''
|-
|valign="center" align="center" style="background-color: #fff3f3"| Simplicity
|valign="top"|Very simple: the whole tree is built in a preliminary pass and all the nodes are available for as long as needed afterwards.
|valign="top"|Less simple: the parser provides a stream of events that have to be dealt with.
On the other hand you have more control over which events are important and what you actually ''do'' with them.
|-
|valign="center" align="center" style="background-color: #fff3f3"| Memory
|valign="top"|Memory hungry since objects are built to represent the whole tree
|valign="top"|Not necessarily memory hungry since there is only a stream of feature calls. Of course you may need to create your own objects but that's up to you.
|-
|valign="center" align="center" style="background-color: #fff3f3"| Performance
|valign="top"|The XML document is used in two passes:
# create the tree (parse the whole document)
# use the tree (navigate in the tree to find nodes of interest)
|valign="top"|The XML document may be exploited in one pass since you have first-hand access to the events during the parsing.
|}

== Validation ==

To validate an XML file, Liberty Eiffel provides a DTD parser. The XML parser may parse the provided DTD and validate your file.

The parser recognizes any kind of DTD: inlined, in a file or on the network. You may also use a cache that locally provides network DTDs (see [[library_class:XML_DTD_PUBLIC_REPOSITORY|<tt>XML_DTD_PUBLIC_REPOSITORY</tt>]]).

== Namespaces and other advanced features ==

Namespaces are not yet natively implemented in Liberty Eiffel, but they will be added later ('''contributions welcome!!''')

The idea is to implement some new kind of XML_CALLBACK that takes the semi-colon in nodes names into account.

Schema validation (therefore using namespaces) may be set by calling <tt>[[library_class:XML_CALLBACKS|XML_CALLBACKS]].set_validator</tt>.

Path parsing has to be implemented.