Ruby Classes Within Classes (Or Modules Within Modules)

When to use nested classes and classes nested in modules?

Other OOP languages have inner classes which cannot be instantiated without being bound to an upper level class. For instance, in Java,

class Car {
    class Wheel { }
}

only methods in the Car class can create Wheels.

Ruby doesn’t have that behaviour.

In Ruby,

class Car
  class Wheel
  end
end

differs from

class Car
end

class Wheel
end

only in the name of the class Wheel vs. Car::Wheel. This difference in name can make explicit to programmers that the Car::Wheel class can only represent a car wheel, as opposed to a general wheel. Nesting class definitions in Ruby is a matter of preference, but it serves a purpose in the sense that it more strongly enforces a contract between the two classes and in doing so conveys more information about them and their uses.

But to the Ruby interpreter, it’s only a difference in name.

As for your second observation, classes nested inside of modules are generally used to namespace the classes. For instance:

module ActiveRecord
  class Base
  end
end

differs from

module ActionMailer
  class Base
  end
end

Although this is not the only use of classes nested inside of modules, it is generally the most common.

Ruby Classes within Classes (or Modules within Modules)

When the interpreter is going through this file, it is assigning classes like this:

OuterClass = Class.new do 
  def foobar
    puts "FOOBAR"
  end

  InnerClass = Class.new do   
    def barfoo
      puts "BARFOO"
    end
  end
end

So when Ruby encounters the nested class, it assigns it to constant InnerClass which is assigned to constant OuterClass They have no relation to each other whatsoever.

The InnerClass has no inheritance to OuterClass:

  InnerClass.ancestors
  => [InnerClass, Object, Kernel, BasicObject]

When you call OuterClass::InnerClass constant you are refering to the InnerClass constant that is namespaced under the OuterClass contstant which equals the Class.new statement assigned to it.

A good book to read about this is "Metaprogramming Ruby". It goes into the details of classes, singletons, modules etc.

Why can't ruby classes inside modules have the same scope as regular classes?

I have a module with a class inside,

No, you don't. You have a module definition with a class definition inside, but that does not make the class a nested class. Ruby does not have nested classes.

Ruby is not Beta, Scala, or Newspeak, there are no nested classes in Ruby.

Nesting a module or class definition inside another module or class definition does not create nesting relationship between the two classes / modules. It only makes the constant which references the class / module part of the outer class' / module's namespace.

In other words, there is no difference between

module Foo
  class Bar
  end
end

and

class Quux
end

module Foo
  Bar = Quux
end

Only the constant is nested, but not the object that is referenced by the constant.

but I find that the class inside can't reach any of the methods in the enclosing module without specifying the module path.

That is precisely because there is no "enclosing module". There is a lexically enclosing module definition but that does not create any form of relationship whatsoever between the Foo class and the MyMod module.

Another way to look at it is that the module_function doesn't seem to carry into the class.

I honestly don't understand what you mean by that, what it means for a method to "carry into a class", but Module#module_function is not magic. It does exactly what the documentation says it does: it takes an instance method of the module, copies it as an instance method of the singleton class of the module, and makes the original instance method private.

You can read its specification in the Ruby/Spec, it is fairly simple. Also, the Rubinius source code, both the basic version for booting the Rubinius kernel and the full version are fairly readable.

In the end, Module#module_function really does not do much more than

class Module
  def module_function(*meths)
    meths.each do |meth|
      define_singleton_method(meth, &instance_method(meth).bind(self))
      private meth
    end

    self
  end
end

If you run this, you get an error on the "But I can't..." line of:
undefined local variable or method `meaning'

The reason is simple: neither the class Foo nor any of its superclasses has any method of that name, so of course you get an exception.

But if you remove the MyMod bits around the whole file, it has no problem accessing the outer method.

There is no "outer method". Ruby does not have Beta-like nested classes. That is really the fundamental cause of your misunderstanding. You expect Ruby to behave like Beta, but it just doesn't. Ruby takes inspiration from any languages, most notably (in rough order of importance) Smalltalk, Lisp, Perl, and Clu, but Beta is not among them.

This here works for a completely different reason:

def meaning
  42
end

class Foo
  def initialize
    meaning
  end
end

Methods that are defined at the top-level are implicitly defined as private instance methods of Object. This is because the default definee at the top-level is ::Object. Since Foo inherits from Object, method lookup will eventually find the meaning method defined in Object.

Is there an easy way to make these accessible without having to give the full path?

Inheritance. For example, Module#append_features, which is called by Module#include, makes the module the superclass of the including class, and thus all instance methods of the module become part of the method lookup ancestry chain.

An aside: if there is no nesting, then what does Module::nesting do? Well, yeah, that is an unfortunately named method. The term "nested class" or "nested module" has a well-defined meaning in OO going all the way back to Beta. But this method is about a completely different kind of nesting:

It refers to the lexical nesting of module definitions, and not to nesting of modules themselves.

For example, these module definitions all define the exact same module, but the definition text has different nesting:

module Foo
  module Bar
    module Baz
      module Qux
        p Module.nesting
        #=> [Foo::Bar::Baz::Qux, Foo::Bar::Baz, Foo::Bar, Foo]
      end
    end
  end
end

module Foo
  module Bar
    module Baz::Qux
      p Module.nesting
      #=> [Foo::Bar::Baz::Qux, Foo::Bar, Foo]
    end
  end
end

module Foo
  module Bar::Baz
    module Qux
      p Module.nesting
      #=> [Foo::Bar::Baz::Qux, Foo::Bar::Baz, Foo]
    end
  end
end

module Foo::Bar
  module Baz
    module Qux
      p Module.nesting
      #=> [Foo::Bar::Baz::Qux, Foo::Bar::Baz, Foo::Bar]
    end
  end
end

module Foo
  module Bar::Baz::Qux
    p Module.nesting
    #=> [Foo::Bar::Baz::Qux, Foo]
  end
end

module Foo::Bar::Baz
  module Qux
    p Module.nesting
    #=> [Foo::Bar::Baz::Qux, Foo::Bar::Baz]
  end
end

module Foo::Bar
  module Baz::Qux
    p Module.nesting
    #=> [Foo::Bar::Baz::Qux, Foo::Bar]
  end
end

module Foo::Bar::Baz::Qux
  p Module.nesting
  #=> [Foo::Bar::Baz::Qux]
end

Again, this is purely lexical nesting of the module definition. The module itself is not nested; the module itself is the same in all of these cases. This nesting only affects constant lookup.

Constants are looked up first lexically outwards in enclosing module definitions, then upwards the inheritance chain.

There is another instance where things can be nested: blocks create nested lexical scopes, whereas all other lexical scopes (script, module / class definition, and method definition) don't nest. In other words, blocks and only blocks have access to the local variables (and self) of their enclosing lexical scopes.

Ruby - How to include classes in a Module

Im not sure what the issue is. I understand that it says uninitialized but Im not sure why. It seems it is looking for a constant instead of reading the class?

It is not clear to me what you mean by "reading the class". Yes, Ruby is looking for a constant. Variable names that begin with a capital letter are constants, ergo, HtmlBody is a constant, HeadingTags is a constant, and HtmlBody::HeadingTags is the constant HeadingTags located in a class or module that is referenced by the constant HtmlBody.

How are you supposed to include classes located in separated files inside a module?

You namespace a class inside a module by defining the class inside the module. If you are sure that the module already exists, you can define the class like this:

class HtmlBody::HeadingTags
  # …
end

However, if HtmlBody is not defined (or is not a class or module), this will fail.

module HtmlBody
  class HeadingTags
    # …
  end
end

This will guarantee that module HtmlBody will be created if it doesn't exist (and simply re-opened if it already exists).

There is also a slight difference in constant lookup rules between the two, which is however not relevant to your question (but be aware of it).

The is something that Im missing in Ruby and the require/require_relative probably.

Indeed, your question stems from a fundamental misunderstanding of what Kerne#load / Kernel#require / Kernel#require_relative does.

Here is the very complicated, detailed, in-depth explanation of all the incredibly convoluted stuff that those three methods do. Brace yourself! Are you ready? Here we go:

They run the file.

Wait … that's it? Yes, that's it! That's all there is to it. They run the file.

So, what happens when you run a file that looks like this:

class HeadingTags
  # …
end

It defines a class named HeadingTags in the top-level namespace, right?

Okay, so what happens when we now do this:

require_relative './html_body/HeadingTags'

Well, we said that require_relative simply runs the file. And we said that running that file defines a class named HeadingTags in the top-level namespace. Therefore, this will obviously define a class named HeadingTags in the top-level namespace.

Now, looking at your code: what happens, when we do this:

module HtmlBody
  require_relative './html_body/HeadingTags'
end

Again, we said that require_relative simply runs the file. Nothing more. Nothing less. Just run the file. And what did we say running that file does? It defines a class named HeadingTags in the top-level namespace.

So, what will calling require_relative from within the module definition of HtmlBody do? It will define a class named HeadingTags in the top-level namespace. Because require_relative simply runs the file, and thus the result will be exactly the same as running the file, and the result of running file is that it defines the class in the top-level namespace.

So, how do you actually achieve what you are trying to do? Well, if you want to define a class inside a module, you have to … define the class inside the module!

lib/html_body.rb

require_relative 'html_body/heading_tags'
require_relative 'html_body/anchor_tags'
require_relative 'html_body/img_tags'

module HtmlBody; end

lib/html_body/heading_tags.rb

module HtmlBody
  class HeadingTags
    # …
  end
end

lib/html_body/anchor_tags.rb

module HtmlBody
  class AnchorTags
    # …
  end
end

lib/html_body/img_tags.rb

module HtmlBody
  class ImgTags
    # …
  end
end

main.rb

require_relative 'lib/html_body'

HtmlBody::HeadingTags.new

Nesting modules in classes and directly calling module functions

There are some fundamental misconceptions of how Ruby OOP works in your example, and without a full code sample and the opportunity to interrogate you about what you're trying to accomplish it's hard to guide you to what might be the most appropriate answer. Any answer I give will be based partly on experience and partly on opinion, so you may see other answers as well.

At a high level, you should have classes in modules and not modules in classes. Although you can put modules in classes you better have a good understanding of why you're doing that before doing it.

Next, the modules and methods you've defined in them do not automatically become accessible to instances of the parent class, so client.Bikes will never work because Ruby expects to find an instance method named Bikes inside the Api class; it won't look for a module with that name.

The only way to access the modules and module methods that you have defined is to use them at the class/module level. So if you have this:

class Foo
  module Bar
    def baz
      puts 'foobarbaz'
    end
  end
end

You can do this at the class/module level:

Foo::Bar.baz
foobarbaz
=> nil

But you can't do anything at the instance level:

Foo.new::Bar.baz
TypeError: #<Foo:0x00007fa037d39260> is not a class/module

Foo.new.Bar.baz
NoMethodError: undefined method `Bar' for #<Foo:0x00007fa037162e28>

So if you understand so far why the structure of your example doesn't work, then you can work on building something a little more sensible. Let's start with naming and the class/module structure.

First, Api is a poor name here because you'll typically use Api for something that provides an API, not connects to one, so I would recommend making the name a bit more descriptive and using a module to indicate that you are encapsulating one or more related classes:

module MonthyApiClient
end

Next, I'd recommend adding a Client class to encapsulate everything related to instantiating a client used to connect to the API:

module MonthyApiClient
  class Client
    def initialize
      @client = nil # insert your logic here
      @connection = nil # insert your logic here
    end
  end
end

The relationship between client and connection in your code example isn't clear, so for simplicity I am going to pretend that they can be combined into a single class (Client) and that we are dropping the module Authentication entirely.

Next, we need a reasonable way to integrate module Bikes and module Phones into this code. It doesn't make sense to convert these to classes because there's no need to instantiate them. These are purely helper functions that do something for an instance of Client, so they should be instance methods within that class:

module MonthyApiClient
  class Client
    def initialize
      # insert your logic here
      @client = nil
      @connection = nil
    end

    def create_bike
      # insert your logic here
      # e.g., @connection.post(something)
    end

    def delete_bike
      # insert your logic here
      # e.g., @connection.delete(something)
    end

    def create_phone
      # insert your logic here
      # e.g., @connection.post(something)
    end
  end
end

Note that we've swapped new for create; you don't want to name a method new in Ruby, and in the context we're using this new would mean instantiate but do not save a new object whereas create would mean instantiate and save a new object.

And now that we're here, and now that we've eliminated all the nested modules by moving their logic elsewhere, we can see that the parent module we set up originally is unnecessarily redundant, and can eliminate it:

class MonthyApiClient
  def initialize
    # insert your logic here
    @client = nil
    @connection = nil
  end

  def create_bike
    # insert your logic here
    # e.g., @connection.post(something)
  end

  def delete_bike
    # insert your logic here
    # e.g., @connection.delete(something)
  end

  def create_phone
    # insert your logic here
    # e.g., @connection.post(something)
  end
end

Then you can accomplish your original goal:

client_one = MonthyApiClient.new
client_one.create_bike
client_two = MonthyApiClient.new
client_two.create_phone

Having worked through this explanation, I think your original code is an example of spending a lot of time trying to over-optimize prematurely. It's better to plan out your business logic and make it as simple as possible first. There's some good information at https://softwareengineering.stackexchange.com/a/80094 that may help explain this concept.

I've even skipped trying to optimize the code I've shown here because I don't know exactly how much commonality there is between creating and deleting bikes and phones. With this functional class, and with a better understanding of other code within this app, I might try to DRY it up (and that might mean going back to having a module with a Client class and either module methods or other classes to encapsulate the DRY logic), but it would be premature to try.

Your last question was about how to structure files and directories for modules and classes, and I would refer you to Ideal ruby project structure (among many other questions on this site) for more information.

Declaring a class within a module

what is the advantage of doing it this way?

It serves as namespace so classes with the same name do not clash (so it has nothing to do with mixins). It's standard.

Why are we appending self to class, is that not already implied?

That's just one of the ways of defining class-methods (the other being def self.method_name).