class Rake::Task

  1. lib/rake/task.rb
Parent: Rake

######################################################################### 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

prerequisites [R]

List of prerequisites for a task.

actions [R]

List of actions attached to a task.

application [RW]

Application owning this task.

comment [R]

Comment for this task. Restricted to a single line of no more than 50 characters.

full_comment [R]

Full text of the (possibly multi-line) comment.

scope [R]

Array of nested namespaces names used for task lookup by 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).

sources [W]

List of sources for task.

Public Instance methods

to_s ()

Return task name

[show source]
    # File lib/rake/task.rb, line 40
40:     def to_s
41:       name
42:     end
inspect ()
[show source]
    # File lib/rake/task.rb, line 44
44:     def inspect
45:       "<#{self.class} #{name} => [#{prerequisites.join(', ')}]>"
46:     end
sources ()
[show source]
    # File lib/rake/task.rb, line 50
50:     def sources
51:       @sources ||= []
52:     end
prerequisite_tasks ()

List of prerequisite tasks

[show source]
    # File lib/rake/task.rb, line 55
55:     def prerequisite_tasks
56:       prerequisites.collect { |pre| lookup_prerequisite(pre) }
57:     end
source ()

First source from a rule (nil if no sources)

[show source]
    # File lib/rake/task.rb, line 65
65:     def source
66:       @sources.first if defined?(@sources)
67:     end
enhance (deps=nil, &block)

Enhance a task with prerequisites or actions. Returns self.

[show source]
    # File lib/rake/task.rb, line 86
86:     def enhance(deps=nil, &block)
87:       @prerequisites |= deps if deps
88:       @actions << block if block_given?
89:       self
90:     end
name ()

Name of the task, including any namespace qualifiers.

[show source]
    # File lib/rake/task.rb, line 93
93:     def name
94:       @name.to_s
95:     end
arg_names ()

Name of arguments for this task.

[show source]
     # File lib/rake/task.rb, line 112
112:     def arg_names
113:       @arg_names || []
114:     end
reenable ()

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

[show source]
     # File lib/rake/task.rb, line 118
118:     def reenable
119:       @already_invoked = false
120:     end
clear ()

Clear the existing prerequisites and actions of a rake task.

[show source]
     # File lib/rake/task.rb, line 123
123:     def clear
124:       clear_prerequisites
125:       clear_actions
126:       self
127:     end
clear_prerequisites ()

Clear the existing prerequisites of a rake task.

[show source]
     # File lib/rake/task.rb, line 130
130:     def clear_prerequisites
131:       prerequisites.clear
132:       self
133:     end
clear_actions ()

Clear the existing actions on a rake task.

[show source]
     # File lib/rake/task.rb, line 136
136:     def clear_actions
137:       actions.clear
138:       self
139:     end
invoke (*args)

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

[show source]
     # File lib/rake/task.rb, line 142
142:     def invoke(*args)
143:       if application.options.threads == 1
144:         invoke_serial(*args)
145:       else
146:         invoke_parallel(*args)
147:       end
148:     end
execute (args=nil)

Execute the actions associated with this task.

[show source]
     # File lib/rake/task.rb, line 214
214:     def execute(args=nil)
215:       args ||= EMPTY_TASK_ARGS
216:       if application.options.dryrun
217:         $stderr.puts "** Execute (dry run) #{name}"
218:         return
219:       end
220:       if application.options.trace
221:         $stderr.puts "** Execute #{name}"
222:       end
223:       application.enhance_with_matching_rule(name) if @actions.empty?
224:       @actions.each do |act|
225:         case act.arity
226:         when 1
227:           act.call(self)
228:         else
229:           act.call(self, args)
230:         end
231:       end
232:     end
needed? ()

Is this task needed?

[show source]
     # File lib/rake/task.rb, line 235
235:     def needed?
236:       true
237:     end
timestamp ()

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

[show source]
     # File lib/rake/task.rb, line 241
241:     def timestamp
242:       prerequisite_tasks.collect { |pre| pre.timestamp }.max || Time.now
243:     end
add_description (description)

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

[show source]
     # File lib/rake/task.rb, line 247
247:     def add_description(description)
248:       return if ! description
249:       comment = description.strip
250:       add_comment(comment) if comment && ! comment.empty?
251:     end
comment= (description)

Writing to the comment attribute is the same as adding a description.

[show source]
     # File lib/rake/task.rb, line 254
254:     def comment=(description)
255:       add_description(description)
256:     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.

[show source]
     # File lib/rake/task.rb, line 277
277:     def set_arg_names(args)
278:       @arg_names = args.map { |a| a.to_sym }
279:     end
investigation ()

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

[show source]
     # File lib/rake/task.rb, line 283
283:     def investigation
284:       result = "------------------------------\n"
285:       result << "Investigating #{name}\n"
286:       result << "class: #{self.class}\n"
287:       result <<  "task needed: #{needed?}\n"
288:       result <<  "timestamp: #{timestamp}\n"
289:       result << "pre-requisites: \n"
290:       prereqs = prerequisite_tasks
291:       prereqs.sort! {|a,b| a.timestamp <=> b.timestamp}
292:       prereqs.each do |p|
293:         result << "--#{p.name} (#{p.timestamp})\n"
294:       end
295:       latest_prereq = prerequisite_tasks.collect { |pre| pre.timestamp }.max
296:       result <<  "latest-prerequisite time: #{latest_prereq}\n"
297:       result << "................................\n\n"
298:       return result
299:     end

Private Instance methods

lookup_prerequisite (prerequisite_name)
[show source]
    # File lib/rake/task.rb, line 59
59:     def lookup_prerequisite(prerequisite_name)
60:       application[prerequisite_name, @scope]
61:     end
add_chain_to (exception, new_chain)
[show source]
     # File lib/rake/task.rb, line 188
188:     def add_chain_to(exception, new_chain)
189:       exception.extend(InvocationExceptionMixin) unless exception.respond_to?(:chain)
190:       exception.chain = new_chain if exception.chain.nil?
191:     end
format_trace_flags ()

Format the trace flags for display.

[show source]
     # File lib/rake/task.rb, line 205
205:     def format_trace_flags
206:       flags = []
207:       flags << "first_time" unless @already_invoked
208:       flags << "not_needed" unless needed?
209:       flags.empty? ? "" : "(" + flags.join(", ") + ")"
210:     end
add_comment (comment)

Add a comment to the task. If a comment already exists, separate the new comment with “ / “.

[show source]
     # File lib/rake/task.rb, line 260
260:     def add_comment(comment)
261:       if @full_comment
262:         @full_comment << " / "
263:       else
264:         @full_comment = ''
265:       end
266:       @full_comment << comment
267:       if @full_comment =~ /\A([^.]+?\.)( |$)/
268:         @comment = $1
269:       else
270:         @comment = @full_comment
271:       end
272:     end

Public Class methods

new (task_name, app)

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

[show source]
    # File lib/rake/task.rb, line 71
71:     def initialize(task_name, app)
72:       @name = task_name.to_s
73:       @prerequisites = []
74:       @actions = []
75:       @already_invoked = false
76:       @full_comment = nil
77:       @comment = nil
78:       @lock = Monitor.new
79:       @application = app
80:       @scope = app.current_scope
81:       @arg_names = nil
82:       @locations = []
83:     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.)

[show source]
     # File lib/rake/task.rb, line 308
308:       def clear
309:         Rake.application.clear
310:       end
tasks ()

List of all defined tasks.

[show source]
     # File lib/rake/task.rb, line 313
313:       def tasks
314:         Rake.application.tasks
315:       end
[] (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.

[show source]
     # File lib/rake/task.rb, line 321
321:       def [](task_name)
322:         Rake.application[task_name]
323:       end
task_defined? (task_name)

TRUE if the task name is already defined.

[show source]
     # File lib/rake/task.rb, line 326
326:       def task_defined?(task_name)
327:         Rake.application.lookup(task_name) != nil
328:       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.

[show source]
     # File lib/rake/task.rb, line 333
333:       def define_task(*args, &block)
334:         Rake.application.define_task(self, *args, &block)
335:       end
create_rule (*args, &block)

Define a rule for synthesizing tasks.

[show source]
     # File lib/rake/task.rb, line 338
338:       def create_rule(*args, &block)
339:         Rake.application.create_rule(*args, &block)
340:       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.

[show source]
     # File lib/rake/task.rb, line 345
345:       def scope_name(scope, task_name)
346:         (scope + [task_name]).join(':')
347:       end