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
-
.[](task_name)
Return a task with the given name.
-
.clear
Clear the task list.
-
.create_rule(*args, &block)
Define a rule for synthesizing tasks.
-
.define_task(*args, &block)
Define a task given
args
and an option block. -
.new(task_name, app) ⇒ Task
constructor
Create a task named
task_name
with no actions or prerequisites. -
.scope_name(scope, task_name)
Apply the scope to the task name according to the rules for this kind of task.
-
.task_defined?(task_name) ⇒ Boolean
TRUE if the task name is already defined.
-
.tasks
List of all defined tasks.
Instance Attribute Summary
-
#application
rw
Application owning this task.
-
#comment
rw
First line (or sentence) of all comments.
- #sources rw
-
#sources=(value)
rw
List of sources for task.
-
#actions
readonly
List of actions attached to a task.
-
#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).
-
#needed? ⇒ Boolean
readonly
Is this task needed?
-
#prerequisites
readonly
List of prerequisites for a task.
-
#scope
readonly
Array of nested namespaces names used for task lookup by this task.
Instance Method Summary
-
#add_description(description)
Add a description to the task.
-
#all_prerequisite_tasks
List of all unique prerequisite tasks including prerequisite tasks' prerequisites.
-
#arg_names
Name of arguments for this task.
-
#clear
Clear the existing prerequisites and actions of a rake task.
-
#clear_actions
Clear the existing actions on a rake task.
-
#clear_comments
Clear the existing comments on a rake task.
-
#clear_prerequisites
Clear the existing prerequisites of a rake task.
-
#enhance(deps = nil, &block)
Enhance a task with prerequisites or actions.
-
#execute(args = nil)
Execute the actions associated with this task.
-
#full_comment
Full collection of comments.
-
#investigation
Return a string describing the internal state of a task.
-
#invoke(*args)
Invoke the task if it is needed.
-
#name
Name of the task, including any namespace qualifiers.
-
#prerequisite_tasks
List of prerequisite tasks.
-
#reenable
Reenable the task, allowing its tasks to be executed if the task is invoked again.
-
#set_arg_names(args)
Set the names of the arguments for this task.
-
#source
First source from a rule (nil if no sources).
-
#timestamp
Timestamp for this task.
-
#to_s
Return task name.
-
#first_sentence(string)
private
Get the first sentence in a string.
-
#format_trace_flags
private
Format the trace flags for display.
-
#transform_comments(separator, &block)
private
Transform the list of comments as specified by the block and join with the separator.
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.
# 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.
# 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.)
# File 'lib/rake/task.rb', line 339
def clear Rake.application.clear end
.create_rule(*args, &block)
Define a rule for synthesizing tasks.
# 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.
# 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.
.task_defined?(task_name) ⇒ Boolean
TRUE if the task name is already defined.
# 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.
# 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.
# File 'lib/rake/task.rb', line 19
attr_reader :actions
#application (rw)
Application owning this task.
# 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 “/”.
# 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).
# File 'lib/rake/task.rb', line 30
attr_reader :locations
#needed? ⇒ Boolean
(readonly)
Is this task needed?
# File 'lib/rake/task.rb', line 246
def needed? true end
#prerequisites (readonly)
List of prerequisites for a task.
# File 'lib/rake/task.rb', line 16
attr_reader :prerequisites
#scope (readonly)
Array of nested namespaces names used for task lookup by this task.
# 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.
# 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.
# 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.
# 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.
# File 'lib/rake/task.rb', line 126
def arg_names @arg_names || [] end
#clear
Clear the existing prerequisites and actions of a rake task.
# 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.
#clear_comments
Clear the existing comments on a rake task.
# File 'lib/rake/task.rb', line 157
def clear_comments @comments = [] self end
#clear_prerequisites
Clear the existing prerequisites of a rake task.
# 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.
# 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.
# File 'lib/rake/task.rb', line 227
def execute(args=nil) args ||= EMPTY_TASK_ARGS if application. .dryrun application.trace "** Execute (dry run) #{name}" return end application.trace "** Execute #{name}" if application. .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.
# 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.
# 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.
# 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.
# 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: #{}\n" result << "pre-requisites: \n" prereqs = prerequisite_tasks prereqs.sort! { |a, b| a. <=> b. } prereqs.each do |p| result << "--#{p.name} (#{p.})\n" end latest_prereq = prerequisite_tasks.map { |pre| pre. }.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.
# 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.
# File 'lib/rake/task.rb', line 107
def name @name.to_s end
#prerequisite_tasks
List of prerequisite tasks
# 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.
# 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.
# 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)
# 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.
# File 'lib/rake/task.rb', line 252
def Time.now end
#to_s
Return task name
# 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.
# 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