From dc364fdc595405aa3d5735e60d46ad3f9544a65b Mon Sep 17 00:00:00 2001 From: Rohit Arondekar Date: Wed, 7 Jul 2010 22:15:15 -0700 Subject: [PATCH 1/5] API Docs: Fixes to the Routing docs --- actionpack/lib/action_dispatch/routing.rb | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb index 89007fab74..c664fb0bc2 100644 --- a/actionpack/lib/action_dispatch/routing.rb +++ b/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| # 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 root as a shorthand to name a route for the root path "". + # Use root 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}/ From f6fa6cf6117e691899c821b8999bd7dfb3f48b38 Mon Sep 17 00:00:00 2001 From: Neeraj Singh Date: Thu, 8 Jul 2010 10:09:20 -0400 Subject: [PATCH 2/5] clarifying how to create non standard primary key --- .../connection_adapters/abstract/schema_statements.rb | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index 76b65bf219..555a611e68 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -106,7 +106,13 @@ def column_exists?(table_name, column_name, type = nil, options = {}) # Join tables for +has_and_belongs_to_many+ should set :id => false. # [:primary_key] # The name of the primary key, if one is to be added automatically. - # Defaults to +id+. + # Defaults to +id+. You must NOT pass :id => false otherwise :primary_key option + # will have no effect. + # + # Also note that this just sets the primary_key in the table. You still need to + # add :set_primary_key => '' in the model to tell model what column is the + # primary_key. Models do NOT auto-detect the primary_key from table defintion. + # # [:options] # Any extra options you want appended to the table definition. # [:temporary] From a9587935dec6b5de01d51553ecc6d4157a8ec173 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Thu, 8 Jul 2010 16:53:37 +0200 Subject: [PATCH 3/5] copy-edits some docs --- .../abstract/schema_statements.rb | 11 ++-- .../active_support_core_extensions.textile | 54 ++++++++++--------- 2 files changed, 34 insertions(+), 31 deletions(-) diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index 555a611e68..ffc3847a31 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -103,15 +103,14 @@ def column_exists?(table_name, column_name, type = nil, options = {}) # The +options+ hash can include the following keys: # [:id] # Whether to automatically add a primary key column. Defaults to true. - # Join tables for +has_and_belongs_to_many+ should set :id => false. + # Join tables for +has_and_belongs_to_many+ should set it to false. # [:primary_key] # The name of the primary key, if one is to be added automatically. - # Defaults to +id+. You must NOT pass :id => false otherwise :primary_key option - # will have no effect. + # Defaults to +id+. If :id is false this option is ignored. # - # Also note that this just sets the primary_key in the table. You still need to - # add :set_primary_key => '' in the model to tell model what column is the - # primary_key. Models do NOT auto-detect the primary_key from table defintion. + # 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. # # [:options] # Any extra options you want appended to the table definition. diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index de0c00ac68..58824d7aeb 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -1107,50 +1107,54 @@ 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 - -h5. +descendants+ - -The +descendants+ method returns all classes, including its children, that inherits from self. - - -class C; end -C.descendants #=> [] - -class B < C; end -C.descendants #=> [B] - -class A < B; end -C.descendants #=> [B, A] - -class D < C; end -C.descendants #=> [B, A, D] - +h4. Subclasses & Descendants h5. +subclasses+ -The +subclasses+ method returns all direct classes that inherits from self. +The +subclasses+ method returns the subclasses of the receiver: class C; end -C.subclasses #=> [] +C.subclasses # => [] class B < C; end -C.subclasses #=> [B] +C.subclasses # => [B] class A < B; end -C.subclasses #=> [B] +C.subclasses # => [B] class D < C; end -C.subclasses #=> [B, D] +C.subclasses # => [B, D] -The order in which these class are returned is unspecified. +The order in which these classes are returned is unspecified. 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 < than its receiver: + + +class C; end +C.descendants # => [] + +class B < C; end +C.descendants # => [B] + +class A < B; end +C.descendants # => [B, A] + +class D < C; end +C.descendants # => [B, A, D] + + +The order in which these classes are returned is unspecified. + +NOTE: Defined in +active_support/core_ext/class/subclasses.rb+. + h3. Extensions to +String+ h4. Output Safety From d7ffa3c077e08921ea7897455084fc2942fe0977 Mon Sep 17 00:00:00 2001 From: Norman Clarke Date: Thu, 8 Jul 2010 17:43:08 -0300 Subject: [PATCH 4/5] Describe recent changes in Multibyte::Chars. --- railties/guides/source/initialization.textile | 137 +++++++++++------- 1 file changed, 81 insertions(+), 56 deletions(-) diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 9a0e23385d..7a44ef7c77 100644 --- a/railties/guides/source/initialization.textile +++ b/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: 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 -There's also these method definitions: +There are also these method definitions: - 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: +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!+ - 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? + 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 + + 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 - false + def mb_chars + if ActiveSupport::Multibyte.proxy_class.wants?(self) + ActiveSupport::Multibyte.proxy_class.new(self) + 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 end - end -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. +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. -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+. +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. -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: - - - def mb_chars - if ActiveSupport::Multibyte.proxy_class.wants?(self) - ActiveSupport::Multibyte.proxy_class.new(self) - 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 - - 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 - end - end - - - - -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)+. - -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 From c6f4c5916ef467814d970c70627a82c1df4d2686 Mon Sep 17 00:00:00 2001 From: Jaime Iniesta Date: Fri, 9 Jul 2010 17:53:47 +0200 Subject: [PATCH 5/5] Minor typos: 'built-in' instead of 'built in', 'built into' instead of 'built in to' --- activesupport/lib/active_support/core_ext/logger.rb | 2 +- railties/guides/source/index.html.erb | 2 +- railties/guides/source/layouts_and_rendering.textile | 2 +- railties/guides/source/plugins.textile | 2 +- railties/guides/source/security.textile | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/logger.rb b/activesupport/lib/active_support/core_ext/logger.rb index d023b4bcff..a1c351bfd9 100644 --- a/activesupport/lib/active_support/core_ext/logger.rb +++ b/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: diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index be077fcd2f..a930db0f1d 100644 --- a/railties/guides/source/index.html.erb +++ b/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 %> -

Guide to using built in Form helpers.

+

Guide to using built-in Form helpers.

<% end %> diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile index a874fa0ca7..f4ba6dd53b 100644 --- a/railties/guides/source/layouts_and_rendering.textile +++ b/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) diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index a12434a95b..e853ba79e9 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -1284,7 +1284,7 @@ class YaffleMigrationGenerator < Rails::Generator::NamedBase end -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. diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index b45514f66d..60108d5ab3 100644 --- a/railties/guides/source/security.textile +++ b/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. Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure. But in SQL fragments, especially in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually. +Ruby on Rails has a built-in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure. But in SQL fragments, especially in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually. Instead of passing a string to the conditions option, you can pass an array to sanitize tainted strings like this: