Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #10124: as_array_docs.3.diff

File as_array_docs.3.diff, 5.4 kB (added by jeremymcanally, 7 months ago)

  • activesupport/lib/active_support/core_ext/array/conversions.rb

    old new  
    44  module CoreExtensions #:nodoc: 
    55    module Array #:nodoc: 
    66      module Conversions 
    7         # Converts the array to comma-seperated 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". 
     7        # Returns a comma-seperated string in which the last element of the 
     8        # array is joined by a connector word. 
     9        # 
     10        # ==== Options 
     11        # * <tt>:connector</tt> - The string used to join the last element in 
     12        #   arrays with two or more elements (default: <tt>"and"</tt>) 
     13        # * <tt>:skip_last_comma</tt> - Set to +true+ to return 
     14        #   <tt>"a, b and c"</tt> instead of <tt>"a, b, and c"</tt> 
     15        # 
     16        # ==== Examples 
     17        #   ["Lions", "tigers", "bears"].to_sentence 
     18        #   # => "Lions, tigers, and bears" 
     19        # 
     20        #   ["Active Record", "Action Pack", "Active Resource"].to_sentence(:connector => "or") 
     21        #   # => "Active Record, Action Pack, or Active Resource"  
     22        # 
     23        #   ["red", "green", "blue"].to_sentence(:skip_last_comma => true) 
     24        #   # => "red, green and blue" 
     25        # 
    1026        def to_sentence(options = {}) 
    1127          options.assert_valid_keys(:connector, :skip_last_comma) 
    1228          options.reverse_merge! :connector => 'and', :skip_last_comma => false 
    …… 
    2440          end 
    2541        end 
    2642 
    27         # When an array is given to url_for, it is converted to a slash separated string. 
     43        # Returns a slash-separated string from the array's elements. This 
     44        # method is used by +url_for+. 
     45        # 
     46        # ==== Examples 
     47        #   ["accounts", "new", 3].to_param 
     48        #   # => "accounts/new/3" 
     49        # 
     50        #   ["users", "opa2332", "pages", "personal"].to_param 
     51        #   # => "users/opa2332/pages/personal" 
     52        # 
    2853        def to_param 
    2954          join '/' 
    3055        end 
    …… 
    4873              to_default_s 
    4974          end 
    5075        end 
    51  
     76         
     77        # Attempts to return a string of XML from the array's elements. Each 
     78        # element must respond to +to_xml+, or an error will be raised. 
     79        # 
     80        # ==== Options 
     81        # * <tt>:root</tt> - The name of the root element (default: the 
     82        #   pluralized class name of the elements if they are homogeneous, or 
     83        #   <tt>"records"</tt> otherwise) 
     84        # * <tt>:children</tt> - The name of the child elements (default: the 
     85        #   singular version of the root element's name) 
     86        # * <tt>:indent</tt> - Number of spaces to indent the XML (default: 
     87        #   <tt>2</tt>) 
     88        # * <tt>:builder</tt> - The Builder instance to use to generate the XML 
     89        #   (default: a new instance of <tt>Builder::XmlMarkup</tt>) 
     90        # * <tt>:dasherize</tt> - Whether to use dashes instead of underscores 
     91        #   when formatting the root element's name (default: +true+) 
     92        # * <tt>:skip_instruct</tt> - Whether to omit the XML declaration from 
     93        #   the beginning of the string (default: +false+) 
     94        # * <tt>:skip_types</tt> - Whether to omit the +type+ attributes from 
     95        #   the XML tags, such as <tt>type="array"</tt> (default: +false+) 
     96        # 
     97        # If a block is given, it will be called with the Builder instance so 
     98        # that you can insert arbitrary XML or adjust Builder options before the 
     99        # array elements are processed. 
     100        # 
     101        # ==== Examples 
     102        # 
     103        #   [1, 2, 3].to_xml 
     104        #   # => RuntimeError: Not all elements respond to to_xml 
     105        #  
     106        #   [{'key' => 'value', 'key2' => 'value'}, {'name' => 'Ruby on Rails'}].to_xml 
     107        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     108        #         <records type="array"> 
     109        #           <record> 
     110        #             <key2>value</key2> 
     111        #             <key>value</key> 
     112        #           </record> 
     113        #           <record> 
     114        #             <name>Ruby on Rails</name> 
     115        #           </record> 
     116        #         </records>' 
     117        # 
     118        #   [{'color' => 'orange'}].to_xml(:root => 'vegetables', :children => 'carrot') 
     119        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     120        #         <vegetables type="array"> 
     121        #           <carrot> 
     122        #             <color>orange</color> 
     123        #           </carrot> 
     124        #         </beets>' 
     125        # 
     126        #   [{'height' => 1.8}].to_xml(:root => 'people') { |xml| 
     127        #     xml.comment!('All measurements are in meters.') 
     128        #   } 
     129        #   # => '<?xml version="1.0" encoding="UTF-8"?> 
     130        #         <people type="array"> 
     131        #           <!-- All measurements are in meters. --> 
     132        #           <person> 
     133        #             <height type="float">1.8</height> 
     134        #           </person> 
     135        #         </people>' 
     136        # 
    52137        def to_xml(options = {}) 
    53138          raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml } 
    54139