Class: Class

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

Overview

Extends the class object with class and instance accessors for class attributes, just like the native attr* accessors for instance attributes.

Instance Method Summary collapse

Instance Method Details

#cattr_accessor(*syms, &blk) ⇒ Object

Defines both class and instance accessors for class attributes.

class Person
  cattr_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]

If a subclass changes the value then that would also change the value for parent class. Similarly if parent class changes the value then that would change the value of subclasses too.

class Male < Person
end

Male.hair_colors << :blue
Person.hair_colors # => [:brown, :black, :blonde, :red, :blue]

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
  cattr_accessor :hair_colors, instance_writer: false, instance_reader: false
end

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

Or pass instance_accessor: false, to opt out both instance methods.

class Person
  cattr_accessor :hair_colors, instance_accessor: false
end

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

Also you can pass a block to set up the attribute with a default value.

class Person
  cattr_accessor :hair_colors do
    [:brown, :black, :blonde, :red]
  end
end

Person.class_variable_get("@@hair_colors") #=> [:brown, :black, :blonde, :red]



166
167
168
169
 
# File 'activesupport/lib/active_support/core_ext/class/attribute_accessors.rb', line 166

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

#cattr_reader(*syms) ⇒ Object

Defines a class attribute if it’s not defined and creates a reader method that returns the attribute value.

class Person
  cattr_reader :hair_colors
end

Person.class_variable_set("@@hair_colors", [:brown, :black])
Person.hair_colors     # => [:brown, :black]
Person.new.hair_colors # => [:brown, :black]

The attribute name must be a valid method name in Ruby.

class Person
  cattr_reader :"1_Badname "
end
# => NameError: invalid attribute name

If you want to opt out the instance reader method, you can pass instance_reader: false or instance_accessor: false.

class Person
  cattr_reader :hair_colors, instance_reader: false
end

Person.new.hair_colors # => NoMethodError



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'activesupport/lib/active_support/core_ext/class/attribute_accessors.rb', line 32

def cattr_reader(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    raise NameError.new("invalid class attribute name: #{sym}") unless sym =~ /^[_A-Za-z]\w*$/
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      unless defined? @@#{sym}
        @@#{sym} = nil
      end

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

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

#cattr_writer(*syms) ⇒ Object

Defines a class attribute if it’s not defined and creates a writer method to allow assignment to the attribute.

class Person
  cattr_writer :hair_colors
end

Person.hair_colors = [:brown, :black]
Person.class_variable_get("@@hair_colors") # => [:brown, :black]
Person.new.hair_colors = [:blonde, :red]
Person.class_variable_get("@@hair_colors") # => [:blonde, :red]

The attribute name must be a valid method name in Ruby.

class Person
  cattr_writer :"1_Badname "
end
# => NameError: invalid attribute name

If you want to opt out the instance writer method, pass instance_writer: false or instance_accessor: false.

class Person
  cattr_writer :hair_colors, instance_writer: false
end

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

Also, you can pass a block to set up the attribute with a default value.

class Person
  cattr_writer :hair_colors do
    [:brown, :black, :blonde, :red]
  end
end

Person.class_variable_get("@@hair_colors") # => [:brown, :black, :blonde, :red]



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'activesupport/lib/active_support/core_ext/class/attribute_accessors.rb', line 93

def cattr_writer(*syms)
  options = syms.extract_options!
  syms.each do |sym|
    raise NameError.new("invalid class attribute name: #{sym}") unless sym =~ /^[_A-Za-z]\w*$/
    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 || options[:instance_accessor] == false
      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
        def #{sym}=(obj)
          @@#{sym} = obj
        end
      EOS
    end
    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, 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.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
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
 
# File 'activesupport/lib/active_support/core_ext/class/attribute.rb', line 71

def class_attribute(*attrs)
  options = attrs.extract_options!
  instance_reader = options.fetch(:instance_accessor, true) && options.fetch(:instance_reader, true)
  instance_writer = options.fetch(:instance_accessor, true) && options.fetch(:instance_writer, true)
  instance_predicate = options.fetch(:instance_predicate, true)

  attrs.each do |name|
    define_singleton_method(name) { nil }
    define_singleton_method("#{name}?") { !!public_send(name) } if instance_predicate

    ivar = "@#{name}"

    define_singleton_method("#{name}=") do |val|
      singleton_class.class_eval do
        remove_possible_method(name)
        define_method(name) { val }
      end

      if singleton_class?
        class_eval do
          remove_possible_method(name)
          define_method(name) do
            if instance_variable_defined? ivar
              instance_variable_get ivar
            else
              singleton_class.send name
            end
          end
        end
      end
      val
    end

    if instance_reader
      remove_possible_method name
      define_method(name) do
        if instance_variable_defined?(ivar)
          instance_variable_get ivar
        else
          self.class.public_send name
        end
      end
      define_method("#{name}?") { !!public_send(name) } if instance_predicate
    end

    attr_writer name if instance_writer
  end
end

#subclasses ⇒ Object

Returns an array with the direct children of self.

Integer.subclasses # => [Fixnum, Bignum]

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

Foo.subclasses # => [Bar]



35
36
37
38
39
40
41
 
# File 'activesupport/lib/active_support/core_ext/class/subclasses.rb', line 35

def subclasses
  subclasses, chain = [], descendants
  chain.each do |k|
    subclasses << k unless chain.any? { |c| c > k }
  end
  subclasses
end

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



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

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