Browse files

Merge remote branch 'docrails/master'

  • Loading branch information...
2 parents c9ae2c1 + c6f4c59 commit 2f04c8785540597b02a265324c91267f09ddd07c @fxn fxn committed Jul 9, 2010
View
10 actionpack/lib/action_dispatch/routing.rb
@@ -31,7 +31,7 @@ module ActionDispatch
# Think of creating routes as drawing a map for your requests. The map tells
# them where to go based on some predefined pattern:
#
- # AppName::Applications.routes.draw do |map|
+ # AppName::Application.routes.draw do |map|
@jonathan
jonathan added a line comment Jul 9, 2010

I thought the |map| was deprecated and not included when generating a new app. Keeping it in with the comments might confuse new users.

@fxn
Ruby on Rails member
fxn added a line comment Jul 9, 2010

Good catch, would you like to fix it? docrails has public write access.

@rohit
rohit added a line comment Jul 10, 2010

But when you generate a Rails app it includes the map block parameter. I'm guessing it's for supporting legacy routes. If you will remove it from the docs then you might as well remove it from the routes.rb template.

@stevenh512
stevenh512 added a line comment Jul 10, 2010

I disagree. I'm pretty new to Rails but it seems to be customary to remove documentation for deprecated functionality before the actual functionality is removed. It looks like the deprecated |map| block parameter is there to provide some backwards functionality. Removing the documentation just discourages its use in new apps, removing the actual functionality kills backwards compatibility with routes from 2.3.x apps (which, I think, is intentionally being left in for 3.0.0 for exactly that reason and will probably be removed in some later release).

@josevalim
Ruby on Rails member
josevalim added a line comment Jul 10, 2010

In Rails master, when you generate a new app, it does not include map. +1 for removing it from the docs.

@fxn
Ruby on Rails member
fxn added a line comment Jul 10, 2010

And if you see the context of that line, it is all about the new routes. It shouldn't be there.

@rohit
rohit added a line comment Jul 10, 2010

My bad, I was looking at a slightly older app (generated from an older Rails source). Sorry for the confusion :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
# Pattern 1 tells some request to go to one place
# Pattern 2 tell them to go to another
# ...
@@ -62,7 +62,7 @@ module ActionDispatch
#
# redirect_to show_item_path(:id => 25)
#
- # Use <tt>root</tt> as a shorthand to name a route for the root path "".
+ # Use <tt>root</tt> as a shorthand to name a route for the root path "/".
#
# # In routes.rb
# root :to => 'blogs#index'
@@ -72,7 +72,7 @@ module ActionDispatch
#
# # and provide these named routes
# root_url # => 'http://www.example.com/'
- # root_path # => ''
+ # root_path # => '/'
#
# Note: when using +controller+, the route is simply named after the
# method you call on the block parameter rather than map.
@@ -91,9 +91,7 @@ module ActionDispatch
#
# Routes can generate pretty URLs. For example:
#
- # match '/articles/:year/:month/:day', :constraints => {
- # :controller => 'articles',
- # :action => 'find_by_date',
+ # match '/articles/:year/:month/:day' => 'articles#find_by_id', :constraints => {
# :year => /\d{4}/,
# :month => /\d{1,2}/,
# :day => /\d{1,2}/
View
9 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -103,10 +103,15 @@ def column_exists?(table_name, column_name, type = nil, options = {})
# The +options+ hash can include the following keys:
# [<tt>:id</tt>]
# Whether to automatically add a primary key column. Defaults to true.
- # Join tables for +has_and_belongs_to_many+ should set <tt>:id => false</tt>.
+ # Join tables for +has_and_belongs_to_many+ should set it to false.
# [<tt>:primary_key</tt>]
# The name of the primary key, if one is to be added automatically.
- # Defaults to +id+.
+ # Defaults to +id+. If <tt>:id</tt> is false this option is ignored.
+ #
+ # Also note that this just sets the primary key in the table. You additionally
+ # need to configure the primary key in the model via the +set_primary_key+ macro.
+ # Models do NOT auto-detect the primary key from their table definition.
+ #
# [<tt>:options</tt>]
# Any extra options you want appended to the table definition.
# [<tt>:temporary</tt>]
View
2 activesupport/lib/active_support/core_ext/logger.rb
@@ -18,7 +18,7 @@ def around_#{level}(before_message, after_message, &block) # def around_debug(b
require 'logger'
-# Extensions to the built in Ruby logger.
+# Extensions to the built-in Ruby logger.
#
# If you want to use the default log formatter as defined in the Ruby core, then you
# will need to set the formatter for the logger as in:
View
36 railties/guides/source/active_support_core_extensions.textile
@@ -1107,47 +1107,51 @@ If for whatever reason an application loads the definition of a mailer class and
NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+.
-h4. Descendants & Subclasses
+h4. Subclasses & Descendants
-h5. +descendants+
+h5. +subclasses+
-The +descendants+ method returns all classes, including its children, that inherits from self.
+The +subclasses+ method returns the subclasses of the receiver:
<ruby>
class C; end
-C.descendants #=> []
+C.subclasses # => []
class B < C; end
-C.descendants #=> [B]
+C.subclasses # => [B]
class A < B; end
-C.descendants #=> [B, A]
+C.subclasses # => [B]
class D < C; end
-C.descendants #=> [B, A, D]
+C.subclasses # => [B, D]
</ruby>
-h5. +subclasses+
+The order in which these classes are returned is unspecified.
-The +subclasses+ method returns all direct classes that inherits from self.
+WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
+
+NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.
+
+h5. +descendants+
+
+The +descendants+ method returns all classes that are <tt>&lt;</tt> than its receiver:
<ruby>
class C; end
-C.subclasses #=> []
+C.descendants # => []
class B < C; end
-C.subclasses #=> [B]
+C.descendants # => [B]
class A < B; end
-C.subclasses #=> [B]
+C.descendants # => [B, A]
class D < C; end
-C.subclasses #=> [B, D]
+C.descendants # => [B, A, D]
</ruby>
-The order in which these class are returned is unspecified.
-
-WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1.
+The order in which these classes are returned is unspecified.
NOTE: Defined in +active_support/core_ext/class/subclasses.rb+.
View
2 railties/guides/source/index.html.erb
@@ -68,7 +68,7 @@ Ruby on Rails Guides
<% end %>
<%= guide("Action View Form Helpers", 'form_helpers.html', :ticket => 1) do %>
- <p>Guide to using built in Form helpers.</p>
+ <p>Guide to using built-in Form helpers.</p>
<% end %>
</dl>
View
137 railties/guides/source/initialization.textile
@@ -3568,28 +3568,24 @@ h3. Appendix A
This file is _activesupport/lib/active_support/inflector/inflections.rb_ and defines the +ActiveSupport::Inflector::Inflections+ class which defines the +singularize+, +pluralize+, +humanize+, +tableize+, +titleize+ and +classify+ methods as well as the code to defining how to work out the irregular, singular, plural and human versions of words. These methods are called +irregular+, +singular+, +plural+ and +human+ respectively, as is the Rails way.
-This file is _activesupport/lib/active_support/inflector/transliterate.rb_ and defines two methods, +transliterate+ and +parameterize+. What +transliterate+ does depends on your Ruby version. If you have something greater than 1.9 installed it will just print out a warning message using the +Kernel#warn+ method (simply called using +warn+) reading "Ruby 1.9 doesn't support Unicode normalization yet". If you're running something that's not 1.9 it will attempt to convert +"föö"+ to +foo+ and if that fails then it'll redefine it.
+This file is _activesupport/lib/active_support/inflector/transliterate.rb_ and defines two methods, +transliterate+ and +parameterize+.
-This file first makes a require to _activesupport/lib/active_support/core_ext/string/multibyte.rb_ which then goes on to require _activesupport/lib/active_support/multibyte.rb_ and that requires _activesupport/core_ext/module/attribute_accessors.rb_. The _attribute_accessors.rb_ file is used to gain access to the +mattr_accessor+ (module attribute accessor) method which is called in _active_suport/multibyte.rb_. Also in _active_support/multibyte.rb_ there's a couple of autoloaded classes:
+This file first requires _activesupport/lib/active_support/core_ext/string/multibyte.rb_, which requires _activesupport/lib/active_support/multibyte.rb_, which subsequently requires _activesupport/core_ext/module/attribute_accessors.rb_. The _attribute_accessors.rb_ file is needed to gain access to the +mattr_accessor+ (module attribute accessor) method, which is called in _active_suport/multibyte.rb_. The file _active_support/multibyte.rb_ also autoloads three other classes:
<ruby>
module ActiveSupport #:nodoc:
module Multibyte
autoload :EncodingError, 'active_support/multibyte/exceptions'
autoload :Chars, 'active_support/multibyte/chars'
- autoload :UnicodeDatabase, 'active_support/multibyte/unicode_database'
- autoload :Codepoint, 'active_support/multibyte/unicode_database'
- autoload :UCD, 'active_support/multibyte/unicode_database'
- ...
+ autoload :Unicode, 'active_support/multibyte/unicode'
+ ...
end
end
</ruby>
-There's also these method definitions:
+There are also these method definitions:
<ruby>
- self.default_normalization_form = :kc
-
# The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy
# class so you can support other encodings. See the ActiveSupport::Multibyte::Chars implementation for
# an example how to do this.
@@ -3608,63 +3604,92 @@ There's also these method definitions:
These methods are used in _activesupport/lib/active_support/core_ext/string/multibyte.rb_.
-If we go back to _activesupport/lib/active_support/core_ext/string/multibyte.rb_, this file makes a couple of extensions to the +String+ class based on if your version of Ruby's +String+ class responds to the +force_encoding+ method. This method was introduced in Ruby 1.9. If you're using 1.9 the methods are defined like this:
-
-<ruby>
- def mb_chars #:nodoc
- self
- end
-
- def is_utf8? #:nodoc
- case encoding
- when Encoding::UTF_8
- valid_encoding?
- when Encoding::ASCII_8BIT, Encoding::US_ASCII
- dup.force_encoding(Encoding::UTF_8).valid_encoding?
- else
- false
- end
- end
-</ruby>
-
-You can see that calling +mb_chars+ on a +String+ instance in Ruby 1.9 will simply return that +String+ object. +String+ objects in Ruby 1.9 are already multibyte strings, so Rails does not need to do any conversion on them.
-
-The second method, +is_utf8?+ return +true+ if the +String+ object is of the UTF8 encoding or if it's able to be forced into that encoding and +false+ if it can't force its encoding or if the encoding of the string is neither +UTF8+, +ASCII_8BIT+ or +US_ASCII+.
-
-If you're using a Ruby version less than 1.9 there are 3 methods defined instead of 2, and they are defined like this:
+The file _activesupport/lib/active_support/core_ext/string/chars.rb_ defines the default proxy class that will be returned by +mb_chars+.
+
+Because Ruby 1.9's +String+ class has support for multibyte encodings, some methods are defined only for Ruby 1.8:
+
+* +self.wants?+
+* +++
+* +=~+
+* +=~+
+* +center+
+* +include?+
+* +index+
+* +insert+
+* +ljust+
+* +lstrip+, +lstrip!+
+* +ord+
+* +rindex+
+* +rjust+
+* +rstrip+, +rstrip!+
+* +size+
+* +strip+, +strip!+
+
+However, Ruby 1.9 lacks support for some needed operations, so the following methods are defined for both Ruby 1.8 and Ruby 1.9:
+
+* +<=>+
+* +[]=+
+* +capitalize+, +capitalize!+
+* +compose+
+* +decompose+
+* +downcase+, +downcase!+
+* +g_length+
+* +limit+
+* +normalize+
+* +reverse+, +reverse+!
+* +slice+, +slice!+
+* +split+
+* +tidy_bytes+, +tidy_bytes!+
+* +titleize+
+* +upcase+, +upcase!+
+
+<ruby>
+ class String
+ if RUBY_VERSION >= "1.9"
+ def mb_chars
+ if ActiveSupport::Multibyte.proxy_class.consumes?(self)
+ ActiveSupport::Multibyte.proxy_class.new(self)
+ else
+ self
+ end
+ end
-<ruby>
- def mb_chars
- if ActiveSupport::Multibyte.proxy_class.wants?(self)
- ActiveSupport::Multibyte.proxy_class.new(self)
+ def is_utf8? #:nodoc
+ case encoding
+ when Encoding::UTF_8
+ valid_encoding?
+ when Encoding::ASCII_8BIT, Encoding::US_ASCII
+ dup.force_encoding(Encoding::UTF_8).valid_encoding?
+ else
+ false
+ end
+ end
else
- self
- end
- end
-
- # Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have
- # them), returns false otherwise.
- def is_utf8?
- ActiveSupport::Multibyte::Chars.consumes?(self)
- end
+ def mb_chars
+ if ActiveSupport::Multibyte.proxy_class.wants?(self)
+ ActiveSupport::Multibyte.proxy_class.new(self)
+ else
+ self
+ end
+ end
- unless '1.8.7 and later'.respond_to?(:chars)
- def chars
- ActiveSupport::Deprecation.warn('String#chars has been deprecated in favor of String#mb_chars.', caller)
- mb_chars
+ # Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have
+ # them), returns false otherwise.
+ def is_utf8?
+ ActiveSupport::Multibyte::Chars.consumes?(self)
+ end
end
- end
-
</ruby>
+As you can see, +mb_chars+ is where the +proxy_class+ property comes in handy. This method will create a new instance of the configured proxy class using the instance of +String+ as a constructor argument. By default, the new +String+-like object will be an instance of the proxy class +ActiveSupport::Multibyte::Chars+. You can use +ActiveSupport::Multibyte.proxy_class=+ to set a different proxy class if you wish.
-As you can see, +mb_chars+ is where the +proxy_class+ method comes in handy. This will create a new instance of that class and pass in the +String+ object in order to make it multibyte-compatible. In this case the new +String+ object will be an instance of the +ActiveSupport::Multibyte::Chars+ class. You can use +ActiveSupport::Multibyte.proxy_class=+ to set this to be a different class if you're that way inclined.
-
-Here, +is_utf8?+ calls a +consumes+ method on the not-yet-loaded +ActiveSupport::Multibyte::Chars+ class. The keen-eye would have seen this was specified as an auto-load earlier, so that is what is going to happen if we call this method or +mb_chars+. This means that it'll require the file located at _activesupport/lib/active_support/multibyte/chars.rb_. This file includes _activesupport/lib/active_support/string/access.rb_ which defines methods such as +at+, +from+, +to+, +first+ and +last+. These methods will return parts of the string depending on what is passed to them and they are defined differently depending on if you're using Ruby 1.9 or not. The second file included is _activesupport/lib/active_support/string/behaviour.rb_ which defines a single method +acts_like_string?+ on +String+ which always returns +true+. This method is used through the +acts_like?+ method which is passed a single argument representing the downcased and symbolised version of the class you want to know if it acts like. In this case the code would be +acts_like?(:string)+.
+Here, +mb_chars+ invokes +is_utf8?+ to checks if the string can be treated as UTF-8. On 1.9, the string's +encoding+ property is checked. On 1.8, +wants?+ checks to see if +$KCODE+ is "UTF-8" and, and +consumes?+ checks whether the string can be unpacked as UTF-8 without raising an error.
-The +Chars+ class defines, along with +consumes?+, other methods such as the "spaceship" method +<=>+. This method is referenced by the methods defined in the included +Comparable+ module and will return either +-1+, +0+ or +1+ depending on if the word is before, identical or after the compared word. For example, +'é'.mb_chars <=> 'ü'.mb_chars+ returns +-1+ as e comes before u in the alphabet. Other methods are the commonly used +split+, +=~+, +insert+ and +include?+.
+The keen eye will have seen +ActiveSupport::Multibyte::Chars+ was specified as an +autoload+ earlier: _activesupport/lib/active_support/multibyte/chars.rb_ will be loaded without an explicit +require+ when we call +is_utf8+ on 1.8, or +mb_chars+ on any Ruby version. This file includes _activesupport/lib/active_support/string/access.rb_ which defines methods such as +at+, +from+, +to+, +first+ and +last+. These methods will return parts of the string depending on what is passed to them.
+The second file included is _activesupport/lib/active_support/string/behavior.rb_ which only defines +acts_like_string?+ on +String+, a method which always returns +true+. This method is used by +Object#acts_like?+, which accepts a single argument representing the downcased and symbolised version of a class, and returns true if the object's behavior is like that class. In this case the code would be +acts_like?(:string)+.
+The +Chars+ class also defines other important methods such as the "spaceship" method +<=>+, which is needed by the +Comparable+ module, in order to allow UTF-8-aware sorting.
h3. Common Includes
View
2 railties/guides/source/layouts_and_rendering.textile
@@ -2,7 +2,7 @@ h2. Layouts and Rendering in Rails
This guide covers the basic layout features of Action Controller and Action View. By referring to this guide, you will be able to:
-* Use the various rendering methods built in to Rails
+* Use the various rendering methods built into Rails
* Create layouts with multiple content sections
* Use partials to DRY up your views
* Use nested layouts (sub-templates)
View
2 railties/guides/source/plugins.textile
@@ -1284,7 +1284,7 @@ class YaffleMigrationGenerator < Rails::Generator::NamedBase
end
</ruby>
-The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement. It reuses the built in rails +migration_template+ method, and reuses the built-in rails migration template.
+The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement. It reuses the built-in rails +migration_template+ method, and reuses the built-in rails migration template.
It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names. This way people using your generator won't have to manually change the generated files if they've turned pluralization off.
View
2 railties/guides/source/security.textile
@@ -670,7 +670,7 @@ Also, the second query renames some columns with the AS statement so that the we
h5(#sql-injection-countermeasures). Countermeasures
-Ruby on Rails has a built in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually</em>.
+Ruby on Rails has a built-in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually</em>.
Instead of passing a string to the conditions option, you can pass an array to sanitize tainted strings like this:

1 comment on commit 2f04c87

@stevenh512

I disagree. I'm pretty new to Rails but it seems to be customary to remove documentation for deprecated functionality before the actual functionality is removed. It looks like the deprecated |map| block parameter is there to provide some backwards functionality. Removing the documentation just discourages its use in new apps, removing the actual functionality kills backwards compatibility with routes from 2.3.x apps (which, I think, is intentionally being left in for 3.0.0 for exactly that reason and will probably be removed in some later release).

Please sign in to comment.