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
List of actions attached to a task.
Has this task already been invoked? Already invoked tasks will be skipped unless you reenable them.
Application
owning this task.
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).
List of order only prerequisites for a task.
List of prerequisites for a task.
List of prerequisites for a task.
Array of nested namespaces names used for task lookup by this task.
List of sources for task.
Public Class Methods
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 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
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 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 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
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
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
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
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 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
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
Name of arguments for this task.
# File rake-13.1.0/lib/rake/task.rb, line 141 def arg_names @arg_names || [] end
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 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 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 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 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
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 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 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 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
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 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 of the task, including any namespace qualifiers.
# File rake-13.1.0/lib/rake/task.rb, line 122 def name @name.to_s end
Is this task needed?
# File rake-13.1.0/lib/rake/task.rb, line 286 def needed? true end
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 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 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
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
# File rake-13.1.0/lib/rake/task.rb, line 52 def sources if defined?(@sources) @sources else prerequisites end end
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
Return task name
# File rake-13.1.0/lib/rake/task.rb, line 42 def to_s name end
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
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
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 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 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