Class: Class

Inherits:
Object show all
Includes:
ActiveSupport::DescendantsTracker::ReloadedClassesFiltering
Defined in:
lib/active_support/core_ext/class/attribute.rb,
lib/active_support/core_ext/class/subclasses.rb

Instance Method Summary collapse

Instance Method Details

#class_attribute(*attrs, instance_accessor: true, instance_reader: instance_accessor, instance_writer: instance_accessor, instance_predicate: true, default: nil) ⇒ 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.

Options

  • :instance_reader - Sets the instance reader method (defaults to true).

  • :instance_writer - Sets the instance writer method (defaults to true).

  • :instance_accessor - Sets both instance methods (defaults to true).

  • :instance_predicate - Sets a predicate method (defaults to true).

  • :default - Sets a default value for the attribute (defaults to nil).

Examples

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 place. Instead 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, an instance predicate method is defined as well. To skip it, pass instance_predicate: false.

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 reader method, pass instance_reader: false.

object.setting          # => NoMethodError
object.setting?         # => NoMethodError

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

object.setting = false  # => NoMethodError

To opt out of both instance methods, pass instance_accessor: false.

To set a default value for the attribute, pass default:, like so:

class_attribute :settings, default: {}


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
# File 'lib/active_support/core_ext/class/attribute.rb', line 85

def class_attribute(*attrs, instance_accessor: true,
  instance_reader: instance_accessor, instance_writer: instance_accessor, instance_predicate: true, default: nil)

  class_methods, methods = [], []
  attrs.each do |name|
    unless name.is_a?(Symbol) || name.is_a?(String)
      raise TypeError, "#{name.inspect} is not a symbol nor a string"
    end

    class_methods << <<~RUBY # In case the method exists and is not public
      silence_redefinition_of_method def #{name}
      end
    RUBY

    methods << <<~RUBY if instance_reader
      silence_redefinition_of_method def #{name}
        defined?(@#{name}) ? @#{name} : self.class.#{name}
      end
    RUBY

    class_methods << <<~RUBY
      silence_redefinition_of_method def #{name}=(value)
        redefine_method(:#{name}) { value } if singleton_class?
        redefine_singleton_method(:#{name}) { value }
        value
      end
    RUBY

    methods << <<~RUBY if instance_writer
      silence_redefinition_of_method(:#{name}=)
      attr_writer :#{name}
    RUBY

    if instance_predicate
      class_methods << "silence_redefinition_of_method def #{name}?; !!self.#{name}; end"
      if instance_reader
        methods << "silence_redefinition_of_method def #{name}?; !!self.#{name}; end"
      end
    end
  end

  location = caller_locations(1, 1).first
  class_eval(["class << self", *class_methods, "end", *methods].join(";").tr("\n", ";"), location.path, location.lineno)

  attrs.each { |name| public_send("#{name}=", default) }
end

#descendantsObject

Returns an array with 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]


21
22
23
# File 'lib/active_support/core_ext/class/subclasses.rb', line 21

def descendants
  subclasses.concat(subclasses.flat_map(&:descendants))
end

#subclassesObject

Returns an array with the direct children of self.

class Foo; end
class Bar < Foo; end
class Baz < Bar; end

Foo.subclasses # => [Bar]


38
39
40
# File 'lib/active_support/core_ext/class/subclasses.rb', line 38

def subclasses
  descendants.select { |descendant| descendant.superclass == self }
end