instiki/vendor/rails/railties/lib/rails_generator/base.rb
Jacques Distler 516d6dfac0 Rails 2.1
Update to Rails 2.1 final.
2008-06-02 01:35:38 -05:00

264 lines
9.9 KiB
Ruby

require File.dirname(__FILE__) + '/options'
require File.dirname(__FILE__) + '/manifest'
require File.dirname(__FILE__) + '/spec'
require File.dirname(__FILE__) + '/generated_attribute'
module Rails
# Rails::Generator is a code generation platform tailored for the Rails
# web application framework. Generators are easily invoked within Rails
# applications to add and remove components such as models and controllers.
# New generators are easy to create and may be distributed as RubyGems,
# tarballs, or Rails plugins for inclusion system-wide, per-user,
# or per-application.
#
# For actual examples see the rails_generator/generators directory in the
# Rails source (or the +railties+ directory if you have frozen the Rails
# source in your application).
#
# Generators may subclass other generators to provide variations that
# require little or no new logic but replace the template files.
#
# For a RubyGem, put your generator class and templates in the +lib+
# directory. For a Rails plugin, make a +generators+ directory at the
# root of your plugin.
#
# The layout of generator files can be seen in the built-in
# +controller+ generator:
#
# generators/
# components/
# controller/
# controller_generator.rb
# templates/
# controller.rb
# functional_test.rb
# helper.rb
# view.html.erb
#
# The directory name (+controller+) matches the name of the generator file
# (controller_generator.rb) and class (ControllerGenerator). The files
# that will be copied or used as templates are stored in the +templates+
# directory.
#
# The filenames of the templates don't matter, but choose something that
# will be self-explanatory since you will be referencing these in the
# +manifest+ method inside your generator subclass.
#
#
module Generator
class GeneratorError < StandardError; end
class UsageError < GeneratorError; end
# The base code generator is bare-bones. It sets up the source and
# destination paths and tells the logger whether to keep its trap shut.
#
# It's useful for copying files such as stylesheets, images, or
# javascripts.
#
# For more comprehensive template-based passive code generation with
# arguments, you'll want Rails::Generator::NamedBase.
#
# Generators create a manifest of the actions they perform then hand
# the manifest to a command which replays the actions to do the heavy
# lifting (such as checking for existing files or creating directories
# if needed). Create, destroy, and list commands are included. Since a
# single manifest may be used by any command, creating new generators is
# as simple as writing some code templates and declaring what you'd like
# to do with them.
#
# The manifest method must be implemented by subclasses, returning a
# Rails::Generator::Manifest. The +record+ method is provided as a
# convenience for manifest creation. Example:
#
# class StylesheetGenerator < Rails::Generator::Base
# def manifest
# record do |m|
# m.directory('public/stylesheets')
# m.file('application.css', 'public/stylesheets/application.css')
# end
# end
# end
#
# See Rails::Generator::Commands::Create for a list of methods available
# to the manifest.
class Base
include Options
# Declare default options for the generator. These options
# are inherited to subclasses.
default_options :collision => :ask, :quiet => false
# A logger instance available everywhere in the generator.
cattr_accessor :logger
# Every generator that is dynamically looked up is tagged with a
# Spec describing where it was found.
class_inheritable_accessor :spec
attr_reader :source_root, :destination_root, :args
def initialize(runtime_args, runtime_options = {})
@args = runtime_args
parse!(@args, runtime_options)
# Derive source and destination paths.
@source_root = options[:source] || File.join(spec.path, 'templates')
if options[:destination]
@destination_root = options[:destination]
elsif defined? ::RAILS_ROOT
@destination_root = ::RAILS_ROOT
end
# Silence the logger if requested.
logger.quiet = options[:quiet]
# Raise usage error if help is requested.
usage if options[:help]
end
# Generators must provide a manifest. Use the +record+ method to create
# a new manifest and record your generator's actions.
def manifest
raise NotImplementedError, "No manifest for '#{spec.name}' generator."
end
# Return the full path from the source root for the given path.
# Example for source_root = '/source':
# source_path('some/path.rb') == '/source/some/path.rb'
#
# The given path may include a colon ':' character to indicate that
# the file belongs to another generator. This notation allows any
# generator to borrow files from another. Example:
# source_path('model:fixture.yml') = '/model/source/path/fixture.yml'
def source_path(relative_source)
# Check whether we're referring to another generator's file.
name, path = relative_source.split(':', 2)
# If not, return the full path to our source file.
if path.nil?
File.join(source_root, name)
# Otherwise, ask our referral for the file.
else
# FIXME: this is broken, though almost always true. Others'
# source_root are not necessarily the templates dir.
File.join(self.class.lookup(name).path, 'templates', path)
end
end
# Return the full path from the destination root for the given path.
# Example for destination_root = '/dest':
# destination_path('some/path.rb') == '/dest/some/path.rb'
def destination_path(relative_destination)
File.join(destination_root, relative_destination)
end
protected
# Convenience method for generator subclasses to record a manifest.
def record
Rails::Generator::Manifest.new(self) { |m| yield m }
end
# Override with your own usage banner.
def banner
"Usage: #{$0} #{spec.name} [options]"
end
# Read USAGE from file in generator base path.
def usage_message
File.read(File.join(spec.path, 'USAGE')) rescue ''
end
end
# The base generator for named components: models, controllers, mailers,
# etc. The target name is taken as the first argument and inflected to
# singular, plural, class, file, and table forms for your convenience.
# The remaining arguments are aliased to +actions+ as an array for
# controller and mailer convenience.
#
# Several useful local variables and methods are populated in the
# +initialize+ method. See below for a list of Attributes and
# External Aliases available to both the manifest and to all templates.
#
# If no name is provided, the generator raises a usage error with content
# optionally read from the USAGE file in the generator's base path.
#
# For example, the +controller+ generator takes the first argument as
# the name of the class and subsequent arguments as the names of
# actions to be generated:
#
# ./script/generate controller Article index new create
#
# See Rails::Generator::Base for a discussion of manifests,
# Rails::Generator::Commands::Create for methods available to the manifest,
# and Rails::Generator for a general discussion of generators.
class NamedBase < Base
attr_reader :name, :class_name, :singular_name, :plural_name, :table_name
attr_reader :class_path, :file_path, :class_nesting, :class_nesting_depth
alias_method :file_name, :singular_name
alias_method :actions, :args
def initialize(runtime_args, runtime_options = {})
super
# Name argument is required.
usage if runtime_args.empty?
@args = runtime_args.dup
base_name = @args.shift
assign_names!(base_name)
end
protected
# Override with your own usage banner.
def banner
"Usage: #{$0} #{spec.name} #{spec.name.camelize}Name [options]"
end
def attributes
@attributes ||= @args.collect do |attribute|
Rails::Generator::GeneratedAttribute.new(*attribute.split(":"))
end
end
private
def assign_names!(name)
@name = name
base_name, @class_path, @file_path, @class_nesting, @class_nesting_depth = extract_modules(@name)
@class_name_without_nesting, @singular_name, @plural_name = inflect_names(base_name)
@table_name = (!defined?(ActiveRecord::Base) || ActiveRecord::Base.pluralize_table_names) ? plural_name : singular_name
@table_name.gsub! '/', '_'
if @class_nesting.empty?
@class_name = @class_name_without_nesting
else
@table_name = @class_nesting.underscore << "_" << @table_name
@class_name = "#{@class_nesting}::#{@class_name_without_nesting}"
end
end
# Extract modules from filesystem-style or ruby-style path:
# good/fun/stuff
# Good::Fun::Stuff
# produce the same results.
def extract_modules(name)
modules = name.include?('/') ? name.split('/') : name.split('::')
name = modules.pop
path = modules.map { |m| m.underscore }
file_path = (path + [name.underscore]).join('/')
nesting = modules.map { |m| m.camelize }.join('::')
[name, path, file_path, nesting, modules.size]
end
def inflect_names(name)
camel = name.camelize
under = camel.underscore
plural = under.pluralize
[camel, under, plural]
end
end
end
end