Class: Class

Inherits:
Object show all
Defined in:
lib/active_support/core_ext/class/subclasses.rb,
lib/active_support/core_ext/class/attribute.rb,
lib/active_support/core_ext/object/duplicable.rb,
lib/active_support/core_ext/class/attribute_accessors.rb,
lib/active_support/core_ext/class/delegating_attributes.rb,
lib/active_support/core_ext/class/inheritable_attributes.rb,
lib/active_support/core_ext/class/inheritable_attributes.rb

Overview

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.

Allows attributes to be shared within an inheritance hierarchy. Each descendant gets a copy of their parents’ attributes, instead of just a pointer to the same. This means that the child can add elements to, for example, an array without those additions being shared with either their parent, siblings, or children. This is unlike the regular class-level attributes that are shared across the entire hierarchy.

The copies of inheritable parent attributes are added to subclasses when they are created, via the inherited hook.

class Person
  class_inheritable_accessor :hair_colors
end

Person.hair_colors = [:brown, :black, :blonde, :red]
Person.hair_colors     # => [:brown, :black, :blonde, :red]
Person.new.hair_colors # => [:brown, :black, :blonde, :red]

To opt out of the instance writer method, pass :instance_writer => false. To opt out of the instance reader method, pass :instance_reader => false.

class Person
  class_inheritable_accessor :hair_colors :instance_writer => false, :instance_reader => false
end

Person.new.hair_colors = [:brown]  # => NoMethodError
Person.new.hair_colors             # => NoMethodError

Instance Method Summary collapse

Instance Method Details

#cattr_accessor(*syms, &blk) ⇒ Object 



75
76
77
78
 
# File 'lib/active_support/core_ext/class/attribute_accessors.rb', line 75

def cattr_accessor(*syms, &blk)
  cattr_reader(*syms)
  cattr_writer(*syms, &blk)
end

#cattr_reader(*syms) ⇒ Object 



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/active_support/core_ext/class/attribute_accessors.rb', line 28

def cattr_reader(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      unless defined? @@#{sym}
        @@#{sym} = nil
      end

      def self.#{sym}
        @@#{sym}
      end
    EOS

    unless options[:instance_reader] == false
      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
        def #{sym}
          @@#{sym}
        end
      EOS
    end
  end
end

#cattr_writer(*syms) ⇒ Object 



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/active_support/core_ext/class/attribute_accessors.rb', line 51

def cattr_writer(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      unless defined? @@#{sym}
        @@#{sym} = nil
      end

      def self.#{sym}=(obj)
        @@#{sym} = obj
      end
    EOS

    unless options[:instance_writer] == false
      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
        def #{sym}=(obj)
          @@#{sym} = obj
        end
      EOS
    end
    self.send("#{sym}=", yield) if block_given?
  end
end

#class_attribute(*attrs) ⇒ Object

Declare a class-level attribute whose value is inheritable by subclasses. Subclasses can change their own value and it will not impact parent class.

class Base
  class_attribute :setting
end

class Subclass < Base
end

Base.setting = true
Subclass.setting            # => true
Subclass.setting = false
Subclass.setting            # => false
Base.setting                # => true

In the above case as long as Subclass does not assign a value to setting by performing Subclass.setting = something , Subclass.setting would read value assigned to parent class. Once Subclass assigns a value then the value assigned by Subclass would be returned.

This matches normal Ruby method inheritance: think of writing an attribute on a subclass as overriding the reader method. However, you need to be aware when using class_attribute with mutable structures as Array or Hash. In such cases, you don’t want to do changes in places but use setters:

Base.setting = []
Base.setting                # => []
Subclass.setting            # => []

# Appending in child changes both parent and child because it is the same object:
Subclass.setting << :foo
Base.setting               # => [:foo]
Subclass.setting           # => [:foo]

# Use setters to not propagate changes:
Base.setting = []
Subclass.setting += [:foo]
Base.setting               # => []
Subclass.setting           # => [:foo]

For convenience, a query method is defined as well:

Subclass.setting?       # => false

Instances may overwrite the class value in the same way:

Base.setting = true
object = Base.new
object.setting          # => true
object.setting = false
object.setting          # => false
Base.setting            # => true

To opt out of the instance writer method, pass :instance_writer => false.

object.setting = false  # => NoMethodError



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/active_support/core_ext/class/attribute.rb', line 62

def class_attribute(*attrs)
  instance_writer = !attrs.last.is_a?(Hash) || attrs.pop[:instance_writer]

  attrs.each do |name|
    class_eval <<-RUBY, __FILE__, __LINE__ + 1
      def self.#{name}() nil end
      def self.#{name}?() !!#{name} end

      def self.#{name}=(val)
        singleton_class.class_eval do
          remove_possible_method(:#{name})
          define_method(:#{name}) { val }
        end
        val
      end

      def #{name}
        defined?(@#{name}) ? @#{name} : singleton_class.#{name}
      end

      def #{name}?
        !!#{name}
      end
    RUBY

    attr_writer name if instance_writer
  end
end

#class_inheritable_accessor(*syms) ⇒ Object 



107
108
109
110
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 107

def class_inheritable_accessor(*syms)
  class_inheritable_reader(*syms)
  class_inheritable_writer(*syms)
end

#class_inheritable_array(*syms) ⇒ Object 



112
113
114
115
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 112

def class_inheritable_array(*syms)
  class_inheritable_reader(*syms)
  class_inheritable_array_writer(*syms)
end

#class_inheritable_array_writer(*syms) ⇒ Object 



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 73

def class_inheritable_array_writer(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      def self.#{sym}=(obj)                          # def self.levels=(obj)
        write_inheritable_array(:#{sym}, obj)        #   write_inheritable_array(:levels, obj)
      end                                            # end
                                                     #
      #{"                                            #
      def #{sym}=(obj)                               # def levels=(obj)
        self.class.#{sym} = obj                      #   self.class.levels = obj
      end                                            # end
      " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
    EOS
  end
end

#class_inheritable_hash(*syms) ⇒ Object 



117
118
119
120
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 117

def class_inheritable_hash(*syms)
  class_inheritable_reader(*syms)
  class_inheritable_hash_writer(*syms)
end

#class_inheritable_hash_writer(*syms) ⇒ Object 



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 90

def class_inheritable_hash_writer(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      def self.#{sym}=(obj)                          # def self.nicknames=(obj)
        write_inheritable_hash(:#{sym}, obj)         #   write_inheritable_hash(:nicknames, obj)
      end                                            # end
                                                     #
      #{"                                            #
      def #{sym}=(obj)                               # def nicknames=(obj)
        self.class.#{sym} = obj                      #   self.class.nicknames = obj
      end                                            # end
      " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
    EOS
  end
end

#class_inheritable_reader(*syms) ⇒ Object

:nodoc:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 38

def class_inheritable_reader(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    next if sym.is_a?(Hash)
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      def self.#{sym}                                # def self.after_add
        read_inheritable_attribute(:#{sym})          #   read_inheritable_attribute(:after_add)
      end                                            # end
                                                     #
      #{"                                            #
      def #{sym}                                     # def after_add
        self.class.#{sym}                            #   self.class.after_add
      end                                            # end
      " unless options[:instance_reader] == false }  # # the reader above is generated unless options[:instance_reader] == false
    EOS
  end
end

#class_inheritable_writer(*syms) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 56

def class_inheritable_writer(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      def self.#{sym}=(obj)                          # def self.color=(obj)
        write_inheritable_attribute(:#{sym}, obj)    #   write_inheritable_attribute(:color, obj)
      end                                            # end
                                                     #
      #{"                                            #
      def #{sym}=(obj)                               # def color=(obj)
        self.class.#{sym} = obj                      #   self.class.color = obj
      end                                            # end
      " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
    EOS
  end
end

#descendants ⇒ Object 



9
10
11
12
13
14
15
16
 
# File 'lib/active_support/core_ext/class/subclasses.rb', line 9

def descendants
  descendants = []
  __subclasses__.each do |k|
    descendants << k
    descendants.concat k.descendants
  end
  descendants
end

#duplicable? ⇒ Boolean

Returns:

  • (Boolean) 


56
57
58
 
# File 'lib/active_support/core_ext/object/duplicable.rb', line 56

def duplicable?
  false
end

#extlib_inheritable_accessor(*syms, &block) ⇒ Array[#to_s]

Defines class-level inheritable attribute accessor. Attributes are available to subclasses, each subclass has a copy of parent’s attribute.

Parameters:

  • *syms (Array[*#to_s, Hash{:instance_writer => Boolean}]) —

    Array of attributes to define inheritable accessor for.

  • syms (Hash) —

    a customizable set of options

Options Hash (*syms):

  • :instance_writer (Boolean) —

    if true, instance-level inheritable attribute writer is defined.

Returns:

  • (Array[#to_s]) —

    An Array of attributes turned into inheritable accessors.



250
251
252
253
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 250

def extlib_inheritable_accessor(*syms, &block)
  extlib_inheritable_reader(*syms)
  extlib_inheritable_writer(*syms, &block)
end

#extlib_inheritable_reader(*ivars, &block) ⇒ Array[#to_s]

TODO:

Do we want to block instance_reader via :instance_reader => false

TODO:

It would be preferable that we do something with a Hash passed in (error out or do the same as other methods above) instead of silently moving on). In particular, this makes the return value of this function less useful.

Defines class-level inheritable attribute reader. Attributes are available to subclasses, each subclass has a copy of parent’s attribute.

Parameters:

  • *syms (Array[#to_s]) —

    Array of attributes to define inheritable reader for.

Returns:

  • (Array[#to_s]) —

    Array of attributes converted into inheritable_readers.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 187

def extlib_inheritable_reader(*ivars, &block)
  options = ivars.extract_options!

  ivars.each do |ivar|
    self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
      def self.#{ivar}
        return @#{ivar} if self.object_id == #{self.object_id} || defined?(@#{ivar})
        ivar = superclass.#{ivar}
        return nil if ivar.nil? && !#{self}.instance_variable_defined?("@#{ivar}")
        @#{ivar} = ivar.duplicable? ? ivar.dup : ivar
      end
    RUBY
    unless options[:instance_reader] == false
      self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
        def #{ivar}
          self.class.#{ivar}
        end
      RUBY
    end
    instance_variable_set(:"@#{ivar}", yield) if block_given?
  end
end

#extlib_inheritable_writer(*ivars) ⇒ Array[#to_s]

TODO:

We need a style for class_eval <<-HEREDOC. I’d like to make it class_eval(<<-RUBY, __FILE__, __LINE__), but we should codify it somewhere.

Defines class-level inheritable attribute writer. Attributes are available to subclasses, each subclass has a copy of parent’s attribute.

Parameters:

  • *syms (Array[*#to_s, Hash{:instance_writer => Boolean}]) —

    Array of attributes to define inheritable writer for.

  • syms (Hash) —

    a customizable set of options

Returns:

  • (Array[#to_s]) —

    An Array of the attributes that were made into inheritable writers.



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 222

def extlib_inheritable_writer(*ivars)
  options = ivars.extract_options!

  ivars.each do |ivar|
    self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
      def self.#{ivar}=(obj)
        @#{ivar} = obj
      end
    RUBY
    unless options[:instance_writer] == false
      self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
        def #{ivar}=(obj) self.class.#{ivar} = obj end
      RUBY
    end

    self.send("#{ivar}=", yield) if block_given?
  end
end

#inheritable_attributes ⇒ Object 



122
123
124
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 122

def inheritable_attributes
  @inheritable_attributes ||= EMPTY_INHERITABLE_ATTRIBUTES
end

#read_inheritable_attribute(key) ⇒ Object 



143
144
145
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 143

def read_inheritable_attribute(key)
  inheritable_attributes[key]
end

#reset_inheritable_attributes ⇒ Object 



147
148
149
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 147

def reset_inheritable_attributes
  @inheritable_attributes = EMPTY_INHERITABLE_ATTRIBUTES
end

#superclass_delegating_accessor(name, options = {}) ⇒ Object 



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/active_support/core_ext/class/delegating_attributes.rb', line 7

def superclass_delegating_accessor(name, options = {})
  # Create private _name and _name= methods that can still be used if the public
  # methods are overridden. This allows
  _superclass_delegating_accessor("_#{name}")

  # Generate the public methods name, name=, and name?
  # These methods dispatch to the private _name, and _name= methods, making them
  # overridable
  singleton_class.send(:define_method, name) { send("_#{name}") }
  singleton_class.send(:define_method, "#{name}?") { !!send("_#{name}") }
  singleton_class.send(:define_method, "#{name}=") { |value| send("_#{name}=", value) }

  # If an instance_reader is needed, generate methods for name and name= on the
  # class itself, so instances will be able to see them
  define_method(name) { send("_#{name}") } if options[:instance_reader] != false
  define_method("#{name}?") { !!send("#{name}") } if options[:instance_reader] != false
end

#write_inheritable_array(key, elements) ⇒ Object 



133
134
135
136
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 133

def write_inheritable_array(key, elements)
  write_inheritable_attribute(key, []) if read_inheritable_attribute(key).nil?
  write_inheritable_attribute(key, read_inheritable_attribute(key) + elements)
end

#write_inheritable_attribute(key, value) ⇒ Object 



126
127
128
129
130
131
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 126

def write_inheritable_attribute(key, value)
  if inheritable_attributes.equal?(EMPTY_INHERITABLE_ATTRIBUTES)
    @inheritable_attributes = {}
  end
  inheritable_attributes[key] = value
end

#write_inheritable_hash(key, hash) ⇒ Object 



138
139
140
141
 
# File 'lib/active_support/core_ext/class/inheritable_attributes.rb', line 138

def write_inheritable_hash(key, hash)
  write_inheritable_attribute(key, {}) if read_inheritable_attribute(key).nil?
  write_inheritable_attribute(key, read_inheritable_attribute(key).merge(hash))
end