Methods

Included Modules

Class Public methods

add_shebang_option!()

Small macro to add ruby as an option to the generator with proper default value plus an instance helper method called shebang.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 396
        def self.add_shebang_option! # :doc:
          class_option :ruby, type: :string, aliases: "-r", default: Thor::Util.ruby_command,
                              desc: "Path to the Ruby binary of your choice", banner: "PATH"

          no_tasks {
            define_method :shebang do
              @shebang ||= begin
                command = if options[:ruby] == Thor::Util.ruby_command
                  "/usr/bin/env #{File.basename(Thor::Util.ruby_command)}"
                else
                  options[:ruby]
                end
                "#!#{command}"
              end
            end
          }
        end
πŸ”Ž See on GitHub

banner()

Use Rails default banner.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 329
        def self.banner # :doc:
          "bin/rails generate #{namespace.delete_prefix("rails:")} #{arguments.map(&:usage).join(' ')} [options]".gsub(/\s+/, " ")
        end
πŸ”Ž See on GitHub

base_name()

Sets the base_name taking into account the current class namespace.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 334
        def self.base_name # :doc:
          @base_name ||= if base = name.to_s.split("::").first
            base.underscore
          end
        end
πŸ”Ž See on GitHub

base_root()

Returns the base root for a common set of generators. This is used to dynamically guess the default source root.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 236
      def self.base_root
        __dir__
      end
πŸ”Ž See on GitHub

default_aliases_for_option(name, options)

Returns default aliases for the option name given doing a lookup in Rails::Generators.aliases.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 357
        def self.default_aliases_for_option(name, options) # :doc:
          default_for_option(Rails::Generators.aliases, name, options, options[:aliases])
        end
πŸ”Ž See on GitHub

default_for_option(config, name, options, default)

Returns default for the option name given doing a lookup in config.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 362
        def self.default_for_option(config, name, options, default) # :doc:
          if generator_name && (c = config[generator_name.to_sym]) && c.key?(name)
            c[name]
          elsif base_name && (c = config[base_name.to_sym]) && c.key?(name)
            c[name]
          elsif config[:rails].key?(name)
            config[:rails][name]
          else
            default
          end
        end
πŸ”Ž See on GitHub

default_generator_root()

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 422
        def self.default_generator_root # :doc:
          path = File.expand_path(File.join(base_name, generator_name), base_root)
          path if File.exist?(path)
        end
πŸ”Ž See on GitHub

default_source_root()

Returns the default source root for a given generator. This is used internally by Rails to set its generators source root. If you want to customize your source root, you should use source_root.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 227
      def self.default_source_root
        return unless base_name && generator_name
        return unless default_generator_root
        path = File.join(default_generator_root, "templates")
        path if File.exist?(path)
      end
πŸ”Ž See on GitHub

default_value_for_option(name, options)

Returns the default value for the option name given doing a lookup in Rails::Generators.options.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 351
        def self.default_value_for_option(name, options) # :doc:
          default_for_option(Rails::Generators.options, name, options, options[:default])
        end
πŸ”Ž See on GitHub

desc(description = nil)

Tries to get the description from a USAGE file one folder above the source root otherwise uses a default description.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 41
      def self.desc(description = nil)
        return super if description

        @desc ||= if usage_path
          ERB.new(File.read(usage_path)).result(binding)
        else
          "Description:\n    Create #{base_name.humanize.downcase} files for #{generator_name} generator."
        end
      end
πŸ”Ž See on GitHub

generator_name()

Removes the namespaces and get the generator name. For example, Rails::Generators::ModelGenerator will return β€œmodel” as generator name.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 342
        def self.generator_name # :doc:
          @generator_name ||= if generator = name.to_s.split("::").last
            generator.delete_suffix!("Generator")
            generator.underscore
          end
        end
πŸ”Ž See on GitHub

hide!()

Convenience method to hide this generator from the available ones when running rails generator command.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 61
      def self.hide!
        Rails::Generators.hide_namespace(namespace)
      end
πŸ”Ž See on GitHub

hook_for(*names, &block)

Invoke a generator based on the value supplied by the user to the given option named β€œname”. A class option is created when this method is invoked and you can set a hash to customize it.

Examples

module Rails::Generators
  class ControllerGenerator < Base
    hook_for :test_framework, aliases: "-t"
  end
end

The example above will create a test framework option and will invoke a generator based on the user supplied value.

For example, if the user invoke the controller generator as:

$ bin/rails generate controller Account --test-framework=test_unit

The controller generator will then try to invoke the following generators:

"rails:test_unit", "test_unit:controller", "test_unit"

Notice that β€œrails:generators:test_unit” could be loaded as well, what Rails looks for is the first and last parts of the namespace. This is what allows any test framework to hook into Rails as long as it provides any of the hooks above.

Options

The first and last part used to find the generator to be invoked are guessed based on class invokes hook_for, as noticed in the example above. This can be customized with two options: :in and :as.

Let’s suppose you are creating a generator that needs to invoke the controller generator from test unit. Your first attempt is:

class AwesomeGenerator < Rails::Generators::Base
  hook_for :test_framework
end

The lookup in this case for test_unit as input is:

"test_unit:awesome", "test_unit"

Which is not the desired lookup. You can change it by providing the :as option:

class AwesomeGenerator < Rails::Generators::Base
  hook_for :test_framework, as: :controller
end

And now it will look up at:

"test_unit:controller", "test_unit"

Similarly, if you want it to also look up in the rails namespace, you just need to provide the :in value:

class AwesomeGenerator < Rails::Generators::Base
  hook_for :test_framework, in: :rails, as: :controller
end

And the lookup is exactly the same as previously:

"rails:test_unit", "test_unit:controller", "test_unit"

Switches

All hooks come with switches for user interface. If you do not want to use any test framework, you can do:

$ bin/rails generate controller Account --skip-test-framework

Or similarly:

$ bin/rails generate controller Account --no-test-framework

Boolean hooks

In some cases, you may want to provide a boolean hook. For example, webrat developers might want to have webrat available on controller generator. This can be achieved as:

Rails::Generators::ControllerGenerator.hook_for :webrat, type: :boolean

Then, if you want webrat to be invoked, just supply:

$ bin/rails generate controller Account --webrat

The hooks lookup is similar as above:

"rails:generators:webrat", "webrat:generators:controller", "webrat"

Custom invocations

You can also supply a block to hook_for to customize how the hook is going to be invoked. The block receives two arguments, an instance of the current class and the class to be invoked.

For example, in the resource generator, the controller should be invoked with a pluralized class name. But by default it is invoked with the same name as the resource generator, which is singular. To change this, we can give a block to customize how the controller can be invoked.

hook_for :resource_controller do |instance, controller|
  instance.invoke controller, [ instance.name.pluralize ]
end
πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 174
      def self.hook_for(*names, &block)
        options = names.extract_options!
        in_base = options.delete(:in) || base_name
        as_hook = options.delete(:as) || generator_name

        names.each do |name|
          unless class_options.key?(name)
            defaults = if options[:type] == :boolean
              {}
            elsif [true, false].include?(default_value_for_option(name, options))
              { banner: "" }
            else
              { desc: "#{name.to_s.humanize} to be invoked", banner: "NAME" }
            end

            class_option(name, defaults.merge!(options))
          end

          klass = self

          singleton_class.define_method("#{name}_generator") do
            value = class_options[name].default
            Rails::Generators.find_by_namespace(klass.generator_name, value)
          end

          hooks[name] = [ in_base, as_hook ]
          invoke_from_option(name, options, &block)
        end
      end
πŸ”Ž See on GitHub

namespace(name = nil)

Convenience method to get the namespace from the class name. It’s the same as Thor default except that the Generator at the end of the class is removed.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 54
      def self.namespace(name = nil)
        return super if name
        @namespace ||= super.delete_suffix("_generator").sub(/:generators:/, ":")
      end
πŸ”Ž See on GitHub

remove_hook_for(*names)

Remove a previously added hook.

remove_hook_for :orm
πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 207
      def self.remove_hook_for(*names)
        remove_invocation(*names)

        names.each do |name|
          singleton_class.undef_method("#{name}_generator")
          hooks.delete(name)
        end
      end
πŸ”Ž See on GitHub

source_root(path = nil)

Returns the source root for this generator using default_source_root as default.

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 34
      def self.source_root(path = nil)
        @_source_root = path if path
        @_source_root ||= default_source_root
      end
πŸ”Ž See on GitHub

usage_path()

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 414
        def self.usage_path # :doc:
          paths = [
            source_root && File.expand_path("../USAGE", source_root),
            default_generator_root && File.join(default_generator_root, "USAGE")
          ]
          paths.compact.detect { |path| File.exist? path }
        end
πŸ”Ž See on GitHub

Instance Private methods

extract_last_module(nesting)

Takes in an array of nested modules and extracts the last module

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 287
        def extract_last_module(nesting) # :doc:
          nesting.inject(Object) do |last_module, nest|
            break unless last_module.const_defined?(nest, false)
            last_module.const_get(nest)
          end
        end
πŸ”Ž See on GitHub

indent(content, multiplier = 2)

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 302
        def indent(content, multiplier = 2) # :doc:
          spaces = " " * multiplier
          content.each_line.map { |line| line.blank? ? line : "#{spaces}#{line}" }.join
        end
πŸ”Ž See on GitHub

module_namespacing(&block)

Wrap block with namespace of current application if namespace exists and is not skipped

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 296
        def module_namespacing(&block) # :doc:
          content = capture(&block)
          content = wrap_with_namespace(content) if namespaced?
          concat(content)
        end
πŸ”Ž See on GitHub

namespace()

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 312
        def namespace # :doc:
          Rails::Generators.namespace
        end
πŸ”Ž See on GitHub

namespaced?()

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 316
        def namespaced? # :doc:
          !options[:skip_namespace] && namespace
        end
πŸ”Ž See on GitHub

namespaced_path()

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 324
        def namespaced_path # :doc:
          @namespaced_path ||= namespace_dirs.join("/")
        end
πŸ”Ž See on GitHub

wrap_with_namespace(content)

πŸ“ Source code
# File railties/lib/rails/generators/base.rb, line 307
        def wrap_with_namespace(content) # :doc:
          content = indent(content).chomp
          "module #{namespace.name}\n#{content}\nend\n"
        end
πŸ”Ž See on GitHub