123456789_123456789_123456789_123456789_123456789_

Class: Rails::Generators::Base

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
ActionMailbox::Generators::InstallGenerator, ActionText::Generators::InstallGenerator, ActiveRecord::Generators::ApplicationRecordGenerator, ActiveRecord::Generators::Base, ActiveRecord::Generators::MigrationGenerator, ActiveRecord::Generators::ModelGenerator, ActiveRecord::Generators::MultiDbGenerator, Erb::Generators::Base, Erb::Generators::ControllerGenerator, Erb::Generators::MailerGenerator, Erb::Generators::ScaffoldGenerator, Rails::Generators::AppBase, AppGenerator, Rails::Generators::ApplicationRecordGenerator, BenchmarkGenerator, ChannelGenerator, Rails::Generators::ControllerGenerator, Rails::Generators::CredentialsGenerator, Rails::Generators::EncryptedFileGenerator, Rails::Generators::EncryptionKeyFileGenerator, Rails::Generators::GeneratorGenerator, Rails::Generators::HelperGenerator, Rails::Generators::IntegrationTestGenerator, Rails::Generators::JobGenerator, MailboxGenerator, MailerGenerator, Rails::Generators::MasterKeyGenerator, Rails::Generators::MigrationGenerator, Rails::Generators::ModelGenerator, NamedBase, Rails::Generators::PluginGenerator, Rails::Generators::ResourceGenerator, Rails::Generators::ResourceRouteGenerator, Rails::Generators::ScaffoldControllerGenerator, Rails::Generators::ScaffoldGenerator, Rails::Generators::SystemTestGenerator, Rails::Generators::TaskGenerator, TestUnit::Generators::Base, TestUnit::Generators::ChannelGenerator, TestUnit::Generators::ControllerGenerator, TestUnit::Generators::GeneratorGenerator, TestUnit::Generators::HelperGenerator, TestUnit::Generators::InstallGenerator, TestUnit::Generators::IntegrationGenerator, TestUnit::Generators::JobGenerator, TestUnit::Generators::MailboxGenerator, TestUnit::Generators::MailerGenerator, TestUnit::Generators::ModelGenerator, TestUnit::Generators::PluginGenerator, TestUnit::Generators::ScaffoldGenerator, TestUnit::Generators::SystemGenerator, Rails::Generators::Db::System::ChangeGenerator
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Thor::Group
Instance Chain:
self, Actions, Thor::Actions, Thor::Group
Inherits: Thor::Group
  • ::Object
Defined in: railties/lib/rails/generators/base.rb

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Actions - Included

#add_source

Add the given source to Gemfile

#application
#environment

Adds configuration code to a Rails runtime environment.

#gem

Adds a gem declaration to the Gemfile for the specified gem.

#gem_group

Wraps gem entries inside a group.

#generate

Runs another generator.

#git

Runs one or more git commands.

#github,
#initializer

Creates an initializer file in config/initializers/.

#lib

Creates a file in lib/.

#rails_command

Runs the specified Rails command.

#rake

Runs the specified Rake task.

#rakefile

Creates a Rake tasks file in lib/tasks/.

#readme

Reads the given file at the source root and prints it in the console.

#route

Make an entry in Rails routing file config/routes.rb.

#vendor

Creates a file in vendor/.

#execute_command

Runs the supplied command using either “rake …” or “rails …” based on the executor parameter provided.

#indentation

Indent the Gemfile to the depth of @indentation.

#log

Define log for backwards compatibility.

#optimize_indentation

Returns optimized string with indentation.

#quote

Always returns value in double quotes.

#with_indentation

Manage Gemfile indentation for a DSL action block.

Class Method Details

.add_shebang_option! (private)

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

[ GitHub ]

  
# 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

.base_name (private)

Sets the base_name taking into account the current class namespace.

[ GitHub ]

  
# 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

.base_root

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

[ GitHub ]

  
# File 'railties/lib/rails/generators/base.rb', line 236

def self.base_root
  __dir__
end

.default_aliases_for_option(name, options) (private)

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

[ GitHub ]

  
# 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

.default_for_option(config, name, options, default) (private)

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

[ GitHub ]

  
# 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

.default_generator_root (private)

[ GitHub ]

  
# 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

.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.

[ GitHub ]

  
# 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

.default_value_for_option(name, options) (private)

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

[ GitHub ]

  
# 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

.desc(description = nil)

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

[ GitHub ]

  
# 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

.generator_name (private)

Removes the namespaces and get the generator name. For example, ModelGenerator will return “model” as generator name.

[ GitHub ]

  
# 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

.hide!

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

[ GitHub ]

  
# File 'railties/lib/rails/generators/base.rb', line 61

def self.hide!
  Rails::Generators.hide_namespace(namespace)
end

.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
[ GitHub ]

  
# 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

.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.

[ GitHub ]

  
# 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

.remove_hook_for(*names)

Remove a previously added hook.

remove_hook_for :orm
[ GitHub ]

  
# 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

.source_root(path = nil)

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

[ GitHub ]

  
# 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

.usage_path (private)

[ GitHub ]

  
# 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

Instance Attribute Details

#namespaced?Boolean (readonly, private)

[ GitHub ]

  
# File 'railties/lib/rails/generators/base.rb', line 316

def namespaced? # :doc:
  !options[:skip_namespace] && namespace
end

Instance Method Details

#extract_last_module(nesting) (private)

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

[ GitHub ]

  
# 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

#indent(content, multiplier = 2) (private)

[ GitHub ]

  
# 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

#module_namespacing(&block) (private)

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

[ GitHub ]

  
# 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

#namespace (private)

[ GitHub ]

  
# File 'railties/lib/rails/generators/base.rb', line 312

def namespace # :doc:
  Rails::Generators.namespace
end

#namespaced_path (private)

[ GitHub ]

  
# File 'railties/lib/rails/generators/base.rb', line 324

def namespaced_path # :doc:
  @namespaced_path ||= namespace_dirs.join("/")
end

#wrap_with_namespace(content) (private)

[ GitHub ]

  
# 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