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

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