vendor/rails/activesupport/lib/active_support/core_ext/array/conversions.rb

   1 require 'builder'
   2
   3 module ActiveSupport #:nodoc:
   4   module CoreExtensions #:nodoc:
   5     module Array #:nodoc:
   6       module Conversions
   7         # Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:
   8         # * <tt>:connector</tt> - The word used to join the last element in arrays with two or more elements (default: "and")
   9         # * <tt>:skip_last_comma</tt> - Set to true to return "a, b and c" instead of "a, b, and c".
  10         def to_sentence(options = {})
  11           options.assert_valid_keys(:connector, :skip_last_comma, :locale)
  12
  13           default = I18n.translate(:'support.array.sentence_connector', :locale => options[:locale])
  14           default_skip_last_comma = I18n.translate(:'support.array.skip_last_comma', :locale => options[:locale])
  15           options.reverse_merge! :connector => default, :skip_last_comma => default_skip_last_comma
  16           options[:connector] = "#{options[:connector]} " unless options[:connector].nil? || options[:connector].strip == ''
  17
  18           case length
  19             when 0
  20               ""
  21             when 1
  22               self[0].to_s
  23             when 2
  24               "#{self[0]} #{options[:connector]}#{self[1]}"
  25             else
  26               "#{self[0...-1].join(', ')}#{options[:skip_last_comma] ? '' : ','} #{options[:connector]}#{self[-1]}"
  27           end
  28         end
  29
  30
  31         # Calls <tt>to_param</tt> on all its elements and joins the result with
  32         # slashes. This is used by <tt>url_for</tt> in Action Pack.
  33         def to_param
  34           collect { |e| e.to_param }.join '/'
  35         end
  36
  37         # Converts an array into a string suitable for use as a URL query string,
  38         # using the given +key+ as the param name.
  39         #
  40         #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
  41         def to_query(key)
  42           prefix = "#{key}[]"
  43           collect { |value| value.to_query(prefix) }.join '&'
  44         end
  45
  46         def self.included(base) #:nodoc:
  47           base.class_eval do
  48             alias_method :to_default_s, :to_s
  49             alias_method :to_s, :to_formatted_s
  50           end
  51         end
  52
  53         # Converts a collection of elements into a formatted string by calling
  54         # <tt>to_s</tt> on all elements and joining them:
  55         #
  56         #   Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post"
  57         #
  58         # Adding in the <tt>:db</tt> argument as the format yields a prettier
  59         # output:
  60         #
  61         #   Blog.find(:all).to_formatted_s(:db) # => "First Post,Second Post,Third Post"
  62         def to_formatted_s(format = :default)
  63           case format
  64             when :db
  65               if respond_to?(:empty?) && self.empty?
  66                 "null"
  67               else
  68                 collect { |element| element.id }.join(",")
  69               end
  70             else
  71               to_default_s
  72           end
  73         end
  74
  75         # Returns a string that represents this array in XML by sending +to_xml+
  76         # to each element. Active Record collections delegate their representation
  77         # in XML to this method.
  78         #
  79         # All elements are expected to respond to +to_xml+, if any of them does
  80         # not an exception is raised.
  81         #
  82         # The root node reflects the class name of the first element in plural
  83         # if all elements belong to the same type and that's not Hash:
  84         #
  85         #   customer.projects.to_xml
  86         #
  87         #   <?xml version="1.0" encoding="UTF-8"?>
  88         #   <projects type="array">
  89         #     <project>
  90         #       <amount type="decimal">20000.0</amount>
  91         #       <customer-id type="integer">1567</customer-id>
  92         #       <deal-date type="date">2008-04-09</deal-date>
  93         #       ...
  94         #     </project>
  95         #     <project>
  96         #       <amount type="decimal">57230.0</amount>
  97         #       <customer-id type="integer">1567</customer-id>
  98         #       <deal-date type="date">2008-04-15</deal-date>
  99         #       ...
 100         #     </project>
 101         #   </projects>
 102         #
 103         # Otherwise the root element is "records":
 104         #
 105         #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
 106         #
 107         #   <?xml version="1.0" encoding="UTF-8"?>
 108         #   <records type="array">
 109         #     <record>
 110         #       <bar type="integer">2</bar>
 111         #       <foo type="integer">1</foo>
 112         #     </record>
 113         #     <record>
 114         #       <baz type="integer">3</baz>
 115         #     </record>
 116         #   </records>
 117         #
 118         # If the collection is empty the root element is "nil-classes" by default:
 119         #
 120         #   [].to_xml
 121         #
 122         #   <?xml version="1.0" encoding="UTF-8"?>
 123         #   <nil-classes type="array"/>
 124         #
 125         # To ensure a meaningful root element use the <tt>:root</tt> option:
 126         #
 127         #   customer_with_no_projects.projects.to_xml(:root => "projects")
 128         #
 129         #   <?xml version="1.0" encoding="UTF-8"?>
 130         #   <projects type="array"/>
 131         #
 132         # By default root children have as node name the one of the root
 133         # singularized. You can change it with the <tt>:children</tt> option.
 134         #
 135         # The +options+ hash is passed downwards:
 136         #
 137         #   Message.all.to_xml(:skip_types => true)
 138         #
 139         #   <?xml version="1.0" encoding="UTF-8"?>
 140         #   <messages>
 141         #     <message>
 142         #       <created-at>2008-03-07T09:58:18+01:00</created-at>
 143         #       <id>1</id>
 144         #       <name>1</name>
 145         #       <updated-at>2008-03-07T09:58:18+01:00</updated-at>
 146         #       <user-id>1</user-id>
 147         #     </message>
 148         #   </messages>
 149         #
 150         def to_xml(options = {})
 151           raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml }
 152
 153           options[:root]     ||= all? { |e| e.is_a?(first.class) && first.class.to_s != "Hash" } ? first.class.to_s.underscore.pluralize : "records"
 154           options[:children] ||= options[:root].singularize
 155           options[:indent]   ||= 2
 156           options[:builder]  ||= Builder::XmlMarkup.new(:indent => options[:indent])
 157
 158           root     = options.delete(:root).to_s
 159           children = options.delete(:children)
 160
 161           if !options.has_key?(:dasherize) || options[:dasherize]
 162             root = root.dasherize
 163           end
 164
 165           options[:builder].instruct! unless options.delete(:skip_instruct)
 166
 167           opts = options.merge({ :root => children })
 168
 169           xml = options[:builder]
 170           if empty?
 171             xml.tag!(root, options[:skip_types] ? {} : {:type => "array"})
 172           else
 173             xml.tag!(root, options[:skip_types] ? {} : {:type => "array"}) {
 174               yield xml if block_given?
 175               each { |e| e.to_xml(opts.merge({ :skip_instruct => true })) }
 176             }
 177           end
 178         end
 179
 180       end
 181     end
 182   end
 183 end