Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 332 lines (221 sloc) 13.733 kb
7e13cf4 @cowboy More docs.
authored
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
3 # [The grunt API](api.md) / grunt.task
4
5 Underscore.js template processing and other template-related methods.
6
7 See the [task lib source](../lib/grunt/task.js) for more information.
8
9 ## The task API
10
7e1323f @cowboy More docs.
authored
11 Note that any method marked with a ☃ (unicode snowman) is available directly on the `grunt` object in addition to being available on the `grunt.task` object. Just so you know. See the [API main page](api.md) for more usage information.
78099bb @cowboy More docs.
authored
12
13
14 ## Creating Tasks
8e1ae74 @cowboy More docs.
authored
15 Tasks are grunt's bread and butter. The stuff you do most often, like `lint` or `test`. Every time grunt is run, you specify one more more tasks to run, which tells grunt what you'd like it to do.
78099bb @cowboy More docs.
authored
16
2622f7b @cowboy More docs.
authored
17 If you don't specify a task, but a task named "default" has been defined, that task will run (unsurprisingly) by default.
78099bb @cowboy More docs.
authored
18
c4c7da4 @cowboy More docs.
authored
19 ### grunt.task.registerTask ☃
78099bb @cowboy More docs.
authored
20 Register an "alias task" or a task function. This method supports the following two signatures:
21
22 **Alias task**
23
f353857 @cowboy More docs.
authored
24 If a task list is specified, the new task will be an alias for one or more other tasks. Whenever this "alias task" is run, every specified task in `taskList` will be run, in the order specified. The `taskList` argument can be a space-separated string or an array of task names.
78099bb @cowboy More docs.
authored
25
26 ```javascript
27 grunt.task.registerTask(taskName, taskList)
28 ```
29
30 This example alias task defines a "default" task whereby the "lint", "qunit", "concat" and "min" tasks are run automatically if grunt is executed without any tasks specified:
31
32 ```javascript
33 task.registerTask('default', 'lint qunit concat min');
34 ```
35
36 **Function task**
37
f683ef9 @cowboy More docs.
authored
38 If a `description` and `taskFunction` are passed, the specified function will be executed whenever the task is run. In addition, the specified description will be shown when `grunt --help` is run. Task-specific properties and methods are available inside the task function as properties of the `this` object. The task function can return `false` to indicate that the task has failed.
78099bb @cowboy More docs.
authored
39
40 Note that the `grunt.task.registerMultiTask` method, explained below, can be used to define a special type of task known as a "multi task."
41
42 ```javascript
43 grunt.task.registerTask(taskName, description, taskFunction)
44 ```
45
46 This example task logs `foo, testing 123` if grunt is run via `grunt foo:testing:123`. If the task is run without arguments as `grunt foo` the task logs `foo, no args`.
47
48 ```javascript
49 grunt.task.registerTask('foo', 'A sample task that logs stuff.', function(arg1, arg2) {
50 if (arguments.length === 0) {
51 grunt.log.writeln(this.name + ", no args");
52 } else {
53 grunt.log.writeln(this.name + ", " + arg1 + " " + arg2);
54 }
55 });
56 ```
57
58 See the [creating tasks](tasks_creating.md) documentation for more examples of tasks and alias tasks.
59
f147157 @cowboy More docs.
authored
60 _This method is also available as [grunt.registerTask](api.md)._
78099bb @cowboy More docs.
authored
61
62
6b1f693 @cowboy More docs.
authored
63 ### grunt.task.registerMultiTask ☃
78099bb @cowboy More docs.
authored
64 Register a "multi task." A multi task is a task that implicitly iterates over all of its named sub-properties (AKA targets) if no target was specified. In addition to the default properties and methods, extra multi task-specific properties are available inside the task function as properties of the `this` object.
65
66 Many of the built-in tasks, including the [lint task](task_lint.md), [concat task](task_concat.md) and [min task](task_min.md) are multi tasks.
67
68 ```javascript
69 grunt.task.registerMultiTask(taskName, description, taskFunction)
70 ```
71
72 Given the specified configuration, this example multi task would log `foo: 1,2,3` if grunt was run via `grunt log:foo`, or it would log `bar: hello world` if grunt was run via `grunt log:bar`. If grunt was run as `grunt log` however, it would log `foo: 1,2,3` then `bar: hello world` then `grunt baz: false`.
73
74 ```javascript
75 grunt.initConfig({
76 log: {
77 foo: [1, 2, 3],
78 bar: 'hello world',
79 baz: false
80 }
81 });
82
83 grunt.task.registerMultiTask('log', 'Log stuff.', function(target) {
84 grunt.log.writeln(target + ': ' + this.data);
85 });
86 ```
87
88 See the [creating tasks](tasks_creating.md) documentation for more examples of multi tasks.
89
f147157 @cowboy More docs.
authored
90 _This method is also available as [grunt.registerMultiTask](api.md)._
78099bb @cowboy More docs.
authored
91
92
6b1f693 @cowboy More docs.
authored
93 ### grunt.task.registerInitTask ☃
78099bb @cowboy More docs.
authored
94 Register an "init task." An init task is a task that doesn't require any configuration data, and as such will still run even if grunt can't find a [grunt.js gruntfile](configuring.md). The [init task](task_init.md) is an example of an init task.
95
96 ```javascript
97 grunt.task.registerInitTask(taskName, description, taskFunction)
98 ```
99
100 For an init task example, see the [init task source](../tasks/init.js).
101
f147157 @cowboy More docs.
authored
102 _This method is also available as [grunt.registerInitTask](api.md)._
78099bb @cowboy More docs.
authored
103
6b1f693 @cowboy More docs.
authored
104 ### grunt.task.renameTask ☃
78099bb @cowboy More docs.
authored
105 Rename a task. This might be useful if you want to override the default behavior of a task, while retaining the old name.
106
107 ```javascript
108 grunt.task.renameTask(oldname, newname)
109 ```
110
f147157 @cowboy More docs.
authored
111 _This method is also available as [grunt.renameTask](api.md)._
78099bb @cowboy More docs.
authored
112
113 ## Inside Tasks
2622f7b @cowboy More docs.
authored
114 An object is made available as `this` inside each task function that contains a number of useful task-specific properties and methods. This same object is also exposed as `grunt.task.current` for use in [templates](api_template.md).
78099bb @cowboy More docs.
authored
115
116 ### this.async / grunt.task.current.async
117 If a task is asynchronous, this method must be invoked to instruct grunt to wait. It returns a handle to a "done" function that should be called when the task has completed. `false` can be passed to the done function to indicate that the task has failed. If this method isn't invoked, the task executes synchronously.
118
119 ```javascript
120 // Tell grunt this task is asynchronous.
121 var done = this.async();
122 // Your async code.
123 setTimeout(function() {
124 // Let's simulate an error, sometimes.
125 var success = Math.random() > 0.5;
126 // All done!
127 done(success);
128 }, 1000);
129 ```
130
f353857 @cowboy More docs.
authored
131 ### this.requires / grunt.task.current.requires
132 If one task depends on the successful completion of another task (or tasks), this method can be used to force grunt to abort if the other task didn't run, or if the other task failed. The task list can be a space-separated string, an array of task names, or individual task name arguments.
133
a167b63 @cowboy More docs.
authored
134 Note that this won't actually run the specified task(s), it will just fail the current task if they haven't already run successfully.
5d9de74 @cowboy More docs.
authored
135
f353857 @cowboy More docs.
authored
136 ```javascript
137 this.requires(taskList)
138 ```
139
78099bb @cowboy More docs.
authored
140 ### this.name / grunt.task.current.name
141 The name of the task, as defined in `grunt.registerTask`. For example, if a "sample" task was run as `grunt sample` or `grunt sample:foo`, inside the task function, `this.name` would be `"sample"`.
142
143 ### this.nameArgs / grunt.task.current.nameArgs
144 The name of the task, as specified with any colon-separated arguments or flags on the command-line. For example, if a "sample" task was run as `grunt sample:foo`, inside the task function, `this.nameArgs` would be `"sample:foo"`.
145
146 ### this.args / grunt.task.current.args
147 An array of arguments passed to the task. For example, if a "sample" task was run as `grunt sample:foo:bar`, inside the task function, `this.args` would be `["foo", "bar"]`. Note that in multi tasks, the target is removed from the `this.args` array and is not passed into the task function.
148
149 ### this.flags / grunt.task.current.flags
150 An object generated from the arguments passed to the task. For example, if a "sample" task was run as `grunt sample:foo:bar`, inside the task function, `this.flags` would be `{foo: true, bar: true}`. In a multi task, the target name is not set as a flag.
151
f353857 @cowboy More docs.
authored
152 ### this.errorCount / grunt.task.current.errorCount
153 The number of [log.error](api_log.md) calls that occurred during this task. This can be used to fail a task if errors occurred during the task.
154
78099bb @cowboy More docs.
authored
155 ### this.extraspaths / grunt.task.current.extraspaths
156 TODO: re-evaluate
157
158
159 ## Inside Multi Tasks
160
161 ### this.target / grunt.task.current.target
162 In a multi task, this is the name of the target currently being iterated over. For example, if a "sample" multi task was run as `grunt sample:foo` with the config data `{sample: {foo: "bar"}}`, inside the task function, `this.target` would be `"foo"`.
163
164 ### this.data / grunt.task.current.data
165 In a multi task, this is the actual data stored in the grunt config object for the given target. For example, if a "sample" multi task was run as `grunt sample:foo` with the config data `{sample: {foo: "bar"}}`, inside the task function, `this.data` would be `"bar"`.
166
167 ### this.file / grunt.task.current.file
168 In a multi task, target data can be stored in two different formats. A relatively basic "compact" format and a much more flexible "full" format. When the compact format is used, that key and value are made available as `this.file.dest` and `this.file.src`, respectively. When the full format is used, the specified `src` and `dest` values are used for `this.file.dest` and `this.file.src`.
169
170 Note that while grunt supports expanding [templates](api_template.md) for both `src` and `dest`, they only work for the `dest` file path when the _full_ format is used.
171
172 ```javascript
173 grunt.initConfig({
174 concat: {
175 // This is the "compact" format.
176 'dist/built.js': ['src/file1.js', 'src/file2.js'],
177 // This is the "full" format.
178 built: {
179 src: ['src/file1.js', 'src/file2.js'],
180 dest: 'dist/built.js'
181 }
182 }
183 });
184 ```
185
186
187 ## Loading Externally-Defined Tasks
188
189
6b1f693 @cowboy More docs.
authored
190 ### grunt.task.loadTasks ☃
78099bb @cowboy More docs.
authored
191 Load task-related files from the specified directory, relative to the [grunt.js gruntfile](configuring.md). This method can be used to load task-related files from a local grunt plugin by specifying the path to that plugin's "tasks" subdirectory.
192
193 ```javascript
194 grunt.task.loadTasks(tasksPath)
195 ```
196
f147157 @cowboy More docs.
authored
197 _This method is also available as [grunt.loadTasks](api.md)._
78099bb @cowboy More docs.
authored
198
199
6b1f693 @cowboy More docs.
authored
200 ### grunt.task.loadNpmTasks ☃
78099bb @cowboy More docs.
authored
201 Load tasks and helpers from the specified Npm-installed grunt plugin. If the verion of grunt being run was installed globally via Npm, this will load a global Npm module. If the verion of grunt being run was installed locally via Npm, this will load a local Npm module.
202
203 ```javascript
204 grunt.task.loadNpmTasks(pluginName)
205 ```
206
f147157 @cowboy More docs.
authored
207 _This method is also available as [grunt.loadNpmTasks](api.md)._
78099bb @cowboy More docs.
authored
208
209
a167b63 @cowboy More docs.
authored
210 ## Helpers
211 Helpers are utility functions that can be used by any task.
212
618f76b @cowboy More docs.
authored
213 For example, in the [min task](../tasks/min.js), the majority of the actual minification work is done in an `uglify` helper, so that other tasks can utilize that minification code if they want to.
78099bb @cowboy More docs.
authored
214
6b1f693 @cowboy More docs.
authored
215 ### grunt.task.registerHelper ☃
2e59c05 @cowboy More docs.
authored
216 Register a helper function that can be used by any task. When called as a directive, `this.directive` will be true inside of the helper.
78099bb @cowboy More docs.
authored
217
218 ```javascript
219 grunt.task.registerHelper(helperName, helperFunction)
220 ```
221
222 In this example helper, the numbers `1` and `2` are passed in and the value `3` is returned.
223
224 ```javascript
225 grunt.task.registerHelper("add_two_nums", function(a, b) {
226 return a + b;
227 });
228 ```
229
f147157 @cowboy More docs.
authored
230 _This method is also available as [grunt.registerHelper](api.md)._
78099bb @cowboy More docs.
authored
231
6b1f693 @cowboy More docs.
authored
232 ### grunt.task.renameHelper ☃
78099bb @cowboy More docs.
authored
233 Rename a helper. This might be useful if you want to override the default behavior of a helper, while retaining the old name (to avoid having to completely recreate an already-made task just because you needed to override or extend a built-in helper).
234
235 ```javascript
236 grunt.task.renameHelper(oldname, newname)
237 ```
238
f147157 @cowboy More docs.
authored
239 _This method is also available as [grunt.renameHelper](api.md)._
78099bb @cowboy More docs.
authored
240
6b1f693 @cowboy More docs.
authored
241 ### grunt.task.helper ☃
78099bb @cowboy More docs.
authored
242 Invoke a registered helper function.
243
244 ```javascript
245 grunt.task.helper(helperName [, arguments...])
246 ```
247
248 In this example, the previously defined `add_two_nums` helper is invoked.
249
250 ```javascript
251 grunt.task.helper("add_two_nums", 1, 2) // 3
252 ```
253
f147157 @cowboy More docs.
authored
254 _This method is also available as [grunt.helper](api.md)._
78099bb @cowboy More docs.
authored
255
f353857 @cowboy More docs.
authored
256 ## Directives
618f76b @cowboy More docs.
authored
257 Directives are essentially string placeholders for helper functions, specified as values in the [config object](configuring.md).
a167b63 @cowboy More docs.
authored
258
259 A good example of directives would be the `<json:package.json>` and `<config:lint.all>` directives in grunt's own [grunt.js gruntfile](../grunt.js). Or the `<banner>` and `<file_strip_banner:src/grunt-jquery-example.js>` directives in the [sample jQuery plugin gruntfile](https://github.com/cowboy/grunt-jquery-example/blob/master/grunt.js).
260
f353857 @cowboy More docs.
authored
261 ### grunt.task.directive
2e59c05 @cowboy More docs.
authored
262 Manually execute a helper based on the passed string directive, returning its value. Note that this only works for synchronous helpers. When called as a directive, `this.directive` will be true inside of the helper.
7e13cf4 @cowboy More docs.
authored
263
264 ```javascript
618f76b @cowboy More docs.
authored
265 grunt.task.directive(directive)
7e13cf4 @cowboy More docs.
authored
266 ```
267
dea2db7 @cowboy More docs.
authored
268 In this example, note that the arguments passed into the helper must be coerced into numbers because all directive arguments are passed into the helper as strings.
7e13cf4 @cowboy More docs.
authored
269
270 ```javascript
618f76b @cowboy More docs.
authored
271 grunt.task.registerHelper('add_two_numbers', function(a, b) {
272 return Number(a) + Number(b);
273 });
274
275 grunt.task.directive('<add_two_numbers:1:2>') // 3
7e13cf4 @cowboy More docs.
authored
276 ```
277
f353857 @cowboy More docs.
authored
278 ### grunt.task.getDirectiveParts
2e59c05 @cowboy More docs.
authored
279 Split a valid directive into its components. Returns `null` if the string can't be parsed as a directive or if the directive doesn't match an existing helper.
7e13cf4 @cowboy More docs.
authored
280
281 ```javascript
2e59c05 @cowboy More docs.
authored
282 grunt.task.getDirectiveParts(directive)
7e13cf4 @cowboy More docs.
authored
283 ```
284
2e59c05 @cowboy More docs.
authored
285 In this example, the directive can't be parsed initially because the appropriate helper hasn't been defined. Once the helper has been defined, the directive can be parsed.
7e13cf4 @cowboy More docs.
authored
286
287 ```javascript
2e59c05 @cowboy More docs.
authored
288 grunt.task.getDirectiveParts('<foo:bar:baz>') // null
289
290 grunt.task.registerHelper('foo', function() {});
291 grunt.task.getDirectiveParts('<foo:bar:baz>') // ['foo', 'bar', 'baz']
7e13cf4 @cowboy More docs.
authored
292 ```
293
294
f353857 @cowboy More docs.
authored
295 ## Queueing Tasks
7e13cf4 @cowboy More docs.
authored
296
f353857 @cowboy More docs.
authored
297 ### grunt.task.run
7e13cf4 @cowboy More docs.
authored
298 DESCRIPTION
299
300 ```javascript
f353857 @cowboy More docs.
authored
301 grunt.task.run()
7e13cf4 @cowboy More docs.
authored
302 ```
303
304 In this example, DESCRIPTION
305
306 ```javascript
307 ```
308
f353857 @cowboy More docs.
authored
309 ### grunt.task.clearQueue
7e13cf4 @cowboy More docs.
authored
310 DESCRIPTION
311
312 ```javascript
f353857 @cowboy More docs.
authored
313 grunt.task.clearQueue()
7e13cf4 @cowboy More docs.
authored
314 ```
315
316 In this example, DESCRIPTION
317
318 ```javascript
319 ```
320
f353857 @cowboy More docs.
authored
321 ### grunt.task.runAllTargets
7e13cf4 @cowboy More docs.
authored
322 DESCRIPTION
323
324 ```javascript
f353857 @cowboy More docs.
authored
325 grunt.task.runAllTargets()
7e13cf4 @cowboy More docs.
authored
326 ```
327
328 In this example, DESCRIPTION
329
330 ```javascript
331 ```
Something went wrong with that request. Please try again.