module XML::Mapping

This is the central interface module of the xml-mapping library.

Including this module in your classes adds XML mapping capabilities to them.

Example¶ ↑

Input document:¶ ↑

<company name="ACME inc.">

    <address>
      <city>Berlin</city>
      <zip>10113</zip>
    </address>

    <customers>

      <customer id="jim">
        <name>James Kirk</name>
      </customer>

      <customer id="ernie">
        <name>Ernie</name>
      </customer>

      <customer id="bert">
        <name>Bert</name>
      </customer>

    </customers>

</company>

mapping class declaration:¶ ↑

require 'xml/mapping'

## forward declarations
class Address; end
class Customer; end

class Company
  include XML::Mapping

  text_node :name, "@name"
  object_node :address, "address", :class=>Address
  array_node :customers, "customers", "customer", :class=>Customer
end

class Address
  include XML::Mapping

  text_node :city, "city"
  numeric_node :zip, "zip"
end

class Customer
  include XML::Mapping

  text_node :id, "@id"
  text_node :name, "name"

  def initialize(id,name)
    @id,@name = [id,name]
  end
end

usage:¶ ↑

c = Company.load_from_file('company.xml') 
=> #<Company:0x007ff64a1077a8 @name="ACME inc.", @address=#<Address:0x007ff64a106f60 @city="Berlin", @zip=10113>, @customers=[#<Customer:0x007ff64a105700 @id="jim", @name="James Kirk">, #<Customer:0x007ff64a1045a8 @id="ernie", @name="Ernie">, #<Customer:0x007ff64a0ff030 @id="bert", @name="Bert">]>
c.name 
=> "ACME inc."
c.customers.size 
=> 3
c.customers[1] 
=> #<Customer:0x007ff64a1045a8 @id="ernie", @name="Ernie">
c.customers[1].name 
=> "Ernie"
c.customers[0].name 
=> "James Kirk"
c.customers[0].name = 'James Tiberius Kirk' 
=> "James Tiberius Kirk"
c.customers << Customer.new('cm','Cookie Monster') 
=> [#<Customer:0x007ff64a105700 @id="jim", @name="James Tiberius Kirk">, #<Customer:0x007ff64a1045a8 @id="ernie", @name="Ernie">, #<Customer:0x007ff64a0ff030 @id="bert", @name="Bert">, #<Customer:0x007ff64a0f78f8 @id="cm", @name="Cookie Monster">]
xml2 = c.save_to_xml 
=> <company name='ACME inc.'> ... </>
xml2.write($stdout,2) 
<company name='ACME inc.'>
  <address>
    <city>
      Berlin
    </city>
    <zip>
      10113
    </zip>
  </address>
  <customers>
    <customer id='jim'>
      <name>
        James Tiberius Kirk
      </name>
    </customer>
    <customer id='ernie'>
      <name>
        Ernie
      </name>
    </customer>
    <customer id='bert'>
      <name>
        Bert
      </name>
    </customer>
    <customer id='cm'>
      <name>
        Cookie Monster
      </name>
    </customer>
  </customers>
</company>#

So you have to include XML::Mapping into your class to turn it into a “mapping class”, that is, to add XML mapping capabilities to it. An instance of the mapping classes is then bidirectionally mapped to an XML node (i.e. an element), where the state (simple attributes, sub-objects, arrays, hashes etc.) of that instance is mapped to sub-nodes of that node. In addition to the class and instance methods defined in XML::Mapping, your mapping class will get class methods like 'text_node', 'array_node' and so on; I call them “node factory methods”. More precisely, there is one node factory method for each registered node type. Node types are classes derived from XML::Mapping::Node; they're registered with the xml-mapping library via ::add_node_class. The node types TextNode, BooleanNode, NumericNode, ObjectNode, ArrayNode, and HashNode are automatically registered by xml/mapping.rb; you can easily write your own ones. The name of a node factory method is inferred by 'underscoring' the name of the corresponding node type; e.g. 'TextNode' becomes 'text_node'. Each node factory method creates an instance of the corresponding node type and adds it to the mapping class (not its instances). The arguments to a node factory method are automatically turned into arguments to the corresponding node type's initializer. So, in order to learn more about the meaning of a node factory method's parameters, you read the documentation of the corresponding node type. All predefined node types expect as their first argument a symbol that names an r/w attribute which will be added to the mapping class. The mapping class is a normal Ruby class; you can add constructors, methods and attributes to it, derive from it, derive it from another class, include additional modules etc.

Including XML::Mapping also adds all methods of XML::Mapping::ClassMethods to your class (as class methods).

It is recommended that if your class does not have required initialize method arguments. The XML loader attempts to create a new object using the new method. If this fails because the initializer expects an argument, then the loader calls allocate instead. allocate bypasses the initializer. If your class must have initializer arguments, then you should verify that bypassing the initializer is acceptable.

As you may have noticed from the example, the node factory methods generally use XPath expressions to specify locations in the mapped XML document. To make this work, XML::Mapping relies on XML::XXPath, which implements a subset of XPath, but also provides write access, which is needed by the node types to support writing data back to XML. Both XML::Mapping and XML::XXPath use REXML (www.germane-software.com/software/rexml/) to represent XML elements/documents in memory.