== WDDX

From http://www.openwddx.org/faq/:
 WDDX is an XML-based technology that enables the exchange of complex data between Web programming languages, 
 creating what some refer to as 'Web syndicate networks'. 
 WDDX consists of a language-independent representation of data based on an XML 1.0 DTD, and a set of 
 modules for a wide variety of languages that use WDDX. 
 WDDX can be used with HTTP, SMTP, POP, FTP and other Internet protocols that support transferring textual data.

WDDX Home: http://www.openwddx.org/

The Ruby WDDX Gem enables easy usage of WDDX in Ruby.

== Author

Copyright (C) 2005, 2006, 2007 by Stefan Saasen <s-NOSPAM-REMOVE@juretta.com> - http://juretta.com/

== Installation

Just run <tt>[sudo] gem install wddx</tt> to install the WDDX Gem.

== Deserialization
You can very easily deserialize WDDX data from a file or from a string.

Simple usage example:
 
 require 'rubygems'
 require 'wddx'        
 # data.xml contains <?xml version="1.0">\
 # <wddxPacket version='1.0'><header><comment>A comment</comment></header><data><string>Klaus 
 Tester</string></data></wddxPacket> 
 wddx = WDDX.load(File.open("data.xml"))
 puts wddx.comment # "A comment"
 puts wddx.data.class # String
 puts wddx.data # "Klaus Tester"
 
WDDX.load accepts a string with xml content, a file object or any object that provides a +read+ method.
 packet =  WDDX.load(open("http://wddx.rubyforge.org/wddx.xml"))
or
 packet =  WDDX.load(File.open("data.xml")) 
or
 packet =  WDDX.load(open("data.xml"))
or
 xml = "<wddxPacket version='1.0'><header/><data><number>123.667</number></data></wddxPacket>"
 packet = WDDX.load(xml)
 puts w.data # => 123.667
 
 xml = <<-EOF 
 <wddxPacket version='1.0'>
 <header/>
 <data>
     <struct>
         <var name='aNull'>
             <null/>
         </var>
         <var name='aString'>
             <string>a string</string>
         </var>
     </struct>
    </data>
  </wddxPacket> 
 EOF
 w = WDDX.load(xml)
 p w.data # => {"aString"=>"a string", "aNull"=>nil}
                                         
If the root element is a +struct+ you can use a shortcut version:
 
 w.data["aString"] # => "a string"

can be written as:

 w.aString # => "a string"


== Serialization
The core Ruby Classes +Symbol+, +String+, +Numeric+, +true+, +false+, +nil+, +Hash+, +Array+ and +Time+ can be 
serialized by calling
+to_wddx+.

 require 'wddx'
 "Stefan Saasen".to_wddx        # => "<wddxPacket version='1.0'><header/><data>\
                                #     <string>Stefan Saasen</string></data></wddxPacket>"

 123.667.to_wddx                # => "<wddxPacket version='1.0'><header/><data>\
                                #     <number>123.667</number></data></wddxPacket>"

 Math::PI.to_wddx               # => "<wddxPacket version='1.0'><header/><data>\
                                #   <number>3.14159265358979</number></data></wddxPacket>"

 [1000, "Klaus Tester"].to_wddx # => "<wddxPacket version='1.0'><header/><data>\
                                #   <array length='2'><number>1000</number>\
                                #   <string>Klaus Tester</string></array></data></wddxPacket>"

=== WDDX.dump
You can use WDDX.dump to serialize Ruby objects.
 WDDX.dump("Hallo Welt") # => "<wddxPacket version='1.0'><header/><data><string>Hallo Welt</string></data></wddxPacket>"

 

Custom Ruby classes can be serialized by adding a +to_wddx_properties+ method (in the style of the YAML library) and 
calling WDDX.dump.

 class SerializeFromOutside
   def initialize(a,b,c)
     @a, @b, @c = a, b, c
   end
   
   def to_wddx_properties
     ["@a", "@c"]
   end  
 end 
 obj = SerializeFromOutside.new("This is a", "This is b", 123) 
 WDDX.dump(obj) # => "<wddxPacket version='1.0'><header/><data><struct><var name='a'>\
                # <string>This is a</string></var><var name='c'><number>123</number>\
                # </var></struct></data></wddxPacket>"

It is possible to include the WDDX module to get a behaviour similiar to the core Ruby classes.

 class MyObject
   include WDDX
   attr_accessor :name, :value, :price

   def to_wddx_properties
     ["@name", :custom_price]
   end               

   def custom_price
     @price * 1.05
   end
 end

 obj = MyObject.new("Stefan Saasen", 120)
 puts ob.to_wddx
 # => "<wddxPacket version='1.0'><header/><data><struct><var name='name'>\
 # <string>Stefan Saasen</string></var><var name='custom_price'><number>126.0</number>\
 # </var></struct></data></wddxPacket>"     
                                    
== WDDX Data types

WDDX defines some data types which can not be mapped to native ruby classes. WDDX::Binary represents a binary object 
(which is in fact a BASE64 encoded String). WDDX::RecordSet represents a RecordSet with data rows an column meta 
information.

== Type mapping
The following table shows the data type mapping WDDX <=> Ruby.
 WDDX Type      Ruby Type
 ---------      ---------------------
 String         String
 Number         Numeric
 Boolean        TrueClass, FalseClass
 Datetime       Time
 Null           nil
 Binary         WDDX::Binary
 Array          Array
 Struct         Hash
 Recordset      WDDX::RecordSet


== Rails Plugin

You can add the wddx gem to your rails application to be able to serialize ActiveRecord objects to WDDX.

In config/environment.rb add:
 require 'wddx'

Example:
 
 ...
 a_ar_obj.to_wddx # => <wddxPacket...


== See

Homepage:: http://rubyforge.org/projects/wddx/
Blog:: http://juretta.com/
Bugtracker:: http://rubyforge.org/tracker/?group_id=2715
WDDX:: http://www.openwddx.org/