xml-mapping 0.8.1 → 0.9.1

data/examples/xpath_ensure_created.intout

@@ -17,98 +17,119 @@ rootelt=d.root
 XML::XXPath.new("/bar/baz[@key='work']").first(rootelt,:ensure_created=>true)
 => <baz key='work'> ... </>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
-    </bar>
-  </foo>
-
-### no change (path existed before)
+ 
+<foo>
+  <bar>
+    <baz key='work'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
+  </bar>
+</foo>### no change (path existed before)
 
 
 XML::XXPath.new("/bar/baz[@key='42']").first(rootelt,:ensure_created=>true)
 => <baz key='42'/>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-      </bar>
-  </foo>
-
-### path was added
+  </bar>
+</foo>### path was added
 
 XML::XXPath.new("/bar/baz[@key='42']").first(rootelt,:ensure_created=>true)
 => <baz key='42'/>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-      </bar>
-  </foo>
-
-### no change this time
+  </bar>
+</foo>### no change this time
 
 XML::XXPath.new("/bar/baz[@key2='hello']").first(rootelt,:ensure_created=>true)
-=> <baz key2='hello' key='work'> ... </>
+=> <baz key='work' key2='hello'> ... </>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key2='hello' key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work' key2='hello'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-      </bar>
-  </foo>
-
-### this fit in the 1st "baz" element since
+  </bar>
+</foo>### this fit in the 1st "baz" element since
 ### there was no "key2" attribute there before.
 
 XML::XXPath.new("/bar/baz[2]").first(rootelt,:ensure_created=>true)
 => <baz key='play'> ... </>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key2='hello' key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work' key2='hello'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-      </bar>
-  </foo>
-
-### no change
+  </bar>
+</foo>### no change
 
 XML::XXPath.new("/bar/baz[6]/@haha").first(rootelt,:ensure_created=>true)
-=> #<XML::XXPath::Accessors::Attribute:0x3223b0 @parent=<baz haha='[unset]'/>, @name="haha">
+=> #<XML::XXPath::Accessors::Attribute:0x7f4876522658 @name="haha", @parent=<baz haha='[unset]'/>>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key2='hello' key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work' key2='hello'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-        <baz/>
-        <baz/>
-        <baz haha='[unset]'/>
-      </bar>
-  </foo>
-
-### for there to be a 6th "baz" element, there must be 1st..5th "baz" elements
+    <baz/>
+    <baz/>
+    <baz haha='[unset]'/>
+  </bar>
+</foo>### for there to be a 6th "baz" element, there must be 1st..5th "baz" elements
 
 XML::XXPath.new("/bar/baz[6]/@haha").first(rootelt,:ensure_created=>true)
-=> #<XML::XXPath::Accessors::Attribute:0x31f830 @parent=<baz haha='[unset]'/>, @name="haha">
+=> #<XML::XXPath::Accessors::Attribute:0x7f4876516bc8 @name="haha", @parent=<baz haha='[unset]'/>>
 d.write($stdout,2)
-    <foo>
-    <bar>
-      <baz key2='hello' key='work'>Java</baz>
-      <baz key='play'>Ruby</baz>
+ 
+<foo>
+  <bar>
+    <baz key='work' key2='hello'>
+      Java
+    </baz>
+    <baz key='play'>
+      Ruby
+    </baz>
     <baz key='42'/>
-        <baz/>
-        <baz/>
-        <baz haha='[unset]'/>
-      </bar>
-  </foo>
-
-### no change this time
+    <baz/>
+    <baz/>
+    <baz haha='[unset]'/>
+  </bar>
+</foo>### no change this time
 

data/examples/xpath_pathological.intout

@@ -24,14 +24,13 @@ newelt = XML::XXPath.new("bar/*").first(rootelt, :ensure_created=>true)
 => </>
 
 d.write($stdout,2)
-    <foo>
-    <bar>
-        </>
-      </bar>
-    <bar/>
-  </foo>
-
-
+ 
+<foo>
+  <bar>
+    </>
+  </bar>
+  <bar/>
+</foo>
 ### a new "unspecified" element was created
 newelt.unspecified?
 => true
@@ -43,14 +42,15 @@ newelt.unspecified?
 => false
 
 d.write($stdout,2)
-    <foo>
-    <bar>
-        <new-one>hello!</new-one>
-      </bar>
-    <bar/>
-  </foo>
-
-
+ 
+<foo>
+  <bar>
+    <new-one>
+      hello!
+    </new-one>
+  </bar>
+  <bar/>
+</foo>
 ### you could also set unspecified to false explicitly, as in:
 newelt.unspecified=true
 

data/examples/xpath_usage.intout

@@ -44,7 +44,7 @@ path2.all(d)
 ## "first" raises XML::XXPathError in such cases...
 path2.first(d)
 XML::XXPathError: path not found: /foo/bar[2]/baz[4]
-	from ../lib/xml/../xml/xxpath.rb:130:in `first'
+	from ../lib/xml/xxpath.rb:75:in `first'
 
 ##...unless we allow nil returns
 path2.first(d,:allow_nil=>true)

data/install.rb

@@ -26,6 +26,7 @@ end
 files = %w-
 xml/mapping.rb
 xml/xxpath.rb
+xml/xxpath_methods.rb
 xml/mapping/base.rb
 xml/mapping/standard_nodes.rb
 xml/mapping/version.rb

data/lib/xml/mapping.rb

@@ -1,14 +1,16 @@
 # xml-mapping -- bidirectional Ruby-XML mapper
-#  Copyright (C) 2004,2005 Olaf Klischat
+#  Copyright (C) 2004-2006 Olaf Klischat
 
 $:.unshift(File.dirname(__FILE__)+"/..")
 
 require 'xml/mapping/base'
 require 'xml/mapping/standard_nodes'
 
+XML::Mapping.add_node_class XML::Mapping::Node
 XML::Mapping.add_node_class XML::Mapping::TextNode
 XML::Mapping.add_node_class XML::Mapping::NumericNode
 XML::Mapping.add_node_class XML::Mapping::ObjectNode
 XML::Mapping.add_node_class XML::Mapping::BooleanNode
 XML::Mapping.add_node_class XML::Mapping::ArrayNode
 XML::Mapping.add_node_class XML::Mapping::HashNode
+XML::Mapping.add_node_class XML::Mapping::ChoiceNode

data/lib/xml/mapping/base.rb

@@ -1,5 +1,5 @@
 # xml-mapping -- bidirectional Ruby-XML mapper
-#  Copyright (C) 2004,2005 Olaf Klischat
+#  Copyright (C) 2004-2006 Olaf Klischat
 
 require 'rexml/document'
 require "xml/xxpath"
@@ -60,6 +60,14 @@ module XML
   # 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
@@ -70,45 +78,96 @@ module XML
   # elements/documents in memory.
   module Mapping
 
-    # can't really use class variables for these because they must be
+    # defined mapping classes for a given root elt name and mapping
+    # name (nested map from root element name to mapping name to array
+    # of classes)
+    #
+    # can't really use a class variable for this because it must be
     # shared by all class methods mixed into classes by including
     # Mapping. See
     # http://user.cs.tu-berlin.de/~klischat/mydocs/ruby/mixin_class_methods_global_state.txt.html
     # for a more detailed discussion.
-    Classes_w_default_rootelt_names = {}     #:nodoc:
-    Classes_w_nondefault_rootelt_names = {}  #:nodoc:
+    Classes_by_rootelt_names = {}  #:nodoc:
+    class << Classes_by_rootelt_names
+      def create_classes_for rootelt_name, mapping
+        (self[rootelt_name] ||= {})[mapping] ||= []
+      end
+      def classes_for rootelt_name, mapping
+        (self[rootelt_name] || {})[mapping] || []
+      end
+      def remove_class rootelt_name, mapping, clazz
+        classes_for(rootelt_name, mapping).delete clazz
+      end
+      def ensure_exists rootelt_name, mapping, clazz
+        clazzes = create_classes_for(rootelt_name, mapping)
+        clazzes << clazz unless clazzes.include? clazz
+      end
+    end
+
 
     def self.append_features(base) #:nodoc:
       super
       base.extend(ClassMethods)
-      Classes_w_default_rootelt_names[base.default_root_element_name] = base
+      Classes_by_rootelt_names.create_classes_for(base.default_root_element_name, :_default) << base
+      base.initializing_xml_mapping
     end
 
-
-    # Finds the mapping class corresponding to the given XML root
-    # element name. This is the inverse operation to
+    # Finds a mapping class corresponding to the given XML root
+    # element name and mapping name. There may be more than one such class --
+    # in that case, the most recently defined one is returned
+    #
+    # This is the inverse operation to
     # <class>.root_element_name (see
     # XML::Mapping::ClassMethods.root_element_name).
-    def self.class_for_root_elt_name(name)
+    def self.class_for_root_elt_name(name, options={:mapping=>:_default})
       # TODO: implement Hash read-only instead of this
       # interface
-      Classes_w_nondefault_rootelt_names[name] ||
-        Classes_w_default_rootelt_names[name]
+      Classes_by_rootelt_names.classes_for(name, options[:mapping])[-1]
     end
 
+    # Finds a mapping class and mapping name corresponding to the
+    # given XML root element name. There may be more than one
+    # (class,mapping) tuple for a given root element name -- in that
+    # case, one of them is selected arbitrarily.
+    #
+    # returns [class,mapping]
+    def self.class_and_mapping_for_root_elt_name(name)
+      (Classes_by_rootelt_names[name] || {}).each_pair{|mapping,classes| return [classes[0],mapping] }
+      nil
+    end
 
-    def initialize_xml_mapping  #:nodoc:
-      self.class.all_xml_mapping_nodes.each do |node|
-        node.obj_initializing(self)
+    # Xml-mapping-specific initializer.
+    #
+    # This will be called when a new instance is being initialized
+    # from an XML source, as well as after calling _class_._new_(args)
+    # (for the latter case to work, you'll have to make sure you call
+    # the inherited _initialize_ method)
+    #
+    # The :mapping keyword argument gives the mapping the instance is
+    # being initialized with. This is non-nil only when the instance
+    # is being initialized from an XML source (:mapping will contain
+    # the :mapping argument passed (explicitly or implicitly) to the
+    # load_from_... method).
+    #
+    # When the instance is being initialized because _class_._new_ was
+    # called, the :mapping argument is set to nil to show that the
+    # object is being initialized with respect to no specific mapping.
+    #
+    # The default implementation of this method calls obj_initializing
+    # on all nodes. You may overwrite this method to do your own
+    # initialization stuff; make sure to call +super+ in that case.
+    def initialize_xml_mapping(options={:mapping=>nil})
+      self.class.all_xml_mapping_nodes(:mapping=>options[:mapping]).each do |node|
+        node.obj_initializing(self,options[:mapping])
       end
     end
 
-    # private :initialize_xml_mapping
-
-    # Initializer. Calls obj_initializing(self) on all nodes. You
-    # should call this using +super+ in your mapping classes to
-    # inherit this behaviour.
+    # Initializer. Called (by Class#new) after _self_ was created
+    # using _new_.
+    #
+    # XML::Mapping's implementation calls #initialize_xml_mapping.
     def initialize(*args)
+      super(*args)
       initialize_xml_mapping
     end
 
@@ -119,19 +178,21 @@ module XML
     # object's class are processed (i.e. have their
     # #xml_to_obj method called) in the order of their definition
     # inside the class, then #post_load is called.
-    def fill_from_xml(xml)
-      pre_load(xml)
-      self.class.all_xml_mapping_nodes.each do |node|
+    def fill_from_xml(xml, options={:mapping=>:_default})
+      raise(MappingError, "undefined mapping: #{options[:mapping].inspect}") \
+        unless self.class.xml_mapping_nodes_hash.has_key?(options[:mapping])
+      pre_load xml, :mapping=>options[:mapping]
+      self.class.all_xml_mapping_nodes(:mapping=>options[:mapping]).each do |node|
         node.xml_to_obj self, xml
       end
-      post_load
+      post_load :mapping=>options[:mapping]
     end
 
     # This method is called immediately before _self_ is filled from
     # an xml source. _xml_ is the source REXML::Element.
     #
     # The default implementation of this method is empty.
-    def pre_load(xml)
+    def pre_load(xml, options={:mapping=>:_default})
     end
 
     
@@ -143,7 +204,7 @@ module XML
     # exception to abandon the whole loading process.
     #
     # The default implementation of this method is empty.
-    def post_load
+    def post_load(options={:mapping=>:_default})
     end
 
 
@@ -152,8 +213,8 @@ module XML
     # (i.e. have their
     # #obj_to_xml method called) in the order of their definition
     # inside the class.
-    def fill_into_xml(xml)
-      self.class.all_xml_mapping_nodes.each do |node|
+    def fill_into_xml(xml, options={:mapping=>:_default})
+      self.class.all_xml_mapping_nodes(:mapping=>options[:mapping]).each do |node|
         node.obj_to_xml self,xml
       end
     end
@@ -163,10 +224,10 @@ module XML
     #
     # This method calls #pre_save, then #fill_into_xml, then
     # #post_save.
-    def save_to_xml
-      xml = pre_save
-      fill_into_xml(xml)
-      post_save(xml)
+    def save_to_xml(options={:mapping=>:_default})
+      xml = pre_save :mapping=>options[:mapping]
+      fill_into_xml xml, :mapping=>options[:mapping]
+      post_save xml, :mapping=>options[:mapping]
       xml
     end
 
@@ -181,47 +242,271 @@ module XML
     # class name, with capital letters converted to lowercase and
     # preceded by a dash, e.g. "MySampleClass" becomes
     # "my-sample-class".
-    def pre_save
-      REXML::Element.new(self.class.root_element_name)
+    def pre_save(options={:mapping=>:_default})
+      REXML::Element.new(self.class.root_element_name(:mapping=>options[:mapping]))
     end
 
     # This method is called immediately after _self_'s state has been
     # filled into an XML element.
     #
     # The default implementation does nothing.
-    def post_save(xml)
+    def post_save(xml, options={:mapping=>:_default})
     end
 
 
     # Save _self_'s state as XML into the file named _filename_.
     # The XML is obtained by calling #save_to_xml.
-    def save_to_file(filename)
-      xml = save_to_xml
+    def save_to_file(filename, options={:mapping=>:_default})
+      xml = save_to_xml :mapping=>options[:mapping]
       File.open(filename,"w") do |f|
-        xml.write(f,2)
+        REXML::Formatters::Transitive.new(2,false).write(xml,f)
+      end
+    end
+
+
+    # The instance methods of this module are automatically added as
+    # class methods to a class that includes XML::Mapping.
+    module ClassMethods
+    #ClassMethods = Module.new do  # this is the alternative -- but see above for peculiarities
+
+      # all nodes of this class, in the order of their definition,
+      # hashed by mapping (hash mapping => array of nodes)
+      def xml_mapping_nodes_hash    #:nodoc:
+        @xml_mapping_nodes ||= {}
+      end
+
+      # called on a class when it is being made a mapping class
+      # (i.e. immediately after XML::Mapping was included in it)
+      def initializing_xml_mapping  #:nodoc:
+        @default_mapping = :_default
+      end
+
+      # Make _mapping_ the mapping to be used by default in future
+      # node declarations in this class. The default can be
+      # overwritten on a per-node basis by passing a :mapping option
+      # parameter to the node factory method
+      #
+      # The initial default mapping in a mapping class is :_default
+      def use_mapping mapping
+        @default_mapping = mapping
+        xml_mapping_nodes_hash[mapping] ||= []  # create empty mapping node list if
+                                                # there wasn't one before so future calls
+                                                # to load/save_xml etc. w/ this mapping don't raise
+      end
+
+      # return the current default mapping (:_default initially, or
+      # the value set with the latest call to use_mapping)
+      def default_mapping
+        @default_mapping
+      end
+
+      # Add getter and setter methods for a new attribute named _name_
+      # to this class. This is a convenience method intended to be
+      # called from Node class initializers.
+      def add_accessor(name)
+        name = name.id2name if name.kind_of? Symbol
+        unless self.instance_methods.include?(name)
+          self.module_eval <<-EOS
+            attr_reader :#{name}
+          EOS
+        end
+        unless self.instance_methods.include?("#{name}=")
+          self.module_eval <<-EOS
+            attr_writer :#{name}
+          EOS
+        end
+      end
+
+      # Create a new instance of this class from the XML contained in
+      # the file named _filename_. Calls load_from_xml internally.
+      def load_from_file(filename, options={:mapping=>:_default})
+        xml = REXML::Document.new(File.new(filename))
+        load_from_xml xml.root, :mapping=>options[:mapping]
+      end
+
+      # Create a new instance of this class from the XML contained in
+      # _xml_ (a REXML::Element).
+      #
+      # Allocates a new object, then calls fill_from_xml(_xml_) on
+      # it.
+      def load_from_xml(xml, options={:mapping=>:_default})
+        raise(MappingError, "undefined mapping: #{options[:mapping].inspect}") \
+          unless xml_mapping_nodes_hash.has_key?(options[:mapping])
+        # create the new object. It is recommended that the class
+        # have a no-argument initializer, so try new first. If that
+        # doesn't work, try allocate, which bypasses the initializer.
+        begin
+          obj = self.new
+        rescue ArgumentError # TODO: this may hide real errors.
+                             #   how to statically check whether
+                             #   self self.new accepts an empty
+                             #   argument list?
+          obj = self.allocate
+        end
+        obj.initialize_xml_mapping :mapping=>options[:mapping]
+        obj.fill_from_xml xml, :mapping=>options[:mapping]
+        obj
+      end
+
+
+      # array of all nodes defined in this class, in the order of
+      # their definition. Option :create specifies whether or not an
+      # empty array should be created and returned if there was none
+      # before (if not, an exception is raised). :mapping specifies
+      # the mapping the returned nodes must have been defined in; nil
+      # means return all nodes regardless of their mapping
+      def xml_mapping_nodes(options={:mapping=>nil,:create=>true})
+        unless options[:mapping]
+          return xml_mapping_nodes_hash.values.inject([]){|a1,a2|a1+a2}
+        end
+        options[:create] = true if options[:create].nil?
+        if options[:create]
+          xml_mapping_nodes_hash[options[:mapping]] ||= []
+        else
+          xml_mapping_nodes_hash[options[:mapping]] ||
+            raise(MappingError, "undefined mapping: #{options[:mapping].inspect}")
+        end
+      end
+
+
+      # enumeration of all nodes in effect when
+      # marshalling/unmarshalling this class, that is, nodes defined
+      # for this class as well as for its superclasses.  The nodes are
+      # returned in the order of their definition, starting with the
+      # topmost superclass that has nodes defined. keyword arguments
+      # are the same as for #xml_mapping_nodes.
+      def all_xml_mapping_nodes(options={:mapping=>nil,:create=>true})
+        # TODO: we could return a dynamic Enumerable here, or cache
+        # the array...
+        result = []
+        if superclass and superclass.respond_to?(:all_xml_mapping_nodes)
+          result += superclass.all_xml_mapping_nodes options
+        end
+        result += xml_mapping_nodes options
       end
+
+
+      # The "root element name" of this class (combined getter/setter
+      # method).
+      #
+      # The root element name is the name of the root element of the
+      # XML tree returned by <this class>.#save_to_xml (or, more
+      # specifically, <this class>.#pre_save). By default, this method
+      # returns the #default_root_element_name; you may call this
+      # method with an argument to set the root element name to
+      # something other than the default. The option argument :mapping
+      # specifies the mapping the root element is/will be defined in,
+      # it defaults to the current default mapping (:_default
+      # initially, or the value set with the latest call to
+      # use_mapping)
+      def root_element_name(name=nil, options={:mapping=>@default_mapping})
+        if Hash===name    # ugly...
+          options=name; name=nil
+        end
+        @root_element_names ||= {}
+        if name
+          Classes_by_rootelt_names.remove_class root_element_name, options[:mapping], self
+          @root_element_names[options[:mapping]] = name
+          Classes_by_rootelt_names.create_classes_for(name, options[:mapping]) << self
+        end
+        @root_element_names[options[:mapping]] || default_root_element_name
+      end
+
+      # The default root element name for this class. Equals the class
+      # name, with all parent module names stripped, and with capital
+      # letters converted to lowercase and preceded by a dash;
+      # e.g. "Foo::Bar::MySampleClass" becomes "my-sample-class".
+      def default_root_element_name
+        self.name.split('::')[-1].gsub(/^(.)/){$1.downcase}.gsub(/(.)([A-Z])/){$1+"-"+$2.downcase}
+      end
+
     end
 
 
+
+    # "polymorphic" load function. Turns the XML tree _xml_ into an
+    # object, which is returned. The class of the object and the
+    # mapping to be used for unmarshalling are automatically
+    # determined from the root element name of _xml_ using
+    # XML::Mapping.class_for_root_elt_name. If :mapping is non-nil,
+    # only root element names defined in that mapping will be
+    # considered (default is to consider all classes)
+    def self.load_object_from_xml(xml,options={:mapping=>nil})
+      if mapping = options[:mapping]
+        c = class_for_root_elt_name xml.name, :mapping=>mapping
+      else
+        c,mapping = class_and_mapping_for_root_elt_name(xml.name)
+      end
+      unless c
+        raise MappingError, "no mapping class for root element name #{xml.name}, mapping #{mapping.inspect}"
+      end
+      c.load_from_xml xml, :mapping=>mapping
+    end
+
+    # Like load_object_from_xml, but loads from the XML file named by
+    # _filename_.
+    def self.load_object_from_file(filename,options={:mapping=>nil})
+      xml = REXML::Document.new(File.new(filename))
+      load_object_from_xml xml.root, options
+    end
+
+
+    # Registers the new node class _c_ (must be a descendant of Node)
+    # with the xml-mapping framework.
+    #
+    # A new "factory method" will automatically be added to
+    # ClassMethods (and therefore to all classes that include
+    # XML::Mapping from now on); so you can call it from the body of
+    # your mapping class definition in order to create nodes of type
+    # _c_. The name of the factory method is derived by "underscoring"
+    # the (unqualified) name of _c_;
+    # e.g. _c_==<tt>Foo::Bar::MyNiftyNode</tt> will result in the
+    # creation of a factory method named +my_nifty_node+. The
+    # generated factory method creates and returns a new instance of
+    # _c_. The list of argument to _c_.new consists of _self_
+    # (i.e. the mapping class the factory method was called from)
+    # followed by the arguments passed to the factory method. You
+    # should always use the factory methods to create instances of
+    # node classes; you should never need to call a node class's
+    # constructor directly.
+    #
+    # For a demonstration, see the calls to +text_node+, +array_node+
+    # etc. in the examples along with the corresponding node classes
+    # TextNode, ArrayNode etc. (these predefined node classes are in
+    # no way "special"; they're added using add_node_class in
+    # mapping.rb just like any custom node classes would be).
+    def self.add_node_class(c)
+      meth_name = c.name.split('::')[-1].gsub(/^(.)/){$1.downcase}.gsub(/(.)([A-Z])/){$1+"_"+$2.downcase}
+      ClassMethods.module_eval <<-EOS
+        def #{meth_name}(*args)
+          #{c.name}.new(self,*args)
+        end
+      EOS
+    end
+
+
+    ###### core node classes
+
     # Abstract base class for all node types. As mentioned in the
     # documentation for XML::Mapping, node types must be registered
-    # using add_node_class, and a corresponding "node factory method"
-    # (e.g. "text_node") will then be added as a class method to your
-    # mapping classes. The node factory method is called from the body
-    # of the mapping classes as demonstrated in the examples. It
-    # creates an instance of its corresponding node type (the list of
-    # parameters to the node factory method, preceded by the owning
-    # mapping class, will be passed to the constructor of the node
-    # type) and adds it to its owning mapping class, so there is one
-    # node object per node definition per mapping class. That node
-    # object will handle all XML marshalling/unmarshalling for this
-    # node, for all instances of the mapping class. For this purpose,
-    # the marshalling and unmarshalling methods of a mapping class
-    # instance (fill_into_xml and fill_from_xml, respectively)
-    # will call obj_to_xml resp. xml_to_obj on all nodes of the
-    # mapping class, in the order of their definition, passing the
-    # REXML element the data is to be marshalled to/unmarshalled from
-    # as well as the object the data is to be read from/filled into.
+    # using XML::Mapping.add_node_class, and a corresponding "node
+    # factory method" (e.g. "text_node") will then be added as a class
+    # method to your mapping classes. The node factory method is
+    # called from the body of the mapping classes as demonstrated in
+    # the examples. It creates an instance of its corresponding node
+    # type (the list of parameters to the node factory method,
+    # preceded by the owning mapping class, will be passed to the
+    # constructor of the node type) and adds it to its owning mapping
+    # class, so there is one node object per node definition per
+    # mapping class. That node object will handle all XML
+    # marshalling/unmarshalling for this node, for all instances of
+    # the mapping class. For this purpose, the marshalling and
+    # unmarshalling methods of a mapping class instance (fill_into_xml
+    # and fill_from_xml, respectively) will call obj_to_xml
+    # resp. xml_to_obj on all nodes of the mapping class, in the order
+    # of their definition, passing the REXML element the data is to be
+    # marshalled to/unmarshalled from as well as the object the data
+    # is to be read from/filled into.
     #
     # Node types that map some XML data to a single attribute of their
     # mapping class (that should be most of them) shouldn't be
@@ -230,14 +515,55 @@ module XML
     class Node
       # Intializer, to be called from descendant classes. _owner_ is
       # the mapping class this node is being defined in. It'll be
-      # stored in _@owner_.
-      def initialize(owner)
+      # stored in _@owner_. @options will be set to a (possibly empty)
+      # hash containing the option arguments passed to
+      # _initialize_. Options :mapping, :reader and :writer will be
+      # handled, subclasses may handle additional options. See the
+      # section on defining nodes in the README for details.
+      def initialize(owner,*args)
         @owner = owner
-        owner.xml_mapping_nodes << self
+        if Hash===args[-1]
+          @options = args[-1]
+          args = args[0..-2]
+        else
+          @options={}
+        end
+        @mapping = @options[:mapping] || owner.default_mapping
+        owner.xml_mapping_nodes(:mapping=>@mapping) << self
+        XML::Mapping::Classes_by_rootelt_names.ensure_exists owner.root_element_name, @mapping, owner
+        if @options[:reader]
+          # override xml_to_obj in this instance with invocation of
+          # @options[:reader]
+          class << self
+            alias_method :default_xml_to_obj, :xml_to_obj
+            def xml_to_obj(obj,xml)
+              begin
+                @options[:reader].call(obj,xml)
+              rescue ArgumentError
+                @options[:reader].call(obj,xml,self.method(:default_xml_to_obj))
+              end
+            end
+          end
+        end
+        if @options[:writer]
+          # override obj_to_xml in this instance with invocation of
+          # @options[:writer]
+          class << self
+            alias_method :default_obj_to_xml, :obj_to_xml
+            def obj_to_xml(obj,xml)
+              begin
+                @options[:writer].call(obj,xml)
+              rescue ArgumentError
+                @options[:writer].call(obj,xml,self.method(:default_obj_to_xml))
+              end
+            end
+          end
+        end
+        args
       end
       # This is called by the XML unmarshalling machinery when the
       # state of an instance of this node's @owner is to be read from
-      # an XML node. _obj_ is the instance, _xml_ is the element (a
+      # an XML tree. _obj_ is the instance, _xml_ is the tree (a
       # REXML::Element). The node must read "its" data from _xml_
       # (using XML::XXPath or any other means) and store it to the
       # corresponding parts (attributes etc.) of _obj_'s state.
@@ -246,32 +572,44 @@ module XML
       end
       # This is called by the XML unmarshalling machinery when the
       # state of an instance of this node's @owner is to be stored
-      # into an XML node. _obj_ is the instance, _xml_ is the element
-      # (a REXML::Element). The node must extract "its" data from
-      # _obj_ and store it to the corresponding parts (sub-elements,
+      # into an XML tree. _obj_ is the instance, _xml_ is the tree (a
+      # REXML::Element). The node must extract "its" data from _obj_
+      # and store it to the corresponding parts (sub-elements,
       # attributes etc.) of _xml_ (using XML::XXPath or any other
       # means).
       def obj_to_xml(obj,xml)
         raise "abstract method called"
       end
-      # Called when a new instance is being initialized. _obj_ is the
-      # instance. You may set up initial values for the attributes
-      # this node is responsible for here. Default implementation is
-      # empty.
-      def obj_initializing(obj)
+      # Called when a new instance of the mapping class this node
+      # belongs to is being initialized. _obj_ is the
+      # instance. _mapping_ is the mapping the initialization is
+      # happening with, if any: If the instance is being initialized
+      # as part of e.g. <tt>Class.load_from_file(name,
+      # :mapping=>:some_mapping</tt> or any other call that specifies
+      # a mapping, that mapping will be passed to this method. If the
+      # instance is being initialized normally with
+      # <tt>Class.new</tt>, _mapping_ is nil here.
+      #
+      # You may set up initial values for the attributes this node is
+      # responsible for here. Default implementation is empty.
+      def obj_initializing(obj,mapping)
+      end
+      # tell whether this node's data is present in _obj_ (when this
+      # method is called, _obj_ will be an instance of the mapping
+      # class this node was defined in). This method is currently used
+      # only by ChoiceNode when writing data back to XML. See
+      # ChoiceNode#obj_to_xml.
+      def is_present_in? obj
+        true
       end
     end
 
 
     # Base class for node types that map some XML data to a single
-    # attribute of their mapping class. This class also introduces a
-    # general "options" hash parameter which may be used to influence
-    # the creation of nodes in numerous ways, e.g. by providing
-    # default attribute values when there is no source data in the
-    # mapped XML.
+    # attribute of their mapping class.
     #
-    # All node types that come with xml-mapping inherit from
-    # SingleAttributeNode.
+    # All node types that come with xml-mapping except one
+    # (ChoiceNode) inherit from SingleAttributeNode.
     class SingleAttributeNode < Node
       # Initializer. _owner_ is the owning mapping class (gets passed
       # to the superclass initializer and therefore put into
@@ -282,10 +620,8 @@ module XML
       # attribute of name attrname) is added to the mapping class
       # (using attr_accessor).
       #
-      # If the last argument is a hash, it is assumed to be the
-      # abovementioned "options hash", and is stored into
-      # @options. Two entries -- :optional and :default_value -- in
-      # the options hash are already processed in SingleAttributeNode:
+      # In the initializer, two option arguments -- :optional and
+      # :default_value -- are processed in SingleAttributeNode:
       #
       # Supplying :default_value=>_obj_ makes _obj_ the _default
       # value_ for this attribute. When unmarshalling (loading) an
@@ -296,43 +632,24 @@ module XML
       #
       # Providing just :optional=>true is equivalent to providing
       # :default_value=>nil.
-      #
-      # The remaining arguments are passed to initialize_impl, which
-      # is the initializer subclasses should overwrite instead of
-      # initialize.
-      #
-      # For example (TextNode is a subclass of SingleAttributeNote):
-      #
-      #   class Address
-      #     include XML::Mapping
-      #     text_node :city, "city", :optional=>true, :default_value=>"Berlin"
-      #   end
-      #
-      # Here +Address+ is the _owner_, <tt>:city</tt> is the
-      # _attrname_,
-      # <tt>{:optional=>true,:default_value=>"Berlin"}</tt> is the
-      # @options, and ["city"] is the argument list that'll be passed
-      # to TextNode.initialize_impl. "city" is of course the XPath
-      # expression locating the XML sub-element this text node refers
-      # to; TextNode.initialize_impl stores it into @path.
-      def initialize(owner,attrname,*args)
-        super(owner)
-        @attrname = attrname
-        owner.add_accessor attrname
-        if Hash===args[-1]
-          @options = args[-1]
-          args = args[0..-2]
-        else
-          @options={}
-        end
+      def initialize(*args)
+        @attrname,*args = super(*args)
+        @owner.add_accessor @attrname
         if @options[:optional] and not(@options.has_key?(:default_value))
           @options[:default_value] = nil
         end
         initialize_impl(*args)
+        args
       end
-      # Initializer to be implemented by subclasses.
+      # this method was retained for compatibility with xml-mapping 0.8.
+      #
+      # It used to be the initializer to be implemented by subclasses. The
+      # arguments (args) are those still unprocessed by
+      # SingleAttributeNode's initializer.
+      #
+      # In xml-mapping 0.9 and up, you should just override initialize() and
+      # call super.initialize. The returned array is the same args array.
       def initialize_impl(*args)
-        raise "abstract method called"
       end
 
       # Exception that may be used by implementations of
@@ -356,15 +673,14 @@ module XML
             obj.send :"#{@attrname}=", @options[:default_value]
           end
         end
+        true
       end
 
-      # (to be overridden by subclasses) Extract and return the
-      # attribute's value from _xml_. In the example above, TextNode's
-      # implementation would return the current value of the
-      # sub-element named by @path (i.e., "city"). If the
-      # implementation decides that the attribute value is "unset" in
-      # _xml_, it should raise NoAttrValueSet in order to initiate
-      # proper handling of possibly supplied :optional and
+      # (to be overridden by subclasses) Extract and return the value
+      # of the attribute this node is responsible for (@attrname) from
+      # _xml_. If the implementation decides that the attribute value
+      # is "unset" in _xml_, it should raise NoAttrValueSet in order
+      # to initiate proper handling of possibly supplied :optional and
       # :default_value options (you may use #default_when_xpath_err
       # for this purpose).
       def extract_attr_value(xml)
@@ -382,14 +698,17 @@ module XML
           end
           set_attr_value(xml, value)
         end
+        true
       end
-      # (to be overridden by subclasses) Write _value_ into the
-      # correct sub-nodes of _xml_.
+      # (to be overridden by subclasses) Write _value_, which is the
+      # current value of the attribute this node is responsible for
+      # (@attrname), into (the correct sub-nodes, attributes,
+      # whatever) of _xml_.
       def set_attr_value(xml, value)
         raise "abstract method called"
       end
-      def obj_initializing(obj)  # :nodoc:
-        if @options.has_key? :default_value
+      def obj_initializing(obj,mapping)  # :nodoc:
+        if @options.has_key?(:default_value) and (mapping==nil || mapping==@mapping)
           begin
             obj.send :"#{@attrname}=", @options[:default_value].clone
           rescue
@@ -410,160 +729,11 @@ module XML
           raise NoAttrValueSet, "Attribute #{@attrname} not set (XXPathError: #{err})"
         end
       end
-    end
-
-
-    # Registers the new node class _c_ (must be a descendant of Node)
-    # with the xml-mapping framework.
-    #
-    # A new "factory method" will automatically be added to
-    # ClassMethods (and therefore to all classes that include
-    # XML::Mapping from now on); so you can call it from the body of
-    # your mapping class definition in order to create nodes of type
-    # _c_. The name of the factory method is derived by "underscoring"
-    # the (unqualified) name of _c_;
-    # e.g. _c_==<tt>Foo::Bar::MyNiftyNode</tt> will result in the
-    # creation of a factory method named +my_nifty_node+. The
-    # generated factory method creates and returns a new instance of
-    # _c_. The list of argument to _c_.new consists of _self_
-    # (i.e. the mapping class the factory method was called from)
-    # followed by the arguments passed to the factory method. You
-    # should always use the factory methods to create instances of
-    # node classes; you should never need to call a node class's
-    # constructor directly.
-    #
-    # For a demonstration, see the calls to +text_node+, +array_node+
-    # etc. in the examples along with the corresponding node classes
-    # TextNode, ArrayNode etc. (these predefined node classes are in
-    # no way "special"; they're added using add_node_class in
-    # mapping.rb just like any custom node classes would be).
-    def self.add_node_class(c)
-      meth_name = c.name.split('::')[-1].gsub(/^(.)/){$1.downcase}.gsub(/(.)([A-Z])/){$1+"_"+$2.downcase}
-      ClassMethods.module_eval <<-EOS
-        def #{meth_name}(*args)
-          #{c.name}.new(self,*args)
-        end
-      EOS
-    end
-
-
-    # The instance methods of this module are automatically added as
-    # class methods to a class that includes XML::Mapping.
-    module ClassMethods
-    #ClassMethods = Module.new do  # this is the alterbative -- but see above for peculiarities
-
-      # Add getter and setter methods for a new attribute named _name_
-      # to this class. This is a convenience method intended to be
-      # called from Node class initializers.
-      def add_accessor(name)
-        name = name.id2name if name.kind_of? Symbol
-        unless self.instance_methods.include?(name)
-          self.module_eval <<-EOS
-            attr_reader :#{name}
-          EOS
-        end
-        unless self.instance_methods.include?("#{name}=")
-          self.module_eval <<-EOS
-            attr_writer :#{name}
-          EOS
-        end
-      end
-
-      # Create a new instance of this class from the XML contained in
-      # the file named _filename_. Calls load_from_xml internally.
-      def load_from_file(filename)
-        xml = REXML::Document.new(File.new(filename))
-        load_from_xml(xml.root)
-      end
-
-      # Create a new instance of this class from the XML contained in
-      # _xml_ (a REXML::Element).
-      #
-      # Allocates a new object, then calls fill_from_xml(_xml_) on
-      # it.
-      def load_from_xml(xml)
-        obj = self.allocate
-        obj.initialize_xml_mapping
-        obj.fill_from_xml(xml)
-        obj
-      end
-
-
-      # array of all nodes types defined in this class, in the order
-      # of their definition
-      def xml_mapping_nodes
-        @xml_mapping_nodes ||= []
-      end
-
-
-      # enumeration of all nodes types in effect when
-      # marshalling/unmarshalling this class, that is, node types
-      # defined for this class as well as for its superclasses.  The
-      # node types are returned in the order of their definition,
-      # starting with the topmost superclass that has node types
-      # defined.
-      def all_xml_mapping_nodes
-        # TODO: we could return a dynamic Enumerable here, or cache
-        # the array...
-        result = []
-        if superclass and superclass.respond_to?(:all_xml_mapping_nodes)
-          result += superclass.all_xml_mapping_nodes
-        end
-        result += xml_mapping_nodes
-      end
-
-
-      # The "root element name" of this class (combined getter/setter
-      # method).
-      #
-      # The root element name is the name of the root element of the
-      # XML tree returned by <this class>.#save_to_xml (or, more
-      # specifically, <this class>.#pre_save). By default, this method
-      # returns the #default_root_element_name; you may call this
-      # method with an argument to set the root element name to
-      # something other than the default.
-      def root_element_name(name=nil)
-        if name
-          Classes_w_nondefault_rootelt_names.delete(root_element_name)
-          Classes_w_default_rootelt_names.delete(root_element_name)
-          Classes_w_default_rootelt_names.delete(name)
-
-          @root_element_name = name
-
-          Classes_w_nondefault_rootelt_names[name]=self
-        end
-        @root_element_name || default_root_element_name
-      end
-
-
-      # The default root element name for this class. Equals the class
-      # name, with all parent module names stripped, and with capital
-      # letters converted to lowercase and preceded by a dash;
-      # e.g. "Foo::Bar::MySampleClass" becomes "my-sample-class".
-      def default_root_element_name
-        self.name.split('::')[-1].gsub(/^(.)/){$1.downcase}.gsub(/(.)([A-Z])/){$1+"-"+$2.downcase}
+      # (overridden) returns true if and only if the value of this
+      # node's attribute in _obj_ is non-nil.
+      def is_present_in? obj
+        nil != obj.send(:"#{@attrname}")
       end
-
-    end
-
-
-
-    # "polymorphic" load function. Turns the XML tree _xml_ into an
-    # object, which is returned. The class of the object is
-    # automatically determined from the root element name of _xml_
-    # using XML::Mapping::class_for_root_elt_name.
-    def self.load_object_from_xml(xml)
-      unless c = class_for_root_elt_name(xml.name)
-        raise MappingError, "no mapping class for root element name #{xml.name}"
-      end
-      c.load_from_xml(xml)
-    end
-
-    # Like load_object_from_xml, but loads from the XML file named by
-    # _filename_.
-    def self.load_object_from_file(filename)
-      xml = REXML::Document.new(File.new(filename))
-      load_object_from_xml(xml.root)
     end
 
   end