Module: Thor::Invocation

Defined in:
lib/thor/invocation.rb

Defined Under Namespace

Modules: ClassMethods

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (Object) included(base)

:nodoc:



3
4
5
# File 'lib/thor/invocation.rb', line 3

def self.included(base) #:nodoc:
  base.extend ClassMethods
end

Instance Method Details

- (Invocation) initialize(args = [], options = {}, config = {}, &block)

Make initializer aware of invocations and the initialization args.



22
23
24
25
26
# File 'lib/thor/invocation.rb', line 22

def initialize(args=[], options={}, config={}, &block) #:nodoc:
  @_invocations = config[:invocations] || Hash.new { |h,k| h[k] = [] }
  @_initializer = [ args, options, config ]
  super
end

- (Object) invoke(name = nil, *args)

Receives a name and invokes it. The name can be a string (either "task" or "namespace:task"), a Thor::Task, a Class or a Thor instance. If the task cannot be guessed by name, it can also be supplied as second argument.

You can also supply the arguments, options and configuration values for the task to be invoked, if none is given, the same values used to initialize the invoker are used to initialize the invoked.

When no name is given, it will invoke the default task of the current class.

Examples

class A < Thor
  def foo
    invoke :bar
    invoke "b:hello", ["Jos??"]
  end

  def bar
    invoke "b:hello", ["Jos??"]
  end
end

class B < Thor
  def hello(name)
    puts "hello #{name}"
  end
end

You can notice that the method "foo" above invokes two tasks: "bar", which belongs to the same class and "hello" which belongs to the class B.

By using an invocation system you ensure that a task is invoked only once. In the example above, invoking "foo" will invoke "b:hello" just once, even if it's invoked later by "bar" method.

When class A invokes class B, all arguments used on A initialization are supplied to B. This allows lazy parse of options. Let's suppose you have some rspec tasks:

class Rspec < Thor::Group
  class_option :mock_framework, :type => :string, :default => :rr

  def invoke_mock_framework
    invoke "rspec:#{options[:mock_framework]}"
  end
end

As you noticed, it invokes the given mock framework, which might have its own options:

class Rspec::RR < Thor::Group
  class_option :style, :type => :string, :default => :mock
end

Since it's not rspec concern to parse mock framework options, when RR is invoked all options are parsed again, so RR can extract only the options that it's going to use.

If you want Rspec::RR to be initialized with its own set of options, you have to do that explicitly:

invoke "rspec:rr", [], :style => :foo

Besides giving an instance, you can also give a class to invoke:

invoke Rspec::RR, [], :style => :foo


96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
# File 'lib/thor/invocation.rb', line 96

def invoke(name=nil, *args)
  if name.nil?
    warn "[Thor] Calling invoke() without argument is deprecated. Please use invoke_all instead.\n#{caller.join("\n")}"
    return invoke_all
  end

  args.unshift(nil) if Array === args.first || NilClass === args.first
  task, args, opts, config = args

  klass, task = _retrieve_class_and_task(name, task)
  raise "Expected Thor class, got #{klass}" unless klass <= Thor::Base

  args, opts, config = _parse_initialization_options(args, opts, config)
  klass.send(:dispatch, task, args, opts, config) do |instance|
    instance.parent_options = options
  end
end

- (Object) invoke_all

Invoke all tasks for the current instance.



125
126
127
# File 'lib/thor/invocation.rb', line 125

def invoke_all #:nodoc:
  self.class.all_tasks.map { |_, task| invoke_task(task) }
end

- (Object) invoke_task(task, *args)

Invoke the given task if the given args.



115
116
117
118
119
120
121
122
# File 'lib/thor/invocation.rb', line 115

def invoke_task(task, *args) #:nodoc:
  current = @_invocations[self.class]

  unless current.include?(task.name)
    current << task.name
    task.run(self, *args)
  end
end

- (Object) invoke_with_padding(*args)

Invokes using shell padding.



130
131
132
# File 'lib/thor/invocation.rb', line 130

def invoke_with_padding(*args)
  with_padding { invoke(*args) }
end