From: Chris Morris <home@...>
Date: 2002-03-29T13:59:36+09:00
Subject: [ANN] Xml Serialization 1.0.pre2

Thanks to all for the feedback so far. The latest readme has all the new
stuff intertwined. Hit the Usage section for more.

=Xml Serialization for Ruby

Download 1.0.pre2::
http://prdownloads.sourceforge.net/scrapware/clxmlserial.1.0.pre2.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/scrapware/clxmlserial/
Anon CVS:: http://sourceforge.net/cvs/?group_id=17451

===Overview

Xml Serialization allows classes to be marshalled to and from XML, with an
emphasis on concise, human readable and editable 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. In later versions, I plan to
refactor
out the dependency on REXML so other XML processors could be plugged-in.

This is still very much in a pre-release state, though functional. If your
interested in this project, please feel free to give me feedback (code
contributions are of course always welcome).

===License

Copyright (c) 2002, Chris Morris (mailto:chrismo@clabs.org). BSD license.

===Install

  % ruby install.rb

===Usage

See the examples directory for a sample. Unit tests are also included in
clxmlserialtest.rb. Here's a quick sample:

  require 'cl/xmlserial'

  class MyClass
    include XmlSerialization

    attr_accessor :attr

    def initialize
      attr = 0
    end
  end

  doc = REXML::Document.new(File.open("class.xml"))
  c = MyClass.from_xml(doc.root)
  c.attr = 60
  f = File.new("class.xml", File::CREAT|File::TRUNC|File::RDWR)
  c.to_xml.write(f, -1)
  f.close

yields either:

  <MyClass>
    <attr>
      <Fixnum>60</Fixnum>
    </attr>
  </MyClass>

or:

  <MyClass>
    <attr>60</attr>
  </MyClass>

The +XmlSerialization+ module includes a singleton configuration class with
an
+outputTypeElements+ setting. Setting this to false gives more concise XML
(the
latter example above). In order to ensure the data is read in correctly, the
instance variables should be initialized in the class's initialize method.

Attempts to correctly grok Strings and Numerics will be made for
uninitialized
instance vars, so the latter example above will read in 60 as a Fixnum, even
if
@attr is not initialized. If the value is neither a valid Integer or Float,
then
it's read in as a String.

All forms of Ruby Numeric notation are supported as well. So this:

  <Array>-5.4,5.a,4e5,0xaabb,123_456</Array>

is read in as:

  [-5.4, "5.a", 400000.0, 43707, 123456]

Arrays and Hashes also work with +outputTypeElements+ set to false, assuming
the
items/keys/values are all of type String or Numeric. In that case, a CSV
string
is output. For example:

  c = MyClass.new
  c.attr = ['a', 5]

becomes

  <MyClass>
    <attr>a,5</attr>
  </MyClass>

and

  c = MyClass.new
  c.attr = { 'a' => 5, 'b' => 6 }

becomes

  <MyClass>
    <attr>a=5,b=6</attr>
  </MyClass>

If any of the items/keys/values are neither a String or Numeric, then type
elements are automagically used:

  c = MyClass.new
  c.attr = ['a', ['b', 'c']]

becomes

  <MyClass>
    <attr>
      <Array>
        <String>a</String>
        <Array>
          <String>b</String>
          <String>c</String>
        </Array>
      </Array>
    </attr>
  </MyClass>

Currently, the following standard classes are supported:

* +String+
* +Fixnum+
* +Array+
* +Hash+
* +Time+
* +Integer+ (+Fixnum+, +Bignum+)
* +Float+