Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'master' of git@github.com:lifo/docrails

  • Loading branch information...
commit ea1eb57f56a4143d575ad8a3df54e063d8cea364 2 parents 6664177 + 91871f2
@FotoVerite FotoVerite authored
Showing with 442 additions and 89 deletions.
  1. +87 −3 activerecord/lib/active_record/association_preload.rb
  2. +6 −0 activerecord/lib/active_record/associations.rb
  3. +70 −22 activerecord/lib/active_record/base.rb
  4. +7 −1 activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
  5. +8 −2 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
  6. +64 −4 activerecord/lib/active_record/validations.rb
  7. +13 −2 activesupport/lib/active_support/base64.rb
  8. +9 −9 activesupport/lib/active_support/core_ext/array/access.rb
  9. +3 −0  activesupport/lib/active_support/core_ext/base64/encoding.rb
  10. +36 −16 activesupport/lib/active_support/core_ext/object/misc.rb
  11. BIN  railties/doc/guides/bechmarking and profiling/.DS_Store
  12. BIN  railties/doc/guides/bechmarking and profiling/Examples/.DS_Store
  13. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/Basics.html
  14. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/Examples/graph.html
  15. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/Images/KGraph.png
  16. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/Images/KList.png
  17. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/appendix.txt
  18. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/basics.txt
  19. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/definitions.txt
  20. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/digging_deeper.txt
  21. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/edge rails features.txt
  22. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/gameplan.txt
  23. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/preamble.html
  24. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/preamble.txt
  25. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/rubyprof.txt
  26. 0  railties/doc/guides/{bechmarking and profiling → benchmarking_and_profiling}/statistics.txt
  27. +36 −1 railties/doc/guides/getting_started_with_rails/getting_started_with_rails.txt
  28. +43 −20 railties/doc/guides/index.txt
  29. +59 −9 railties/doc/guides/routing/routing_outside_in.txt
  30. +1 −0  railties/lib/tasks/documentation.rake
View
90 activerecord/lib/active_record/association_preload.rb
@@ -1,14 +1,88 @@
module ActiveRecord
+ # See ActiveRecord::AssociationPreload::ClassMethods for documentation.
module AssociationPreload #:nodoc:
def self.included(base)
base.extend(ClassMethods)
end
+ # Implements the details of eager loading of ActiveRecord associations.
+ # Application developers should not use this module directly.
+ #
+ # ActiveRecord::Base is extended with this module. The source code in
+ # ActiveRecord::Base references methods defined in this module.
+ #
+ # Note that 'eager loading' and 'preloading' are actually the same thing.
+ # However, there are two different eager loading strategies.
+ #
+ # The first one is by using table joins. This was only strategy available
+ # prior to Rails 2.1. Suppose that you have an Author model with columns
+ # 'name' and 'age', and a Book model with columns 'name' and 'sales'. Using
+ # this strategy, ActiveRecord would try to retrieve all data for an author
+ # and all of its books via a single query:
+ #
+ # SELECT * FROM authors
+ # LEFT OUTER JOIN books ON authors.id = books.id
+ # WHERE authors.name = 'Ken Akamatsu'
+ #
+ # However, this could result in many rows that contain redundant data. After
+ # having received the first row, we already have enough data to instantiate
+ # the Author object. In all subsequent rows, only the data for the joined
+ # 'books' table is useful; the joined 'authors' data is just redundant, and
+ # processing this redundant data takes memory and CPU time. The problem
+ # quickly becomes worse and worse as the level of eager loading increases
+ # (i.e. if ActiveRecord is to eager load the associations' assocations as
+ # well).
+ #
+ # The second strategy is to use multiple database queries, one for each
+ # level of association. Since Rails 2.1, this is the default strategy. In
+ # situations where a table join is necessary (e.g. when the +:conditions+
+ # option references an association's column), it will fallback to the table
+ # join strategy.
+ #
+ # See also ActiveRecord::Associations::ClassMethods, which explains eager
+ # loading in a more high-level (application developer-friendly) manner.
module ClassMethods
-
- # Loads the named associations for the activerecord record (or records) given
- # preload_options is passed only one level deep: don't pass to the child associations when associations is a Hash
protected
+
+ # Eager loads the named associations for the given ActiveRecord record(s).
+ #
+ # In this description, 'association name' shall refer to the name passed
+ # to an association creation method. For example, a model that specifies
+ # <tt>belongs_to :author</tt>, <tt>has_many :buyers</tt> has association
+ # names +:author+ and +:buyers+.
+ #
+ # == Parameters
+ # +records+ is an array of ActiveRecord::Base. This array needs not be flat,
+ # i.e. +records+ itself may also contain arrays of records. In any case,
+ # +preload_associations+ will preload the associations all records by
+ # flattening +records+.
+ #
+ # +associations+ specifies one or more associations that you want to
+ # preload. It may be:
+ # - a Symbol or a String which specifies a single association name. For
+ # example, specifiying +:books+ allows this method to preload all books
+ # for an Author.
+ # - an Array which specifies multiple association names. This array
+ # is processed recursively. For example, specifying <tt>[:avatar, :books]</tt>
+ # allows this method to preload an author's avatar as well as all of his
+ # books.
+ # - a Hash which specifies multiple association names, as well as
+ # association names for the to-be-preloaded association objects. For
+ # example, specifying <tt>{ :author => :avatar }</tt> will preload a
+ # book's author, as well as that author's avatar.
+ #
+ # +:associations+ has the same format as the +:include+ option for
+ # <tt>ActiveRecord::Base.find</tt>. So +associations+ could look like this:
+ #
+ # :books
+ # [ :books, :author ]
+ # { :author => :avatar }
+ # [ :books, { :author => :avatar } ]
+ #
+ # +preload_options+ contains options that will be passed to ActiveRecord#find
+ # (which is called under the hood for preloading records). But it is passed
+ # only one level deep in the +associations+ argument, i.e. it's not passed
+ # to the child associations when +associations+ is a Hash.
def preload_associations(records, associations, preload_options={})
records = [records].flatten.compact.uniq
return if records.empty?
@@ -30,6 +104,8 @@ def preload_associations(records, associations, preload_options={})
private
+ # Preloads a specific named association for the given records. This is
+ # called by +preload_associations+ as its base case.
def preload_one_association(records, association, preload_options={})
class_to_reflection = {}
# Not all records have the same class, so group then preload
@@ -37,6 +113,10 @@ def preload_one_association(records, association, preload_options={})
# unnecessarily
records.group_by {|record| class_to_reflection[record.class] ||= record.class.reflections[association]}.each do |reflection, records|
raise ConfigurationError, "Association named '#{ association }' was not found; perhaps you misspelled it?" unless reflection
+
+ # 'reflection.macro' can return 'belongs_to', 'has_many', etc. Thus,
+ # the following could call 'preload_belongs_to_association',
+ # 'preload_has_many_association', etc.
send("preload_#{reflection.macro}_association", records, reflection, preload_options)
end
end
@@ -77,6 +157,10 @@ def set_association_single_records(id_to_record_map, reflection_name, associated
end
end
+ # Given a collection of ActiveRecord objects, constructs a Hash which maps
+ # the objects' IDs to the relevant objects. Returns a 2-tuple
+ # <tt>(id_to_record_map, ids)</tt> where +id_to_record_map+ is the Hash,
+ # and +ids+ is an Array of record IDs.
def construct_id_map(records)
id_to_record_map = {}
ids = []
View
6 activerecord/lib/active_record/associations.rb
@@ -1452,6 +1452,8 @@ def configure_dependency_for_has_many(reflection)
end
end
+ # Creates before_destroy callback methods that nullify, delete or destroy
+ # has_one associated objects, according to the defined :dependent rule.
def configure_dependency_for_has_one(reflection)
if reflection.options.include?(:dependent)
case reflection.options[:dependent]
@@ -1465,6 +1467,10 @@ def configure_dependency_for_has_one(reflection)
when :delete
method_name = "has_one_dependent_delete_for_#{reflection.name}".to_sym
define_method(method_name) do
+ # Retrieve the associated object and delete it. The retrieval
+ # is necessary because there may be multiple associated objects
+ # with foreign keys pointing to this object, and we only want
+ # to delete the correct one, not all of them.
association = send(reflection.name)
association.class.delete(association.id) unless association.nil?
end
View
92 activerecord/lib/active_record/base.rb
@@ -512,7 +512,7 @@ class << self # Class methods
#
# All approaches accept an options hash as their last parameter.
#
- # ==== Attributes
+ # ==== Parameters
#
# * <tt>:conditions</tt> - An SQL fragment like "administrator = 1" or <tt>[ "user_name = ?", username ]</tt>. See conditions in the intro.
# * <tt>:order</tt> - An SQL fragment like "created_at DESC, name".
@@ -697,7 +697,7 @@ def create(attributes = nil, &block)
# Updates an object (or multiple objects) and saves it to the database, if validations pass.
# The resulting object is returned whether the object was saved successfully to the database or not.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +id+ - This should be the id or an array of ids to be updated.
# * +attributes+ - This should be a Hash of attributes to be set on the object, or an array of Hashes.
@@ -725,9 +725,10 @@ def update(id, attributes)
# is executed on the database which means that no callbacks are fired off running this. This is an efficient method
# of deleting records that don't need cleaning up after or other actions to be taken.
#
- # Objects are _not_ instantiated with this method.
+ # Objects are _not_ instantiated with this method, and so +:dependent+ rules
+ # defined on associations are not honered.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +id+ - Can be either an Integer or an Array of Integers.
#
@@ -750,7 +751,7 @@ def delete(id)
# This essentially finds the object (or multiple objects) with the given id, creates a new object
# from the attributes, and then calls destroy on it.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +id+ - Can be either an Integer or an Array of Integers.
#
@@ -774,7 +775,7 @@ def destroy(id)
# also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the
# database. It does not instantiate the involved models and it does not trigger Active Record callbacks.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +updates+ - A string of column and value pairs that will be set on any records that match conditions.
# What goes into the SET clause.
@@ -820,34 +821,39 @@ def update_all(updates, conditions = nil, options = {})
# many records. If you want to simply delete records without worrying about dependent associations or
# callbacks, use the much faster +delete_all+ method instead.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +conditions+ - Conditions are specified the same way as with +find+ method.
#
# ==== Example
#
- # Person.destroy_all "last_login < '2004-04-04'"
+ # Person.destroy_all("last_login < '2004-04-04'")
#
# This loads and destroys each person one by one, including its dependent associations and before_ and
# after_destroy callbacks.
+ #
+ # +conditions+ can be anything that +find+ also accepts:
+ #
+ # Person.destroy_all(:last_login => 6.hours.ago)
def destroy_all(conditions = nil)
find(:all, :conditions => conditions).each { |object| object.destroy }
end
# Deletes the records matching +conditions+ without instantiating the records first, and hence not
# calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that
- # goes straight to the database, much more efficient than +destroy_all+. Careful with relations
- # though, in particular <tt>:dependent</tt> is not taken into account.
+ # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations
+ # though, in particular <tt>:dependent</tt> rules defined on associations are not honored.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +conditions+ - Conditions are specified the same way as with +find+ method.
#
# ==== Example
#
- # Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')"
+ # Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
+ # Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
#
- # This deletes the affected posts all at once with a single DELETE statement. If you need to destroy dependent
+ # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent
# associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead.
def delete_all(conditions = nil)
sql = "DELETE FROM #{quoted_table_name} "
@@ -859,7 +865,7 @@ def delete_all(conditions = nil)
# The use of this method should be restricted to complicated SQL queries that can't be executed
# using the ActiveRecord::Calculations class methods. Look into those before using this.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +sql+ - An SQL statement which should return a count query from the database, see the example below.
#
@@ -877,7 +883,7 @@ def count_by_sql(sql)
# with the given ID, altering the given hash of counters by the amount
# given by the corresponding value:
#
- # ==== Attributes
+ # ==== Parameters
#
# * +id+ - The id of the object you wish to update a counter on.
# * +counters+ - An Array of Hashes containing the names of the fields
@@ -907,7 +913,7 @@ def update_counters(id, counters)
# For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
# shown it would have to run an SQL query to find how many posts and comments there are.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +counter_name+ - The name of the field that should be incremented.
# * +id+ - The id of the object that should be incremented.
@@ -924,7 +930,7 @@ def increment_counter(counter_name, id)
#
# This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +counter_name+ - The name of the field that should be decremented.
# * +id+ - The id of the object that should be decremented.
@@ -1019,7 +1025,7 @@ def readonly_attributes
# The serialization is done through YAML. If +class_name+ is specified, the serialized object must be of that
# class on retrieval or SerializationTypeMismatch will be raised.
#
- # ==== Attributes
+ # ==== Parameters
#
# * +attr_name+ - The field name that should be serialized.
# * +class_name+ - Optional, class name that the object type should be equal to.
@@ -1927,6 +1933,9 @@ def define_attr_method(name, value=nil, &block)
# end
# end
# end
+ #
+ # *Note*: the +:find+ scope also has effect on update and deletion methods,
+ # like +update_all+ and +delete_all+.
def with_scope(method_scoping = {}, action = :merge, &block)
method_scoping = method_scoping.method_scoping if method_scoping.respond_to?(:method_scoping)
@@ -2274,7 +2283,28 @@ def id
end
- # Enables Active Record objects to be used as URL parameters in Action Pack automatically.
+ # Returns a String, which Action Pack uses for constructing an URL to this
+ # object. The default implementation returns this record's id as a String,
+ # or nil if this record's unsaved.
+ #
+ # For example, suppose that you have a Users model, and that you have a
+ # <tt>map.resources :users</tt> route. Normally, +users_path+ will
+ # construct an URI with the user object's 'id' in it:
+ #
+ # user = User.find_by_name('Phusion')
+ # user_path(path) # => "/users/1"
+ #
+ # You can override +to_param+ in your model to make +users_path+ construct
+ # an URI using the user's name instead of the user's id:
+ #
+ # class User < ActiveRecord::Base
+ # def to_param # overridden
+ # name
+ # end
+ # end
+ #
+ # user = User.find_by_name('Phusion')
+ # user_path(path) # => "/users/Phusion"
def to_param
# We can't use alias_method here, because method 'id' optimizes itself on the fly.
(id = self.id) ? id.to_s : nil # Be sure to stringify the id for routes
@@ -2356,6 +2386,9 @@ def save!
# Deletes the record in the database and freezes this instance to reflect that no changes should
# be made (since they can't be persisted).
+ #
+ # In addition to deleting this record, any defined +before_delete+ and +after_delete+
+ # callbacks are run, and +:dependent+ rules defined on associations are run.
def destroy
unless new_record?
connection.delete <<-end_sql, "#{self.class.name} Destroy"
@@ -2493,10 +2526,25 @@ def []=(attr_name, value)
end
# Allows you to set all the attributes at once by passing in a hash with keys
- # matching the attribute names (which again matches the column names). Sensitive attributes can be protected
- # from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively
- # specify which attributes *can* be accessed with the +attr_accessible+ macro. Then all the
+ # matching the attribute names (which again matches the column names).
+ #
+ # If +guard_protected_attributes+ is true (the default), then sensitive
+ # attributes can be protected from this form of mass-assignment by using
+ # the +attr_protected+ macro. Or you can alternatively specify which
+ # attributes *can* be accessed with the +attr_accessible+ macro. Then all the
# attributes not included in that won't be allowed to be mass-assigned.
+ #
+ # class User < ActiveRecord::Base
+ # attr_protected :is_admin
+ # end
+ #
+ # user = User.new
+ # user.attributes = { :username => 'Phusion', :is_admin => true }
+ # user.username # => "Phusion"
+ # user.is_admin? # => false
+ #
+ # user.send(:attributes=, { :username => 'Phusion', :is_admin => true }, false)
+ # user.is_admin? # => true
def attributes=(new_attributes, guard_protected_attributes = true)
return if new_attributes.nil?
attributes = new_attributes.dup
View
8 activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
@@ -98,8 +98,14 @@ def add_limit!(sql, options)
add_limit_offset!(sql, options) if options
end
- # Appends +LIMIT+ and +OFFSET+ options to an SQL statement.
+ # Appends +LIMIT+ and +OFFSET+ options to an SQL statement, or some SQL
+ # fragment that has the same semantics as LIMIT and OFFSET.
+ #
+ # +options+ must be a Hash which contains a +:limit+ option (required)
+ # and an +:offset+ option (optional).
+ #
# This method *modifies* the +sql+ parameter.
+ #
# ===== Examples
# add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50})
# generates
View
10 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -31,19 +31,25 @@ def table_exists?(table_name)
# See the concrete implementation for details on the expected parameter values.
def columns(table_name, name = nil) end
- # Creates a new table
+ # Creates a new table with the name +table_name+. +table_name+ may either
+ # be a String or a Symbol.
+ #
# There are two ways to work with +create_table+. You can use the block
# form or the regular form, like this:
#
# === Block form
- # # create_table() yields a TableDefinition instance
+ # # create_table() passes a TableDefinition object to the block.
+ # # This form will not only create the table, but also columns for the
+ # # table.
# create_table(:suppliers) do |t|
# t.column :name, :string, :limit => 60
# # Other fields here
# end
#
# === Regular form
+ # # Creates a table called 'suppliers' with no columns.
# create_table(:suppliers)
+ # # Add a column to 'suppliers'.
# add_column(:suppliers, :name, :string, {:limit => 60})
#
# The +options+ hash can include the following keys:
View
68 activerecord/lib/active_record/validations.rb
@@ -625,10 +625,6 @@ def validates_length_of(*attrs)
# When the record is created, a check is performed to make sure that no record exists in the database with the given value for the specified
# attribute (that maps to a column). When the record is updated, the same check is made but disregarding the record itself.
#
- # Because this check is performed outside the database there is still a chance that duplicate values
- # will be inserted in two parallel transactions. To guarantee against this you should create a
- # unique index on the field. See +add_index+ for more information.
- #
# Configuration options:
# * <tt>:message</tt> - Specifies a custom error message (default is: "has already been taken").
# * <tt>:scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint.
@@ -641,6 +637,70 @@ def validates_length_of(*attrs)
# * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
# not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
# method, proc or string should return or evaluate to a true or false value.
+ #
+ # === Concurrency and integrity
+ #
+ # Using this validation method in conjunction with ActiveRecord::Base#save
+ # does not guarantee the absence of duplicate record insertions, because
+ # uniqueness checks on the application level are inherently prone to racing
+ # conditions. For example, suppose that two users try to post a Comment at
+ # the same time, and a Comment's title must be unique. At the database-level,
+ # the actions performed by these users could be interleaved in the following manner:
+ #
+ # User 1 | User 2
+ # ------------------------------------+--------------------------------------
+ # # User 1 checks whether there's |
+ # # already a comment with the title |
+ # # 'My Post'. This is not the case. |
+ # SELECT * FROM comments |
+ # WHERE title = 'My Post' |
+ # |
+ # | # User 2 does the same thing and also
+ # | # infers that his title is unique.
+ # | SELECT * FROM comments
+ # | WHERE title = 'My Post'
+ # |
+ # # User 1 inserts his comment. |
+ # INSERT INTO comments |
+ # (title, content) VALUES |
+ # ('My Post', 'hi!') |
+ # |
+ # | # User 2 does the same thing.
+ # | INSERT INTO comments
+ # | (title, content) VALUES
+ # | ('My Post', 'hello!')
+ # |
+ # | # ^^^^^^
+ # | # Boom! We now have a duplicate
+ # | # title!
+ #
+ # This could even happen if you use transactions with the 'serializable'
+ # isolation level. There are several ways to get around this problem:
+ # - By locking the database table before validating, and unlocking it after
+ # saving. However, table locking is very expensive, and thus not
+ # recommended.
+ # - By locking a lock file before validating, and unlocking it after saving.
+ # This does not work if you've scaled your Rails application across
+ # multiple web servers (because they cannot share lock files, or cannot
+ # do that efficiently), and thus not recommended.
+ # - Creating a unique index on the field, by using
+ # ActiveRecord::ConnectionAdapters::SchemaStatements#add_index. In the
+ # rare case that a racing condition occurs, the database will guarantee
+ # the field's uniqueness.
+ #
+ # When the database catches such a duplicate insertion,
+ # ActiveRecord::Base#save will raise an ActiveRecord::StatementInvalid
+ # exception. You can either choose to let this error propagate (which
+ # will result in the default Rails exception page being shown), or you
+ # can catch it and restart the transaction (e.g. by telling the user
+ # that the title already exists, and asking him to re-enter the title).
+ # This technique is also known as optimistic concurrency control:
+ # http://en.wikipedia.org/wiki/Optimistic_concurrency_control
+ #
+ # Active Record currently provides no way to distinguish unique
+ # index constraint errors from other types of database errors, so you
+ # will have to parse the (database-specific) exception message to detect
+ # such a case.
def validates_uniqueness_of(*attr_names)
configuration = { :case_sensitive => true }
configuration.update(attr_names.extract_options!)
View
15 activesupport/lib/active_support/base64.rb
@@ -7,13 +7,24 @@ module ActiveSupport
if defined? ::Base64
Base64 = ::Base64
else
- # Ruby 1.9 doesn't provide base64, so we wrap this here
+ # Base64 provides utility methods for encoding and de-coding binary data
+ # using a base 64 representation. A base 64 representation of binary data
+ # consists entirely of printable US-ASCII characters. The Base64 module
+ # is included in Ruby 1.8, but has been removed in Ruby 1.9.
module Base64
-
+ # Encodes a string to its base 64 representation. Each 60 characters of
+ # output is separated by a newline character.
+ #
+ # ActiveSupport::Base64.encode64("Original unencoded string")
+ # # => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==\n"
def self.encode64(data)
[data].pack("m")
end
+ # Decodes a base 64 encoded string to its original representation.
+ #
+ # ActiveSupport::Base64.decode64("T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==")
+ # # => "Original unencoded string"
def self.decode64(data)
data.unpack("m").first
end
View
18 activesupport/lib/active_support/core_ext/array/access.rb
@@ -23,47 +23,47 @@ def to(position)
self[0..position]
end
- # Equals to <tt>self[1]</tt>.
+ # Equal to <tt>self[1]</tt>.
def second
self[1]
end
- # Equals to <tt>self[2]</tt>.
+ # Equal to <tt>self[2]</tt>.
def third
self[2]
end
- # Equals to <tt>self[3]</tt>.
+ # Equal to <tt>self[3]</tt>.
def fourth
self[3]
end
- # Equals to <tt>self[4]</tt>.
+ # Equal to <tt>self[4]</tt>.
def fifth
self[4]
end
- # Equals to <tt>self[5]</tt>.
+ # Equal to <tt>self[5]</tt>.
def sixth
self[5]
end
- # Equals to <tt>self[6]</tt>.
+ # Equal to <tt>self[6]</tt>.
def seventh
self[6]
end
- # Equals to <tt>self[7]</tt>.
+ # Equal to <tt>self[7]</tt>.
def eighth
self[7]
end
- # Equals to <tt>self[8]</tt>.
+ # Equal to <tt>self[8]</tt>.
def ninth
self[8]
end
- # Equals to <tt>self[9]</tt>.
+ # Equal to <tt>self[9]</tt>.
def tenth
self[9]
end
View
3  activesupport/lib/active_support/core_ext/base64/encoding.rb
@@ -4,6 +4,9 @@ module Base64 #:nodoc:
module Encoding
# Encodes the value as base64 without the newline breaks. This makes the base64 encoding readily usable as URL parameters
# or memcache keys without further processing.
+ #
+ # ActiveSupport::Base64.encode64s("Original unencoded string")
+ # # => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw=="
def encode64s(value)
encode64(value).gsub(/\n/, '')
end
View
52 activesupport/lib/active_support/core_ext/object/misc.rb
@@ -1,30 +1,50 @@
class Object
- # A Ruby-ized realization of the K combinator, courtesy of Mikael Brockman.
+ # Returns +value+ after yielding +value+ to the block. This simplifies the
+ # process of constructing an object, performing work on the object, and then
+ # returning the object from a method. It is a Ruby-ized realization of the K
+ # combinator, courtesy of Mikael Brockman.
#
- # def foo
- # returning values = [] do
- # values << 'bar'
- # values << 'baz'
- # end
- # end
+ # ==== Examples
#
- # foo # => ['bar', 'baz']
+ # # Without returning
+ # def foo
+ # values = []
+ # values << "bar"
+ # values << "baz"
+ # return values
+ # end
#
- # def foo
- # returning [] do |values|
- # values << 'bar'
- # values << 'baz'
- # end
- # end
+ # foo # => ['bar', 'baz']
#
- # foo # => ['bar', 'baz']
+ # # returning with a local variable
+ # def foo
+ # returning values = [] do
+ # values << 'bar'
+ # values << 'baz'
+ # end
+ # end
#
+ # foo # => ['bar', 'baz']
+ #
+ # # returning with a block argument
+ # def foo
+ # returning [] do |values|
+ # values << 'bar'
+ # values << 'baz'
+ # end
+ # end
+ #
+ # foo # => ['bar', 'baz']
def returning(value)
yield(value)
value
end
- # An elegant way to refactor out common options
+ # An elegant way to factor duplication out of options passed to a series of
+ # method calls. Each method called in the block, with the block variable as
+ # the receiver, will have its options merged with the default +options+ hash
+ # provided. Each method called on the block variable must take an options
+ # hash as its final argument.
#
# with_options :order => 'created_at', :class_name => 'Comment' do |post|
# post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all
View
BIN  railties/doc/guides/bechmarking and profiling/.DS_Store
Binary file not shown
View
BIN  railties/doc/guides/bechmarking and profiling/Examples/.DS_Store
Binary file not shown
View
0  .../doc/guides/bechmarking and profiling/Basics.html → ...doc/guides/benchmarking_and_profiling/Basics.html
File renamed without changes
View
0  ...des/bechmarking and profiling/Examples/graph.html → ...es/benchmarking_and_profiling/Examples/graph.html
File renamed without changes
View
0  ...uides/bechmarking and profiling/Images/KGraph.png → ...ides/benchmarking_and_profiling/Images/KGraph.png
File renamed without changes
View
0  ...guides/bechmarking and profiling/Images/KList.png → ...uides/benchmarking_and_profiling/Images/KList.png
File renamed without changes
View
0  ...doc/guides/bechmarking and profiling/appendix.txt → ...oc/guides/benchmarking_and_profiling/appendix.txt
File renamed without changes
View
0  ...s/doc/guides/bechmarking and profiling/basics.txt → .../doc/guides/benchmarking_and_profiling/basics.txt
File renamed without changes
View
0  .../guides/bechmarking and profiling/definitions.txt → ...guides/benchmarking_and_profiling/definitions.txt
File renamed without changes
View
0  ...ides/bechmarking and profiling/digging_deeper.txt → ...des/benchmarking_and_profiling/digging_deeper.txt
File renamed without changes
View
0  ...bechmarking and profiling/edge rails features.txt → ...enchmarking_and_profiling/edge rails features.txt
File renamed without changes
View
0  ...doc/guides/bechmarking and profiling/gameplan.txt → ...oc/guides/benchmarking_and_profiling/gameplan.txt
File renamed without changes
View
0  ...oc/guides/bechmarking and profiling/preamble.html → ...c/guides/benchmarking_and_profiling/preamble.html
File renamed without changes
View
0  ...doc/guides/bechmarking and profiling/preamble.txt → ...oc/guides/benchmarking_and_profiling/preamble.txt
File renamed without changes
View
0  ...doc/guides/bechmarking and profiling/rubyprof.txt → ...oc/guides/benchmarking_and_profiling/rubyprof.txt
File renamed without changes
View
0  ...c/guides/bechmarking and profiling/statistics.txt → .../guides/benchmarking_and_profiling/statistics.txt
File renamed without changes
View
37 railties/doc/guides/getting_started_with_rails/getting_started_with_rails.txt
@@ -317,7 +317,42 @@ This time, we're setting `@post` to a single record in the database that is sear
==== New & Create
-Description of new and create actions
+In your controller, you'll see the `new` and `create` actions, which are used together to create a new record. Our `new` action simply instantiates a new Post object without any parameters:
+
+-----------------------------------------
+def new
+ @post = Post.new
+
+ respond_to do |format|
+ format.html # new.html.erb
+ format.xml { render :xml => @post }
+ end
+end
+----------------------------------------
+
+Our `create` action, on the other hand, instantiates a new Post object while setting its attributes to the parameters that we specify in our form. It then uses a `flash[:notice]` to inform the user of the status of the action. If the Post is saved successfully, the action will redirect to the `show` action containing our new Post simply by calling the simple `redirect_to(@post)`.
+
+.The Flash
+**************************************************************************************************************
+Rails provides the Flash so that messages can be carried over to another action, providing the user with useful information on the status of their request. In our `create` example, the user never actually sees any page rendered during the Post creation process, because it immediately redirects to the new Post as soon as the record is saved. The Flash allows us to carry over a message to the next action, so once the user is redirected back to the `show` action, they are presented with a message saying "Post was successfully created."
+**************************************************************************************************************
+
+----------------------------------------
+def create
+ @post = Post.new(params[:post])
+
+ respond_to do |format|
+ if @post.save
+ flash[:notice] = 'Post was successfully created.'
+ format.html { redirect_to(@post) }
+ format.xml { render :xml => @post, :status => :created, :location => @post }
+ else
+ format.html { render :action => "new" }
+ format.xml { render :xml => @post.errors, :status => :unprocessable_entity }
+ end
+ end
+end
+---------------------------------------
==== Edit & Update
View
63 railties/doc/guides/index.txt
@@ -3,28 +3,60 @@ Ruby on Rails guides
WARNING: This page is the result of ongoing http://hackfest.rubyonrails.org/guide[Rails Guides hackfest] and a work in progress.
-.link:getting_started_with_rails/getting_started_with_rails.html[Getting Started with Rails]
+++++++++++++++++++++++++++++++++++++++
+<h2>Finished Guides</h2>
+++++++++++++++++++++++++++++++++++++++
+
+These guides are complete and the authors are listed link:authors.html[here].
+
+.link:migrations/migrations.html[Rails Database Migrations]
***********************************************************
TODO: Insert some description here.
***********************************************************
-.link:activerecord/association_basics.html[Active Record Associations]
+.link:routing/routing_outside_in.html[Rails Routing from the Outside In]
***********************************************************
-Introduction to Active Record associations.
+This guide covers the user-facing features of Rails routing. If you want to
+understand how to use routing in your own Rails applications, start here.
***********************************************************
-.link:migrations/migrations.html[Rails Database Migrations]
+++++++++++++++++++++++++++++++++++++++
+<h2>Guides in progress</h2>
+++++++++++++++++++++++++++++++++++++++
+
+These guides are currently being worked on. While they still might be useful to you, you could always help by reviewing them and posting your
+findings at the respective Lighthouse ticket.
+
+.link:debugging/debugging_rails_applications.html[Debugging Rails Applications]
***********************************************************
-TODO: Insert some description here.
+link:http://rails.lighthouseapp.com/projects/16213/tickets/5[Lighthouse Ticket]
+
+This guide describes how to debug Rails applications. It covers the different
+ways of achieving this and how to understand what is happening "behind the scenes"
+of your code.
+***********************************************************
+
+.link:getting_started_with_rails/getting_started_with_rails.html[Getting Started with Rails]
+***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/2[Lighthouse Ticket]
+***********************************************************
+
+.link:activerecord/association_basics.html[Active Record Associations]
+***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/11[Lighthouse Ticket]
***********************************************************
.link:forms/form_helpers.html[Action View Form Helpers]
***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/1[Lighthouse Ticket]
+
Guide to using built in Form helpers.
***********************************************************
.link:testing_rails_applications/testing_rails_applications.html[Testing Rails Applications]
***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/8[Lighthouse Ticket]
+
This is a rather comprehensive guide to doing both unit and functional tests
in Rails. It covers everything from ``What is a test?'' to the testing APIs.
Enjoy.
@@ -32,29 +64,20 @@ Enjoy.
.link:securing_rails_applications/security.html[Securing Rails Applications]
***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/7[Lighthouse Ticket]
+
This manual describes common security problems in web applications and how to
avoid them with Rails.
***********************************************************
-.link:routing/routing_outside_in.html[Rails Routing from the Outside In]
-***********************************************************
-This guide covers the user-facing features of Rails routing. If you want to
-understand how to use routing in your own Rails applications, start here.
+.link:caching/caching_with_rails.html[Rails Caching]
***********************************************************
+link:http://rails.lighthouseapp.com/projects/16213/tickets/10[Lighthouse Ticket]
-.link:debugging/debugging_rails_applications.html[Debugging Rails Applications]
-***********************************************************
-This guide describes how to debug Rails applications. It covers the different
-ways of achieving this and how to understand what is happening "behind the scenes"
-of your code.
+TODO: Insert some description here.
***********************************************************
.link:creating_plugins/creating_plugins.html[The Basics of Creating Rails Plugins]
***********************************************************
-TODO: Insert some description here.
+TODO: Insert some description here. No Lighthouse ticket.
***********************************************************
-
-.link:caching/caching_with_rails.html[Rails Caching]
-***********************************************************
-TODO: Insert some description here.
-***********************************************************
View
68 railties/doc/guides/routing/routing_outside_in.txt
@@ -168,6 +168,24 @@ photos_url # => "http://www.example.com/photos"
photos_path # => "/photos"
-------------------------------------------------------
+=== Defining Multiple Resources at the Same Time
+
+If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to +map.resources+:
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :photos, :books, :videos
+-------------------------------------------------------
+
+This has exactly the same effect as
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :photos
+map.resources :books
+map.resources :videos
+-------------------------------------------------------
+
=== Singular Resources
You can also apply RESTful routing to singleton resources within your application. In this case, you use +map.resource+ instead of +map.resources+ and the route generation is slightly different. For example, a routing entry of
@@ -379,11 +397,11 @@ HTTP verb URL controller action used for
--------------------------------------------------------------------------------------------
GET /magazines/1/ads Ads index display a list of all ads for a specific magazine
GET /magazines/1/ads/new Ads new return an HTML form for creating a new ad belonging to a specific magazine
-POST /magazines/1/ads Ads create create a new photo belonging to a specific magazine
-GET /magazines/1/ads/1 Ads show display a specific photo belonging to a specific magazine
-GET /magazines/1/ads/1/edit Ads edit return an HTML form for editing a photo belonging to a specific magazine
-PUT /magazines/1/ads/1 Ads update update a specific photo belonging to a specific magazine
-DELETE /magazines/1/ads/1 Ads destroy delete a specific photo belonging to a specific magazine
+POST /magazines/1/ads Ads create create a new ad belonging to a specific magazine
+GET /magazines/1/ads/1 Ads show display a specific ad belonging to a specific magazine
+GET /magazines/1/ads/1/edit Ads edit return an HTML form for editing an ad belonging to a specific magazine
+PUT /magazines/1/ads/1 Ads update update a specific ad belonging to a specific magazine
+DELETE /magazines/1/ads/1 Ads destroy delete a specific ad belonging to a specific magazine
--------------------------------------------------------------------------------------------
This will also create routing helpers such as +magazine_ads_url+ and +magazine_edit_ad_path+.
@@ -499,6 +517,29 @@ If you like, you can combine shallow nesting with the +:has_one+ and +:has_many+
map.resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
-------------------------------------------------------
+=== Namespaced Resources
+
+It's possible to do some quite complex things by combining +:path_prefix+ and +:name_prefix+. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :photos, :path_prefix => 'admin', :controller => 'admin/photos'
+map.resources :tags, :path_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_tags'
+map.resources :ratings, :path_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_ratings'
+-------------------------------------------------------
+
+The good news is that if you find yourself using this level of complexity, you can stop. Rails supports _namespaced resources_ to make placing resources in their own folder a snap. Here's the namespaced version of those same three routes:
+
+[source, ruby]
+-------------------------------------------------------
+map.namespace(:admin) do |admin|
+ admin.resources :photos,
+ :has_many => { :tags, :ratings}
+end
+-------------------------------------------------------
+
+As you can see, the namespaced version is much more succinct than the one that spells everything out - but it still creates the same routes. For example, you'll get +admin_photos_url+ that expects to find an +Admin::PhotosController+ and that matches +admin/photos+, and +admin_photos_ratings+path+ that matches +/admin/photos/_photo_id_/ratings+, expecting to use +Admin::RatingsController+.
+
=== Adding More RESTful Actions
You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional member routes (those which apply to a single instance of the resource), additional new routes (those that apply to creating a new resource), or additional collection routes (those which apply to the collection of resources as a whole).
@@ -574,7 +615,7 @@ You can set up as many wildcard symbols within a regular route as you like. Anyt
[source, ruby]
-------------------------------------------------------
-map.connect ':controller/:action/:id/:userid:'
+map.connect ':controller/:action/:id/:user_id'
-------------------------------------------------------
An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be set to 2.
@@ -585,7 +626,7 @@ You can specify static text when creating a route. In this case, the static text
[source, ruby]
-------------------------------------------------------
-map.connect ':controller/:action/:id/with_user/:userid:'
+map.connect ':controller/:action/:id/with_user/:user_id'
-------------------------------------------------------
This route would respond to URLs such as +/photos/show/1/with_user/2+.
@@ -612,6 +653,15 @@ map.connect 'photo/:id', :controller => 'photos', :action => 'show'
With this route, an incoming URL of +/photos/12+ would be dispatched to the +show+ action within the +Photos+ controller.
+You an also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:
+
+[source, ruby]
+-------------------------------------------------------
+map.connect 'photo/:id', :controller => 'photos', :action => 'show', :defaults => { :format => 'jpg' }
+-------------------------------------------------------
+
+With this route, an incoming URL of +photos/12+ would be dispatched to the +show+ action within the +Photos+ controller, and +params[:format]+ will be set to +jpg+.
+
=== Named Routes
Regular routes need not use the +connect+ method. You can use any other name here to create a _named route_. For example,
@@ -655,7 +705,7 @@ As with conditions in RESTful routes, you can specify +:get+, +:post+, +:put+, +
=== Route Globbing
-Route globbing is a way to specify that a particular parameter (which must be the last parameter in the route) should engulf all the remaining parts of a route. For example
+Route globbing is a way to specify that a particular parameter (which must be the last parameter in the route) should be matched to all the remaining parts of a route. For example
[source, ruby]
-------------------------------------------------------
@@ -690,7 +740,7 @@ For instance, consider the second of the default routes in the boilerplate +rout
map.connect ':controller/:action/:id.:format'
-------------------------------------------------------
-This route matches requests such as +/photo/new/1.xml+ or +/photo/show/2.rss+. Within the appropriate action code, you can issue different responses depending on the requested format:
+This route matches requests such as +/photo/edit/1.xml+ or +/photo/show/2.rss+. Within the appropriate action code, you can issue different responses depending on the requested format:
[source, ruby]
-------------------------------------------------------
View
1  railties/lib/tasks/documentation.rake
@@ -55,6 +55,7 @@ namespace :doc do
namespace :plugins do
# Define doc tasks for each plugin
plugins.each do |plugin|
+ desc "Generate documentation for the #{plugin} plugin"
task(plugin => :environment) do
plugin_base = "vendor/plugins/#{plugin}"
options = []
Please sign in to comment.
Something went wrong with that request. Please try again.