In Ruby, why are class methods really singleton methods, and what does class << self open inside a class body?

## A class is an object In Ruby, `class Report; end` creates an object: an instance of `Class`, assigned to the constant `Report`. Calling `Report.new` or `Report.build` is an ordinary method call on that object. The question is where such methods live, since they must not become methods of every other class. The answer is the same as for any other object with methods of its own: the **singleton class**. Every class object has one, and it holds the class's class methods. "Class method" is a name for a role, not a separate mechanism. ## Two ways to write into the singleton class | Form | What it does | |---|---| | `def self.build` in the class body | defines `build` in `Report`'s singleton class, because `self` is `Report` there | | `def build` inside `class << self` | the same, written inside the singleton class's own body | Both produce the same result: - `Report.singleton_methods` includes `:build`; - `Report.singleton_class.instance_methods(false)` includes `:build`; - `Report.new.respond_to?(:build)` is `false`. ## What class << self adds `class << obj` opens the singleton class of `obj` as a class body; inside a class body, `self` is the class, so `class << self` opens the class's singleton class. Inside it, the usual class-body tools act at **class level**: 1. **`attr_accessor`, `attr_reader`, `attr_writer`** create class-level accessors: `Report.config = {...}` and `Report.config`. 2. **`private` and `protected`** without arguments affect the following `def`s, giving private class methods. 3. **`alias_method`** and **`define_method`** operate on class methods. 4. **Grouping**: many class methods sit together without repeating `self.`. ## The private trap A bare `private` in the class body changes the default visibility of later **instance** methods. `def self.x` does not define an instance method, so it stays public: ```ruby class Report private def self.secret = :still_public end Report.secret # => :still_public ``` Writing `private def self.secret` is worse: `private` receives `:secret` and looks for an instance method of that name, so it raises `NameError`. The two correct forms are `private` inside `class << self`, or `private_class_method :secret` after the definition. ## Inheritance of class methods When `Subreport < Report`, Ruby arranges that `Subreport`'s singleton class inherits from `Report`'s singleton class. So `Subreport.build` finds `Report.build`, `super` inside a redefined class method reaches the parent's version, and `Subreport.singleton_methods` includes the inherited ones unless you pass `false`. ## Looking at the singleton class directly The singleton class is an ordinary `Class` object you can hold in a variable: - `Report.singleton_class` returns it; it inspects as `#<Class:Report>`. - `Report.singleton_class.instance_methods(false)` lists the public and protected class methods `Report` defines itself. - `Report.singleton_class.private_instance_methods(false)` lists private class methods, which `singleton_methods` leaves out. A `class << self` body, like any class body, returns the value of its last expression, so `class << self; self; end` evaluates to the singleton class itself. Older code used that expression to reach the singleton class; `singleton_class` says the same thing directly. ## Choosing a style - `def self.x` is the most common and the easiest to grep. - `class << self` pays off when you need class-level accessors, private class methods, or a long group of class methods. - Mixing both in one class is legal but makes readers look in two places. ## Mistakes to avoid - Describing class methods as a separate kind of method stored in the class itself. - Expecting a bare `private` in the class body to hide `def self.x`. - Writing `private def self.x` and getting `NameError`. - Forgetting that `attr_accessor` inside `class << self` creates class-level, not instance-level, accessors. - Thinking subclasses must redefine class methods to use them.