1 require File
.dirname(__FILE__
) + '/options'
2 require File
.dirname(__FILE__
) + '/manifest'
3 require File
.dirname(__FILE__
) + '/spec'
4 require File
.dirname(__FILE__
) + '/generated_attribute'
7 # Rails::Generator is a code generation platform tailored for the Rails
8 # web application framework. Generators are easily invoked within Rails
9 # applications to add and remove components such as models and controllers.
10 # New generators are easy to create and may be distributed as RubyGems,
11 # tarballs, or Rails plugins for inclusion system-wide, per-user,
14 # For actual examples see the rails_generator/generators directory in the
15 # Rails source (or the +railties+ directory if you have frozen the Rails
16 # source in your application).
18 # Generators may subclass other generators to provide variations that
19 # require little or no new logic but replace the template files.
21 # For a RubyGem, put your generator class and templates in the +lib+
22 # directory. For a Rails plugin, make a +generators+ directory at the
23 # root of your plugin.
25 # The layout of generator files can be seen in the built-in
26 # +controller+ generator:
31 # controller_generator.rb
38 # The directory name (+controller+) matches the name of the generator file
39 # (controller_generator.rb) and class (ControllerGenerator). The files
40 # that will be copied or used as templates are stored in the +templates+
43 # The filenames of the templates don't matter, but choose something that
44 # will be self-explanatory since you will be referencing these in the
45 # +manifest+ method inside your generator subclass.
49 class GeneratorError
< StandardError
; end
50 class UsageError
< GeneratorError
; end
53 # The base code generator is bare-bones. It sets up the source and
54 # destination paths and tells the logger whether to keep its trap shut.
56 # It's useful for copying files such as stylesheets, images, or
59 # For more comprehensive template-based passive code generation with
60 # arguments, you'll want Rails::Generator::NamedBase.
62 # Generators create a manifest of the actions they perform then hand
63 # the manifest to a command which replays the actions to do the heavy
64 # lifting (such as checking for existing files or creating directories
65 # if needed). Create, destroy, and list commands are included. Since a
66 # single manifest may be used by any command, creating new generators is
67 # as simple as writing some code templates and declaring what you'd like
70 # The manifest method must be implemented by subclasses, returning a
71 # Rails::Generator::Manifest. The +record+ method is provided as a
72 # convenience for manifest creation. Example:
74 # class StylesheetGenerator < Rails::Generator::Base
77 # m.directory('public/stylesheets')
78 # m.file('application.css', 'public/stylesheets/application.css')
83 # See Rails::Generator::Commands::Create for a list of methods available
88 # Declare default options for the generator. These options
89 # are inherited to subclasses.
90 default_options
:collision => :ask, :quiet => false
92 # A logger instance available everywhere in the generator.
93 cattr_accessor
:logger
95 # Every generator that is dynamically looked up is tagged with a
96 # Spec describing where it was found.
97 class_inheritable_accessor
:spec
99 attr_reader
:source_root, :destination_root, :args
101 def initialize(runtime_args
, runtime_options
= {})
103 parse
!(@args, runtime_options
)
105 # Derive source and destination paths.
106 @source_root = options
[:source] || File
.join(spec
.path
, 'templates')
107 if options
[:destination]
108 @destination_root = options
[:destination]
109 elsif defined? ::RAILS_ROOT
110 @destination_root = ::RAILS_ROOT
113 # Silence the logger if requested.
114 logger
.quiet
= options
[:quiet]
116 # Raise usage error if help is requested.
117 usage
if options
[:help]
120 # Generators must provide a manifest. Use the +record+ method to create
121 # a new manifest and record your generator's actions.
123 raise NotImplementedError
, "No manifest for '#{spec.name}' generator."
126 # Return the full path from the source root for the given path.
127 # Example for source_root = '/source':
128 # source_path('some/path.rb') == '/source/some/path.rb'
130 # The given path may include a colon ':' character to indicate that
131 # the file belongs to another generator. This notation allows any
132 # generator to borrow files from another. Example:
133 # source_path('model:fixture.yml') = '/model/source/path/fixture.yml'
134 def source_path(relative_source
)
135 # Check whether we're referring to another generator's file.
136 name
, path
= relative_source
.split(':', 2)
138 # If not, return the full path to our source file.
140 File
.join(source_root
, name
)
142 # Otherwise, ask our referral for the file.
144 # FIXME: this is broken, though almost always true. Others'
145 # source_root are not necessarily the templates dir.
146 File
.join(self.class.lookup(name
).path
, 'templates', path
)
150 # Return the full path from the destination root for the given path.
151 # Example for destination_root = '/dest':
152 # destination_path('some/path.rb') == '/dest/some/path.rb'
153 def destination_path(relative_destination
)
154 File
.join(destination_root
, relative_destination
)
161 # Convenience method for generator subclasses to record a manifest.
163 Rails
::Generator::Manifest.new(self) { |m
| yield m
}
166 # Override with your own usage banner.
168 "Usage: #{$0} #{spec.name} [options]"
171 # Read USAGE from file in generator base path.
173 File
.read(File
.join(spec
.path
, 'USAGE')) rescue ''
178 # The base generator for named components: models, controllers, mailers,
179 # etc. The target name is taken as the first argument and inflected to
180 # singular, plural, class, file, and table forms for your convenience.
181 # The remaining arguments are aliased to +actions+ as an array for
182 # controller and mailer convenience.
184 # Several useful local variables and methods are populated in the
185 # +initialize+ method. See below for a list of Attributes and
186 # External Aliases available to both the manifest and to all templates.
188 # If no name is provided, the generator raises a usage error with content
189 # optionally read from the USAGE file in the generator's base path.
191 # For example, the +controller+ generator takes the first argument as
192 # the name of the class and subsequent arguments as the names of
193 # actions to be generated:
195 # ./script/generate controller Article index new create
197 # See Rails::Generator::Base for a discussion of manifests,
198 # Rails::Generator::Commands::Create for methods available to the manifest,
199 # and Rails::Generator for a general discussion of generators.
200 class NamedBase
< Base
201 attr_reader
:name, :class_name, :singular_name, :plural_name, :table_name
202 attr_reader
:class_path, :file_path, :class_nesting, :class_nesting_depth
203 alias_method
:file_name, :singular_name
204 alias_method
:actions, :args
206 def initialize(runtime_args
, runtime_options
= {})
209 # Name argument is required.
210 usage
if runtime_args
.empty
?
212 @args = runtime_args
.dup
213 base_name
= @args.shift
214 assign_names
!(base_name
)
218 # Override with your own usage banner.
220 "Usage: #{$0} #{spec.name} #{spec.name.camelize}Name [options]"
224 @attributes ||= @args.collect
do |attribute
|
225 Rails
::Generator::GeneratedAttribute.new(*attribute
.split(":"))
231 def assign_names
!(name
)
233 base_name
, @class_path, @file_path, @class_nesting, @class_nesting_depth = extract_modules(@name)
234 @class_name_without_nesting, @singular_name, @plural_name = inflect_names(base_name
)
235 @table_name = (!defined?(ActiveRecord
::Base) || ActiveRecord
::Base.pluralize_table_names
) ? plural_name
: singular_name
236 @table_name.gsub
! '/', '_'
237 if @class_nesting.empty
?
238 @class_name = @class_name_without_nesting
240 @table_name = @class_nesting.underscore
<< "_" << @table_name
241 @class_name = "#{@class_nesting}::#{@class_name_without_nesting}"
245 # Extract modules from filesystem-style or ruby-style path:
248 # produce the same results.
249 def extract_modules(name
)
250 modules
= name
.include?('/') ? name
.split('/') : name
.split('::')
252 path
= modules
.map
{ |m
| m
.underscore
}
253 file_path
= (path
+ [name
.underscore
]).join('/')
254 nesting
= modules
.map
{ |m
| m
.camelize
}.join('::')
255 [name
, path
, file_path
, nesting
, modules
.size
]
258 def inflect_names(name
)
259 camel
= name
.camelize
260 under
= camel
.underscore
261 plural
= under
.pluralize
262 [camel
, under
, plural
]