class Rake::Task

A Task is the basic unit of work in a Rakefile. Tasks have associated actions (possibly more than one) and a list of prerequisites. When invoked, a task will first ensure that all of its prerequisites have an opportunity to run and then it will execute its own actions.

Tasks are not usually created directly using the new method, but rather use the file and task convenience methods.

Attributes

actions[R]

List of actions attached to a task.

already_invoked[R]

Has this task already been invoked? Already invoked tasks will be skipped unless you reenable them.

application[RW]

Application owning this task.

locations[R]

File/Line locations of each of the task definitions for this task (only valid if the task was defined with the detect location option set).

order_only_prerequisites[R]

List of order only prerequisites for a task.

prereqs[R]

List of prerequisites for a task.

prerequisites[R]

List of prerequisites for a task.

scope[R]

Array of nested namespaces names used for task lookup by this task.

sources[W]

List of sources for task.

Public Class Methods

[](task_name) click to toggle source

Return a task with the given name. If the task is not currently known, try to synthesize one from the defined rules. If no rules are found, but an existing file matches the task name, assume it is a file task with no dependencies or actions.

# File rake-13.1.0/lib/rake/task.rb, line 404
def [](task_name)
  Rake.application[task_name]
end

clear() click to toggle source

Clear the task list. This cause rake to immediately forget all the tasks that have been assigned. (Normally used in the unit tests.)

# File rake-13.1.0/lib/rake/task.rb, line 391
def clear
  Rake.application.clear
end

create_rule(*args, &block) click to toggle source

Define a rule for synthesizing tasks.

# File rake-13.1.0/lib/rake/task.rb, line 421
def create_rule(*args, &block)
  Rake.application.create_rule(*args, &block)
end

define_task(*args, &block) click to toggle source

Define a task given args and an option block. If a rule with the given name already exists, the prerequisites and actions are added to the existing task. Returns the defined task.

# File rake-13.1.0/lib/rake/task.rb, line 416
def define_task(*args, &block)
  Rake.application.define_task(self, *args, &block)
end

format_deps(deps) click to toggle source

Format dependencies parameter to pass to task.

# File rake-13.1.0/lib/rake/task.rb, line 373
def self.format_deps(deps)
  deps = [deps] unless deps.respond_to?(:to_ary)
  deps.map { |d| Rake.from_pathname(d).to_s }
end

new(task_name, app) click to toggle source

Create a task named task_name with no actions or prerequisites. Use enhance to add actions and prerequisites.

# File rake-13.1.0/lib/rake/task.rb, line 99
def initialize(task_name, app)
  @name            = task_name.to_s
  @prerequisites   = []
  @actions         = []
  @already_invoked = false
  @comments        = []
  @lock            = Monitor.new
  @application     = app
  @scope           = app.current_scope
  @arg_names       = nil
  @locations       = []
  @invocation_exception = nil
  @order_only_prerequisites = []
end

scope_name(scope, task_name) click to toggle source

Apply the scope to the task name according to the rules for this kind of task. Generic tasks will accept the scope as part of the name.

# File rake-13.1.0/lib/rake/task.rb, line 428
def scope_name(scope, task_name)
  scope.path_with_task_name(task_name)
end

task_defined?(task_name) click to toggle source

TRUE if the task name is already defined.

# File rake-13.1.0/lib/rake/task.rb, line 409
def task_defined?(task_name)
  Rake.application.lookup(task_name) != nil
end

tasks() click to toggle source

List of all defined tasks.

# File rake-13.1.0/lib/rake/task.rb, line 396
def tasks
  Rake.application.tasks
end

Public Instance Methods

add_description(description) click to toggle source

Add a description to the task. The description can consist of an option argument list (enclosed brackets) and an optional comment.

# File rake-13.1.0/lib/rake/task.rb, line 298
def add_description(description)
  return unless description
  comment = description.strip
  add_comment(comment) if comment && !comment.empty?
end

all_prerequisite_tasks() click to toggle source

List of all unique prerequisite tasks including prerequisite tasks’ prerequisites. Includes self when cyclic dependencies are found.

# File rake-13.1.0/lib/rake/task.rb, line 77
def all_prerequisite_tasks
  seen = {}
  collect_prerequisites(seen)
  seen.values
end

arg_names() click to toggle source

Name of arguments for this task.

# File rake-13.1.0/lib/rake/task.rb, line 141
def arg_names
  @arg_names || []
end

clear() click to toggle source

Clear the existing prerequisites, actions, comments, and arguments of a rake task.

# File rake-13.1.0/lib/rake/task.rb, line 153
def clear
  clear_prerequisites
  clear_actions
  clear_comments
  clear_args
  self
end

clear_actions() click to toggle source

Clear the existing actions on a rake task.

# File rake-13.1.0/lib/rake/task.rb, line 168
def clear_actions
  actions.clear
  self
end

clear_args() click to toggle source

Clear the existing arguments on a rake task.

# File rake-13.1.0/lib/rake/task.rb, line 180
def clear_args
  @arg_names = nil
  self
end

clear_comments() click to toggle source

Clear the existing comments on a rake task.

# File rake-13.1.0/lib/rake/task.rb, line 174
def clear_comments
  @comments = []
  self
end

clear_prerequisites() click to toggle source

Clear the existing prerequisites of a rake task.

# File rake-13.1.0/lib/rake/task.rb, line 162
def clear_prerequisites
  prerequisites.clear
  self
end

comment() click to toggle source

First line (or sentence) of all comments. Multiple comments are separated by a “/”.

# File rake-13.1.0/lib/rake/task.rb, line 322
def comment
  transform_comments(" / ") { |c| first_sentence(c) }
end

enhance(deps=nil, &block) click to toggle source

Enhance a task with prerequisites or actions. Returns self.

# File rake-13.1.0/lib/rake/task.rb, line 115
def enhance(deps=nil, &block)
  @prerequisites |= deps if deps
  @actions << block if block_given?
  self
end

execute(args=nil) click to toggle source

Execute the actions associated with this task.

# File rake-13.1.0/lib/rake/task.rb, line 270
def execute(args=nil)
  args ||= EMPTY_TASK_ARGS
  if application.options.dryrun
    application.trace "** Execute (dry run) #{name}"
    return
  end
  application.trace "** Execute #{name}" if application.options.trace
  application.enhance_with_matching_rule(name) if @actions.empty?
  if opts = Hash.try_convert(args) and !opts.empty?
    @actions.each { |act| act.call(self, args, **opts) }
  else
    @actions.each { |act| act.call(self, args) }
  end
end

full_comment() click to toggle source

Full collection of comments. Multiple comments are separated by newlines.

# File rake-13.1.0/lib/rake/task.rb, line 316
def full_comment
  transform_comments("\n")
end

investigation() click to toggle source

Return a string describing the internal state of a task. Useful for debugging.

# File rake-13.1.0/lib/rake/task.rb, line 354
def investigation
  result = "------------------------------\n".dup
  result << "Investigating #{name}\n"
  result << "class: #{self.class}\n"
  result <<  "task needed: #{needed?}\n"
  result <<  "timestamp: #{timestamp}\n"
  result << "pre-requisites: \n"
  prereqs = prerequisite_tasks
  prereqs.sort! { |a, b| a.timestamp <=> b.timestamp }
  prereqs.each do |p|
    result << "--#{p.name} (#{p.timestamp})\n"
  end
  latest_prereq = prerequisite_tasks.map(&:timestamp).max
  result <<  "latest-prerequisite time: #{latest_prereq}\n"
  result << "................................\n\n"
  return result
end

invoke(*args) click to toggle source

Invoke the task if it is needed. Prerequisites are invoked first.

# File rake-13.1.0/lib/rake/task.rb, line 186
def invoke(*args)
  task_args = TaskArguments.new(arg_names, args)
  invoke_with_call_chain(task_args, InvocationChain::EMPTY)
end

name() click to toggle source

Name of the task, including any namespace qualifiers.

# File rake-13.1.0/lib/rake/task.rb, line 122
def name
  @name.to_s
end

needed?() click to toggle source

Is this task needed?

# File rake-13.1.0/lib/rake/task.rb, line 286
def needed?
  true
end

prerequisite_tasks() click to toggle source

List of prerequisite tasks

# File rake-13.1.0/lib/rake/task.rb, line 61
def prerequisite_tasks
  (prerequisites + order_only_prerequisites).map { |pre| lookup_prerequisite(pre) }
end

reenable() click to toggle source

Reenable the task, allowing its tasks to be executed if the task is invoked again.

# File rake-13.1.0/lib/rake/task.rb, line 147
def reenable
  @already_invoked = false
  @invocation_exception = nil
end

set_arg_names(args) click to toggle source

Set the names of the arguments for this task. args should be an array of symbols, one for each argument name.

# File rake-13.1.0/lib/rake/task.rb, line 348
def set_arg_names(args)
  @arg_names = args.map(&:to_sym)
end

source() click to toggle source

First source from a rule (nil if no sources)

# File rake-13.1.0/lib/rake/task.rb, line 93
def source
  sources.first
end

sources() click to toggle source

# File rake-13.1.0/lib/rake/task.rb, line 52
def sources
  if defined?(@sources)
    @sources
  else
    prerequisites
  end
end

timestamp() click to toggle source

Timestamp for this task. Basic tasks return the current time for their time stamp. Other tasks can be more sophisticated.

# File rake-13.1.0/lib/rake/task.rb, line 292
def timestamp
  Time.now
end

to_s() click to toggle source

Return task name

# File rake-13.1.0/lib/rake/task.rb, line 42
def to_s
  name
end

|(deps) click to toggle source

Add order only dependencies.

# File rake-13.1.0/lib/rake/task.rb, line 379
def |(deps)
  @order_only_prerequisites |= Task.format_deps(deps) - @prerequisites
  self
end

Protected Instance Methods

invoke_with_call_chain(task_args, invocation_chain) click to toggle source

Same as invoke, but explicitly pass a call chain to detect circular dependencies.

If multiple tasks depend on this one in parallel, they will all fail if the first execution of this task fails.

# File rake-13.1.0/lib/rake/task.rb, line 197
def invoke_with_call_chain(task_args, invocation_chain)
  new_chain = Rake::InvocationChain.append(self, invocation_chain)
  @lock.synchronize do
    begin
      if application.options.trace
        application.trace "** Invoke #{name} #{format_trace_flags}"
      end

      if @already_invoked
        if @invocation_exception
          if application.options.trace
            application.trace "** Previous invocation of #{name} failed #{format_trace_flags}"
          end
          raise @invocation_exception
        else
          return
        end
      end

      @already_invoked = true

      invoke_prerequisites(task_args, new_chain)
      execute(task_args) if needed?
    rescue Exception => ex
      add_chain_to(ex, new_chain)
      @invocation_exception = ex
      raise ex
    end
  end
end

Private Instance Methods

first_sentence(string) click to toggle source

Get the first sentence in a string. The sentence is terminated by the first period, exclamation mark, or the end of the line. Decimal points do not count as periods.

# File rake-13.1.0/lib/rake/task.rb, line 341
def first_sentence(string)
  string.split(/(?<=\w)(\.|!)[ \t]|(\.$|!)|\n/).first
end

format_trace_flags() click to toggle source

Format the trace flags for display.

# File rake-13.1.0/lib/rake/task.rb, line 261
def format_trace_flags
  flags = []
  flags << "first_time" unless @already_invoked
  flags << "not_needed" unless needed?
  flags.empty? ? "" : "(" + flags.join(", ") + ")"
end

transform_comments(separator, &block) click to toggle source

Transform the list of comments as specified by the block and join with the separator.

# File rake-13.1.0/lib/rake/task.rb, line 328
def transform_comments(separator, &block)
  if @comments.empty?
    nil
  else
    block ||= lambda { |c| c }
    @comments.map(&block).join(separator)
  end
end