Parent

Included Modules

Templater::Generator

Attributes

manifold[RW]
destination_root[RW]

Instance methods

arguments[RW]

Instance methods

options[RW]

Instance methods

Public Class Methods

actions() click to toggle source

Returns an Hash that maps the type of action to a list of ActionDescriptions.

Returns

Hash{Symbol=>Array[Templater::ActionDescription]}

A Hash of actions

    # File lib/templater/generator.rb, line 50
50:       def actions; @actions ||= {} end
argument(n, name, options={}, &block) click to toggle source

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

Parameters

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

Options (opts)

: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
arguments() click to toggle source

Returns an array of hashes, where each hash describes a single argument.

Returns

Array[Hash{Symbol=>Object}]

A list of arguments

    # File lib/templater/generator.rb, line 18
18:       def arguments; @arguments ||= []; end
desc(text = nil) click to toggle source

If the argument is omitted, simply returns the description for this generator, otherwise sets the description to the passed string.

Parameters

text

A description

Returns

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
directories() click to toggle source

Returns an array of ActionDescriptions, where each describes a single directory.

Returns

Array[Templater::ActionDescription]

A list of file descriptions.

    # File lib/templater/generator.rb, line 68
68:       def directories; actions[:directories] ||= []; end
directory(name, *args, &block) click to toggle source

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.

Parameters

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

Options

: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
directory_list(list) click to toggle source

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.

Parameters

list

A list of non-rendering templates to be added to this generator

Examples

  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
empty_directories() click to toggle source

Returns an array of ActionDescriptions, where each describes a single empty directory created by generator.

Returns

Array[Templater::ActionDescription]

A list of empty directory descriptions.

    # File lib/templater/generator.rb, line 74
74:       def empty_directories; actions[:empty_directories] ||= []; end
empty_directory(name, *args, &block) click to toggle source

Adds an empty directory that will be created when the generator is run.

Parameters

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

Options

: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
file(name, *args, &block) click to toggle source

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.

Parameters

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

Options

: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
file_list(list) click to toggle source

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.

Parameters

list

A list of non-rendering templates to be added to this generator

Examples

  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
files() click to toggle source

Returns an array of ActionDescriptions, where each describes a single file.

Returns

Array[Templater::ActionDescription]

A list of file descriptions.

    # File lib/templater/generator.rb, line 62
62:       def files; actions[:files] ||= []; end
first_argument(*args) click to toggle source

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
fourth_argument(*args) click to toggle source

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
generators() click to toggle source

Returns a list of the classes of all generators (recursively) that are invoked together with this one.

Returns

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
glob!(dir = nil, template_extensions = %w(rb css js erb html yml Rakefile TODO LICENSE README), options={}) click to toggle source

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.

Parameters

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

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
invocations() click to toggle source

Returns an array of hashes, where each hash describes a single invocation.

Returns

Array[Hash{Symbol=>Object}]

A list of invocations

    # File lib/templater/generator.rb, line 43
43:       def invocations; @invocations ||= []; end
invoke(name, options={}, &block) click to toggle source

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.

Parameters

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

Examples

  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
new(destination_root, options = {}, *args) click to toggle source

Create a new generator. Checks the list of arguments agains the requirements set using argument.

Parameters

destination_root

The destination, where the generated files will be put.

options Symbol}>

Options given to this generator.

*arguments

The list of arguments. These must match the declared requirements.

Raises

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
option(name, options={}) click to toggle source

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.

Parameters

name

The name of this option, an accessor with this name will be created for the option

options

Options for this option (how meta!)

Options (opts)

: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
options() click to toggle source

Returns an array of options, where each hash describes a single option.

Returns

Array[Hash{Symbol=>Object}]

A list of options

    # File lib/templater/generator.rb, line 37
37:       def options; @options ||= []; end
second_argument(*args) click to toggle source

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
source_root() click to toggle source

This should return the directory where source templates are located. This method must be overridden in any Generator inheriting from Templater::Source.

Raises

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
template(name, *args, &block) click to toggle source

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.

Parameters

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

Options

:before

Name of a method to execute before this template is invoked

:after

Name of a method to execute after this template is invoked

Examples

  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
template_list(list) click to toggle source

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.

Parameters

list

A list of templates to be added to this generator

Examples

  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
templates() click to toggle source

Returns an array of ActionDescriptions, where each describes a single template.

Returns

Array[Templater::ActionDescription]

A list of template descriptions.

    # File lib/templater/generator.rb, line 56
56:       def templates; actions[:templates] ||= []; end
third_argument(*args) click to toggle source

A shorthand method for adding the third argument, see +Templater::Generator.argument+

    # File lib/templater/generator.rb, line 27
27:       def third_argument(*args); argument(2, *args); end

Public Instance Methods

actions(type=nil) click to toggle source

Finds and returns all templates and files for this generators whose options match its options.

Parameters

type

The type of actions to look up (optional)

Returns

[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
after_deletion() click to toggle source
     # File lib/templater/generator.rb, line 608
608:     def after_deletion
609:       # override in subclasses if necessary
610:     end
after_generation() click to toggle source
     # File lib/templater/generator.rb, line 604
604:     def after_generation
605:       # override in subclasses if necessary
606:     end
after_run() click to toggle source
     # File lib/templater/generator.rb, line 600
600:     def after_run
601:       # override in subclasses if necessary
602:     end
all_actions(type=nil) click to toggle source

Finds and returns all templates and files for this generators and any of those generators it invokes, whose options match that generator’s options.

Returns

[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
destination_root() click to toggle source

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.

Returns

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
empty_directories() click to toggle source

Finds and returns all empty directories generator creates.

Returns

[Templater::Actions::File]

The found files.

     # File lib/templater/generator.rb, line 526
526:     def empty_directories
527:       actions(:empty_directories)
528:     end
empty_directory(name) click to toggle source

Finds and returns all empty directories whose options match the generator options.

Returns

[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
file(name) click to toggle source

Finds and returns the file of the given name. If that file’s options don’t match the generator options, returns nil.

Parameters

name

The name of the file to look up.

Returns

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
files() click to toggle source

Finds and returns all files whose options match the generator options.

Returns

[Templater::Actions::File]

The found files.

     # File lib/templater/generator.rb, line 518
518:     def files
519:       actions(:files)
520:     end
invocations() click to toggle source

Finds and returns all templates whose options match the generator options.

Returns

[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
invoke!() click to toggle source

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
render!() click to toggle source

Renders all actions in this generator. Use this to verify that rendering templates raises no errors.

Returns

[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
source_root() click to toggle source

Returns this generator’s source root

Returns

String

The source root of this generator.

Raises

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
template(name) click to toggle source

Finds and returns the template of the given name. If that template’s options don’t match the generator options, returns nil.

Parameters

name

The name of the template to look up.

Returns

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
templates() click to toggle source

Finds and returns all templates whose options match the generator options.

Returns

[Templater::Actions::Template]

The found templates.

     # File lib/templater/generator.rb, line 510
510:     def templates
511:       actions(:templates)
512:     end

Protected Instance Methods

get_argument(n) click to toggle source
     # File lib/templater/generator.rb, line 624
624:     def get_argument(n)
625:       @arguments[n]
626:     end
get_option(name) click to toggle source
     # File lib/templater/generator.rb, line 632
632:     def get_option(name)
633:       @options[name]
634:     end
match_options?(options) click to toggle source
     # 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
set_argument(n, value) click to toggle source
     # 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
set_option(name, value) click to toggle source
     # File lib/templater/generator.rb, line 628
628:     def set_option(name, value)
629:       @options[name] = value
630:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.