Object
Returns an Hash that maps the type of action to a list of ActionDescriptions.
Hash{Symbol=>Array[Templater::ActionDescription]} | A Hash of actions |
# File lib/templater/generator.rb, line 50 50: def actions; @actions ||= {} end
Assign a name to the n:th argument that this generator takes. An accessor with that name will automatically be added to the generator. Options can be provided to ensure the argument conforms to certain requirements. If a block is provided, when an argument is assigned, the block is called with that value and if :invalid is thrown, a proper error is raised
n | The index of the argument that this describes |
name | The name of this argument, an accessor with this name will be created for the argument |
options | Options for this argument |
&block | Is evaluated on assignment to check the validity of the argument |
:default | Specify a default value for this argument |
:as | If set to :hash or :array, this argument will ‘consume’ all remaining arguments and bundle them |
Use this only for the last argument to this generator.
:required | If set to true, the generator will throw an error if it initialized without this argument |
:desc | Provide a description for this argument |
# File lib/templater/generator.rb, line 108 108: def argument(n, name, options={}, &block) 109: self.arguments[n] = ArgumentDescription.new(name.to_sym, options, &block) 110: class_eval def #{name} get_argument(#{n}) end def #{name}=(arg) set_argument(#{n}, arg) end 111: end
Returns an array of hashes, where each hash describes a single argument.
Array[Hash{Symbol=>Object}] | A list of arguments |
# File lib/templater/generator.rb, line 18 18: def arguments; @arguments ||= []; end
If the argument is omitted, simply returns the description for this generator, otherwise sets the description to the passed string.
text | A description |
String | The description for this generator |
# File lib/templater/generator.rb, line 85 85: def desc(text = nil) 86: @text = text.realign_indentation if text 87: return @text 88: end
Returns an array of ActionDescriptions, where each describes a single directory.
Array[Templater::ActionDescription] | A list of file descriptions. |
# File lib/templater/generator.rb, line 68 68: def directories; actions[:directories] ||= []; end
Adds a directory that is copied directly. This method is usedful when globbing is not exactly what you want, or you need to access options to decide what source or destination should be.
name | The name of this template |
source | The source template, can be omitted |
destination | The destination where the result will be put. |
options | Options for this template |
&block | A block to execute when the generator is instantiated |
:before | Name of a method to execute before this template is invoked |
:after | Name of a method to execute after this template is invoked |
# File lib/templater/generator.rb, line 277 277: def directory(name, *args, &block) 278: options = args.last.is_a?(Hash) ? args.pop : {} 279: source, destination = args 280: source, destination = source, source if args.size == 1 281: 282: directories << ActionDescription.new(name, options) do |generator| 283: directory = Actions::Directory.new(generator, name, source, destination, options) 284: generator.instance_exec(directory, &block) if block 285: directory 286: end 287: end
An easy way to add many non-rendering templates to a generator. The provided list can be either an array of Strings or a Here-Doc with templates on individual lines.
list | A list of non-rendering templates to be added to this generator |
class MyGenerator < Templater::Generator directory_list <<-LIST path/to/directory another/directory LIST directory_list ['a/third/directory', 'and/a/fourth'] end
# File lib/templater/generator.rb, line 373 373: def directory_list(list) 374: list = list.to_lines if list.is_a?(String) 375: list.each do |item| 376: item = item.to_s.chomp.strip 377: self.directory(item.gsub(/[\.\/]/, '_').to_sym, item) 378: end 379: end
Returns an array of ActionDescriptions, where each describes a single empty directory created by generator.
Array[Templater::ActionDescription] | A list of empty directory descriptions. |
# File lib/templater/generator.rb, line 74 74: def empty_directories; actions[:empty_directories] ||= []; end
Adds an empty directory that will be created when the generator is run.
name | The name of this empty directory |
destination | The destination where the empty directory will be created |
options | Options for this empty directory |
&block | A block to execute when the generator is instantiated |
:before | Name of a method to execute before this template is invoked |
:after | Name of a method to execute after this template is invoked |
# File lib/templater/generator.rb, line 300 300: def empty_directory(name, *args, &block) 301: options = args.last.is_a?(Hash) ? args.pop : {} 302: destination = args.first 303: 304: empty_directories << ActionDescription.new(name, options) do |generator| 305: directory = Actions::EmptyDirectory.new(generator, name, destination, options) 306: generator.instance_exec(directory, &block) if block 307: directory 308: end 309: end
Adds a template that is not rendered using ERB, but copied directly. Unlike Templater::Generator.template this will not append a ‘t’ to the source, otherwise it works identically.
name | The name of this template |
source | The source template, can be omitted |
destination | The destination where the result will be put. |
options | Options for this template |
&block | A block to execute when the generator is instantiated |
:before | Name of a method to execute before this template is invoked |
:after | Name of a method to execute after this template is invoked |
# File lib/templater/generator.rb, line 251 251: def file(name, *args, &block) 252: options = args.last.is_a?(Hash) ? args.pop : {} 253: source, destination = args 254: source, destination = source, source if args.size == 1 255: 256: files << ActionDescription.new(name, options) do |generator| 257: file = Actions::File.new(generator, name, source, destination, options) 258: generator.instance_exec(file, &block) if block 259: file 260: end 261: end
An easy way to add many non-rendering templates to a generator. The provided list can be either an array of Strings or a Here-Doc with templates on individual lines.
list | A list of non-rendering templates to be added to this generator |
class MyGenerator < Templater::Generator file_list <<-LIST path/to/file.jpg another/file.html.erb LIST file_list ['a/third/file.gif', 'and/a/fourth.rb'] end
# File lib/templater/generator.rb, line 350 350: def file_list(list) 351: list = list.to_lines if list.is_a?(String) 352: list.each do |item| 353: item = item.to_s.chomp.strip 354: self.file(item.gsub(/[\.\/]/, '_').to_sym, item) 355: end 356: end
Returns an array of ActionDescriptions, where each describes a single file.
Array[Templater::ActionDescription] | A list of file descriptions. |
# File lib/templater/generator.rb, line 62 62: def files; actions[:files] ||= []; end
A shorthand method for adding the first argument, see +Templater::Generator.argument+
# File lib/templater/generator.rb, line 21 21: def first_argument(*args); argument(0, *args); end
A shorthand method for adding the fourth argument, see +Templater::Generator.argument+
# File lib/templater/generator.rb, line 30 30: def fourth_argument(*args); argument(3, *args); end
Returns a list of the classes of all generators (recursively) that are invoked together with this one.
Array[Templater::Generator] | an array of generator classes. |
# File lib/templater/generator.rb, line 414 414: def generators 415: generators = [self] 416: if manifold 417: generators += invocations.map do |i| 418: generator = manifold.generator(i.name) 419: generator ? generator.generators : nil 420: end 421: end 422: generators.flatten.compact 423: end
Search a directory for templates and files and add them to this generator. Any file whose extension matches one of those provided in the template_extensions parameter is considered a template and will be rendered with ERB, all others are considered normal files and are simply copied.
A hash of options can be passed which will be assigned to each file and template. All of these options are matched against the options passed to the generator.
source | The directory to search in, relative to the source_root, if omitted |
the source root itself is searched.
template_destination | A list of extensions. If a file has one of these |
extensions, it is considered a template and will be rendered with ERB.
options | A list of options. |
# File lib/templater/generator.rb, line 396 396: def glob!(dir = nil, template_extensions = %(rb css js erb html yml Rakefile TODO LICENSE README), options={}) 397: ::Dir[::File.join(source_root, dir.to_s, '**/*')].each do |action| 398: unless ::File.directory?(action) 399: action = action.sub("#{source_root}/", '') 400: 401: if template_extensions.include?(::File.extname(action.sub(/\.%.+%$/,''))[1..1]) or template_extensions.include?(::File.basename(action)) 402: template(action.downcase.gsub(/[^a-z0-9]+/, '_').to_sym, action, action) 403: else 404: file(action.downcase.gsub(/[^a-z0-9]+/, '_').to_sym, action, action) 405: end 406: end 407: end 408: end
Returns an array of hashes, where each hash describes a single invocation.
Array[Hash{Symbol=>Object}] | A list of invocations |
# File lib/templater/generator.rb, line 43 43: def invocations; @invocations ||= []; end
Adds an invocation of another generator to this generator. This allows the interface to invoke any templates in that target generator. This requires that the generator is part of a manifold. The name provided is the name of the target generator in this generator’s manifold.
A hash of options can be passed, all of these options are matched against the options passed to the generator.
If a block is given, the generator class is passed to the block, and it is expected that the block yields an instance. Otherwise the target generator is instantiated with the same options and arguments as this generator.
name | The name in the manifold of the generator that is to be invoked |
options | A hash of requirements that are matched against the generator options |
&block | A block to execute when the generator is instantiated |
class MyGenerator < Templater::Generator invoke :other_generator end class MyGenerator < Templater::Generator def random rand(100000).to_s end # invoke :other_generator with some invoke :other_generator do |generator| generator.new(destination_root, options, random) end end class MyGenerator < Templater::Generator option :animal # other_generator will be invoked only if the option 'animal' is set to 'bear' invoke :other_generator, :animal => :bear end
# File lib/templater/generator.rb, line 183 183: def invoke(name, options={}, &block) 184: self.invocations << InvocationDescription.new(name.to_sym, options, &block) 185: end
Create a new generator. Checks the list of arguments agains the requirements set using argument.
destination_root | The destination, where the generated files will be put. |
options | Options given to this generator. |
*arguments | The list of arguments. These must match the declared requirements. |
Templater::ArgumentError | If the arguments are invalid |
# File lib/templater/generator.rb, line 452 452: def initialize(destination_root, options = {}, *args) 453: @destination_root = destination_root 454: @arguments = [] 455: @options = options 456: 457: # Initialize options to their default values. 458: self.class.options.each do |option| 459: @options[option.name] ||= option.options[:default] 460: end 461: 462: args.each_with_index do |arg, n| 463: set_argument(n, arg) 464: end 465: 466: self.class.arguments.each_with_index do |argument, i| 467: # Initialize arguments to their default values. 468: @arguments[i] ||= argument.options[:default] 469: # Check if all arguments are valid. 470: argument.valid?(@arguments[i]) 471: end 472: end
Adds an accessor with the given name to this generator, also automatically fills that value through the options hash that is provided when the generator is initialized.
name | The name of this option, an accessor with this name will be created for the option |
options | Options for this option (how meta!) |
:default | Specify a default value for this option |
:as | If set to :boolean provides a hint to the interface using this generator. |
:desc | Provide a description for this option |
# File lib/templater/generator.rb, line 132 132: def option(name, options={}) 133: self.options << Description.new(name.to_sym, options) 134: class_eval def #{name} get_option(:#{name}) end def #{name}=(arg) set_option(:#{name}, arg) end 135: end
Returns an array of options, where each hash describes a single option.
Array[Hash{Symbol=>Object}] | A list of options |
# File lib/templater/generator.rb, line 37 37: def options; @options ||= []; end
A shorthand method for adding the second argument, see +Templater::Generator.argument+
# File lib/templater/generator.rb, line 24 24: def second_argument(*args); argument(1, *args); end
This should return the directory where source templates are located. This method must be overridden in any Generator inheriting from Templater::Source.
Templater::SourceNotSpecifiedError | Always raises this error, so be sure to override this method. |
# File lib/templater/generator.rb, line 430 430: def source_root 431: raise Templater::SourceNotSpecifiedError, "Subclasses of Templater::Generator must override the source_root method, to specify where source templates are located." 432: end
Adds a template to this generator. Templates are named and can later be retrieved by that name. Templates have a source and a destination. When a template is invoked, the source file is rendered, passing through ERB, and the result is copied to the destination. Source and destination can be specified in different ways, and are always assumed to be relative to source_root and destination_root.
If only a destination is given, the source is assumed to be the same destination, only appending the letter ‘t’, so a destination of ‘app/model.rb’, would assume a source of ‘app/model.rbt‘
Source and destination can be set in a block, which makes it possible to call instance methods to determine the correct source and/or desination.
A hash of options can be passed, these options are matched against the options passed to the generator. Some special options, for callbacks for example, are also supported, see below.
name | The name of this template |
source | The source template, can be omitted |
destination | The destination where the result will be put. |
options | Options for this template |
&block | A block to execute when the generator is instantiated |
:before | Name of a method to execute before this template is invoked |
:after | Name of a method to execute after this template is invoked |
class MyGenerator < Templater::Generator def random rand(100000).to_s end template :one, 'template.rb' # source will be inferred as 'template.rbt' template :two, 'source.rbt', 'template.rb' # source expicitly given template :three do source('source.rbt') destination("#{random}.rb") end end
# File lib/templater/generator.rb, line 226 226: def template(name, *args, &block) 227: options = args.last.is_a?(Hash) ? args.pop : {} 228: source, destination = args 229: source, destination = source + 't', source if args.size == 1 230: 231: templates << ActionDescription.new(name, options) do |generator| 232: template = Actions::Template.new(generator, name, source, destination, options) 233: generator.instance_exec(template, &block) if block 234: template 235: end 236: end
An easy way to add many templates to a generator, each item in the list is added as a template. The provided list can be either an array of Strings or a Here-Doc with templates on individual lines.
list | A list of templates to be added to this generator |
class MyGenerator < Templater::Generator template_list <<-LIST path/to/template1.rb another/template.css LIST template_list ['a/third/template.rb', 'and/a/fourth.js'] end
# File lib/templater/generator.rb, line 327 327: def template_list(list) 328: list = list.to_lines if list.is_a?(String) 329: list.each do |item| 330: item = item.to_s.chomp.strip 331: self.template(item.gsub(/[\.\/]/, '_').to_sym, item) 332: end 333: end
Finds and returns all templates and files for this generators whose options match its options.
type | The type of actions to look up (optional) |
[Templater::Actions::*] | The found templates and files. |
# File lib/templater/generator.rb, line 548 548: def actions(type=nil) 549: actions = type ? self.class.actions[type] : self.class.actions.values.flatten 550: actions.inject([]) do |actions, description| 551: actions << description.compile(self) if match_options?(description.options) 552: actions 553: end 554: end
# File lib/templater/generator.rb, line 608 608: def after_deletion 609: # override in subclasses if necessary 610: end
# File lib/templater/generator.rb, line 604 604: def after_generation 605: # override in subclasses if necessary 606: end
# File lib/templater/generator.rb, line 600 600: def after_run 601: # override in subclasses if necessary 602: end
Finds and returns all templates and files for this generators and any of those generators it invokes, whose options match that generator’s options.
[Templater::Actions::File, Templater::Actions::Template] | The found templates and files. |
# File lib/templater/generator.rb, line 561 561: def all_actions(type=nil) 562: all_actions = actions(type) 563: all_actions += invocations.map { |i| i.all_actions(type) } 564: all_actions.flatten 565: end
Returns the destination root that is given to the generator on initialization. If the generator is a command line program, this would usually be Dir.pwd.
String | The destination root |
# File lib/templater/generator.rb, line 596 596: def destination_root 597: @destination_root # just here so it can be documented. 598: end
Finds and returns all empty directories generator creates.
[Templater::Actions::File] | The found files. |
# File lib/templater/generator.rb, line 526 526: def empty_directories 527: actions(:empty_directories) 528: end
Finds and returns all empty directories whose options match the generator options.
[Templater::Actions::EmptyDirectory] | The found empty directories that generator creates. |
# File lib/templater/generator.rb, line 502 502: def empty_directory(name) 503: empty_directories.find { |d| d.name == name } 504: end
Finds and returns the file of the given name. If that file’s options don’t match the generator options, returns nil.
name | The name of the file to look up. |
Templater::Actions::File | The found file. |
# File lib/templater/generator.rb, line 494 494: def file(name) 495: files.find { |f| f.name == name } 496: end
Finds and returns all files whose options match the generator options.
[Templater::Actions::File] | The found files. |
# File lib/templater/generator.rb, line 518 518: def files 519: actions(:files) 520: end
Finds and returns all templates whose options match the generator options.
[Templater::Generator] | The found templates. |
# File lib/templater/generator.rb, line 534 534: def invocations 535: return [] unless self.class.manifold 536: 537: self.class.invocations.map do |invocation| 538: invocation.get(self) if match_options?(invocation.options) 539: end.compact 540: end
Invokes the templates for this generator
# File lib/templater/generator.rb, line 568 568: def invoke! 569: all_actions.each { |t| t.invoke! } 570: end
Renders all actions in this generator. Use this to verify that rendering templates raises no errors.
[String] | The results of the rendered actions |
# File lib/templater/generator.rb, line 576 576: def render! 577: all_actions.map { |t| t.render } 578: end
Returns this generator’s source root
String | The source root of this generator. |
Templater::SourceNotSpecifiedError | IF the source_root class method has not been overridden. |
# File lib/templater/generator.rb, line 587 587: def source_root 588: self.class.source_root 589: end
Finds and returns the template of the given name. If that template’s options don’t match the generator options, returns nil.
name | The name of the template to look up. |
Templater::Actions::Template | The found template. |
# File lib/templater/generator.rb, line 482 482: def template(name) 483: templates.find { |t| t.name == name } 484: end
# File lib/templater/generator.rb, line 624 624: def get_argument(n) 625: @arguments[n] 626: end
# File lib/templater/generator.rb, line 632 632: def get_option(name) 633: @options[name] 634: end
# File lib/templater/generator.rb, line 636 636: def match_options?(options) 637: options.all? do |key, value| 638: key.to_sym.in?(Templater::ACTION_RESERVED_OPTIONS) or self.send(key) == value 639: end 640: end
# File lib/templater/generator.rb, line 614 614: def set_argument(n, value) 615: expected = self.class.arguments[n] 616: raise Templater::TooManyArgumentsError, "This generator does not take this many Arguments" if expected.nil? 617: 618: value = expected.extract(value) 619: 620: expected.valid?(value) 621: @arguments[n] = value 622: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.