123456789_123456789_123456789_123456789_123456789_

Class: Rake::Task

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Inherits: Object
Defined in: lib/rake/task.rb

Overview

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.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(task_name, app) ⇒ Task

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 86

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       = []
end

Class Method Details

.[](task_name)

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.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 352

def [](task_name)
  Rake.application[task_name]
end

.clear

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 339

def clear
  Rake.application.clear
end

.create_rule(*args, &block)

Define a rule for synthesizing tasks.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 369

def create_rule(*args, &block)
  Rake.application.create_rule(*args, &block)
end

.define_task(*args, &block)

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.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 364

def define_task(*args, &block)
  Rake.application.define_task(self, *args, &block)
end

.scope_name(scope, task_name)

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.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 376

def scope_name(scope, task_name)
#        (scope + [task_name]).join(':')
  scope.path_with_task_name(task_name)
end

.task_defined?(task_name) ⇒ Boolean

TRUE if the task name is already defined.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 357

def task_defined?(task_name)
  Rake.application.lookup(task_name) != nil
end

.tasks

List of all defined tasks.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 344

def tasks
  Rake.application.tasks
end

Instance Attribute Details

#actions (readonly)

List of actions attached to a task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 19

attr_reader :actions

#application (rw)

Application owning this task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 22

attr_accessor :application

#comment (rw)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 282

def comment
  transform_comments(" / ") { |c| first_sentence(c) }
end

#locations (readonly)

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).

[ GitHub ]

  
# File 'lib/rake/task.rb', line 30

attr_reader :locations

#needed?Boolean (readonly)

Is this task needed?

[ GitHub ]

  
# File 'lib/rake/task.rb', line 246

def needed?
  true
end

#prerequisites (readonly)

List of prerequisites for a task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 16

attr_reader :prerequisites

#scope (readonly)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 25

attr_reader :scope

#sources (rw)

[ GitHub ]

  
# File 'lib/rake/task.rb', line 43

def sources
  if defined?(@sources)
    @sources
  else
    prerequisites
  end
end

#sources=(value) (rw)

List of sources for task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 42

attr_writer :sources

Instance Method Details

#add_description(description)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 258

def add_description(description)
  return unless description
  comment = description.strip
  add_comment(comment) if comment && ! comment.empty?
end

#all_prerequisite_tasks

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 64

def all_prerequisite_tasks
  seen = {}
  collect_prerequisites(seen)
  seen.values
end

#arg_names

Name of arguments for this task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 126

def arg_names
  @arg_names || []
end

#clear

Clear the existing prerequisites and actions of a rake task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 137

def clear
  clear_prerequisites
  clear_actions
  clear_comments
  self
end

#clear_actions

Clear the existing actions on a rake task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 151

def clear_actions
  actions.clear
  self
end

#clear_comments

Clear the existing comments on a rake task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 157

def clear_comments
  @comments = []
  self
end

#clear_prerequisites

Clear the existing prerequisites of a rake task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 145

def clear_prerequisites
  prerequisites.clear
  self
end

#enhance(deps = nil, &block)

Enhance a task with prerequisites or actions. Returns self.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 100

def enhance(deps=nil, &block)
  @prerequisites |= deps if deps
  @actions << block if block_given?
  self
end

#execute(args = nil)

Execute the actions associated with this task.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 227

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?
  @actions.each do |act|
    case act.arity
    when 1
      act.call(self)
    else
      act.call(self, args)
    end
  end
end

#first_sentence(string) (private)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 301

def first_sentence(string)
  string.split(/\.[ \t]|\.$|\n/).first
end

#format_trace_flags (private)

Format the trace flags for display.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 218

def format_trace_flags
  flags = []
  flags << "first_time" unless @already_invoked
  flags << "not_needed" unless needed?
  flags.empty? ? "" : "(" + flags.join(", ") + ")"
end

#full_comment

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 276

def full_comment
  transform_comments("\n")
end

#investigation

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 314

def investigation
  result = "------------------------------\n"
  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 { |pre| pre.timestamp }.max
  result <<  "latest-prerequisite time: #{latest_prereq}\n"
  result << "................................\n\n"
  return result
end

#invoke(*args)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 163

def invoke(*args)
  task_args = TaskArguments.new(arg_names, args)
  invoke_with_call_chain(task_args, InvocationChain::EMPTY)
end

#name

Name of the task, including any namespace qualifiers.

[ GitHub ]

  
# File 'lib/rake/task.rb', line 107

def name
  @name.to_s
end

#prerequisite_tasks

List of prerequisite tasks

[ GitHub ]

  
# File 'lib/rake/task.rb', line 52

def prerequisite_tasks
  prerequisites.map { |pre| lookup_prerequisite(pre) }
end

#reenable

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 132

def reenable
  @already_invoked = false
end

#set_arg_names(args)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 308

def set_arg_names(args)
  @arg_names = args.map { |a| a.to_sym }
end

#source

First source from a rule (nil if no sources)

[ GitHub ]

  
# File 'lib/rake/task.rb', line 80

def source
  sources.first
end

#timestamp

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 252

def timestamp
  Time.now
end

#to_s

Return task name

[ GitHub ]

  
# File 'lib/rake/task.rb', line 33

def to_s
  name
end

#transform_comments(separator, &block) (private)

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

[ GitHub ]

  
# File 'lib/rake/task.rb', line 288

def transform_comments(separator, &block)
  if @comments.empty?
    nil
  else
    block ||= lambda { |c| c }
    @comments.map(&block).join(separator)
  end
end