gulp-showhelp
Gulp plugin to show a help message for your gulpfile.js.
Install
Install gulp-showhelp
with npm:
$ npm install --save-dev gulp-showhelp
Usage
First, load gulp-showhelp
module and add a task to show a help message in your gulpfile.js like following:
var gulp = ;var ghelp = ; gulphelp = 'shows this help message.';
Then, you can show a help message about help
task via gulp help
.
$ gulp help[gulp] Starting 'help'... Usage gulp task Tasks help : shows this help message. [gulp] Finished 'help' after 557 μs
Next, add a description to each tasks. There are three types to add.
Add a task description
1. Task only
If you want to show a description about a task with no option, add help
property as a string to a task object, e.g.:
gulphelp = 'lints all js files.';
The result is:
$ gulp help[gulp] Starting 'help'... Usage gulp task Tasks help : shows this help message. lint : lints all js files. [gulp] Finished 'help' after 660 μs
2. Task with options
If you want to show a description about a task with some options, add help
property as an object to a task object.
A value of a propery of which a key is an empty string is treated as a task description.
gulphelp = '': 'compiles source files.' '--srcs=pattern': 'specifys a path pattern of source files.' '--dest=path': 'specifys a file path.';
The result is:
$ gulp help[gulp] Starting 'help'... Usage gulp task [ option ... ] Tasks help : shows this help message. lint : lints all js files. compile : compiles source files. --srcs=pattern : specifys a path pattern of source files. --dest=path : specifys a file path. [gulp] Finished 'help' after 753 μs
3. Free description using a function
If you want to show a free format description about a task, add help
property as a function to a task object.
You can use showTask
function to show a task description and showOption
function to show a option description.
gulp { ghelp; ghelp; var text = '\n' + ' Test case IDs:\n' + ' ID : description\n' + ' ------:-------------------------------------\n' + ' case1 : .... \n' + ' case2 : .... \n' + ' case3 : .... \n' + ''; console;};
The result is:
$ gulp help[gulp] Starting 'help'... Usage gulp task [ option ... ] Tasks help : shows this help message. lint : lints all js files. compile : compiles source files. --srcs=pattern : specifys a path pattern of source files. --dest=path : specifys a file path. test : tests modules. --
Select and order tasks
You can select and order tasks of which you want to show a description by specifying task names in order.
gulphelp = 'shows this help message.';
If a null or an empty string is specified as a task name, an empty line is displayed.
Select a task via a command-line argument.
If you want to be able to select a task via a command-line argument, getArgv
function is useful. Write as follows:
gulphelp = '': 'shows this help message.' '[ --task=t ]': 'specifys a task shown. Alias: -t.' ;
APIs
API names are changed to camel case according to JavaScript coding conventions. So the functions
show_task
,show_option
,get_argv
are deprecated, but they are left for compatibility.
gulp-showhelp
provides the following functions:
.show([ ...taskname ]) : Void
Shows a help message about all tasks or specified tasks in gulpfile.js.
Parameters:
Parameter | Type | Description |
---|---|---|
taskname | string | A task name. If null or empty, displays an empty line. |
.show(tasknames) : Void
Shows a help message about tasks specified by an array in gulpfile.js.
Parameters:
Parameter | Type | Description |
---|---|---|
tasknames | Array | An array which contains task names. |
.showTask(taskname, taskdesc) : Void
Shows a task description using a help message.
Parameter | Type | Description |
---|---|---|
taskname | string | A task name. |
taskdesc | string | A task explanation. |
.showOption(optionname, optiondesc) : Void
Shows a option description using a help message.
Parameter | Type | Description |
---|---|---|
optionname | string | An option name. |
optiondesc | string | An option explanation. |
.getArgv(optionname [, optionalias, ...]) : Void
Gets a option value corresponding to the specified option name or alias.
Parameter | Type | Description |
---|---|---|
optionname | string | An option name. |
optionalias | string | An option alias. |
.taskNames() : Array
Gets an array which contains all task names.
Returns:
An array of task names.
Type: Array
License
Copyright (C) 2014-2017 Takayuki Sato.
This program is free software under MIT License. See the file LICENSE in this distribution for more details.