(partial Readme follows -- see web site for full information)

=Xml Serialization for Ruby

Download 1.0.pre3::
http://prdownloads.sourceforge.net/clxmlserial/clxmlserial.1.0.pre3.zip
REXML (>=1.2.5)*:: http://www.germane-software.com/~ser/Software/rexml
Home Page:: http://clabs.org/clxmlserial.htm
ViewCVS:: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/clxmlserial/xmls/
Anon CVS:: http://sourceforge.net/cvs/?group_id=51071

\* not tested (yet) with any version > 1.2.7.

please review the Security Issues section before using.

===Overview

Xml Serialization allows classes to be marshalled to and from XML.

It consists of a module (+XmlSerialization+) and modified standard
classes which add +to_xml+ and +from_xml+ methods. +to_xml+ is an
instance method which returns an XML element containing the data from
each instance variable in the including class. +from_xml+ is a
singleton/class method which accepts an XML element and creates an
instance of the class with the data in the element.

Currently, REXML is used for XML parsing. It's possible later versions
could plug-in other XML processors.

This project is still in a pre-release state, though functional. Feel
free to give me feedback (code contributions are of course always
welcome).

===License (see website for full license)

Copyright (c) 2002, Chris Morris (mailto:clxmlserial / clabs.org). BSD
license.

===Security Issues

1.0.pre3 switched from requiring attribute accessors for deserialization
to calling +instance_eval+. This is more convenient, but has a potential
security hole.

If the $+SAFE+ level is set to 1, all strings read in from a file are
marked tainted, and cannot be passed to +instance_eval+. However,
because REXML passes all strings through +Array+.+pack+ and
+Array+.+unpack+ calls to support various xml encodings, the string's
taintedness is lost, and the +instance_eval+ calls are allowed.

Beyond that, a $+SAFE+ level of 3 or more will simply not allow calls
to +instance_eval+, so the current release won't work under those
conditions.

In 1.0.pre4, I plan to re-add the original code that uses +send+ and
requires writer accessor methods, in addition to the +instance_eval+
code, and add a +XSConf+ switch to control this. The default setting
will be required accessor methods to play it safe with the potential
security hole.

I've been discussing this issue with Sean Russell, author of REXML, and
it's possible that REXML will be changed to retain the string's
taintedness through the encoding process. In this case, the security
hole should be closed, and the option to not use +instance_eval+ will be
necessary at any $+SAFE+ level.

===Contributors
* Harry Ohlsen
  * Support for classes in modules and inner classes
  * Code to use eval instead of send for classes w/o accessors
  * Code to workaround initialize method for instantiating classes with
    parameterized intializers

* Stefan Mueller
  * +TrueClass+ and +FalseClass+ support

===Change Log

====1.0.pre3
* Support for classes in modules and inner classes
* +instance_eval+ used instead of send to set instance data. Accessor
methods no longer required
* +XSConf+.+bypassInitialize+ option to deserialize classes without
default/parameterless initialize methods
* +TrueClass+ and +FalseClass+ support

===To Do

====pre4

- add back attribute accessor and a XSConf switch to support both options.
Using +instance_eval+ has a potential security hole that is not protected by
$SAFE == 1 even when deserializing from an xml file. Using +instance_eval+
is not an option in $SAFE >= 3.

- xmlserial gets stuck in a loop if the elements in my tree have references
to their parents. I had to delete the references before to_xmling the tree,
and restore them afterwards. Marshal does not have this problem. [Stefan
Mueller]