27

I am trying to understand code from github repo. It's the main module of the gem to setup the client.

module Github
  # more code
  class << self
    def included(base)
      base.extend ClassMethods # what would this be for?
    end
    def new(options = {}, &block)
      Client.new(options, &block)
    end
    def method_missing(method_name, *args, &block)
      if new.respond_to?(method_name)
        new.send(method_name, *args, &block)
      elsif configuration.respond_to?(method_name)
        Github.configuration.send(method_name, *args, &block)
      else
        super
      end
    end
    def respond_to?(method_name, include_private = false)
      new.respond_to?(method_name, include_private) ||
      configuration.respond_to?(method_name) ||
      super(method_name, include_private)
    end
  end

  module ClassMethods
    def require_all(prefix, *libs)
      libs.each do |lib|
        require "#{File.join(prefix, lib)}"
      end
    end
    # more methods ...
  end

  extend ClassMethods
  require_all LIBDIR,
    'authorization',
    'validations',
    'normalizer',
    'parameter_filter',
    'api',
    'client',
    'pagination',
    'request',
    'response',
    'response_wrapper',
    'error',
    'mime_type',
    'page_links',
    'paged_request',
    'page_iterator',
    'params_hash'

end
  1. Why is class << self and module ClassMethods used, and then extended instead of being included in the class << self part?
  2. There is a class method def included(base). This seems to add the class methods into a specific object. Why is it like this? It could relate to the functionality of the class, but I do not understand it.

2 Answers 2

34
module MyModule
  class << self
    def included(base)
      base.extend ClassMethods # what would this be for?
    end
    <...>
  end
  <...>
end

This is actually a pretty common practice in Ruby. Basically, what it's saying is: when some object performs include MyModule, make it also extend MyModule::ClassMethods. Such a feat is useful if you want a mixin that adds some methods not just to the instances of a class, but to the class itself.

A short example:

module M
  # A normal instance method
  def mul
    @x * @y
  end
 
  module ClassMethods
    # A class method
    def factory(x)
      new(x, 2 * x)
    end
  end
 
  def self.included(base)
    base.extend ClassMethods
  end
end
 
class P
  include M
  def initialize(x, y)
    @x = x
    @y = y
  end
 
  def sum
    @x + @y
  end
end
 
p1 = P.new(5, 15)
puts "#{p1.sum} #{p1.mul}" # <= 20 75

# Calling the class method from the module here!
p2 = P.factory(10)
puts "#{p2.sum} #{p2.mul}" # <= 30 200
4
  • 1
    That makes sense. I am a little confused about the method self.included(base), could you maybe explain what that is for and how it relates to module M or class P Commented Jun 10, 2015 at 13:37
  • 6
    when P calls include M, ruby automatically calls included on M if it is defined. It is a callback of the include method. This is use to extend the module's class methods onto P. See: ruby-doc.org/core-2.2.0/Module.html#method-i-included
    – DGM
    Commented Jun 10, 2015 at 13:48
  • 1
    Is there any chance you could point me to a practical example of this? I am still not clear on the situations it would be used in. I am sure i just need to see a practical example to understand it's true application. Commented Jun 12, 2015 at 8:54
  • 1
    Adding a note here for anyone using Sorbet. Will also need to inform Sorbet by using mixes_in_class_methods See sorbet.org/docs/abstract
    – karmakaze
    Commented Apr 16 at 17:51
4

Looking more at the repo there is another class Github::API. This class seems to require functionality of the Github::ClassMethods module.

module Github
  # Core class responsible for api interface operations
  class API
    extend Github::ClassMethods

So it makes sense that it's own own module. It gives the ability to only import those methods. If the methods from class << self were included, they would become available which is probably not wanted.

It may have been better to have the module in it's own class or named something else. But I guess that is just personal choice.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.