JSXML XML Tools Version 1.2 Readme

JSXML XML Tools

Version 1.2 Readme

June 20, 2001

This is the first public release of JSXML. It includes

REXML, a Regular Expression based XML parser
REXML Lite, a stripped down version of REXML
JSXMLBuilder, a linear interface to edit XML
JSXMLIterator, a tool to iterate the tree structure of REXML XML elements without using recursion

REXML, JSXMLBuilder, and JSXMLIterator are packaged together in jsxml.js. rexml.js includes REXML by itself, and REXML Lite is in rexmllite.js. rexmllitenw.js is REXML Lite with all whitespace removed.

For more information and the latest release see: http://www.envy.nu/voprak/jsxml/

For comments, a list of issues, or to submit an new issue see: http://sourceforge.net/projects/jsxml/

REXML

REXML is a simple non-validating XML parser based on regular expressions. It takes a string of XML and makes it accessible programmatically. The document is broken up into a root element which may have child elements, all of which (if they are type "element") may have child elements.

On instantiation REXML exposes the property rootElement. The root element is an XML Element, all of which have these properties and methods:

type The type of the element can be:

element
text
comment
pi
cdata

name If the type is "element," the tag name
childElements[] An array of XML Elements
parentElement The XML Element's parent XML Element
text The concatenated value of all text and cdata elements for the element
getText() Returns all text and cdata of all child elements
childElement Takes the elements tag name and returns the element if it's found in the element's children
attribute Takes the attribute name and returns the value, if found. Returns an empty string if the attribute isn't found.

Example:

function ShowXML(strXML) {
    var xmlDoc = new REXML(strXML);

    alert("The root element " + xmlDoc.rootElement.name + " has " xmlDoc.rootElement.childElements.length + " child elements.");
    for (var i=0; i<xmlDoc.rootElement.childElements.length; i++) {
        alert("Child element of type " + xmlDoc.rootElement.childElements[i].type);
    }
}

REXML Lite

REXML Lite is a stripped-down version of REXML. It is under 90 lines and under 2.5 kb. The type of an element is always "element." It doesn't handle comments, processing instructions, or cdata, and the text of an element is stored in the text property only, there is no getText() method and there are no text elements. It's useful for client-side XML parsing when there are only normal elements.

JSXMLBuilder

JSXMLBuilder is a tool for editing XML. It takes the XML from a REXML element and breaks it into a linear structure. This structure was chosen because it is easy to wire into a GUI. An element's position can be found through its index and level properties. index is the vertical index of the element in the document. level is the level it's nested at. So to find all of an element's child elements you'd start at the element and go down until you find an element with a level equal to or less than the starting element's level. Instead of adding an element to an element you add the element to the document and let it know the index and level where you want to add it. You'll find that the linear structure makes it much easier to program GUIs than a tree structure would.

The JSXMLBuilder object has these properties and methods:

XML The string of XML.
elements an array of JSXMLBuilder XML Elements
load Takes either a REXML XML Element or a string of XML, if a string of XML is passed it will still need REXML to load the XML.
addElementAt() Inserts the element at the specified level and index, after elements at the same level
insertElementAt() Inserts the element at the specified level and index
removeElement() removes the element at the specified index
moveElement() moves the element and child elements at index 1 to index 2.

JSXMLBuilder XML Elements have these properties and methods:

type The type is always "element," JSXMLBuilder currently only supports normal elements.
name The tag name
text The text of the element
index The vertical index of the element in the document
xmlBuilder A reference back to the xmlBuilder object
attribute Returns attribute value by name
setAttribute edits or adds an attribute
removeAttribute Removes an attribute
parentElement Returns the elements parent element
childElement Returns a child element by name or number (0 is the first child element, 1 is the second, etc)

JSXMLIterator

JSXMLIterator iterates through the tree structure without using recursion. It's easy to iterate tree structures with recursion, but costly. Avoiding recursion saves valuable time.

The JSXMLIterator object has these properties and methods:

xmleElem The current XML Element
getNextNode() Moves to the next element and sets xmleElem

Comparisons

	REXML (1.2)	REXML Lite (1.2)	Xparse (.91)	XML For Script (.22)
Size	6.5 kb	2.5 (1.9 with no whitespace) kb	8.27 kb	20 kb
Lines	150	90	390	690
Time to parse (s:ms):
20 Lines	0:010	0:010	0:030	0:020
300 Lines	0:201	0:140	1:771	1:651
700 Lines	0:411	0:371	3:124	3:643
1400 Lines	1:261	1:132	13:498	9:363
1400 Heavy Lines*	10:103	6:518	45:761	18:115

* 1 root element with attribute, sets of 1 element with one attribute, text, and no children, followed by two elements with three chilren each with text.

Licensing

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA