Skip to content
Browse files

documents Hash#to_xml

  • Loading branch information...
1 parent d9ac4a7 commit d7e85f363a5e8d51a6e5f5d5d98b0147343a2a1f @fxn fxn committed Sep 12, 2009
Showing with 48 additions and 0 deletions.
  1. +48 −0 activesupport/lib/active_support/core_ext/hash/conversions.rb
View
48 activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -83,6 +83,54 @@ def to_query(namespace = nil)
alias_method :to_param, :to_query
+ # Returns a string containing an XML representation of its receiver:
+ #
+ # {"foo" => 1, "bar" => 2}.to_xml
+ # # =>
+ # # <?xml version="1.0" encoding="UTF-8"?>
+ # # <hash>
+ # # <foo type="integer">1</foo>
+ # # <bar type="integer">2</bar>
+ # # </hash>
+ #
+ # To do so, the method loops over the pairs and builds nodes that depend on
+ # the _values_. Given a pair +key+, +value+:
+ #
+ # * If +value+ is a hash there's a recursive call with +key+ as <tt>:root</tt>.
+ #
+ # * If +value+ is an array there's a recursive call with +key+ as <tt>:root</tt>,
+ # and +key+ singularized as <tt>:children</tt>.
+ #
+ # * If +value+ is a callable object it must expect one or two arguments. Depending
+ # on the arity, the callable is invoked with the +options+ hash as first argument
+ # with +key+ as <tt>:root</tt>, and +key+ singularized as second argument. Its
+ # return value becomes a new node.
+ #
+ # * If +value+ responds to +to_xml+ the method is invoked with +key+ as <tt>:root</tt>.
+ #
+ # * Otherwise, a node with +key+ as tag is created with a string representation of
+ # +value+ as text node. If +value+ is +nil+ an attribute "nil" set to "true" is added.
+ # Unless the option <tt>:skip_types</tt> exists and is true, an attribute "type" is
+ # added as well according to the following mapping:
+ #
+ # XML_TYPE_NAMES = {
+ # "Symbol" => "symbol",
+ # "Fixnum" => "integer",
+ # "Bignum" => "integer",
+ # "BigDecimal" => "decimal",
+ # "Float" => "float",
+ # "TrueClass" => "boolean",
+ # "FalseClass" => "boolean",
+ # "Date" => "date",
+ # "DateTime" => "datetime",
+ # "Time" => "datetime"
+ # }
+ #
+ # By default the root node is "hash", but that's configurable via the <tt>:root</tt> option.
+ #
+ # The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can
+ # configure your own builder with the <tt>:builder</tt> option. The method also accepts
+ # options like <tt>:dasherize</tt> and friends, they are forwarded to the builder.
def to_xml(options = {})
require 'builder' unless defined?(Builder)

0 comments on commit d7e85f3

Please sign in to comment.
Something went wrong with that request. Please try again.