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

Changeset 9093

Show
Ignore:
Timestamp:
03/26/08 12:27:52 (2 months ago)
Author:
pratik
Message:

Improve documentation.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/actionpack/CHANGELOG

    r9088 r9093  
    11*SVN* 
     2 
     3* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert] 
    24 
    35* Fixed that FormHelper#radio_button would produce invalid ids #11298 [harlancrystal] 

  • trunk/actionpack/lib/action_controller/resources.rb

    r8982 r9093  
    227227    # 
    228228    #   <% form_for :message, @message, :url => message_path(@message), :html => {:method => :put} do |f| %> 
     229    # 
     230    # or 
     231    # 
     232    #   <% form_for @message do |f| %> 
     233    # 
     234    # which takes into account whether <tt>@message</tt> is a new record or not and generates the 
     235    # path and method accordingly. 
    229236    # 
    230237    # The #resources method accepts the following options to customize the resulting routes: 

  • trunk/actionpack/lib/action_view/helpers/atom_feed_helper.rb

    r9044 r9093  
    5050      # * <tt>:schema_date</tt>: The date at which the tag scheme for the feed was first used. A good default is the year you  
    5151      #   created the feed. See http://feedvalidator.org/docs/error/InvalidTAG.html for more information. If not specified,  
    52       #   2005 is used (as a "I don't care"-value). 
     52      #   2005 is used (as an "I don't care" value). 
    5353      # 
    5454      # Other namespaces can be added to the root element: 

  • trunk/actionpack/lib/action_view/helpers/form_helper.rb

    r9088 r9093  
    7777      # 
    7878      #   <% form_for :person, @person, :url => { :action => "update" } do |f| %> 
     79      #     <%= f.error_messages %> 
    7980      #     First name: <%= f.text_field :first_name %> 
    8081      #     Last name : <%= f.text_field :last_name %> 
    …… 
    8687      # not <tt><%= %></tt>. Also worth noting is that form_for yields a <tt>form_builder</tt> object, in this example as <tt>f</tt>, which emulates 
    8788      # the API for the stand-alone FormHelper methods, but without the object name. So instead of <tt>text_field :person, :name</tt>, 
    88       # you get away with <tt>f.text_field :name</tt>. 
     89      # you get away with <tt>f.text_field :name</tt>. Notice that you can even do <tt><%= f.error_messages %></tt> to display the 
     90      # error messsages of the model object in question. 
    8991      # 
    9092      # Even further, the form_for method allows you to more easily escape the instance variable convention. So while the stand-alone 
    …… 
    406408      #   # Let's say that @post.validated? is 1: 
    407409      #   check_box("post", "validated") 
    408       #   # => <input type="checkbox" id="post_validate" name="post[validated]" value="1" checked="checked" /> 
     410      #   # => <input type="checkbox" id="post_validated" name="post[validated]" value="1" /> 
    409411      #   #    <input name="post[validated]" type="hidden" value="0" /> 
    410412      # 
    …… 
    414416      #   #    <input name="puppy[gooddog]" type="hidden" value="no" /> 
    415417      # 
    416       #   check_box("eula", "accepted", {}, "yes", "no", :class => 'eula_check') 
    417       #   # => <input type="checkbox" id="eula_accepted" name="eula[accepted]" value="no" /> 
     418      #   check_box("eula", "accepted", { :class => 'eula_check' }, "yes", "no") 
     419      #   # => <input type="checkbox" class="eula_check" id="eula_accepted" name="eula[accepted]" value="yes" /> 
    418420      #   #    <input name="eula[accepted]" type="hidden" value="no" /> 
    419421      # 
    …… 
    431433      #   radio_button("post", "category", "rails") 
    432434      #   radio_button("post", "category", "java") 
    433       #   # => <input type="radio" id="post_category" name="post[category]" value="rails" checked="checked" /> 
    434       #   #    <input type="radio" id="post_category" name="post[category]" value="java" /> 
     435      #   # => <input type="radio" id="post_category_rails" name="post[category]" value="rails" checked="checked" /> 
     436      #   #    <input type="radio" id="post_category_java" name="post[category]" value="java" /> 
    435437      # 
    436438      #   radio_button("user", "receive_newsletter", "yes") 
    437439      #   radio_button("user", "receive_newsletter", "no") 
    438       #   # => <input type="radio" id="user_receive_newsletter" name="user[receive_newsletter]" value="yes" /> 
    439       #   #    <input type="radio" id="user_receive_newsletter" name="user[receive_newsletter]" value="no" checked="checked" /> 
     440      #   # => <input type="radio" id="user_receive_newsletter_yes" name="user[receive_newsletter]" value="yes" /> 
     441      #   #    <input type="radio" id="user_receive_newsletter_no" name="user[receive_newsletter]" value="no" checked="checked" /> 
    440442      def radio_button(object_name, method, tag_value, options = {}) 
    441443        InstanceTag.new(object_name, method, self, nil, options.delete(:object)).to_radio_button_tag(tag_value, options) 

  • trunk/activerecord/CHANGELOG

    r9090 r9093  
    11*SVN* 
     2 
     3* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert] 
    24 
    35* Fixed that ActiveRecord#Base.find_or_create/initialize would not honor attr_protected/accessible when used with a hash #11422 [miloops] 

  • trunk/activerecord/lib/active_record/fixtures.rb

    r9051 r9093  
    177177# mix ERb in with your YAML or CSV fixtures to create a bunch of fixtures for load testing, like: 
    178178# 
    179 # <% for i in 1..1000 %> 
    180 # fix_<%= i %>: 
    181 #   id: <%= i %> 
    182 #   name: guy_<%= 1 %> 
    183 # <% end %> 
     179#   <% for i in 1..1000 %> 
     180#   fix_<%= i %>: 
     181#     id: <%= i %> 
     182#     name: guy_<%= 1 %> 
     183#   <% end %> 
    184184# 
    185185# This will create 1000 very simple YAML fixtures. 

  • trunk/activerecord/lib/active_record/migration.rb

    r8481 r9093  
    9292  # The Rails package has several tools to help create and apply migrations. 
    9393  # 
    94   # To generate a new migration, use <tt>script/generate migration MyNewMigration</tt> 
     94  # To generate a new migration, you can use  
     95  #   script/generate migration MyNewMigration 
     96  # 
    9597  # where MyNewMigration is the name of your migration. The generator will 
    96   # create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt> 
     98  # create an empty migration file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt> 
    9799  # directory where <tt>nnn</tt> is the next largest migration number. 
     100  # 
    98101  # You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of 
    99102  # MyNewMigration. 
    100103  # 
     104  # There is a special syntactic shortcut to generate migrations that add fields to a table. 
     105  #   script/generate migration add_fieldname_to_tablename fieldname:string 
     106  # 
     107  # This will generate the file <tt>nnn_add_fieldname_to_tablename</tt>, which will look like this: 
     108  #   class AddFieldnameToTablename < ActiveRecord::Migration 
     109  #     def self.up 
     110  #       add_column :tablenames, :fieldname, :string 
     111  #     end 
     112  #  
     113  #     def self.down 
     114  #       remove_column :tablenames, :fieldname 
     115  #     end 
     116  #   end 
     117  #  
    101118  # To run migrations against the currently configured database, use 
    102119  # <tt>rake db:migrate</tt>. This will update the database by running all of the 

  • trunk/activerecord/lib/active_record/serializers/json_serializer.rb

    r7905 r9093  
    99    #   konata = User.find(1) 
    1010    #   konata.to_json 
    11     # 
    12     #   {"id": 1, "name": "Konata Izumi", "age": 16, 
    13     #    "created_at": "2006/08/01", "awesome": true} 
     11    #   # => {"id": 1, "name": "Konata Izumi", "age": 16, 
     12    #         "created_at": "2006/08/01", "awesome": true} 
    1413    # 
    1514    # The :only and :except options can be used to limit the attributes 
    …… 
    1716    # 
    1817    #   konata.to_json(:only => [ :id, :name ]) 
    19     # 
    20     #   {"id": 1, "name": "Konata Izumi"} 
     18    #   # => {"id": 1, "name": "Konata Izumi"} 
    2119    # 
    2220    #   konata.to_json(:except => [ :id, :created_at, :age ]) 
    23     # 
    24     #   {"name": "Konata Izumi", "awesome": true} 
     21    #   # => {"name": "Konata Izumi", "awesome": true} 
    2522    # 
    2623    # To include any methods on the model, use :methods. 
    2724    # 
    2825    #   konata.to_json(:methods => :permalink) 
    29     # 
    30     #   {"id": 1, "name": "Konata Izumi", "age": 16, 
    31     #    "created_at": "2006/08/01", "awesome": true, 
    32     #    "permalink": "1-konata-izumi"} 
     26    #   # => {"id": 1, "name": "Konata Izumi", "age": 16, 
     27    #         "created_at": "2006/08/01", "awesome": true, 
     28    #         "permalink": "1-konata-izumi"} 
    3329    # 
    3430    # To include associations, use :include. 
    3531    # 
    3632    #   konata.to_json(:include => :posts) 
    37     # 
    38     #   {"id": 1, "name": "Konata Izumi", "age": 16, 
    39     #    "created_at": "2006/08/01", "awesome": true, 
    40     #    "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"}, 
    41     #              {"id": 2, author_id: 1, "title": "So I was thinking"}]} 
     33    #   # => {"id": 1, "name": "Konata Izumi", "age": 16, 
     34    #         "created_at": "2006/08/01", "awesome": true, 
     35    #         "posts": [{"id": 1, "author_id": 1, "title": "Welcome to the weblog"}, 
     36    #                   {"id": 2, author_id: 1, "title": "So I was thinking"}]} 
    4237    # 
    4338    # 2nd level and higher order associations work as well: 
    …… 
    4742    #                                                :only => :body } }, 
    4843    #                                  :only => :title } }) 
    49     # 
    50     #   {"id": 1, "name": "Konata Izumi", "age": 16, 
    51     #    "created_at": "2006/08/01", "awesome": true, 
    52     #    "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}], 
    53     #               "title": "Welcome to the weblog"}, 
    54     #              {"comments": [{"body": "Don't think too hard"}], 
    55     #               "title": "So I was thinking"}]} 
     44    #   # => {"id": 1, "name": "Konata Izumi", "age": 16, 
     45    #         "created_at": "2006/08/01", "awesome": true, 
     46    #         "posts": [{"comments": [{"body": "1st post!"}, {"body": "Second!"}], 
     47    #                    "title": "Welcome to the weblog"}, 
     48    #                   {"comments": [{"body": "Don't think too hard"}], 
     49    #                    "title": "So I was thinking"}]} 
    5650    def to_json(options = {}) 
    5751      JsonSerializer.new(self, options).to_s 

  • trunk/activerecord/lib/active_record/serializers/xml_serializer.rb

    r8258 r9093  
    11module ActiveRecord #:nodoc: 
    22  module Serialization 
    3     # Builds an XML document to represent the model.   Some configuration is 
    4     # available through +options+, however more complicated cases should 
    5     # override ActiveRecord's to_xml. 
     3    # Builds an XML document to represent the model. Some configuration is 
     4    # available through +options+. However more complicated cases should 
     5    # override ActiveRecord's to_xml method. 
    66    # 
    77    # By default the generated XML document will include the processing 
    8     # instruction and all object's attributes. For example: 
     8    # instruction and all the object's attributes. For example: 
    99    # 
    1010    #   <?xml version="1.0" encoding="UTF-8"?> 
    …… 
    2424    # 
    2525    # This behavior can be controlled with :only, :except, 
    26     # :skip_instruct, :skip_types and :dasherize. The :only and 
     26    # :skip_instruct, :skip_types and :dasherize. The :only and 
    2727    # :except options are the same as for the #attributes method. 
    2828    # The default is to dasherize all column names, to disable this, 
    29     # set :dasherize to false. To not have the column type included 
     29    # set :dasherize to false. To not have the column type included 
    3030    # in the XML output, set :skip_types to true. 
    3131    # 
    …… 
    6969    #   </firm> 
    7070    # 
     71    # To include deeper levels of associations pass a hash like this: 
     72    # 
     73    #   firm.to_xml :include => {:account => {}, :clients => {:include => :address}} 
     74    #   <?xml version="1.0" encoding="UTF-8"?> 
     75    #   <firm> 
     76    #     <id type="integer">1</id> 
     77    #     <rating type="integer">1</rating> 
     78    #     <name>37signals</name> 
     79    #     <clients type="array"> 
     80    #       <client> 
     81    #         <rating type="integer">1</rating> 
     82    #         <name>Summit</name> 
     83    #         <address> 
     84    #           ... 
     85    #         </address> 
     86    #       </client> 
     87    #       <client> 
     88    #         <rating type="integer">1</rating> 
     89    #         <name>Microsoft</name> 
     90    #         <address> 
     91    #           ... 
     92    #         </address> 
     93    #       </client> 
     94    #     </clients> 
     95    #     <account> 
     96    #       <id type="integer">1</id> 
     97    #       <credit-limit type="integer">50</credit-limit> 
     98    #     </account> 
     99    #   </firm> 
     100    # 
    71101    # To include any methods on the object(s) being called use :methods 
    72102    # 
    …… 
    79109    #   </firm> 
    80110    # 
    81     # To call any Proc's on the object(s) use :procs.  The Proc's 
     111    # To call any Procs on the object(s) use :procs. The Procs 
    82112    # are passed a modified version of the options hash that was 
    83113    # given to #to_xml. 
    …… 
    91121    #   </firm> 
    92122    # 
    93     # Alternatively, you can also just yield the builder object as part of the to_xml call: 
     123    # Alternatively, you can yield the builder object as part of the to_xml call: 
    94124    # 
    95125    #   firm.to_xml do |xml| 
    …… 
    109139    # 
    110140    # You can override the to_xml method in your ActiveRecord::Base 
    111     # subclasses if you need to. The general form of doing this is 
     141    # subclasses if you need to. The general form of doing this is: 
    112142    # 
    113143    #   class IHaveMyOwnXML < ActiveRecord::Base 
    …… 
    156186    end 
    157187 
    158  
    159     # To replicate the behavior in ActiveRecord#attributes, 
    160     # :except takes precedence over :only.  If :only is not set 
    161     # for a N level model but is set for the N+1 level models, 
    162     # then because :except is set to a default value, the second 
    163     # level model can have both :except and :only set.  So if 
    164     # :only is set, always delete :except. 
    165188    def serializable_attributes 
    166189      serializable_attribute_names.collect { |name| Attribute.new(name, @record) } 
    …… 
    252275      # There is a significant speed improvement if the value 
    253276      # does not need to be escaped, as #tag! escapes all values 
    254       # to ensure that valid XML is generated. For known binary 
     277      # to ensure that valid XML is generated. For known binary 
    255278      # values, it is at least an order of magnitude faster to 
    256279      # Base64 encode binary values and directly put them in the 

  • trunk/activerecord/lib/active_record/timestamp.rb

    r8217 r9093  
    66  #   <tt>ActiveRecord::Base.record_timestamps = false</tt> 
    77  # 
    8   # Timestamps are in the local timezone by default but can use UTC by setting 
     8  # Timestamps are in the local timezone by default but you can use UTC by setting 
    99  #   <tt>ActiveRecord::Base.default_timezone = :utc</tt> 
    1010  module Timestamp 

  • trunk/activeresource/CHANGELOG

    r8827 r9093  
    11*SVN* 
     2 
     3* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert] 
    24 
    35* Use HEAD instead of GET in exists? [bscofield] 

  • trunk/activesupport/CHANGELOG

    r9081 r9093  
    11*SVN* 
     2 
     3* Improve documentation. [Radar, Jan De Poorter, chuyeow, xaviershay, danger, miloops, Xavier Noria,  Sunny Ripert] 
    24 
    35* Ensure that TimeWithZone#to_yaml works when passed a YAML::Emitter.  [rick] 

  • trunk/activesupport/lib/active_support/basic_object.rb

    r8523 r9093  
    1 # Ruby 1.9 introduces BasicObject which differs slighly from Builder's BlankSlate 
    2 # that had been used so far ActiveSupport::BasicObject provides a barebones object with 
    3 # the same method on both versions. 
     1# A base class with no predefined methods that tries to behave like Builder's 
     2# BlankSlate in Ruby 1.9. In Ruby pre-1.9, this is actually the 
     3# Builder::BlankSlate class. 
     4# 
     5# Ruby 1.9 introduces BasicObject which differs slightly from Builder's 
     6# BlankSlate that has been used so far. ActiveSupport::BasicObject provides a 
     7# barebones base class that emulates Builder::BlankSlate while still relying on 
     8# Ruby 1.9's BasicObject in Ruby 1.9. 
    49module ActiveSupport 
    510  if RUBY_VERSION >= '1.9' 

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

    r8384 r9093  
    2525        end 
    2626 
    27         # Calls to_param on all its elements and joins the result with slashes. This is used by url_for in Action Pack.  
     27        # Calls <tt>to_param</tt> on all its elements and joins the result with 
     28        # slashes. This is used by <tt>url_for</tt> in Action Pack.  
    2829        def to_param 
    2930          map(&:to_param).join '/' 
    …… 
    3334        # param name. 
    3435        # 
    35         # ==== Example: 
    36         #   ['Rails', 'coding'].to_query('hobbies') => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" 
     36        # Example: 
     37        # 
     38        #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" 
    3739        def to_query(key) 
    3840          collect { |value| value.to_query("#{key}[]") } * '&' 
    …… 
    4648        end 
    4749 
     50        # Converts a collection of elements into a formatted string by calling 
     51        # <tt>to_s</tt> on all elements and joining them: 
     52        # 
     53        #   Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post" 
     54        # 
     55        # Adding in the <tt>:db</tt> argument as the format yields a prettier 
     56        # output: 
     57        # 
     58        #   Blog.find(:all).to_formatted_s(:db) # => "First Post,Second Post,Third Post" 
    4859        def to_formatted_s(format = :default) 
    4960          case format 
    …… 
    5970        end 
    6071 
     72        # Returns a string that represents this array in XML by sending 
     73        # <tt>to_xml</tt> to each element. 
     74        # 
     75        # All elements are expected to respond to <tt>to_xml</tt>, if any of 
     76        # them does not an exception is raised. 
     77        # 
     78        # The root node reflects the class name of the first element in plural 
     79        # if all elements belong to the same type and that's not <tt>Hash</tt>. 
     80        # Otherwise the root element is "records". 
     81        # 
     82        # Root children have as node name the one of the root singularized. 
     83        # 
     84        # Example: 
     85        # 
     86        #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml 
     87        # 
     88        #   <?xml version="1.0" encoding="UTF-8"?> 
     89        #   <records type="array"> 
     90        #     <record> 
     91        #       <bar type="integer">2</bar> 
     92        #       <foo type="integer">1</foo> 
     93        #     </record> 
     94        #     <record> 
     95        #       <baz type="integer">3</baz> 
     96        #     </record> 
     97        #   </records> 
     98        # 
     99        # The +options+ hash is passed downwards: 
     100        # 
     101        #   [Message.find(:first)].to_xml(:skip_types => true) 
     102        # 
     103        #   <?xml version="1.0" encoding="UTF-8"?> 
     104        #   <messages> 
     105        #     <message> 
     106        #       <created-at>2008-03-07T09:58:18+01:00</created-at> 
     107        #       <id>1</id> 
     108        #       <name>1</name> 
     109        #       <updated-at>2008-03-07T09:58:18+01:00</updated-at> 
     110        #       <user-id>1</user-id> 
     111        #     </message> 
     112        #   </messages> 
     113        # 
    61114        def to_xml(options = {}) 
    62115          raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml } 

  • trunk/activesupport/lib/active_support/core_ext/array/grouping.rb

    r8161 r9093  
    99        # <tt>false</tt>. 
    1010        #  
    11         # E.g. 
     11        # Examples: 
    1212        #  
    1313        #   %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g} 
    …… 
    4646        # or the result of an optional block. 
    4747        # 
    48         # ex. 
     48        # Examples: 
    4949        # 
    5050        #   [1, 2, 3, 4, 5].split(3)                # => [[1, 2], [4, 5]] 

  • trunk/activesupport/lib/active_support/core_ext/blank.rb

    r8137 r9093  
    11class Object 
    2   # An object is blank if it's nil, empty, or a whitespace string. 
     2  # An object is blank if it's false, empty, or a whitespace string. 
    33  # For example, "", "   ", nil, [], and {} are blank. 
    44  # 

  • trunk/activesupport/lib/active_support/core_ext/class/removal.rb

    r7474 r9093  
    11class Class #:nodoc: 
     2   
     3  # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves. 
     4  # >> Integer.remove_subclasses 
     5  # => [Bignum, Fixnum] 
     6  # >> Fixnum 
     7  # NameError: uninitialized constant Fixnum 
    28  def remove_subclasses 
    39    Object.remove_subclasses_of(self) 
    410  end 
    511 
     12  # Returns a list of classes that inherit from this class in an array. 
     13  # Example: Integer.subclasses => ["Bignum", "Fixnum"] 
    614  def subclasses 
    715    Object.subclasses_of(self).map { |o| o.to_s } 
    816  end 
    917 
     18  # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them. 
    1019  def remove_class(*klasses) 
    1120    klasses.flatten.each do |klass| 

  • trunk/activesupport/lib/active_support/core_ext/date/calculations.rb

    r8934 r9093  
    1717 
    1818        module ClassMethods 
     19          # Finds yesterday's date, in the format similar to: Mon, 17 Mar 2008 
    1920          def yesterday 
    2021            ::Date.today.yesterday 
    2122          end 
    2223           
     24          # Finds tommorrow's date, in the format similar to: Tue, 18 Mar 2008 
    2325          def tomorrow 
    2426            ::Date.today.tomorrow 

  • trunk/activesupport/lib/active_support/core_ext/enumerable.rb

    r8700 r9093  
    33  # for example, for grouping records by date. 
    44  # 
    5   # e.g.  
     5  # Example: 
    66  # 
    77  #   latest_transcripts.group_by(&:day).each do |day, transcripts|  
    …… 
    2424  # Calculates a sum from the elements. Examples: 
    2525  # 
    26   #  payments.sum { |p| p.price * p.tax_rate } 
    27   #  payments.sum(&:price) 
     26  #  payments.sum { |p| p.price * p.tax_rate } 
     27  #  payments.sum(&:price) 
    2828  # 
    29   # This is instead of payments.inject { |sum, p| sum + p.price } 
     29  # This is instead of 
     30  # 
     31  #   payments.inject { |sum, p| sum + p.price } 
    3032  # 
    3133  # Also calculates sums without the use of a block: 
     34  # 
    3235  #   [5, 15, 10].sum # => 30 
    3336  # 
    …… 
    3538  # However, you can override this default: 
    3639  # 
    37   # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) 
     40  #   [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) 
    3841  # 
    3942  def sum(identity = 0, &block) 

  • trunk/activesupport/lib/active_support/core_ext/file.rb

    r6262 r9093  
    44# want other processes or threads to see half-written files. 
    55# 
    6 #  File.atomic_write("important.file") do |file| 
    7 #    file.write("hello") 
    8 #  end 
     6#  File.atomic_write("important.file") do |file| 
     7#    file.write("hello") 
     8#  end 
    99# 
    1010# If your temp directory is not on the same filesystem as the file you're  
    1111# trying to write, you can provide a different temporary directory. 
    1212#  
    13 # File.atomic_write("/data/something.imporant", "/data/tmp") do |f| 
    14 #   file.write("hello") 
    15 # end 
     13#   File.atomic_write("/data/something.important", "/data/tmp") do |f| 
     14#     file.write("hello") 
     15#   end 
    1616def File.atomic_write(file_name, temp_dir = Dir.tmpdir) 
    1717  temp_file = Tempfile.new(File.basename(file_name), temp_dir) 

  • trunk/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb

    r8332 r9093  
    11# This class has dubious semantics and we only have it so that 
    22# people can write params[:key] instead of params['key'] 
     3# and they get the same value for both keys. 
    34 
    45class HashWithIndifferentAccess < Hash 
    …… 
    2324  alias_method :regular_update, :update unless method_defined?(:regular_update) 
    2425 
     26  # 
     27  # Assigns a new value to the hash. 
     28  # 
     29  # Example: 
     30  # 
     31  #   hash = HashWithIndifferentAccess.new 
     32  #   hash[:key] = "value" 
     33  # 
    2534  def []=(key, value) 
    2635    regular_writer(convert_key(key), convert_value(value)) 
    2736  end 
    2837 
     38  #  
     39  # Updates the instantized hash with values from the second. 
     40  #  
     41  # Example: 
     42  #  
     43  #   >> hash_1 = HashWithIndifferentAccess.new 
     44  #   => {} 
     45  #  
     46  #   >> hash_1[:key] = "value" 
     47  #   => "value" 
     48  #  
     49  #   >> hash_2 = HashWithIndifferentAccess.new 
     50  #   => {} 
     51  #  
     52  #   >> hash_2[:key] = "New Value!" 
     53  #   => "New Value!" 
     54  #  
     55  #   >> hash_1.update(hash_2) 
     56  #   => {"key"=>"New Value!"} 
     57  #  
    2958  def update(other_hash) 
    3059    other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) } 
    …… 
    3463  alias_method :merge!, :update 
    3564 
     65  # Checks the hash for a key matching the argument passed in 
    3666  def key?(key) 
    3767    super(convert_key(key)) 
    …… 
    4272  alias_method :member?, :key? 
    4373 
     74  # Fetches the value for the specified key, same as doing hash[key] 
    4475  def fetch(key, *extras) 
    4576    super(convert_key(key), *extras) 
    4677  end 
    4778 
     79  # Returns an array of the values at the specified indicies.  
    4880  def values_at(*indices) 
    4981    indices.collect {|key| self[convert_key(key)]} 
    5082  end 
    5183 
     84  # Returns an exact copy of the hash. 
    5285  def dup 
    5386    HashWithIndifferentAccess.new(self) 
    5487  end 
    5588 
     89  # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash 
     90  # Does not overwrite the existing hash. 
    5691  def merge(hash) 
    5792    self.dup.update(hash) 
    5893  end 
    5994 
     95  # Removes a specified key from the hash. 
    6096  def delete(key) 
    6197    super(convert_key(key)) 

  • trunk/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb

    r5725 r9093  
    1111      # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set. 
    1212      module ReverseMerge 
     13        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. 
    1314        def reverse_merge(other_hash) 
    1415          other_hash.merge(self) 
    1516        end 
    1617 
     18        # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. 
     19        # Modifies the receiver in place. 
    1720        def reverse_merge!(other_hash) 
    1821          replace(reverse_merge(other_hash)) 

  • trunk/activesupport/lib/active_support/core_ext/integer/even_odd.rb

    r8397 r9093  
    22  module CoreExtensions #:nodoc: 
    33    module Integer #:nodoc: 
    4       # For checking if a fixnum is even or odd.  
    5       # * 1.even? # => false 
    6       # * 1.odd?  # => true 
    7       # * 2.even? # => true 
    8       # * 2.odd? # => false 
     4      # For checking if a fixnum is even or odd. 
     5      # 
     6      # Examples: 
     7      # 
     8      #   1.even? # => false 
     9      #   1.odd?  # => true 
     10      #   2.even? # => true 
     11      #   2.odd? # => false 
    912      module EvenOdd 
    1013        def multiple_of?(number) 

  • trunk/activesupport/lib/active_support/core_ext/integer/inflections.rb

    r5924 r9093  
    88        # position in an ordered sequence such as 1st, 2nd, 3rd, 4th. 
    99        # 
    10         # Examples 
     10        # Examples: 
     11        # 
    1112        #   1.ordinalize    # => "1st" 
    1213        #   2.ordinalize    # => "2nd" 

  • trunk/activesupport/lib/active_support/core_ext/kernel/reporting.rb

    r3761 r9093  
    4343  end 
    4444 
     45  # Blocks and ignores any exception passed as argument if raised within the block. 
     46  # 
     47  #   suppress(ZeroDivisionError) do 
     48  #     1/0 
     49  #     puts "This code is NOT reached" 
     50  #   end 
     51  # 
     52  #   puts "This code gets executed and nothing related to ZeroDivisionError was seen" 
    4553  def suppress(*exception_classes) 
    4654    begin yield 

  • trunk/activesupport/lib/active_support/core_ext/module/attr_internal.rb

    r4839 r9093  
    1414  end 
    1515 
    16   # Declare attributes backed by 'internal' instance variables names. 
     16  # Declare an attribute reader and writer backed by an internally-named instance 
     17  # variable. 
    1718  def attr_internal_accessor(*attrs) 
    1819    attr_internal_reader(*attrs) 

  • trunk/activesupport/lib/active_support/core_ext/module/inclusion.rb

    r3519 r9093  
    11class Module 
     2  # Returns the classes in the current ObjectSpace where this module has been 
     3  # mixed in according to Module#included_modules. 
     4  # 
     5  #   module M 
     6  #   end 
     7  #    
     8  #   module N 
     9  #     include M 
     10  #   end 
     11  #    
     12  #   class C 
     13  #     include M 
     14  #   end 
     15  #    
     16  #   class D < C 
     17  #   end 
     18  # 
     19  #   p M.included_in_classes # => [C, D] 
     20  # 
    221  def included_in_classes 
    322    classes = [] 

  • trunk/activesupport/lib/active_support/core_ext/module/introspection.rb

    r8555 r9093  
    11class Module 
    2   # Return the module which contains this one; if this is a root module, such as 
    3   # +::MyModule+, then Object is returned. 
     2  # Returns the module which contains this one according to its name. 
     3  # 
     4  #   module M 
     5  #     module N 
     6  #     end 
     7  #   end 
     8  #   X = M::N 
     9  #    
     10  #   p M::N.parent # => M 
     11  #   p X.parent