roxml 2.4.3 → 2.5.0

data/lib/roxml.rb

@@ -1,12 +1,14 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__)) unless
   $LOAD_PATH.include?(File.dirname(__FILE__)) || $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
 
+require 'uri'
+
 %w(extensions definition xml).each do |file|
   require File.join('roxml', file)
 end
 
 module ROXML # :nodoc:
-  VERSION = '2.4.3'
+  VERSION = '2.5.0'
 
   def self.included(base) # :nodoc:
     base.extend ClassMethods::Accessors,
@@ -46,8 +48,8 @@ module ROXML # :nodoc:
       #  class Measurement
       #    include ROXML
       #
-      #    xml_reader :units, :attr
-      #    xml_reader :value, :content
+      #    xml_reader :units, :from => :attr
+      #    xml_reader :value, :from => :content
       #
       #    def xml_initialize
       #      # the object is instantiated, and all xml attributes are imported
@@ -69,14 +71,15 @@ module ROXML # :nodoc:
       # #xml_initialize may be written to take arguments, in which case extra arguments
       # from from_xml will be passed into the function.
       #
-      def xml_initialize
+      def xml_initialize # :nodoc:
       end
+      deprecate :xml_initialize => :after_parse
     end
 
     module Conversions
       # Returns a LibXML::XML::Node or a REXML::Element representing this object
       def to_xml(name = nil)
-        returning XML::Node.new_element(name || self.class.tag_name) do |root|
+        returning XML::Node.new(name || self.class.tag_name) do |root|
           self.class.roxml_attrs.each do |attr|
             ref = attr.to_ref(self)
             v = ref.to_xml
@@ -175,9 +178,9 @@ module ROXML # :nodoc:
         (@roxml_naming_convention || superclass.try(:roxml_naming_convention)).freeze
       end
 
-      # Declares an accesser to a certain xml element, whether an attribute, a node,
-      # or a typed collection of nodes.  Typically you should call xml_reader or xml_accessor
-      # rather than calling this method directly, but the instructions below apply to both.
+      # Declares a reference to a certain xml element, whether an attribute, a node,
+      # or a typed collection of nodes.  This method does not add a corresponding accessor
+      # to the object.  For that behavior see the similar methods: .xml_reader and .xml_accessor.
       #
       # == Sym Option
       # [sym]   Symbol representing the name of the accessor.
@@ -187,12 +190,12 @@ module ROXML # :nodoc:
       # if no other is declared.  For example,
       #
       #  xml_reader   :bob
-      #  xml_accessor :pony, :attr
+      #  xml_accessor :pony, :from => :attr
       #
       # are equivalent to:
       #
       #  xml_reader   :bob, :from => 'bob'
-      #  xml_accessor :pony, :attr => 'pony'
+      #  xml_accessor :pony, :from => '@pony'
       #
       # === Boolean attributes
       # If the name ends in a ?, ROXML will attempt to coerce the value to true or false,
@@ -200,7 +203,7 @@ module ROXML # :nodoc:
       # to false, as shown below:
       #
       #  xml_reader :desirable?
-      #  xml_reader :bizzare?, :attr => 'BIZZARE'
+      #  xml_reader :bizzare?, :from => '@BIZZARE'
       #
       #  x = #from_xml(%{
       #    <object BIZZARE="1">
@@ -234,94 +237,90 @@ module ROXML # :nodoc:
       #  }).strange?
       #  => DUNNO
       #
-      # == Type options
-      # All type arguments may be used as the type argument to indicate just type,
-      # or used as :from, pointing to a xml name to indicate both type and attribute name.
-      # Also, any type may be passed via an array to indicate that multiple instances
-      # of the object should be returned as an array.
+      # == Blocks
+      # You may also pass a block which manipulates the associated parsed value.
       #
-      # === :attr
-      # Declare an accessor that represents an XML attribute.
+      #  class Muffins
+      #    include ROXML
       #
-      # Example:
-      #  class Book
-      #   xml_reader :isbn, :attr => "ISBN" # 'ISBN' is used to specify :from
-      #   xml_accessor :title, :attr        # :from defaults to :title
+      #    xml_reader(:count, :from => 'bakers_dozens') {|val| val.to_i * 13 }
       #  end
       #
-      # To map:
-      #  <book ISBN="0974514055" title="Programming Ruby: the pragmatic programmers' guide" />
+      # For hash types, the block recieves the key and value as arguments, and they should
+      # be returned as an array of [key, value]
       #
-      # === :text
-      # The default type, if none is specified. Declares an accessor that
-      # represents a text node from XML.
+      # For array types, the entire array is passed in, and must be returned in the same fashion.
       #
-      # Example:
-      #  class Book
-      #    xml_reader :author, :text => 'Author'
-      #    xml_accessor :description, :text, :as => :cdata
-      #    xml_reader :title
-      #  end
+      # == Options
+      # === :as
+      # ==== Basic Types
+      # Allows you to specify one of several basic types to return the value as.  For example
       #
-      # To map:
+      #  xml_reader :count, :as => Integer
+      #
+      # is equivalent to:
+      #
+      #  xml_reader(:count) {|val| Integer(val) unless val.empty? }
+      #
+      # Such block shorthands for Integer, Float, Fixnum, BigDecimal, Date, Time, and DateTime
+      # are currently available, but only for non-Hash declarations.
+      #
+      # To reference many elements, put the desired type in a literal array. e.g.:
+      #
+      #   xml_reader :counts, :as => [Integer]
+      #
+      # Even an array of :text nodes can be specified with :as => []
+      #
+      #   xml_reader :quotes, :as => []
+      #
+      # === Other ROXML Class
+      # Declares an accessor that represents another ROXML class as child XML element
+      # (one-to-one or composition) or array of child elements (one-to-many or
+      # aggregation) of this type. Default is one-to-one. For one-to-many, simply pass the class
+      # as the only element in an array.
+      #
+      # Composition example:
       #  <book>
-      #   <title>Programming Ruby: the pragmatic programmers' guide</title>
-      #   <description><![CDATA[Probably the best Ruby book out there]]></description>
-      #   <Author>David Thomas</author>
+      #   <publisher>
+      #     <name>Pragmatic Bookshelf</name>
+      #   </publisher>
       #  </book>
       #
-      # Likewise, a number of :text node values can be collected in an array like so:
+      # Can be mapped using the following code:
+      #   class Book
+      #     xml_reader :publisher, :as => Publisher
+      #   end
       #
-      # Example:
+      # Aggregation example:
+      #  <library>
+      #   <books>
+      #    <book/>
+      #    <book/>
+      #   </books>
+      #  </library>
+      #
+      # Can be mapped using the following code:
       #  class Library
-      #    xml_reader :books, [:text], :in => 'books'
+      #    xml_reader :books, :as => [Book], :in => "books"
       #  end
       #
-      # To map:
+      # If you don't have the <books> tag to wrap around the list of <book> tags:
       #  <library>
-      #    <books>
-      #      <book>To kill a mockingbird</book>
-      #      <book>House of Leaves</book>
-      #      <book>Gödel, Escher, Bach</book>
-      #    </books>
+      #   <name>Ruby books</name>
+      #   <book/>
+      #   <book/>
       #  </library>
       #
-      # === :content
-      # A special case of :text, this refers to the content of the current node,
-      # rather than a sub-node
-      #
-      # Example:
-      #  class Contributor
-      #    xml_reader :name, :content
-      #    xml_reader :role, :attr
-      #  end
-      #
-      # To map:
-      #  <contributor role="editor">James Wick</contributor>
+      # You can skip the wrapper argument:
+      #    xml_reader :books, :as => [Book]
       #
-      # === Hash
+      # ==== Hash
       # Somewhere between the simplicity of a :text/:attr mapping, and the complexity of
       # a full Object/Type mapping, lies the Hash mapping.  It serves in the case where you have
       # a collection of key-value pairs represented in your xml.  You create a hash declaration by
       # passing a hash mapping as the type argument.  A few examples:
       #
-      # ==== Hash of :attrs
-      # For xml such as this:
-      #
-      #    <dictionary>
-      #      <definitions>
-      #        <definition dt="quaquaversally"
-      #                    dd="adjective: (of a geological formation) sloping downward from the center in all directions." />
-      #        <definition dt="tergiversate"
-      #                    dd="To use evasions or ambiguities; equivocate." />
-      #      </definitions>
-      #    </dictionary>
-      #
-      # You can use the :attrs key in you has with a [:key, :value] name array:
-      #
-      #    xml_reader :definitions, {:attrs => ['dt', 'dd']}, :in => :definitions
-      #
-      # ==== Hash of :texts
+      # ===== Hash of :texts
       # For xml such as this:
       #
       #    <dictionary>
@@ -336,10 +335,10 @@ module ROXML # :nodoc:
       #    </dictionary>
       #
       # You can individually declare your key and value names:
-      #    xml_reader :definitions, {:key => 'word',
-      #                              :value => 'meaning'}
+      #    xml_reader :definitions, :as => {:key => 'word',
+      #                                     :value => 'meaning'}
       #
-      # ==== Hash of :content &c.
+      # ===== Hash of :content &c.
       # For xml such as this:
       #
       #    <dictionary>
@@ -350,10 +349,10 @@ module ROXML # :nodoc:
       # You can individually declare the key and value, but with the attr, you need to provide both the type
       # and name of that type (i.e. {:attr => :word}), because omitting the type will result in ROXML
       # defaulting to :text
-      #    xml_reader :definitions, {:key => {:attr => 'word'},
-      #                              :value => :content}
+      #    xml_reader :definitions, :as => {:key => {:attr => 'word'},
+      #                                     :value => :content}
       #
-      # ==== Hash of :name &c.
+      # ===== Hash of :name &c.
       # For xml such as this:
       #
       #    <dictionary>
@@ -362,112 +361,119 @@ module ROXML # :nodoc:
       #    </dictionary>
       #
       # You can pick up the node names (e.g. quaquaversally) using the :name keyword:
-      #    xml_reader :definitions, {:key => :name,
-      #                              :value => :content}
-      #
-      # === Other ROXML Class
-      # Declares an accessor that represents another ROXML class as child XML element
-      # (one-to-one or composition) or array of child elements (one-to-many or
-      # aggregation) of this type. Default is one-to-one. Use :array option for one-to-many, or
-      # simply pass the class in an array.
+      #    xml_reader :definitions, :as => {:key => :name,
+      #                                     :value => :content}
       #
-      # Composition example:
-      #  <book>
-      #   <publisher>
-      #     <name>Pragmatic Bookshelf</name>
-      #   </publisher>
-      #  </book>
+      # === :from
+      # The name by which the xml value will be found, either an attribute or tag name in XML.
+      # Default is sym, or the singular form of sym, in the case of arrays and hashes.
       #
-      # Can be mapped using the following code:
-      #   class Book
-      #     xml_reader :publisher, Publisher
-      #   end
+      # This value may also include XPath notation.
       #
-      # Aggregation example:
-      #  <library>
-      #   <books>
-      #    <book/>
-      #    <book/>
-      #   </books>
-      #  </library>
+      # ==== :from => :content
+      # When :from is set to :content, this refers to the content of the current node,
+      # rather than a sub-node. It is equivalent to :from => '.'
       #
-      # Can be mapped using the following code:
-      #  class Library
-      #    xml_reader :books, [Book], :in => "books"
+      # Example:
+      #  class Contributor
+      #    xml_reader :name, :from => :content
+      #    xml_reader :role, :from => :attr
       #  end
       #
-      # If you don't have the <books> tag to wrap around the list of <book> tags:
-      #  <library>
-      #   <name>Ruby books</name>
-      #   <book/>
-      #   <book/>
-      #  </library>
-      #
-      # You can skip the wrapper argument:
-      #    xml_reader :books, [Book]
-      #
-      # == Blocks
-      # You may also pass a block which manipulates the associated parsed value.
+      # To map:
+      #  <contributor role="editor">James Wick</contributor>
       #
-      #  class Muffins
-      #    include ROXML
+      # ==== :from => :attr
+      # When :from is set to :attr, this refers to the content of an attribute,
+      # rather than a sub-node. It is equivalent to :from => '@attribute_name'
       #
-      #    xml_reader(:count, :from => 'bakers_dozens') {|val| val.to_i * 13 }
+      # Example:
+      #  class Book
+      #    xml_reader :isbn, :from => "@ISBN"
+      #    xml_accessor :title, :from => :attr # :from defaults to '@title'
       #  end
       #
-      # For hash types, the block recieves the key and value as arguments, and they should
-      # be returned as an array of [key, value]
+      # To map:
+      #  <book ISBN="0974514055" title="Programming Ruby: the pragmatic programmers' guide" />
       #
-      # For array types, the entire array is passed in, and must be returned in the same fashion.
+      # ==== :from => :text
+      # The default source, if none is specified, this means the accessor
+      # represents a text node from XML.  This is documented for completeness
+      # only.  You should just leave this option off when you want the default behavior,
+      # as in the examples below.
       #
-      # === Block Shorthands
+      # :text is equivalent to :from => accessor_name, and you should specify the
+      # actual node name if it differs, as in the case of :author below.
       #
-      # Alternatively, you may use block shorthands to specify common coercions, such that:
+      # Example:
+      #  class Book
+      #    xml_reader :author, :from => 'Author
+      #    xml_accessor :description, :cdata => true
+      #    xml_reader :title
+      #  end
       #
-      #  xml_reader :count, :as => Integer
+      # To map:
+      #  <book>
+      #   <title>Programming Ruby: the pragmatic programmers' guide</title>
+      #   <description><![CDATA[Probably the best Ruby book out there]]></description>
+      #   <Author>David Thomas</Author>
+      #  </book>
       #
-      # is equivalent to:
+      # Likewise, a number of :text node values can be collected in an array like so:
       #
-      #  xml_reader(:count) {|val| Integer(val) }
+      # Example:
+      #  class Library
+      #    xml_reader :books, :as => []
+      #  end
       #
-      # Block shorthands :float, Float, :integer and Integer are currently available,
-      # but only for non-Hash declarations.
+      # To map:
+      #  <library>
+      #      <book>To kill a mockingbird</book>
+      #      <book>House of Leaves</book>
+      #    <book>Gödel, Escher, Bach</book>
+      #  </library>
       #
-      # == Other options
-      # [:from] The name by which the xml value will be found, either an attribute or tag name in XML.  Default is sym, or the singular form of sym, in the case of arrays and hashes.
-      # [:as] one or more of the following: :cdata for character data; Integer, Float, Date, Time or DateTime to coerce to the respective type
-      # [:in] An optional name of a wrapping tag for this XML accessor
-      # [:else] Default value for attribute, if missing
+      # === Other Options
+      # [:in] An optional name of a wrapping tag for this XML accessor.
+      #       This can include other xpath values, which will be joined with :from with a '/'
+      # [:else] Default value for attribute, if missing from the xml on .from_xml
       # [:required] If true, throws RequiredElementMissing when the element isn't present
       # [:frozen] If true, all results are frozen (using #freeze) at parse-time.
+      # [:cdata] True for values which should be input from or output as cdata elements
       #
-      def xml_reference(writable, sym, type_and_or_opts = :text, opts = nil, &block)
-        opts = Definition.new(sym, *[type_and_or_opts, opts].compact, &block)
-
-        add_accessor(opts, writable)
+      def xml_attr(sym, type_and_or_opts = nil, opts = nil, &block)
+        returning Definition.new(sym, *[type_and_or_opts, opts].compact, &block) do |attr|
+          if roxml_attrs.map(&:accessor).include? attr.accessor
+            raise "Accessor #{attr.accessor} is already defined as XML accessor in class #{self.name}"
+          end
+          @roxml_attrs << attr
+        end
       end
 
-      def xml(sym, writable = false, type_and_or_opts = :text, opts = nil, &block) #:nodoc:
-        xml_reference(writable, sym, type_and_or_opts, opts, &block)
+      def xml(sym, writable = false, type_and_or_opts = nil, opts = nil, &block) #:nodoc:
+        send(writable ? :xml_accessor : :xml_reader, sym, type_and_or_opts, opts, &block)
       end
-      deprecate :xml => :xml_reference
+      deprecate :xml => "use xml_attr, xml_reader, or xml_accessor instead"
 
-      # Declares a read-only xml reference. See xml for details.
+      # Declares a read-only xml reference. See xml_attr for details.
       #
       # Note that while xml_reader does not create a setter for this attribute,
       # its value can be modified indirectly via methods.  For more complete
       # protection, consider the :frozen option.
-      def xml_reader(sym, type_and_or_opts = :text, opts = nil, &block)
-        xml_reference false, sym, type_and_or_opts, opts, &block
+      def xml_reader(sym, type_and_or_opts = nil, opts = nil, &block)
+        attr = xml_attr sym, type_and_or_opts, opts, &block
+        add_reader(attr)
       end
 
-      # Declares a writable xml reference. See xml for details.
+      # Declares a writable xml reference. See xml_attr for details.
       #
       # Note that while xml_accessor does create a setter for this attribute,
       # you can use the :frozen option to prevent its value from being
       # modified indirectly via methods.
-      def xml_accessor(sym, type_and_or_opts = :text, opts = nil, &block)
-        xml_reference true, sym, type_and_or_opts, opts, &block
+      def xml_accessor(sym, type_and_or_opts = nil, opts = nil, &block)
+        attr = xml_attr sym, type_and_or_opts, opts, &block
+        add_reader(attr)
+        attr_writer(attr.variable_name)
       end
 
       # This method is deprecated, please use xml_initialize instead
@@ -484,23 +490,9 @@ module ROXML # :nodoc:
       deprecate :xml_construct => :xml_initialize
 
     private
-      def add_accessor(attr, writable)
-        if roxml_attrs.map(&:accessor).include? attr.accessor
-          raise "Accessor #{attr.accessor} is already defined as XML accessor in class #{self.name}"
-        end
-        @roxml_attrs << attr
-
+      def add_reader(attr)
         define_method(attr.accessor) do
-          result = instance_variable_get("@#{attr.variable_name}")
-          if result.nil?
-            result = attr.default
-            instance_variable_set("@#{attr.variable_name}", result)
-          end
-          result
-        end
-
-        if writable && !instance_methods.include?("#{attr.accessor}=")
-          attr_writer(attr.accessor)
+          instance_variable_get("@#{attr.variable_name}")
         end
       end
     end
@@ -559,7 +551,7 @@ module ROXML # :nodoc:
       # Creates a new Ruby object from XML using mapping information
       # annotated in the class.
       #
-      # The input data is either an XML::Node or a String representing
+      # The input data is either an XML::Node, String, Pathname, or File representing
       # the XML document.
       #
       # Example
@@ -568,7 +560,9 @@ module ROXML # :nodoc:
       #  book = Book.from_xml("<book><name>Beyond Java</name></book>")
       #
       # _initialization_args_ passed into from_xml will be passed into
-      # the object #xml_initialize method.
+      # the object's .new, prior to populating the xml_attrs.
+      #
+      # After the instatiation and xml population
       #
       # See also: xml_initialize
       #
@@ -581,13 +575,19 @@ module ROXML # :nodoc:
           end.map {|attr| attr.to_ref(self).value_in(xml) }
           new(*args)
         else
-          returning allocate do |inst|
+          returning new(*initialization_args) do |inst|
             roxml_attrs.each do |attr|
-              inst.instance_variable_set("@#{attr.variable_name}", attr.to_ref(inst).value_in(xml))
+              value = attr.to_ref(inst).value_in(xml)
+              setter = :"#{attr.variable_name}="
+              inst.respond_to?(setter) \
+                ? inst.send(setter, value) \
+                : inst.instance_variable_set("@#{attr.variable_name}", value)
             end
-            inst.send(:xml_initialize, *initialization_args)
+            inst.try(:after_parse)
           end
         end
+      rescue ArgumentError => e
+        raise e, e.message + " for class #{self}"
       end
 
       # Deprecated in favor of #from_xml