diff options
19 files changed, 222 insertions, 75 deletions
diff --git a/actionpack/lib/action_controller/metal/http_authentication.rb b/actionpack/lib/action_controller/metal/http_authentication.rb index 87225d74c1..57bb0e2a32 100644 --- a/actionpack/lib/action_controller/metal/http_authentication.rb +++ b/actionpack/lib/action_controller/metal/http_authentication.rb @@ -2,8 +2,9 @@ require 'base64' require 'active_support/core_ext/object/blank' module ActionController + # Makes it dead easy to do HTTP Basic, Digest and Token authentication. module HttpAuthentication - # Makes it dead easy to do HTTP \Basic and \Digest authentication. + # Makes it dead easy to do HTTP \Basic authentication. # # === Simple \Basic example # @@ -60,47 +61,6 @@ module ActionController # # assert_equal 200, status # end - # - # === Simple \Digest example - # - # require 'digest/md5' - # class PostsController < ApplicationController - # REALM = "SuperSecret" - # USERS = {"dhh" => "secret", #plain text password - # "dap" => Digest::MD5.hexdigest(["dap",REALM,"secret"].join(":"))} #ha1 digest password - # - # before_filter :authenticate, :except => [:index] - # - # def index - # render :text => "Everyone can see me!" - # end - # - # def edit - # render :text => "I'm only accessible if you know the password" - # end - # - # private - # def authenticate - # authenticate_or_request_with_http_digest(REALM) do |username| - # USERS[username] - # end - # end - # end - # - # === Notes - # - # The +authenticate_or_request_with_http_digest+ block must return the user's password - # or the ha1 digest hash so the framework can appropriately hash to check the user's - # credentials. Returning +nil+ will cause authentication to fail. - # - # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If - # the password file or database is compromised, the attacker would be able to use the ha1 hash to - # authenticate as the user at this +realm+, but would not have the user's password to try using at - # other sites. - # - # In rare instances, web servers or front proxies strip authorization headers before - # they reach your application. You can debug this situation by logging all environment - # variables, and check for HTTP_AUTHORIZATION, amongst others. module Basic extend self @@ -155,6 +115,48 @@ module ActionController end end + # Makes it dead easy to do HTTP \Digest authentication. + # + # === Simple \Digest example + # + # require 'digest/md5' + # class PostsController < ApplicationController + # REALM = "SuperSecret" + # USERS = {"dhh" => "secret", #plain text password + # "dap" => Digest::MD5.hexdigest(["dap",REALM,"secret"].join(":"))} #ha1 digest password + # + # before_filter :authenticate, :except => [:index] + # + # def index + # render :text => "Everyone can see me!" + # end + # + # def edit + # render :text => "I'm only accessible if you know the password" + # end + # + # private + # def authenticate + # authenticate_or_request_with_http_digest(REALM) do |username| + # USERS[username] + # end + # end + # end + # + # === Notes + # + # The +authenticate_or_request_with_http_digest+ block must return the user's password + # or the ha1 digest hash so the framework can appropriately hash to check the user's + # credentials. Returning +nil+ will cause authentication to fail. + # + # Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If + # the password file or database is compromised, the attacker would be able to use the ha1 hash to + # authenticate as the user at this +realm+, but would not have the user's password to try using at + # other sites. + # + # In rare instances, web servers or front proxies strip authorization headers before + # they reach your application. You can debug this situation by logging all environment + # variables, and check for HTTP_AUTHORIZATION, amongst others. module Digest extend self diff --git a/activerecord/lib/active_record/aggregations.rb b/activerecord/lib/active_record/aggregations.rb index a4db627535..c7a329d74d 100644 --- a/activerecord/lib/active_record/aggregations.rb +++ b/activerecord/lib/active_record/aggregations.rb @@ -71,7 +71,7 @@ module ActiveRecord # Now it's possible to access attributes from the database through the value objects instead. If # you choose to name the composition the same as the attribute's name, it will be the only way to # access that attribute. That's the case with our +balance+ attribute. You interact with the value - # objects just like you would any other attribute, though: + # objects just like you would with any other attribute: # # customer.balance = Money.new(20) # sets the Money value object and the attribute # customer.balance # => Money value object diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb index ff2b0b5576..f5349b0bea 100644 --- a/activerecord/lib/active_record/core.rb +++ b/activerecord/lib/active_record/core.rb @@ -204,13 +204,35 @@ module ActiveRecord self end - + + ## + # :method: clone + # Identical to Ruby's clone method. This is a "shallow" copy. Be warned that your attributes are not copied. + # That means that modifying attributes of the clone will modify the original, since they will both point to the + # same attributes hash. If you need a copy of your attributes hash, please use the #dup method. + # + # user = User.first + # new_user = user.clone + # user.name # => "Bob" + # new_user.name = "Joe" + # user.name # => "Joe" + # + # user.object_id == new_user.object_id # => false + # user.name.object_id == new_user.name.object_id # => true + # + # user.name.object_id == user.dup.name.object_id # => false + + ## + # :method: dup # Duped objects have no id assigned and are treated as new records. Note # that this is a "shallow" copy as it copies the object's attributes # only, not its associations. The extent of a "deep" copy is application # specific and is therefore left to the application to implement according # to its need. # The dup method does not preserve the timestamps (created|updated)_(at|on). + + ## + # :nodoc: def initialize_dup(other) cloned_attributes = other.clone_attributes(:read_attribute_before_type_cast) self.class.initialize_attributes(cloned_attributes) diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb index 32a1dae6bc..95a2ddcc11 100644 --- a/activerecord/lib/active_record/nested_attributes.rb +++ b/activerecord/lib/active_record/nested_attributes.rb @@ -19,10 +19,10 @@ module ActiveRecord # = Active Record Nested Attributes # # Nested attributes allow you to save attributes on associated records - # through the parent. By default nested attribute updating is turned off, - # you can enable it using the accepts_nested_attributes_for class method. - # When you enable nested attributes an attribute writer is defined on - # the model. + # through the parent. By default nested attribute updating is turned off + # and you can enable it using the accepts_nested_attributes_for class + # method. When you enable nested attributes an attribute writer is + # defined on the model. # # The attribute writer is named after the association, which means that # in the following example, two new methods are added to your model: diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb index 3c7dbb369c..c6c7e2821b 100644 --- a/activesupport/lib/active_support/callbacks.rb +++ b/activesupport/lib/active_support/callbacks.rb @@ -54,7 +54,6 @@ module ActiveSupport # saving... # - save # saved - # module Callbacks extend Concern @@ -73,7 +72,6 @@ module ActiveSupport # run_callbacks :save do # save # end - # def run_callbacks(kind, &block) runner_name = self.class.__define_callbacks(kind, self) send(runner_name, &block) @@ -198,7 +196,6 @@ module ActiveSupport # yield self # end # end - # def define_conditional_callback name = "_conditional_callback_#{@kind}_#{next_id}" @klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1 @@ -252,7 +249,6 @@ module ActiveSupport # Objects:: # a method is created that calls the before_foo method # on the object. - # def _compile_filter(filter) method_name = "_callback_#{@kind}_#{next_id}" case filter @@ -404,7 +400,6 @@ module ActiveSupport # will be called only when it returns a false value. # * <tt>:prepend</tt> - If true, the callback will be prepended to the existing # chain rather than appended. - # def set_callback(name, *filter_list, &block) mapped = nil @@ -429,7 +424,6 @@ module ActiveSupport # class Writer < Person # skip_callback :validate, :before, :check_membership, :if => lambda { self.age > 18 } # end - # def skip_callback(name, *filter_list, &block) __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options| filters.each do |filter| @@ -448,7 +442,6 @@ module ActiveSupport end # Remove all set callbacks for the given event. - # def reset_callbacks(symbol) callbacks = send("_#{symbol}_callbacks") @@ -529,7 +522,6 @@ module ActiveSupport # define_callbacks :save, :scope => [:name] # # would call <tt>Audit#save</tt>. - # def define_callbacks(*callbacks) config = callbacks.last.is_a?(Hash) ? callbacks.pop : {} callbacks.each do |callback| diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb index 4834eca8b1..9ea93d7226 100644 --- a/activesupport/lib/active_support/core_ext/array/wrap.rb +++ b/activesupport/lib/active_support/core_ext/array/wrap.rb @@ -25,9 +25,6 @@ class Array # Array(:foo => :bar) # => [[:foo, :bar]] # Array.wrap(:foo => :bar) # => [{:foo => :bar}] # - # Array("foo\nbar") # => ["foo\n", "bar"], in Ruby 1.8 - # Array.wrap("foo\nbar") # => ["foo\nbar"] - # # There's also a related idiom that uses the splat operator: # # [*object] diff --git a/activesupport/lib/active_support/core_ext/integer/multiple.rb b/activesupport/lib/active_support/core_ext/integer/multiple.rb index 8dff217ddc..7c6c2f1ca7 100644 --- a/activesupport/lib/active_support/core_ext/integer/multiple.rb +++ b/activesupport/lib/active_support/core_ext/integer/multiple.rb @@ -1,5 +1,9 @@ class Integer # Check whether the integer is evenly divisible by the argument. + # + # 0.multiple_of?(0) #=> true + # 6.multiple_of?(5) #=> false + # 10.multiple_of?(2) #=> true def multiple_of?(number) number != 0 ? self % number == 0 : zero? end diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb index 23aaee9c43..5c32a2453d 100644 --- a/activesupport/lib/active_support/core_ext/string/access.rb +++ b/activesupport/lib/active_support/core_ext/string/access.rb @@ -1,18 +1,79 @@ require 'active_support/multibyte' class String + # If you pass a single Fixnum, returns a substring of one character at that + # position. The first character of the string is at position 0, the next at + # position 1, and so on. If a range is supplied, a substring containing + # characters at offsets given by the range is returned. In both cases, if an + # offset is negative, it is counted from the end of the string. Returns nil + # if the initial offset falls outside the string. Returns an empty string if + # the beginning of the range is greater than the end of the string. + # + # str = "hello" + # str.at(0) #=> "h" + # str.at(1..3) #=> "ell" + # str.at(-2) #=> "l" + # str.at(-2..-1) #=> "lo" + # str.at(5) #=> nil + # str.at(5..-1) #=> "" + # + # If a Regexp is given, the matching portion of the string is returned. + # If a String is given, that given string is returned if it occurs in + # the string. In both cases, nil is returned if there is no match. + # + # str = "hello" + # str.at(/lo/) #=> "lo" + # str.at(/ol/) #=> nil + # str.at("lo") #=> "lo" + # str.at("ol") #=> nil def at(position) self[position] end + # Returns a substring from the given position to the end of the string. + # If the position is negative, it is counted from the end of the string. + # + # str = "hello" + # str.from(0) #=> "hello" + # str.from(3) #=> "lo" + # str.from(-2) #=> "lo" + # + # You can mix it with +to+ method and do fun things like: + # + # str = "hello" + # str.from(0).to(-1) #=> "hello" + # str.from(1).to(-2) #=> "ell" def from(position) self[position..-1] end + # Returns a substring from the beginning of the string to the given position. + # If the position is negative, it is counted from the end of the string. + # + # str = "hello" + # str.to(0) #=> "h" + # str.to(3) #=> "hell" + # str.to(-2) #=> "hell" + # + # You can mix it with +from+ method and do fun things like: + # + # str = "hello" + # str.from(0).to(-1) #=> "hello" + # str.from(1).to(-2) #=> "ell" def to(position) self[0..position] end + # Returns the first character. If a limit is supplied, returns a substring + # from the beginning of the string until it reaches the limit value. If the + # given limit is greater than or equal to the string length, returns self. + # + # str = "hello" + # str.first #=> "h" + # str.first(1) #=> "h" + # str.first(2) #=> "he" + # str.first(0) #=> "" + # str.first(6) #=> "hello" def first(limit = 1) if limit == 0 '' @@ -23,6 +84,16 @@ class String end end + # Returns the last character of the string. If a limit is supplied, returns a substring + # from the end of the string until it reaches the limit value (counting backwards). If + # the given limit is greater than or equal to the string length, returns self. + # + # str = "hello" + # str.last #=> "o" + # str.last(1) #=> "o" + # str.last(2) #=> "lo" + # str.last(0) #=> "" + # str.last(6) #=> "hello" def last(limit = 1) if limit == 0 '' diff --git a/activesupport/lib/active_support/core_ext/string/conversions.rb b/activesupport/lib/active_support/core_ext/string/conversions.rb index 9084bbee32..022b376aec 100644 --- a/activesupport/lib/active_support/core_ext/string/conversions.rb +++ b/activesupport/lib/active_support/core_ext/string/conversions.rb @@ -15,6 +15,12 @@ class String end end + # Converts a string to a Date value. + # + # "1-1-2012".to_date #=> Sun, 01 Jan 2012 + # "01/01/2012".to_date #=> Sun, 01 Jan 2012 + # "2012-12-13".to_date #=> Thu, 13 Dec 2012 + # "12/13/2012".to_date #=> ArgumentError: invalid date def to_date unless blank? date_values = ::Date._parse(self, false).values_at(:year, :mon, :mday) @@ -23,6 +29,12 @@ class String end end + # Converts a string to a DateTime value. + # + # "1-1-2012".to_datetime #=> Sun, 01 Jan 2012 00:00:00 +0000 + # "01/01/2012 23:59:59".to_datetime #=> Sun, 01 Jan 2012 23:59:59 +0000 + # "2012-12-13 12:50".to_datetime #=> Thu, 13 Dec 2012 12:50:00 +0000 + # "12/13/2012".to_datetime #=> ArgumentError: invalid date def to_datetime unless blank? date_values = ::Date._parse(self, false). diff --git a/activesupport/lib/active_support/core_ext/string/exclude.rb b/activesupport/lib/active_support/core_ext/string/exclude.rb index 5e184ec1b3..114bcb87f0 100644 --- a/activesupport/lib/active_support/core_ext/string/exclude.rb +++ b/activesupport/lib/active_support/core_ext/string/exclude.rb @@ -1,5 +1,10 @@ class String - # The inverse of <tt>String#include?</tt>. Returns true if the string does not include the other string. + # The inverse of <tt>String#include?</tt>. Returns true if the string + # does not include the other string. + # + # "hello".exclude? "lo" #=> false + # "hello".exclude? "ol" #=> true + # "hello".exclude? ?h #=> false def exclude?(string) !include?(string) end diff --git a/activesupport/lib/active_support/core_ext/string/filters.rb b/activesupport/lib/active_support/core_ext/string/filters.rb index 32a37296d5..2478f42290 100644 --- a/activesupport/lib/active_support/core_ext/string/filters.rb +++ b/activesupport/lib/active_support/core_ext/string/filters.rb @@ -5,7 +5,6 @@ class String # the string, and then changing remaining consecutive whitespace # groups into one space each. # - # Examples: # %{ Multi-line # string }.squish # => "Multi-line string" # " foo bar \n \t boo".squish # => "foo bar boo" diff --git a/activesupport/lib/active_support/core_ext/string/inflections.rb b/activesupport/lib/active_support/core_ext/string/inflections.rb index 049ffe7986..070bfd7af6 100644 --- a/activesupport/lib/active_support/core_ext/string/inflections.rb +++ b/activesupport/lib/active_support/core_ext/string/inflections.rb @@ -13,7 +13,6 @@ class String # the singular form will be returned if <tt>count == 1</tt>. # For any other value of +count+ the plural will be returned. # - # ==== Examples # 'post'.pluralize # => "posts" # 'octopus'.pluralize # => "octopi" # 'sheep'.pluralize # => "sheep" @@ -46,7 +45,6 @@ class String # in the string. It raises a NameError when the name is not in CamelCase # or is not initialized. See ActiveSupport::Inflector.constantize # - # Examples # 'Module'.constantize # => Module # 'Class'.constantize # => Class # 'blargle'.constantize # => NameError: wrong constant name blargle @@ -58,7 +56,6 @@ class String # in the string. It returns nil when the name is not in CamelCase # or is not initialized. See ActiveSupport::Inflector.safe_constantize # - # Examples # 'Module'.safe_constantize # => Module # 'Class'.safe_constantize # => Class # 'blargle'.safe_constantize # => nil @@ -140,8 +137,6 @@ class String # Replaces special characters in a string so that it may be used as part of a 'pretty' URL. # - # ==== Examples - # # class Person # def to_param # "#{id}-#{name.parameterize}" @@ -194,7 +189,6 @@ class String # +separate_class_name_and_id_with_underscore+ sets whether # the method should put '_' between the name and 'id'. # - # Examples # 'Message'.foreign_key # => "message_id" # 'Message'.foreign_key(false) # => "messageid" # 'Admin::Post'.foreign_key # => "post_id" diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb index 215ba87ca9..6bda970e40 100644 --- a/activesupport/lib/active_support/core_ext/string/output_safety.rb +++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb @@ -14,7 +14,6 @@ class ERB # In your ERB templates, use this method to escape any unsafe content. For example: # <%=h @person.name %> # - # ==== Example: # puts html_escape('is a > 0 & a < 10?') # # => is a > 0 & a < 10? def html_escape(s) @@ -37,7 +36,6 @@ class ERB # A utility method for escaping HTML without affecting existing escaped entities. # - # ==== Examples # html_escape_once('1 < 2 & 3') # # => "1 < 2 & 3" # diff --git a/activesupport/test/core_ext/hash_ext_test.rb b/activesupport/test/core_ext/hash_ext_test.rb index afca636777..8239054117 100644 --- a/activesupport/test/core_ext/hash_ext_test.rb +++ b/activesupport/test/core_ext/hash_ext_test.rb @@ -491,11 +491,11 @@ class HashExtTest < ActiveSupport::TestCase original = { :a => 'x', :b => 'y', :c => 10 } expected = { :a => 'x', :b => 'y' } - # Should return a new hash with only the given keys. + # Should return a new hash without the given keys. assert_equal expected, original.except(:c) assert_not_equal expected, original - # Should replace the hash with only the given keys. + # Should replace the hash without the given keys. assert_equal expected, original.except!(:c) assert_equal expected, original end diff --git a/guides/source/caching_with_rails.textile b/guides/source/caching_with_rails.textile index e455b504ce..34a100cd3a 100644 --- a/guides/source/caching_with_rails.textile +++ b/guides/source/caching_with_rails.textile @@ -229,6 +229,42 @@ class ProductsController < ActionController end </ruby> +Sometimes it is necessary to disambiguate the controller when you call +expire_action+, such as when there are two identically named controllers in separate namespaces: + +<ruby> +class ProductsController < ActionController + caches_action :index + + def index + @products = Product.all + end +end + +module Admin + class ProductsController < ActionController + cache_sweeper :product_sweeper + + def new + @product = Product.new + end + + def create + @product = Product.create(params[:product]) + end + end +end + +class ProductSweeper < ActionController::Caching::Sweeper + observe Product + + def after_create(product) + expire_action(:controller => '/products', :action => 'index') + end +end +</ruby> + +Note the use of '/products' here rather than 'products'. If you wanted to expire an action cache for the +Admin::ProductsController+, you would use 'admin/products' instead. + h4. SQL Caching Query caching is a Rails feature that caches the result set returned by each query so that if Rails encounters the same query again for that request, it will use the cached result set as opposed to running the query against the database again. diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index c4e54348d4..b2c9300034 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -448,9 +448,9 @@ There are a few configuration options available in Active Support: * +config.active_support.bare+ enables or disables the loading of +active_support/all+ when booting Rails. Defaults to +nil+, which means +active_support/all+ is loaded. -* +config.active_support.escape_html_entities_in_json+ enables or disables the escaping of HTML entities in JSON serialization. Defaults to +true+. +* +config.active_support.escape_html_entities_in_json+ enables or disables the escaping of HTML entities in JSON serialization. Defaults to +false+. -* +config.active_support.use_standard_json_time_format+ enables or disables serializing dates to ISO 8601 format. Defaults to +false+. +* +config.active_support.use_standard_json_time_format+ enables or disables serializing dates to ISO 8601 format. Defaults to +true+. * +ActiveSupport::BufferedLogger.silencer+ is set to +false+ to disable the ability to silence logging in a block. The default is +true+. diff --git a/guides/source/engines.textile b/guides/source/engines.textile index 71bcf6b713..880be57fb5 100644 --- a/guides/source/engines.textile +++ b/guides/source/engines.textile @@ -448,6 +448,8 @@ rake db:migrate SCOPE=blorgh VERSION=0 h4. Using a class provided by the application +h5. Using a model provided by the application + When an engine is created, it may want to use specific classes from an application to provide links between the pieces of the engine and the pieces of the application. In the case of the +blorgh+ engine, making posts and comments have authors would make a lot of sense. Usually, an application would have a +User+ class that would provide the objects that would represent the posts' and comments' authors, but there could be a case where the application calls this class something different, such as +Person+. It's because of this reason that the engine should not hardcode the associations to be exactly for a +User+ class, but should allow for some flexibility around what the class is called. @@ -544,6 +546,19 @@ end Now instead of the ugly Ruby object output the author's name will be displayed. +h5. Using a controller provided by the application + +Because Rails controllers generally share code for things like authentication and accessing session variables, by default they inherit from <tt>ApplicationController</tt>. Rails engines, however are scoped to run independently from the main application, so each engine gets a scoped +ApplicationController+. This namespace prevents code collisions, but often engine controllers should access methods in the main application's +ApplicationController+. An easy way to provide this access is to change the engine's scoped +ApplicationController+ to inherit from the main application's +ApplicationController+. For our Blorgh engine this would be done by changing +app/controllers/blorgh/application_controller.rb+ to look like: + +<ruby> +class Blorgh::ApplicationController < ApplicationController +end +</ruby> + +By default, the engine's controllers inherit from <tt>Blorgh::ApplicationController</tt>. So, after making this change they will have access to the main applications +ApplicationController+ as though they were part of the main application. + +This change does require that the engine is run from a Rails application that has an +ApplicationController+. + h4. Configuring an engine This section covers firstly how you can make the +user_class+ setting of the Blorgh engine configurable, followed by general configuration tips for the engine. diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile index 947abd7ba0..1e9bd1f144 100644 --- a/guides/source/getting_started.textile +++ b/guides/source/getting_started.textile @@ -717,7 +717,7 @@ If you reload try to save a post without a title, Rails will send you back to the form, but that's not very useful. You need to tell the user that something went wrong. To do that, you'll modify -+app/views/posts/index.html.erb+ to check for error messages: ++app/views/posts/new.html.erb+ to check for error messages: <erb> <%= form_for :post, :url => { :action => :create } do |f| %> diff --git a/guides/source/security.textile b/guides/source/security.textile index ac64b82bf6..ac55d60368 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -627,7 +627,7 @@ h4. Whitelists versus Blacklists -- _When sanitizing, protecting or verifying something, whitelists over blacklists._ -A blacklist can be a list of bad e-mail addresses, non-public actions or bad HTML tags. This is opposed to a whitelist which lists the good e-mail addresses, public actions, good HTML tags and so on. Although, sometimes it is not possible to create a whitelist (in a SPAM filter, for example), _(highlight)prefer to use whitelist approaches_: +A blacklist can be a list of bad e-mail addresses, non-public actions or bad HTML tags. This is opposed to a whitelist which lists the good e-mail addresses, public actions, good HTML tags and so on. Although sometimes it is not possible to create a whitelist (in a SPAM filter, for example), _(highlight)prefer to use whitelist approaches_: * Use before_filter :only => [...] instead of :except => [...]. This way you don't forget to turn it off for newly added actions. * Use attr_accessible instead of attr_protected. See the mass-assignment section for details |