xml-fu 0.1.9 → 0.2.0

data/README.md

@@ -25,6 +25,23 @@ Or install it yourself as:
 
     $ gem install xml-fu
 
+## BREAKING CHANGES in 0.2.0
+
+Configuration was reworked to be more flexible and provide a centralized object for configuration. As such,
+the configuration options have been moved off of the XmlFu module into the XmlFu.config object. The XmlFu.configure
+method still works the same for setting configurations, but for reading configuration variables, you need to go
+through the XmlFu.config object.
+
+* ADDED
+  * support for OpenStruct conversion
+* REMOVED
+  * infer_simple_value_nodes configuration option
+  * XmlFu::Array.infer_node
+  * XmlFu.parse()
+    * XmlFu is for generation of XML, not parsing.
+* MOVED
+  * configuration options moved to XmlFu.config
+
 
 ## Hash Keys
 
@@ -34,15 +51,16 @@ Hash keys are translated into XML nodes (whether it be a document node or attrib
 ### Key Translation
 
 With Ruby, a hash key may be a string or a symbol.  **Strings will be preserved** as they may
-contain node namespacing ("foo:Bar" would need preserved rather than converted).  Symbols will
-be converted into an XML safe name by lower camel-casing them. So :foo\_bar will become "fooBar".
-You may change the conversion algorithm to your liking by setting the
-XmlFu.symbol\_conversion\_algorithm to a lambda or proc of your liking.
+contain node namespacing ("foo:Bar" would need preserved rather than converted).  There are some
+exceptions to this rule (especially with special key syntax discussed in *Types of Nodes* and the
+like).  Symbols will be converted into an XML safe name by lower camel-casing them. So :foo\_bar
+will become "fooBar".  You may change the conversion algorithm to your liking by setting the
+XmlFu.config.symbol_conversion_algorithm to a lambda or proc of your liking.
 
 
 #### Built-In Algorithms
 
-For a complete list, reference XmlFu::Node::ALGORITHMS
+For a complete list, reference XmlFu::Configuration::ALGORITHMS
 
 * :camelcase
 * :downcase
@@ -57,27 +75,27 @@ XmlFu.xml( :foo_bar => "bang" ) #=> "<fooBar>bang</fooBar>"
 
 
 # Built-in Algorithms (:camelcase)
-XmlFu.symbol_conversion_algorithm = :camelcase
+XmlFu.config.symbol_conversion_algorithm = :camelcase
 XmlFu.xml( :Foo_Bar => "bang" ) #=> "<FooBar>bang</FooBar>"
 XmlFu.xml( :foo_bar => "bang" ) #=> "<FooBar>bang</FooBar>"
 
 
 # Built-in Algorithms (:downcase)
-XmlFu.symbol_conversion_algorithm = :downcase
+XmlFu.config.symbol_conversion_algorithm = :downcase
 XmlFu.xml( :foo_bar => "bang" ) #=> "<foo_bar>bang</foo_bar>"
 XmlFu.xml( :Foo_Bar => "bang" ) #=> "<foo_bar>bang</foo_bar>"
 XmlFu.xml( :FOO => "bar" ) #=> "<foo>bar</foo>"
 
 
 # Built-in Algorithms (:upcase)
-XmlFu.symbol_conversion_algorithm = :upcase
+XmlFu.config.symbol_conversion_algorithm = :upcase
 XmlFu.xml( :foo_bar => "bang" ) #=> "<FOO_BAR>bang</FOO_BAR>"
 XmlFu.xml( :Foo_Bar => "bang" ) #=> "<FOO_BAR>bang</FOO_BAR>"
 XmlFu.xml( :foo => "bar" ) #=> "<FOO>bar</FOO>"
 
 
 # Custom Algorithm
-XmlFu.symbol_conversion_algorithm = lambda {|sym| sym.do_something_special }
+XmlFu.config.symbol_conversion_algorithm = lambda {|sym| sym.do_something_special }
 ```
 
 ### Types of Nodes
@@ -119,6 +137,11 @@ XmlFu.xml("foo!" => "<bar/>") #=> "<foo><bar/></foo>"
 Yes, the attributes of an XML node are nodes themselves, so we need a way of defining them. Since XPath syntax
 uses @ to denote an attribute, so does XmlFu.
 
+**Note**: Keep in mind, because of the way that XML::Builder accepts an attributes hash and the way that
+Ruby stores and retrieves values from a Hash, that attributes won't always be generated in the same
+order. We can only guarantee that the attributes will be present, not in any specific order.
+
+
 ``` ruby
 XmlFu.xml(:agent => {
   "@id" => "007",
@@ -190,6 +213,14 @@ XmlFu.xml("foo/" => {"@id" => "123", "=" => "You can't see me."})
 ```
 
 
+### OpenStructs
+
+Since version 0.2.0, support has been added for converting an OpenStruct object. OpenStruct objects behave
+similar to Hashes, but they do not allow the flexibility that Hashes provide when naming keys/methods. As such,
+the advanced naming capabilities are not available with OpenStruct objects and key conversion will go through
+XmlFu.config.symbol_conversion_algorithm.
+
+
 ### Arrays
 
 Since the value in a key/value pair is (for the most part) used as the contents of a key/node, there are some
@@ -271,20 +302,55 @@ are currently ignored in arrays and only Hashes are translated.
 ```ruby
   "foo" => [
     {:bar => "biz"},
-    nil, # ignored
-    true, # ignored
-    false, # ignored
-    42, # ignored
-    3.14, # ignored
-    "simple string", # ignored
+    nil,                              # ignored
+    true,                             # ignored
+    false,                            # ignored
+    42,                               # ignored
+    3.14,                             # ignored
+    "simple string",                  # ignored
     ['another','array','of','values'] # ignored
   ]
   #=> "<foo><bar>biz</bar></foo>"
 ```
 
 ## Options
+
+The following options are available to pass to XmlFu.xml(obj, options).
+
 * **:instruct** => true
-  * Adds &lt;xml version="1.0" encoding="UTF-8"?&gt; to generated XML
+  * Adds &lt;?xml version="1.0" encoding="UTF-8"?&gt; to generated XML
+  * This will be overridden by XmlFu.config.include_xml_declaration
+
+
+## Configuration
+```
+  XmlFu.configure do |config|
+    config.symbol_conversion_algorithm = :default  # (:lower_camelcase)
+    config.fail_on_invalid_construct = false       # (false)
+    config.include_xml_declaration = nil           # (nil)
+  end
+```
+
+### symbol_conversion_algorithm
+
+This is used to convert symbol keys in a Hash to Strings.
+
+
+### fail_on_invalid_construct
+
+When an unsupported object is passed to XmlFu.xml(), the default action is to return nil as
+the result. When fail_on_invalid_construct is enabled, XmlFu.xml() will raise an ArgumentError
+to denote that the passed object is not supported rather than fail silently.
+
+### include_xml_declaration
+
+Deals with adding/excluding &lt;?xml version="1.0" encoding="UTF-8"?&gt; to generated XML
+
+* When enabled, ALWAYS adds declaration to XML
+* When disabled, NEVER adds declaration to XML
+* When nil, control given to XmlFu.xml :instruct option (default)
+
+
 
 
 ## Cheat Sheet

data/lib/xml-fu.rb

@@ -1,75 +1,69 @@
 #require "xml-fu/version"
 require "xml-fu/hash"
+require "xml-fu/open_struct"
 require "xml-fu/array"
 require "xml-fu/markup"
+require "xml-fu/configuration"
 
 module XmlFu
-  class << self
 
-    # Convert construct into XML
-    def xml(construct, options={})
-      case construct
-      when ::Hash   then Hash.to_xml( construct.dup, options )
-      when ::Array  then Array.to_xml( construct.dup, options )
-      else nil
-      end
-    end#convert
-
-    # @todo Add Nori-like parsing capability to convert XML back into XmlFu-compatible Hash/Array
-    # Parse XML into array of hashes.  If XML used as input contains only sibling nodes, output
-    # will be array of hashes corresponding to those sibling nodes.
-    #
-    #     <foo/><bar/> => [{"foo/" => ""}, {"bar/" => ""}]
-    #
-    # If XML used as input contains a full document with root node, output will be
-    # an array of one hash (the root node hash)
-    #
-    #     <foo><bar/><baz/></foo> => [{"foo" => [{"bar/" => ""},{"baz/" => ""}] }]
-    def parse(xml=nil, options={})
-      parsed_xml = xml
+  # Convert construct into XML
+  def self.xml(construct, options={})
 
-      return Array(parsed_xml)
+    # Override options for xml_declaration if config is present
+    unless self.config.include_xml_declaration.nil?
+      options[:instruct] = self.config.include_xml_declaration
     end
 
-    def configure
-      yield self
+    case construct
+    when ::OpenStruct then
+      OpenStruct.to_xml( construct.dup, options )
+    when ::Hash then
+      Hash.to_xml( construct.dup, options )
+    when ::Array then
+      Array.to_xml( construct.dup, options )
+    else
+      if construct.respond_to?(:to_xml)
+        construct.to_xml
+      else
+        # Options have been exhausted
+        if self.config.fail_on_invalid_construct
+          raise ArgumentError, "Invalid construct"
+        else
+          nil
+        end
+      end
     end
+  end#self.xml
 
-    ################################################################################
-    ## CONFIGURATIONS
-    ################################################################################
 
-    @@infer_simple_value_nodes = false
-
-    # Set configuration option to be used with future releases
-    def infer_simple_value_nodes=(val)
-      @@infer_simple_value_nodes = val
+  # Used to determine if the top-level #xml method recognizes the passed object
+  def self.recognized_object?(obj)
+    case obj
+    when ::Hash       then return true
+    when ::Array      then return true
+    when ::OpenStruct then return true
+    else
+      return true if obj.respond_to?(:to_xml)
+      return false
     end
+  end#self.recognized_object?
 
-    # Configuration option to be used with future releases
-    # This option should allow for the inferrance of parent node names of simple value types
-    #
-    # Example:
-    #     1 => <Integer>1</Integer>
-    #     true => <Boolean>true</Boolean>
-    #
-    # This is disabled by default as it is conflicting with working logic.
-    def infer_simple_value_nodes
-      return @@infer_simple_value_nodes
-    end
 
+  ################################################################################
+  ## CONFIGURATIONS
+  ################################################################################
+
+  # Modify configuration for library
+  # @yield [Configuration]
+  def self.configure
+    yield self.config if block_given?
+  end#configure
 
-    # @param formula_enum Formula Enumeration
-    # @return [lambda]
-    def symbol_conversion_algorithm=( formula_enum=nil, &block )
-      XmlFu::Node.symbol_conversion_algorithm = (formula_enum ? formula_enum : block)
-    end#symbol_conversion_algorithm
 
+  def self.config
+    @@config ||= Configuration.new
+  end#self.config
 
-    # @return [lambda]
-    def symbol_conversion_algorithm
-      XmlFu::Node.symbol_conversion_algorithm
-    end#symbol_conversion_algorithm
 
-  end#class<<self
 end#XmlFu

data/lib/xml-fu/array.rb

@@ -22,46 +22,24 @@ module XmlFu
         case options[:content_type].to_s
         when "collection"
           raise(MissingKeyException, "Key name missing for collection") if key.empty?
-          
-          case 
-          when ::Array === item
+
+          case item
+          when ::Array then
             xml << Array.to_xml(item.flatten,options)
           else
             xml << Node.new(key, item, attributes).to_xml
           end
         else
           # Array is content of node rather than collection of node elements
-          case
-          when ::Hash === item   
-            xml << Hash.to_xml(item, options)
-          when ::Array === item  
-            xml << Array.to_xml(item, options)
-          when XmlFu.infer_simple_value_nodes == true
-            xml << infer_node(item, attributes)
-          when item.respond_to?(:to_xml)
-            xml << item.to_xml
+          if XmlFu.recognized_object?(item)
+            xml << XmlFu.xml(item, options)
           else
-            # unknown xml tranfromation process
+            # unknown xml transformation
           end
         end
       end
     end#self.to_xml
 
-    # Future Functionality - VERY ALPHA STAGE!!!
-    # @todo Add node inferrance functionality
-    # @note Do not use if you want stable functionality
-    # @param item Simple Value
-    # @param [Hash] attributes Hash of attributes to assign to inferred node.
-    def self.infer_node(item, attributes={})
-      node_name = case item.class
-                  when "TrueClass"
-                  when "FalseClass"
-                    "Boolean"
-                  else
-                    item.class
-                  end
-      Node.new(node_name, item, attributes).to_xml
-    end#self.infer_node
 
     # Convenience function to iterate over array items as well as
     # providing a single location for logic
@@ -74,7 +52,7 @@ module XmlFu
         key = opts.fetch(:key, "")
         item_content = item
 
-        # Attributes reuires duplicate or child elements will 
+        # Attributes reuires duplicate or child elements will
         # contain attributes of their siblings.
         attributes = (opts[:attributes] ? opts[:attributes].dup : {})
 
@@ -84,7 +62,7 @@ module XmlFu
         end
 
         item_name = ( Symbol === key ?
-                     XmlFu::Node.symbol_conversion_algorithm.call(key) :
+                     XmlFu.config.symbol_conversion_algorithm.call(key) :
                      key.to_s )
 
         yield xml, item_name, item_content, attributes

data/lib/xml-fu/configuration.rb

@@ -0,0 +1,58 @@
+module XmlFu
+  class Configuration
+    # @attr [lambda] symbol_conversion_algorithm (:lower_camelcase)
+    #   symbol-to-string conversion algorithm
+    attr_reader :symbol_conversion_algorithm # define my own writer
+
+    # @attr [Boolean] fail_on_invalid_construct (false)
+    #   By default, XmlFu works for converting Hash, Array, and OpenStruct objects. Any other
+    #   type of object will be ignored and the result would return an empty string. With this option
+    #   enabled, XmlFu will raise an exception if an unsupported object is attempted to be
+    #   converted.
+    attr_accessor :fail_on_invalid_construct
+
+    # @attr [Boolean, nil] include_xml_declaration (nil)
+    #   If set, will override XmlFu.xml :istruct option for toggling the XML declaration for
+    #   the generated output.
+    attr_accessor :include_xml_declaration
+
+
+    ALGORITHMS = {
+      :camelcase => lambda { |sym| sym.to_s.camelcase },
+      :downcase => lambda { |sym| sym.to_s.downcase },
+      :lower_camelcase => lambda { |sym| sym.to_s.lower_camelcase }, # DEFAULT
+      :none => lambda { |sym| sym.to_s },
+      :upcase => lambda { |sym| sym.to_s.upcase }
+    }
+
+
+    # Set default values
+    def initialize
+      @symbol_conversion_algorithm = ALGORITHMS[:lower_camelcase]
+      @fail_on_invalid_construct = false
+      @include_xml_declaration = nil
+    end#initialize
+
+
+    # Method for setting global Symbol-to-string conversion algorithm
+    # @param [symbol, lambda] algorithm
+    #   Can be symbol corresponding to predefined algorithm or a lambda that accepts a symbol
+    #   as an argument and returns a string
+    def symbol_conversion_algorithm=(algorithm)
+      raise(ArgumentError, "Missing symbol conversion algorithm") unless algorithm
+
+      if algorithm.respond_to?(:call)
+        @symbol_conversion_algorithm = algorithm
+      else
+        if algorithm == :default
+          @symbol_conversion_algorithm = ALGORITHMS[:lower_camelcase]
+        elsif ALGORITHMS.keys.include?(algorithm)
+          @symbol_conversion_algorithm = ALGORITHMS[algorithm]
+        else
+          raise(ArgumentError, "Invalid symbol conversion algorithm")
+        end
+      end
+    end#symbol_conversion_algorithm
+
+  end#class
+end#module

data/lib/xml-fu/hash.rb

@@ -9,61 +9,67 @@ module XmlFu
   # If order is of concern, use Array.to_xml
   class Hash
 
-    class << self
-
-      # Convert Hash to XML String
-      def to_xml(hash, options={})
-        each_with_xml hash, options do |xml, name, value, attributes|
+    # Convert Hash to XML String
+    def self.to_xml(hash, options={})
+      each_with_xml hash, options do |xml, name, value, attributes|
+        case value
+        when ::OpenStruct then
+          node = Node.new( name, OpenStruct.to_xml(value, options) )
+          # We want the value returned from OpenStruct.to_xml NOT to be escaped
+          node.escape_xml = false
+
+          xml << node.to_xml
+        else
           xml << Node.new(name, value, attributes).to_xml
         end
-      end#to_xml
+      end
+    end#self.to_xml
 
 
-      # Class method to filter out attributes and content
-      # from a given hash
-      def filter(hash)
-        attribs = {}
-        content = hash.dup
+    # Class method to filter out attributes and content
+    # from a given hash
+    def self.filter(hash)
+      attribs = {}
+      content = hash.dup
 
-        content.keys.select{|k| k =~ /^@/ }.each do |k|
-          attribs[k[1..-1]] = content.delete(k)
-        end
+      content.keys.select{|k| k =~ /^@/ }.each do |k|
+        attribs[k[1..-1]] = content.delete(k)
+      end
 
-        # Use _content value if defined
-        content = content.delete("=") || content
+      # Use _content value if defined
+      content = content.delete("=") || content
 
-        return [content, attribs]
-      end#filter
+      return [content, attribs]
+    end#self.filter
 
-    private
+  private
 
-      # Provides a convenience function to iterate over the hash
-      # Logic will filter out attribute and content keys from hash values
-      def each_with_xml(hash, opts={})
-        xml = XmlFu::Markup.new(opts)
+    # Provides a convenience function to iterate over the hash
+    # Logic will filter out attribute and content keys from hash values
+    def self.each_with_xml(hash, opts={})
+      xml = XmlFu::Markup.new(opts)
 
-        hash.each do |key,value|
-          node_value = value
-          node_attrs = {}
+      hash.each do |key,value|
+        node_value = value
+        node_attrs = {}
 
-          # yank the attribute keys into their own hash
-          if value.respond_to?(:keys)
-            filtered = Hash.filter(value)
-            node_value, node_attrs = filtered.first, filtered.last
-          end
+        # yank the attribute keys into their own hash
+        if value.respond_to?(:keys)
+          filtered = Hash.filter(value)
+          node_value, node_attrs = filtered.first, filtered.last
+        end
 
-          # Use symbol conversion algorithm to set tag name
-          node_name = ( Symbol === key ?
-                       XmlFu::Node.symbol_conversion_algorithm.call(key) :
-                       key.to_s )
+        # Use symbol conversion algorithm to set tag name
+        node_name = ( Symbol === key ?
+                     XmlFu.config.symbol_conversion_algorithm.call(key) :
+                     key.to_s )
 
-          yield xml, node_name, node_value, node_attrs
-        end
+        yield xml, node_name, node_value, node_attrs
+      end
 
-        xml.target!
-      end#each_with_xml
+      xml.target!
+    end#self.each_with_xml
 
-    end#class << self
 
   end#Hash
 

data/lib/xml-fu/node.rb

@@ -15,35 +15,6 @@ module XmlFu
     # xs:dateTime format.
     XS_DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
 
-    # default set of algorithms to choose from
-    ALGORITHMS = {
-      :camelcase => lambda { |sym| sym.to_s.camelcase },
-      :downcase => lambda { |sym| sym.to_s.downcase },
-      :lower_camelcase => lambda { |sym| sym.to_s.lower_camelcase }, # DEFAULT
-      :none => lambda { |sym| sym.to_s },
-      :upcase => lambda { |sym| sym.to_s.upcase }
-    }
-
-    # Class method for retrieving global Symbol-to-string conversion algorithm
-    # @return [lambda]
-    def self.symbol_conversion_algorithm
-      @symbol_conversion_algorithm ||= ALGORITHMS[:lower_camelcase]
-    end#self.symbol_conversion_algorithm
-
-    # Class method for setting global Symbol-to-string conversion algorithm
-    # @param [symbol, lambda] algorithm
-    #   Can be symbol corresponding to predefined algorithm or a lambda that accepts a symbol
-    #   as an argument and returns a string
-    def self.symbol_conversion_algorithm=(algorithm)
-      if algorithm == :default
-        algorithm = ALGORITHMS[:lower_camelcase]
-      else
-        algorithm = ALGORITHMS[algorithm] unless algorithm.respond_to?(:call)
-      end
-      raise(ArgumentError, "Invalid symbol conversion algorithm") unless algorithm
-      @symbol_conversion_algorithm = algorithm
-    end#self.symbol_conversion_algorithm=
-
     attr_accessor :escape_xml
     attr_accessor :self_closing
     attr_accessor :content_type
@@ -61,6 +32,7 @@ module XmlFu
       self.name = name
     end#initialize
 
+
     attr_reader :attributes
     def attributes=(val)
       if ::Hash === val
@@ -70,6 +42,7 @@ module XmlFu
       end
     end
 
+
     attr_reader :name
     def name=(val)
       use_name = val.dup
@@ -80,13 +53,14 @@ module XmlFu
       use_name = use_name[1..-1] if use_name[0,1] == ":"
 
       if Symbol === val
-        use_name = self.class.symbol_conversion_algorithm.call(use_name)
+        use_name = XmlFu.config.symbol_conversion_algorithm.call(use_name)
       end
 
       # Set name to remaining value
       @name = "#{use_name}"
     end#name=
 
+
     # Converts name into proper XML node name
     # @param [String, Symbol] val Raw name
     def name_parse_special_characters(val)
@@ -116,15 +90,17 @@ module XmlFu
       return use_this
     end#name_parse_special_characters
 
+
     # Custom Setter for @value instance method
     def value=(val)
       case val
-      when ::String   then @value = val.to_s
-      when ::Hash     then @value = val
-      when ::Array    then @value = val
-      when ::DateTime then @value = val.strftime XS_DATETIME_FORMAT
-      when ::Time     then @value = val.strftime XS_DATETIME_FORMAT
-      when ::Date     then @value = val.strftime XS_DATETIME_FORMAT
+      when ::String     then @value = val.to_s
+      when ::Hash       then @value = val
+      when ::Array      then @value = val
+      when ::OpenStruct then @value = val
+      when ::DateTime   then @value = val.strftime XS_DATETIME_FORMAT
+      when ::Time       then @value = val.strftime XS_DATETIME_FORMAT
+      when ::Date       then @value = val.strftime XS_DATETIME_FORMAT
       else
         if val.respond_to?(:to_datetime)
           @value = val.to_datetime
@@ -140,6 +116,7 @@ module XmlFu
       @value = val.to_s
     end#value=
 
+
     # @return [String, nil]
     # Value can be nil, else it should return a String value.
     def value
@@ -147,6 +124,7 @@ module XmlFu
       return @value
     end#value
 
+
     # Create XML String from XmlFu::Node object
     def to_xml
       xml = Builder::XmlMarkup.new

data/lib/xml-fu/open_struct.rb

@@ -0,0 +1,17 @@
+require 'ostruct'
+require 'builder'
+require 'xml-fu/node'
+
+module XmlFu
+  # An OpenStruct object behaves similar to a Hash in that it has key/value pairs,
+  # but is more restrictive with key names. As such, it is near impossible to set "attribute"
+  # keys on an OpenStruct object.
+  class OpenStruct
+
+    def self.to_xml(obj, options={})
+      Hash.to_xml(obj.marshal_dump, options)
+    end#self.to_xml
+
+  end#class
+
+end#module

data/lib/xml-fu/version.rb

@@ -1,3 +1,3 @@
 module XmlFu
-  VERSION = "0.1.9"
+  VERSION = "0.2.0"
 end

data/spec/lib/configuration_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe XmlFu::Configuration do
+  subject { XmlFu::Configuration }
+
+  it "should have ::ALGORITHMS" do
+    lambda { subject::ALGORITHMS }.should_not raise_exception
+    subject::ALGORITHMS.should_not be_nil
+  end
+
+  describe "instance" do
+    subject { XmlFu::Configuration.new }
+
+    [ :symbol_conversion_algorithm,
+      :symbol_conversion_algorithm=,
+      :fail_on_invalid_construct,
+      :include_xml_declaration
+    ].each do |m|
+      it "should respond_to '#{m}'" do
+        subject.should respond_to(m)
+      end
+    end
+  end#instance
+end

data/spec/lib/open_struct_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+require 'ostruct'
+
+describe XmlFu::OpenStruct do
+  let(:klass) { XmlFu::OpenStruct }
+
+  describe ".to_xml" do
+    subject { OpenStruct.new({:foo => "bar"}) }
+
+    it "should result in correct output" do
+      klass.to_xml(subject).should == "<foo>bar</foo>"
+    end
+
+    context "with complex nesting" do
+      subject do
+        OpenStruct.new({
+          :foo => [
+            OpenStruct.new({ :bar => "bang" }),
+            { :bang => :biz },
+            { "number*" => [
+              { "@name" => "pi", "=" => 3.14159 }
+            ]}
+          ]
+        })
+      end
+
+      # NOTE: (TL;DR) Cannot guarantee attribute order, can only guarantee attribute presence
+      #
+      # Due to the way XML::Builder iterates over attributes, the order of the attributes
+      # cannot be guaranteed. This is because of the way that ruby stores and iterates
+      # over a Hash, and it is different depending on the version of Ruby being used.
+      it "should result in correct output" do
+        klass.to_xml(subject).should == '<foo><bar>bang</bar><bang>biz</bang><number name="pi">3.14159</number></foo>'
+      end
+    end
+  end#.to_xml
+end

data/spec/lib/xml-fu_spec.rb

@@ -2,12 +2,12 @@ require 'spec_helper'
 
 describe XmlFu do
   after(:each) do
-    XmlFu.symbol_conversion_algorithm = :default
+    XmlFu.config.symbol_conversion_algorithm = :default
   end
 
   describe "with default symbol conversion algorithm" do
     before(:each) do
-      XmlFu.symbol_conversion_algorithm = :default
+      XmlFu.config.symbol_conversion_algorithm = :default
     end
 
     {
@@ -24,7 +24,7 @@ describe XmlFu do
 
   describe "with built-in :camelcase algorithm" do
     before(:each) do
-      XmlFu.symbol_conversion_algorithm = :camelcase
+      XmlFu.config.symbol_conversion_algorithm = :camelcase
     end
 
     {
@@ -41,7 +41,7 @@ describe XmlFu do
 
   describe "with built-in :downcase algorithm" do
     before(:each) do
-      XmlFu.symbol_conversion_algorithm = :downcase
+      XmlFu.config.symbol_conversion_algorithm = :downcase
     end
 
     {
@@ -58,7 +58,7 @@ describe XmlFu do
 
   describe "with built-in :upcase algorithm" do
     before(:each) do
-      XmlFu.symbol_conversion_algorithm = :upcase
+      XmlFu.config.symbol_conversion_algorithm = :upcase
     end
 
     {
@@ -71,5 +71,4 @@ describe XmlFu do
       end
     end
   end#:upcase
-
-end
+end#XmlFu

data/spec/xmlfu_spec.rb

@@ -2,97 +2,180 @@ require 'spec_helper'
 
 describe XmlFu do
   describe ".xml" do
-    it "should return nil for value that isn't a Hash or Array" do
-      XmlFu.xml(1).should == nil
-      XmlFu.xml(nil).should == nil
-      XmlFu.xml(Object.new).should == nil
-    end
+    context "(default configuration)" do
+      context "with an unsupported construct as argument" do
+        it "should return nil" do
+          XmlFu.xml(1).should == nil
+          XmlFu.xml(nil).should == nil
+          XmlFu.xml(Object.new).should == nil
+        end
+      end
 
-    it "translates a given Hash to XML" do
-      XmlFu.xml( :id => 1 ).should == "<id>1</id>"
-    end
+      it "translates a given Hash to XML" do
+        XmlFu.xml({:id => 1}).should == "<id>1</id>"
+      end
 
-    it "doesn't modify the input hash" do
-      the_hash = {
-        :person => {
-          "@id" => "007",
-          :first_name => "James",
-          :last_name => "Bond"
+      it "doesn't modify the input hash" do
+        the_hash = {
+          :person => {
+            "@id" => "007",
+            :first_name => "James",
+            :last_name => "Bond"
+          }
         }
-      }
-      original_hash = the_hash.dup
+        original_hash = the_hash.dup
 
-      XmlFu.xml(the_hash)
-      original_hash.should == the_hash
-    end
+        XmlFu.xml(the_hash)
+        original_hash.should == the_hash
+      end
 
-    it "should return correct value based on nested array of hashes" do
-      hash = {
-        "SecretAgents" => [
-          {"agent/" => {"@name"=>"Alec Trevelyan"}}, 
-          {"agent/" => {"@name"=>"James Bond"}}
-        ]
-      }
-      expected = "<SecretAgents><agent name=\"Alec Trevelyan\"/><agent name=\"James Bond\"/></SecretAgents>" 
-      XmlFu.xml(hash).should == expected
-    end
+      it "should return correct value based on nested array of hashes" do
+        hash = {
+          "SecretAgents" => [
+            {"agent/" => {"@name"=>"Alec Trevelyan"}},
+            {"agent/" => {"@name"=>"James Bond"}}
+          ]
+        }
+        expected = '<SecretAgents><agent name="Alec Trevelyan"/><agent name="James Bond"/></SecretAgents>'
+        XmlFu.xml(hash).should == expected
+      end
 
-    it "should return correct value for nested collection of hashes" do
-      hash = {
-        "foo*" => [
-          {"@bar" => "biz"},
-          {"@biz" => "bang"}
-        ]
-      }
-      XmlFu.xml(hash).should == "<foo bar=\"biz\"></foo><foo biz=\"bang\"></foo>"
-    end
+      it "should return correct value for nested collection of hashes" do
+        hash = {
+          "foo*" => [
+            {"@bar" => "biz"},
+            {"@biz" => "bang"}
+          ]
+        }
+        XmlFu.xml(hash).should == '<foo bar="biz"></foo><foo biz="bang"></foo>'
+      end
 
-    it "should return list of self-closing nodes" do
-      hash = {
-        "foo/*" => [
-          {"@bar" => "biz"},
-          {"@biz" => "bang"}
-        ]
-      }
-      XmlFu.xml(hash).should == "<foo bar=\"biz\"/><foo biz=\"bang\"/>"
-    end
+      it "should return list of self-closing nodes" do
+        hash = {
+          "foo/*" => [
+            {"@bar" => "biz"},
+            {"@biz" => "bang"}
+          ]
+        }
+        XmlFu.xml(hash).should == '<foo bar="biz"/><foo biz="bang"/>'
+      end
 
-    it "should ignore nested values for content array" do
-      output = XmlFu.xml("foo/" => [{:bar => "biz"}, {:bar => "biz"}])
-      output.should == "<foo/>"
-    end
+      it "should ignore nested values for content array" do
+        output = XmlFu.xml("foo/" => [{:bar => "biz"}, {:bar => "biz"}])
+        output.should == "<foo/>"
+      end
 
-    it "should ignore nested keys if they aren't attributes" do
-      output = XmlFu.xml("foo/" => {"bar" => "biz"})
-      output.should == "<foo/>"
+      it "should ignore nested keys if they aren't attributes" do
+        output = XmlFu.xml("foo/" => {"bar" => "biz"})
+        output.should == "<foo/>"
 
-      output = XmlFu.xml("foo/" => {"@id" => "0"})
-      output.should == "<foo id=\"0\"/>"
-    end
-  end
+        output = XmlFu.xml("foo/" => {"@id" => "0"})
+        output.should == '<foo id="0"/>'
+      end
+    end#default configuration
 
-  describe "configure" do
-    it "yields the XmlFu module" do
-      XmlFu.configure do |xf|
-        xf.should respond_to(:infer_simple_value_nodes)
+    context "with 'fail_on_invalid_construct' enabled" do
+      before(:each) do
+        XmlFu.configure do |config|
+          config.fail_on_invalid_construct = true
+        end
       end
-    end
 
-    it "should set XmlFu Module variable 'infer_simple_value_nodes'" do
-      XmlFu.infer_simple_value_nodes.should == false
-      XmlFu.infer_simple_value_nodes = true
-      XmlFu.infer_simple_value_nodes.should == true
-      XmlFu.infer_simple_value_nodes = false
-      XmlFu.infer_simple_value_nodes.should == false
+      context "with an unsupported construct as argument" do
+        it "should raise an ArgumentError exception" do
+          lambda { XmlFu.xml(1) }.should raise_exception
+          lambda { XmlFu.xml(nil) }.should raise_exception
+          lambda { XmlFu.xml(Object.new) }.should raise_exception
+        end
+      end
+    end#fail_on_invalid_construct enabled
+
+    context "with 'include_xml_declaration" do
+      context "set TRUE" do
+        before(:each) do
+          XmlFu.configure do |config|
+            config.include_xml_declaration = true
+          end
+        end
+
+        it "should ALWAYS output the xml declaration" do
+          XmlFu.xml({:foo => "bar"}).should == '<?xml version="1.0" encoding="UTF-8"?><foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => false}).should == '<?xml version="1.0" encoding="UTF-8"?><foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => true}).should == '<?xml version="1.0" encoding="UTF-8"?><foo>bar</foo>'
+        end
+      end#enabled
+
+      context "set FALSE" do
+        before(:each) do
+          XmlFu.configure do |config|
+            config.include_xml_declaration = false
+          end
+        end
+
+        it "should NEVER output the xml declaration" do
+          XmlFu.xml({:foo => "bar"}).should == '<foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => false}).should == '<foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => true}).should == '<foo>bar</foo>'
+        end
+      end#enabled
+
+      context "set NIL" do
+        before(:each) do
+          XmlFu.configure do |config|
+            config.include_xml_declaration = nil
+          end
+        end
+
+        it "should output if option says so" do
+          XmlFu.xml({:foo => "bar"}).should == '<foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => false}).should == '<foo>bar</foo>'
+          XmlFu.xml({:foo => "bar"}, {:instruct => true}).should == '<?xml version="1.0" encoding="UTF-8"?><foo>bar</foo>'
+        end
+      end
     end
-  end
+  end#.xml
+
+  describe ".recognized_object?" do
+    describe "should be true" do
+      it { XmlFu.recognized_object?(Hash.new).should be_true }
+      it { XmlFu.recognized_object?(Array.new).should be_true }
+      it { XmlFu.recognized_object?(OpenStruct.new).should be_true }
+
+      context "if object responds to :to_xml" do
+        subject do
+          obj = Object.new
+          def obj.to_xml; end
+          obj
+        end
+        it { XmlFu.recognized_object?(subject).should be_true }
+      end
+    end#should be true
+
+    describe "should be false" do
+      it { XmlFu.recognized_object?(1).should_not be_true }
+      it { XmlFu.recognized_object?("foobar").should_not be_true }
+      it { XmlFu.recognized_object?(1.23).should_not be_true }
+      context "if object does not respond to :to_xml" do
+        it { XmlFu.recognized_object?(Object.new).should_not be_true }
+      end
+    end#should be false
+  end#.recognized_object?
+
+  describe ".configure" do
+    context "yielded value" do
+      it "should be the same object as .config()" do
+        yielded = nil
+        XmlFu.configure { |c| yielded = c }
+        yielded.should == XmlFu.config
+      end
+    end#yielded value
+  end#.configure
 
-  describe ".parse" do
-    it "should always return an array" do
-      ::Array === XmlFu.parse()
-      ::Array === XmlFu.parse("foo")
-      ::Array === XmlFu.parse("foo", {:bar => true})
+  describe ".config" do
+    subject { XmlFu.config }
+    it "should be a XmlFu::Configuration object" do
+      subject.should be_a_kind_of(XmlFu::Configuration)
     end
-  end
+  end#.config
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: xml-fu
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 9
-  version: 0.1.9
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Ryan Johnson
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-07-22 00:00:00 Z
+date: 2013-09-24 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: builder
@@ -83,14 +83,18 @@ files:
 - Rakefile
 - lib/xml-fu.rb
 - lib/xml-fu/array.rb
+- lib/xml-fu/configuration.rb
 - lib/xml-fu/core_ext/string.rb
 - lib/xml-fu/hash.rb
 - lib/xml-fu/markup.rb
 - lib/xml-fu/node.rb
+- lib/xml-fu/open_struct.rb
 - lib/xml-fu/version.rb
 - spec/lib/array_spec.rb
+- spec/lib/configuration_spec.rb
 - spec/lib/hash_spec.rb
 - spec/lib/node_spec.rb
+- spec/lib/open_struct_spec.rb
 - spec/lib/xml-fu_spec.rb
 - spec/lib/xml_spec.rb
 - spec/spec_helper.rb
@@ -125,14 +129,16 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: xml-fu
-rubygems_version: 1.8.24
+rubygems_version: 1.8.26
 signing_key: 
 specification_version: 3
 summary: Simple Hash/Array to XML generation
 test_files: 
 - spec/lib/array_spec.rb
+- spec/lib/configuration_spec.rb
 - spec/lib/hash_spec.rb
 - spec/lib/node_spec.rb
+- spec/lib/open_struct_spec.rb
 - spec/lib/xml-fu_spec.rb
 - spec/lib/xml_spec.rb
 - spec/spec_helper.rb