#######################################################################################
XML Interface (XMLI) Specifications
-----------------------------------
Draft
-----
Version: 0.01
Date: 5/19/2001
Author(s)
-------
Ilya Sterin (isterin@ciber.com)
Description
-----------
XMLI provides a driver independent interface to XML drivers
(XML::CSV, XML::Excel, and many more to come). XML drivers
allow mapping of data defined by other formats to XML,
therefore an independent interface is necessary to allow
consistant manipulation independent of data formats.
#######################################################################################
Copyright (c) Ilya Sterin 2001
Permission is hereby granted to make and distribute verbatim
(complete and unedited) copies of this document. Permission is also
granted to translate this document into other languages and formats
provided that all text is included.
---------------------------------------------------------------------------------------
Section 1 (Purpose)
---------------------------------------------------------------------------------------
XMLI will provide a common interface API to XML::* drivers to allow
conversion of various data type to XML. XMLI will hide the real driver
implementation, and will act as a (thin) layer on top of them to provide
common methods. XMLI will not restrict the driver implementation in
any way, other than provide required common methods which will be used
by the user.
---------------------------------------------------------------------------------------
Section 2 (Current Implementation)
---------------------------------------------------------------------------------------
There are currently two modules, XML::CSV and XML::Excel, available.
These modules convert CSV and Excel data to XML format. They allow
various flexible methods for file and data manipulation as well as
dumping to XML, XML declaration, and doctype declaration. The do not
in any way validate the XML, and are not designed to do so. Other
modules are more suitable for that task.
---------------------------------------------------------------------------------------
Section 3 (Guidelines)
---------------------------------------------------------------------------------------
o XMLi will provide a **fast**, **efficient**, and easy interface to
convert data types to XML.
o Speed and efficiency is very important since using XMLI within a
program to convert files to XML and then using other modules for
XML validation, processing, etc..., already provides huge overhead.
There should really be very little overhead in using XMLI.
o XMLI itself will be very small and efficient and run on top of
XML::* drivers to call it's functions.
o XMLI can be written in pure Perl, although if a C interface is
needed and is proven to work more efficently, it will be implemented.
o XMLI and it's drivers will adapt to object oriented style
so that it can easily be inhereted by other modules and used in an
object oriented fashion.
o XMLI will support UTF-8/UTF-16/ISO-8859-1 character
sets.
o XMLI will support dynamic loading of XML::* drivers
o XMLI will be available under GNU or Artistic License, and
will be up to the users choice.
---------------------------------------------------------------------------------------
Section 4 (Visual Diagram)
---------------------------------------------------------------------------------------
--- ______\ ------------- ______\ -------------
| | / | XML::CSV | / | CSV file |
--------------- | X | ------------- -------------
|Perl program |_____\ | M |______\ ------------- ______\ -------------
|using XMLI | / | L | / | XML::Excel | / | Excel file |
--------------- | I | ------------- -------------
| |______\ ------------- ______\ -------------
--- / | XML::* | / | .* file |
------------- -------------
---------------------------------------------------------------------------------------
Section 5 (Functions)
---------------------------------------------------------------------------------------
new(driver) || new(driver, \%attr)
o Creates a new XMLI object.
o Dynamically loads the driver
o Sets attributes/defaults
parse_data(file_name, \%attr) || parse_data(\$string, \%attr) ||
parse_data(STDIN, \%attr)
o Open the file_name for read if provided one
o Read data in from a file_name, $string, or a file handle
o Call a parse method of the XML::* driver, passing it the
reference to data, as well as reference to data structure
(XMLI->{column_data}), reference to tag names array
(XMLI->{column_headings}), to load the data into
o Receive and process the data structure as needed
o close the file handle
declare_xml(\%attr)
o Declares XML with version, encoding, and standalone attributes
o Sets a XMLI attribute {xml_declare} to the declared string (for
later processing)
declare_doctype(\%attr)
o Declares XML doctype with source, location1, location2, and
subset attributes
o Sets a XMLI attribute {doctype_declare} to the declared string
(for later processing)
print_xml(file_name, \%attr) || print_xml(\$string, \%attr) ||
print_xml(STDOUT, \%attr)
o Open the file_name for write if provided one
o Print the {xml_declare} and {doctype_declare} if applicable
o Call a print method of the XML::* driver, passing it
the reference to the data structure and tag names created by
parse_data, as well as the reference to the string or file
handle, and various attributes
o close the file_handle
Add other methods here..........
---------------------------------------------------------------------------------------
Section 5 (Publicly accessible data)
---------------------------------------------------------------------------------------
XMLI->{column_headings}
o Reference to XML data
XMLI->{column_data}
o Reference to XML tag names
XMLI->{xml_declare}
o Contains XML declaration
XMLI->{doctype_declare}
o Conatains doctype declaration
---------------------------------------------------------------------------------------
Section 6 (XML::* driver implementation)
---------------------------------------------------------------------------------------
XMLI will define a XML::* driver implementation interface.
The interface will be as minimal restrictive as possible, other
than provide mandatory methods which are used as callbacks by
XMLI itself.