gulp-showhelp

    1.2.0 • Public • Published

    gulp-showhelp NPM version MIT License Build Status Build Status Coverage Status

    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 = require('gulp');
    var ghelp = require('gulp-showhelp');
     
    gulp.task('help', function() {
      ghelp.show();
    }).help = '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.:

    gulp.task('lint', function() {
      ...
    }).help = '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.

    gulp.task('compile', function() {
      ...
    }).help = {
      '': '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.task('test', function(){
      ...
    }).help = function() {
      ghelp.showTask('test', 'tests modules.');
      ghelp.showOption('--case=id', 'specifys a test case ID.');
      var text = '\n' +
        '    Test case IDs:\n' +
        '        ID  :        description\n' +
        '      ------:-------------------------------------\n' +
        '      case1 : .... \n' +
        '      case2 : .... \n' +
        '      case3 : .... \n' +
        '';
      console.log(text);
    };

    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.
        --case=id : specifys a test case ID.
     
        Test case IDs:
            ID  :        description
          ------:-------------------------------------
          case1 : .... 
          case2 : .... 
          case3 : .... 
     
     
    [gulp] Finished 'help' after 934 μs

    Select and order tasks

    You can select and order tasks of which you want to show a description by specifying task names in order.

    gulp.task('help', function() {
      ghelp.show('lint', 'help', '', 'compile');
    }).help = '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:

    gulp.task('help', function() {
      var task = ghelp.getArgv('task', 't');
      if (task != null) {
        ghelp.show(task);
      } else {
        ghelp.show();
      }
    }).help = {
      '': '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.

    Install

    npm i gulp-showhelp

    DownloadsWeekly Downloads

    55

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    14.3 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar