From b636a9c9600137e158f0cdb9a923d526bfad6f80 Mon Sep 17 00:00:00 2001 From: Janice Niemeir Date: Tue, 21 Aug 2018 17:20:46 -0700 Subject: [PATCH] Docs: Update task() documentation --- docs/api/task.md | 211 ++++++++++++++--------------------------------- 1 file changed, 63 insertions(+), 148 deletions(-) diff --git a/docs/api/task.md b/docs/api/task.md index b644de602..698cf8437 100644 --- a/docs/api/task.md +++ b/docs/api/task.md @@ -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
**(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.
**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