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 = options.dup
167 options[:root] ||= all? { |e| e.is_a?(first.class) && first.class.to_s != "Hash" } ? first.class.to_s.underscore.pluralize.tr('/', '-') : "records"
168 options[:children] ||= options[:root].singularize
169 options[:indent] ||= 2
170 options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent])
171
172 root = options.delete(:root).to_s
173 children = options.delete(:children)
174
175 if !options.has_key?(:dasherize) || options[:dasherize]
176 root = root.dasherize
177 end
178
179 options[:builder].instruct! unless options.delete(:skip_instruct)
180
181 opts = options.merge({ :root => children })
182
183 xml = options[:builder]
184 if empty?
185 xml.tag!(root, options[:skip_types] ? {} : {:type => "array"})
186 else
187 xml.tag!(root, options[:skip_types] ? {} : {:type => "array"}) {
188 yield xml if block_given?
189 each { |e| e.to_xml(opts.merge({ :skip_instruct => true })) }
190 }
191 end
192 end
193
194 end
195 end
196 end
197 end