From dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 16:28:30 +0200 Subject: Documented active_support/concern dependency handling --- activesupport/lib/active_support/concern.rb | 82 ++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index 2d87e8d0e5..6781082786 100644 --- a/activesupport/lib/active_support/concern.rb +++ b/activesupport/lib/active_support/concern.rb @@ -1,4 +1,4 @@ -# A typical module looks like this +# A typical module looks like this: # # module M # def self.included(base) @@ -17,6 +17,8 @@ # end # # By using ActiveSupport::Concern the above module could instead be written as: +# +# require 'active_support/concern' # # module M # extend ActiveSupport::Concern @@ -33,6 +35,84 @@ # def im; puts 'I am an instance method'; end # end # end +# +# Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following: +# +# module Foo +# def self.included(base) +# # Define some :enhanced_method for Host class +# base.class_eval do +# def self.enhanced_method +# # Do enhanced stuff +# end +# end +# end +# end +# +# module Bar +# def self.included(base) +# base.send(:enhanced_method) +# end +# end +# +# class Host +# include Foo # We need to include this dependency for Bar +# include Bar # Bar is the module that Host really needs +# end +# +# But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar: +# +# module Foo +# def self.included(base) +# # Define some :enhanced_method for Host class +# base.class_eval do +# def self.enhanced_method +# # Do enhanced stuff +# end +# end +# end +# end +# +# module Bar +# include Foo +# def self.included(base) +# base.send(:enhanced_method) +# end +# end +# +# class Host +# include Bar +# end +# +# Unfortunately this won't work, since when Foo is included, its base is Bar module, not Host class. +# With ActiveSupport::Concern, module dependencies are properly resolved: +# +# require 'active_support/concern' +# +# module Foo +# extend ActiveSupport::Concern +# included do +# class_eval do +# def self.enhanced_method +# # Do enhanced stuff +# end +# end +# end +# end +# +# module Bar +# extend ActiveSupport::Concern +# include Foo +# +# included do +# self.send(:enhanced_method) +# end +# end +# +# class Host +# include Bar # Host only needs to care about Bar without needing to know about its dependencies +# end +# module ActiveSupport module Concern def self.extended(base) -- cgit v1.2.3 From b5175566af8d77ee990fa70e262c8b05119add49 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 16:52:05 +0200 Subject: Documentation just before Concern module --- activesupport/lib/active_support/concern.rb | 230 ++++++++++++++-------------- 1 file changed, 115 insertions(+), 115 deletions(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index 6781082786..d1e03e596c 100644 --- a/activesupport/lib/active_support/concern.rb +++ b/activesupport/lib/active_support/concern.rb @@ -1,119 +1,119 @@ -# A typical module looks like this: -# -# module M -# def self.included(base) -# base.send(:extend, ClassMethods) -# base.send(:include, InstanceMethods) -# scope :foo, :conditions => { :created_at => nil } -# end -# -# module ClassMethods -# def cm; puts 'I am a class method'; end -# end -# -# module InstanceMethods -# def im; puts 'I am an instance method'; end -# end -# end -# -# By using ActiveSupport::Concern the above module could instead be written as: -# -# require 'active_support/concern' -# -# module M -# extend ActiveSupport::Concern -# -# included do -# scope :foo, :conditions => { :created_at => nil } -# end -# -# module ClassMethods -# def cm; puts 'I am a class method'; end -# end -# -# module InstanceMethods -# def im; puts 'I am an instance method'; end -# end -# end -# -# Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following: -# -# module Foo -# def self.included(base) -# # Define some :enhanced_method for Host class -# base.class_eval do -# def self.enhanced_method -# # Do enhanced stuff -# end -# end -# end -# end -# -# module Bar -# def self.included(base) -# base.send(:enhanced_method) -# end -# end -# -# class Host -# include Foo # We need to include this dependency for Bar -# include Bar # Bar is the module that Host really needs -# end -# -# But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar: -# -# module Foo -# def self.included(base) -# # Define some :enhanced_method for Host class -# base.class_eval do -# def self.enhanced_method -# # Do enhanced stuff -# end -# end -# end -# end -# -# module Bar -# include Foo -# def self.included(base) -# base.send(:enhanced_method) -# end -# end -# -# class Host -# include Bar -# end -# -# Unfortunately this won't work, since when Foo is included, its base is Bar module, not Host class. -# With ActiveSupport::Concern, module dependencies are properly resolved: -# -# require 'active_support/concern' -# -# module Foo -# extend ActiveSupport::Concern -# included do -# class_eval do -# def self.enhanced_method -# # Do enhanced stuff -# end -# end -# end -# end -# -# module Bar -# extend ActiveSupport::Concern -# include Foo -# -# included do -# self.send(:enhanced_method) -# end -# end -# -# class Host -# include Bar # Host only needs to care about Bar without needing to know about its dependencies -# end -# module ActiveSupport + # A typical module looks like this: + # + # module M + # def self.included(base) + # base.send(:extend, ClassMethods) + # base.send(:include, InstanceMethods) + # scope :foo, :conditions => { :created_at => nil } + # end + # + # module ClassMethods + # def cm; puts 'I am a class method'; end + # end + # + # module InstanceMethods + # def im; puts 'I am an instance method'; end + # end + # end + # + # By using ActiveSupport::Concern the above module could instead be written as: + # + # require 'active_support/concern' + # + # module M + # extend ActiveSupport::Concern + # + # included do + # scope :foo, :conditions => { :created_at => nil } + # end + # + # module ClassMethods + # def cm; puts 'I am a class method'; end + # end + # + # module InstanceMethods + # def im; puts 'I am an instance method'; end + # end + # end + # + # Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following: + # + # module Foo + # def self.included(base) + # # Define some :enhanced_method for Host class + # base.class_eval do + # def self.enhanced_method + # # Do enhanced stuff + # end + # end + # end + # end + # + # module Bar + # def self.included(base) + # base.send(:enhanced_method) + # end + # end + # + # class Host + # include Foo # We need to include this dependency for Bar + # include Bar # Bar is the module that Host really needs + # end + # + # But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar: + # + # module Foo + # def self.included(base) + # # Define some :enhanced_method for Host class + # base.class_eval do + # def self.enhanced_method + # # Do enhanced stuff + # end + # end + # end + # end + # + # module Bar + # include Foo + # def self.included(base) + # base.send(:enhanced_method) + # end + # end + # + # class Host + # include Bar + # end + # + # Unfortunately this won't work, since when Foo is included, its base is Bar module, not Host class. + # With ActiveSupport::Concern, module dependencies are properly resolved: + # + # require 'active_support/concern' + # + # module Foo + # extend ActiveSupport::Concern + # included do + # class_eval do + # def self.enhanced_method + # # Do enhanced stuff + # end + # end + # end + # end + # + # module Bar + # extend ActiveSupport::Concern + # include Foo + # + # included do + # self.send(:enhanced_method) + # end + # end + # + # class Host + # include Bar # Host only needs to care about Bar without needing to know about its dependencies + # end + # module Concern def self.extended(base) base.instance_variable_set("@_dependencies", []) -- cgit v1.2.3 From 25145d6f5f173dbba2945ab2b4fffa5a67785bb5 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 17:01:11 +0200 Subject: Documented active_support/configurable --- activesupport/lib/active_support/configurable.rb | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index a0c9c9e33a..5b85f9394a 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -4,6 +4,8 @@ require 'active_support/core_ext/kernel/singleton_class' require 'active_support/core_ext/module/delegation' module ActiveSupport + # Configurable provides a config method to store and retrieve + # configuration options as an OrderedHash. module Configurable extend ActiveSupport::Concern @@ -29,8 +31,25 @@ module ActiveSupport end end + # Reads and writes attributes from a configuration OrderedHash. + # + # require 'active_support/configurable' + # + # class User + # include ActiveSupport::Configurable + # end + # + # user = User.new + # + # user.config.allowed_access = true + # user.config.level = 1 + # + # user.config.allowed_access # => true + # user.config.level # => 1 + # def config @_config ||= ActiveSupport::InheritableOptions.new(self.class.config) end end -end \ No newline at end of file +end + -- cgit v1.2.3 From d6fd0f7fa7372dff9782fdc303bf5324faca9228 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 14 Aug 2010 17:04:17 +0200 Subject: reviews commit dcc9d38 --- activesupport/lib/active_support/concern.rb | 54 ++++++++++++----------------- 1 file changed, 22 insertions(+), 32 deletions(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index d1e03e596c..ac94d12e5e 100644 --- a/activesupport/lib/active_support/concern.rb +++ b/activesupport/lib/active_support/concern.rb @@ -3,48 +3,48 @@ module ActiveSupport # # module M # def self.included(base) - # base.send(:extend, ClassMethods) + # base.extend, ClassMethods # base.send(:include, InstanceMethods) - # scope :foo, :conditions => { :created_at => nil } + # scope :disabled, where(:disabled => true) # end # # module ClassMethods - # def cm; puts 'I am a class method'; end + # ... # end # # module InstanceMethods - # def im; puts 'I am an instance method'; end + # ... # end # end # # By using ActiveSupport::Concern the above module could instead be written as: - # + # # require 'active_support/concern' # # module M # extend ActiveSupport::Concern # # included do - # scope :foo, :conditions => { :created_at => nil } + # scope :disabled, where(:disabled => true) # end # # module ClassMethods - # def cm; puts 'I am a class method'; end + # ... # end # # module InstanceMethods - # def im; puts 'I am an instance method'; end + # ... # end # end # - # Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following: + # Moreover, it gracefully handles module dependencies. Given a +Foo+ module and a +Bar+ + # module which depends on the former, we would typically write the following: # # module Foo # def self.included(base) - # # Define some :enhanced_method for Host class # base.class_eval do - # def self.enhanced_method - # # Do enhanced stuff + # def self.method_injected_by_foo + # ... # end # end # end @@ -52,7 +52,7 @@ module ActiveSupport # # module Bar # def self.included(base) - # base.send(:enhanced_method) + # base.method_injected_by_foo # end # end # @@ -61,23 +61,13 @@ module ActiveSupport # include Bar # Bar is the module that Host really needs # end # - # But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar: - # - # module Foo - # def self.included(base) - # # Define some :enhanced_method for Host class - # base.class_eval do - # def self.enhanced_method - # # Do enhanced stuff - # end - # end - # end - # end + # But why should +Host+ care about +Bar+'s dependencies, namely +Foo+? We could try to hide + # these from +Host+ directly including +Foo+ in +Bar+: # # module Bar # include Foo # def self.included(base) - # base.send(:enhanced_method) + # base.method_injected_by_foo # end # end # @@ -85,8 +75,8 @@ module ActiveSupport # include Bar # end # - # Unfortunately this won't work, since when Foo is included, its base is Bar module, not Host class. - # With ActiveSupport::Concern, module dependencies are properly resolved: + # Unfortunately this won't work, since when +Foo+ is included, its base is the +Bar+ module, + # not the +Host+ class. With ActiveSupport::Concern, module dependencies are properly resolved: # # require 'active_support/concern' # @@ -94,8 +84,8 @@ module ActiveSupport # extend ActiveSupport::Concern # included do # class_eval do - # def self.enhanced_method - # # Do enhanced stuff + # def self.method_injected_by_foo + # ... # end # end # end @@ -106,12 +96,12 @@ module ActiveSupport # include Foo # # included do - # self.send(:enhanced_method) + # self.method_injected_by_foo # end # end # # class Host - # include Bar # Host only needs to care about Bar without needing to know about its dependencies + # include Bar # works, Bar takes care now of its dependencies # end # module Concern -- cgit v1.2.3 From f480b2cea69247239f6fc2ad171b231595cc08c6 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 17:15:03 +0200 Subject: Add example label to activesupport/configurable --- activesupport/lib/active_support/configurable.rb | 2 ++ 1 file changed, 2 insertions(+) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index 5b85f9394a..3bfbd7f7d6 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -33,6 +33,8 @@ module ActiveSupport # Reads and writes attributes from a configuration OrderedHash. # + # Example: + # # require 'active_support/configurable' # # class User -- cgit v1.2.3 From 693f770afe0e14fc1b4658ef51910d993e67dd07 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 17:19:04 +0200 Subject: Add example label to active_support/configurable --- activesupport/lib/active_support/configurable.rb | 1 - 1 file changed, 1 deletion(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index 3bfbd7f7d6..61c4b1be02 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -32,7 +32,6 @@ module ActiveSupport end # Reads and writes attributes from a configuration OrderedHash. - # # Example: # # require 'active_support/configurable' -- cgit v1.2.3 From 68e1b72f7a7ac88a0f0287d856d36f1d317ed8f3 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 17:52:52 +0200 Subject: Whitespace and example identation --- activesupport/lib/active_support/lazy_load_hooks.rb | 14 +++++++------- activesupport/lib/active_support/log_subscriber.rb | 4 ++-- activesupport/lib/active_support/rescuable.rb | 1 + activesupport/lib/active_support/secure_random.rb | 14 ++++++++++---- activesupport/lib/active_support/time_with_zone.rb | 2 ++ 5 files changed, 22 insertions(+), 13 deletions(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/lazy_load_hooks.rb b/activesupport/lib/active_support/lazy_load_hooks.rb index 3b8696b5c7..82507c1e03 100644 --- a/activesupport/lib/active_support/lazy_load_hooks.rb +++ b/activesupport/lib/active_support/lazy_load_hooks.rb @@ -5,17 +5,17 @@ # # Here is an example where +on_load+ method is called to register a hook. # -# initializer "active_record.initialize_timezone" do -# ActiveSupport.on_load(:active_record) do -# self.time_zone_aware_attributes = true -# self.default_timezone = :utc -# end -# end +# initializer "active_record.initialize_timezone" do +# ActiveSupport.on_load(:active_record) do +# self.time_zone_aware_attributes = true +# self.default_timezone = :utc +# end +# end # # When the entirety of +activerecord/lib/active_record/base.rb+ has been evaluated then +run_load_hooks+ is invoked. # The very last line of +activerecord/lib/active_record/base.rb+ is: # -# ActiveSupport.run_load_hooks(:active_record, ActiveRecord::Base) +# ActiveSupport.run_load_hooks(:active_record, ActiveRecord::Base) # module ActiveSupport @load_hooks = Hash.new {|h,k| h[k] = [] } diff --git a/activesupport/lib/active_support/log_subscriber.rb b/activesupport/lib/active_support/log_subscriber.rb index 63c0470d3f..49f7513193 100644 --- a/activesupport/lib/active_support/log_subscriber.rb +++ b/activesupport/lib/active_support/log_subscriber.rb @@ -4,7 +4,7 @@ require 'active_support/core_ext/class/attribute' module ActiveSupport # ActiveSupport::LogSubscriber is an object set to consume ActiveSupport::Notifications # with solely purpose of logging. The log subscriber dispatches notifications to a - # regirested object based on its given namespace. + # registered object based on its given namespace. # # An example would be Active Record log subscriber responsible for logging queries: # @@ -16,7 +16,7 @@ module ActiveSupport # end # end # - # And it's finally registed as: + # And it's finally registered as: # # ActiveRecord::LogSubscriber.attach_to :active_record # diff --git a/activesupport/lib/active_support/rescuable.rb b/activesupport/lib/active_support/rescuable.rb index cd6f92cdfe..0f4a06468a 100644 --- a/activesupport/lib/active_support/rescuable.rb +++ b/activesupport/lib/active_support/rescuable.rb @@ -47,6 +47,7 @@ module ActiveSupport # exception.record.new_record? ? ... # end # end + # def rescue_from(*klasses, &block) options = klasses.extract_options! diff --git a/activesupport/lib/active_support/secure_random.rb b/activesupport/lib/active_support/secure_random.rb index 73344498cb..488a7e14a7 100644 --- a/activesupport/lib/active_support/secure_random.rb +++ b/activesupport/lib/active_support/secure_random.rb @@ -46,8 +46,10 @@ module ActiveSupport # p SecureRandom.random_bytes(10) # => "\016\t{\370g\310pbr\301" # p SecureRandom.random_bytes(10) # => "\323U\030TO\234\357\020\a\337" # ... + # module SecureRandom - # SecureRandom.random_bytes generates a random binary string. + + # Generates a random binary string. # # The argument n specifies the length of the result string. # @@ -56,6 +58,7 @@ module ActiveSupport # # If secure random number generator is not available, # NotImplementedError is raised. + # def self.random_bytes(n=nil) n ||= 16 @@ -124,7 +127,7 @@ module ActiveSupport raise NotImplementedError, "No random device" end - # SecureRandom.hex generates a random hex string. + # Generates a random hex string. # # The argument n specifies the length of the random length. # The length of the result string is twice of n. @@ -134,11 +137,12 @@ module ActiveSupport # # If secure random number generator is not available, # NotImplementedError is raised. + # def self.hex(n=nil) random_bytes(n).unpack("H*")[0] end - # SecureRandom.base64 generates a random base64 string. + # Generates a random base64 string. # # The argument n specifies the length of the random length. # The length of the result string is about 4/3 of n. @@ -148,11 +152,12 @@ module ActiveSupport # # If secure random number generator is not available, # NotImplementedError is raised. + # def self.base64(n=nil) [random_bytes(n)].pack("m*").delete("\n") end - # SecureRandom.random_number generates a random number. + # Generates a random number. # # If an positive integer is given as n, # SecureRandom.random_number returns an integer: @@ -161,6 +166,7 @@ module ActiveSupport # If 0 is given or an argument is not given, # SecureRandom.random_number returns an float: # 0.0 <= SecureRandom.random_number() < 1.0. + # def self.random_number(n=0) if 0 < n hex = n.to_s(16) diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb index 48c7990b1e..93f5d5a0cc 100644 --- a/activesupport/lib/active_support/time_with_zone.rb +++ b/activesupport/lib/active_support/time_with_zone.rb @@ -32,6 +32,7 @@ module ActiveSupport # t > Time.utc(1999) # => true # t.is_a?(Time) # => true # t.is_a?(ActiveSupport::TimeWithZone) # => true + # class TimeWithZone def self.name 'Time' # Report class name as 'Time' to thwart type checking @@ -127,6 +128,7 @@ module ActiveSupport # # With ActiveSupport::JSON::Encoding.use_standard_json_time_format = false # Time.utc(2005,2,1,15,15,10).in_time_zone.to_json # # => "2005/02/01 15:15:10 +0000" + # def as_json(options = nil) if ActiveSupport::JSON::Encoding.use_standard_json_time_format xmlschema -- cgit v1.2.3 From f725ae3fef6cd4706f263cfc4be9a6869149c4c9 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 14 Aug 2010 18:34:32 +0200 Subject: Revert "Add example label to active_support/configurable" This reverts commit 693f770afe0e14fc1b4658ef51910d993e67dd07. Reason: to be able to revert f480b2cea69247239f6fc2ad171b231595cc08c6 --- activesupport/lib/active_support/configurable.rb | 1 + 1 file changed, 1 insertion(+) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index 61c4b1be02..3bfbd7f7d6 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -32,6 +32,7 @@ module ActiveSupport end # Reads and writes attributes from a configuration OrderedHash. + # # Example: # # require 'active_support/configurable' -- cgit v1.2.3 From 0d5a060710de0642d5e1538cd6a2de6a24bc77e0 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 14 Aug 2010 18:35:01 +0200 Subject: Revert "Add example label to activesupport/configurable" This reverts commit f480b2cea69247239f6fc2ad171b231595cc08c6. Reason: API guidelines discourage this, see http://edgeguides.rubyonrails.org/api_documentation_guidelines.html#example-code --- activesupport/lib/active_support/configurable.rb | 2 -- 1 file changed, 2 deletions(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index 3bfbd7f7d6..5b85f9394a 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -33,8 +33,6 @@ module ActiveSupport # Reads and writes attributes from a configuration OrderedHash. # - # Example: - # # require 'active_support/configurable' # # class User -- cgit v1.2.3 From 2ad3d96cb03faef1bac9c1678a7306c19e725636 Mon Sep 17 00:00:00 2001 From: Santiago Pastorino Date: Sun, 15 Aug 2010 08:43:44 -0300 Subject: recommended is the right word here --- .../lib/active_support/core_ext/class/inheritable_attributes.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'activesupport') diff --git a/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb b/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb index 6283bd0981..7a6a0be69d 100644 --- a/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb +++ b/activesupport/lib/active_support/core_ext/class/inheritable_attributes.rb @@ -5,7 +5,7 @@ require 'active_support/core_ext/array/extract_options' module ClassInheritableAttributes # :nodoc: end -# It is recommend to use class_attribute over methods defined in this file. Please +# It is recommended to use class_attribute over methods defined in this file. Please # refer to documentation for class_attribute for more information. Officially it is not # deprecated but class_attribute is faster. # -- cgit v1.2.3