Skip to content

Commit

Permalink
Docs: Update task() documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@janiceilene @phated
janiceilene authored and phated committed Oct 19, 2018
1 parent d580efa commit b636a9c
Showing 1 changed file with 63 additions and 148 deletions.
211 changes: 63 additions & 148 deletions docs/api/task.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,190 +5,105 @@ hide_title: true
sidebar_label: task()
-->

# `gulp.task([name,] fn)`
# task()

Define a task exposed to gulp-cli, `gulp.series`, `gulp.parallel` and
`gulp.lastRun`; inherited from [undertaker].
**Reminder**: This API isn't the recommended pattern anymore - export your tasks.

```js
gulp.task(function someTask() {
// Do stuff
});
```
Defines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs.

Or get a task that has been registered.
## Usage

Register a named function as a task:
```js
// someTask will be the registered task function
var someTask = gulp.task('someTask');
```

## name
Type: `String`

If the name is not provided, the task will be named after the function
`name` or `displayName` property. The name argument is required if the
`name` and `displayName` properties of `fn` are empty.
const { task } = require('gulp');

Since the task can be run from the command line, you should avoid using
spaces in task names.

## fn

The function that performs the task's operations. Generally it takes this form:

```js
function someTask() {
return gulp.src(['some/glob/**/*.ext']).pipe(someplugin());
function build(cb) {
// body omitted
cb();
}
someTask.description = 'Does something';

gulp.task(someTask)
task(build);
```

Gulp tasks are asynchronous and Gulp uses [async-done] to wait for the task's
completion. Tasks are called with a callback parameter to call to signal
completion. Alternatively, Task can return a stream, a promise, a child process
or a RxJS observable to signal the end of the task.

**Warning:** Sync tasks are not supported and your function will never complete
if the one of the above strategies is not used to signal completion. However,
thrown errors will be caught by Gulp.

## fn properties

### fn.name

`gulp.task` names the task after the function `name` property
if the optional `name` parameter of `gulp.task` is not provided.

**Note:** [Function.name] is not writable; it cannot be set or edited. If
you need to assign a function name or use characters that aren't allowed
in function names, use the `displayName` property.
It will be empty for anonymous functions:

Register an anonymous function as a task:
```js
function foo() {};
foo.name === 'foo' // true

var bar = function() {};
bar.name === '' // true
const { task } = require('gulp');

bar.name = 'bar'
bar.name === '' // true
task('build', function(cb) {
// body omitted
cb();
});
```

### fn.displayName

`gulp.task` names the task after the function `displayName` property
if function is anonymous and the optional `name` parameter of `gulp.task`
is not provided.

### fn.description

gulp-cli prints this description alongside the task name when listing tasks:

Retrieve a task that has been registered previously:
```js
var gulp = require('gulp');

function test(done){
done();
}
test.description = 'I do nothing';
const { task } = require('gulp');

gulp.task(test);
```
task('build', function(cb) {
// body omitted
cb();
});

```sh
$> gulp --tasks
[12:00:02] Tasks for ~/Documents/some-project/gulpfile.js
[12:00:02] └── test I do nothing
const build = task('build');
```

## Async support

### Accept a callback
## Signature

```js
var del = require('del');
task([taskName], taskFunction)
```

gulp.task('clean', function(done) {
del(['.build/'], done);
});
### Parameters

// use an async result in a pipe
gulp.task('somename', function(cb) {
getFilesAsync(function(err, res) {
if (err) return cb(err);
var stream = gulp.src(res)
.pipe(minify())
.pipe(gulp.dest('build'))
.on('end', cb);
});
});
```
If the `taskName` is not provided, the task will be referenced by the `name` property of a named function or a user-defined `displayName` property. The `taskName` parameter must be used for anonymous functions missing a `displayName` property.

The callback accepts an optional `Error` object. If it receives an error,
the task will fail.
Since any registered task can be run from the command line, avoid using spaces in task names.

### Return a stream
| parameter | type | note |
|:--------------:|:------:|-------|
| taskName | string | An alias for the task function within the the task system. Not needed when using named functions for `taskFunction`. |
| taskFunction <br> **(required)** | function | A [task function][tasks-concepts] or composed task - generated by `series()` and `parallel()`. Ideally a named function. [Task metadata][task-metadata-section] can be attached to provide extra information to the command line. |

```js
gulp.task('somename', function() {
return gulp.src('client/**/*.js')
.pipe(minify())
.pipe(gulp.dest('build'));
});
```
### Returns

### Return a promise
When registering a task, nothing is returned.

```js
var Promise = require('promise');
var del = require('del');

gulp.task('clean', function() {
return new Promise(function (resolve, reject) {
del(['.build/'], function(err) {
if (err) {
reject(err);
} else {
resolve();
}
});
});
});
```
When retrieving a task, a wrapped task (not the original function) registered as `taskName` will be returned. The wrapped task has an `unwrap()` method that will return the original function.

or:
```js
var promisedDel = require('promised-del');
### Errors

gulp.task('clean', function() {
return promisedDel(['.build/']);
});
```
When registering a task where `taskName` is missing and `taskFunction` is anonymous, will throw an error with the message, "Task name must be specified".

## Task metadata

### Return a child process
| property | type | note |
|:--------------:|:------:|-------|
| name | string | A special property of named functions. Used to register the task. <br> **Note:** [`name`][function-name-external] is not writable; it cannot be set or changed. |
| displayName | string | When attached to a `taskFunction` creates an alias for the task. If using characters that aren't allowed in function names, use this property. |
| description | string | When attached to a `taskFunction` provides a description to be printed by the command line when listing tasks. |
| flags | object | When attached to a `taskFunction` provides flags to be printed by the command line when listing tasks. The keys of the object represent the flags and the values are their descriptions. |

```js
gulp.task('clean', function() {
return spawn('rm', ['-rf', path.join(__dirname, 'build')]);
});
const { task } = require('gulp');

```
const clean = function(cb) {
// body omitted
cb();
};
clean.displayName = 'clean:all';

### Return a [RxJS] observable
task(clean);

```js
var Observable = require('rx').Observable;
function build(cb) {
// body omitted
cb();
}
build.description = 'Build the project';
build.flags = { '-e': 'An example flag' };

gulp.task('sometask', function() {
return Observable.return(42);
});
task(build);
```

[Function.name]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
[RxJS]: https://www.npmjs.com/package/rx
[async-done]: https://www.npmjs.com/package/async-done
[undertaker]: https://github.com/gulpjs/undertaker
[task-metadata-section]: #task-metadata
[task-concepts]: concepts.md#tasks
[function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name

0 comments on commit b636a9c

Please sign in to comment.