gulp-command-handling

Table of contents

1. Introduction
2. Installation
   • System requirements
3. Main features
4. Usage
   • Command line structure
   • Methods
   • Custom definition
5. Example
6. Thank you!

1. Introduction

The lightweight library is used for Gulp application. It's useful when you want to enhance the Gulp CLI with your own parameters (option, sub option, argument).

The development is using:

• [x] Plain JavaScript ES6
• [x] No using other library
• [x] Simplification , effect and performance

2. Installation

$ npm install gulp-command-handling

System requirements

• The minimum support for:
  • Node.js version is 8.17.0 (LTS version is a good choice for the stability).
  • Gulp.js version is 4.0.0 (Gulp CLI is installed on global).

3. Main features

• Enhancement for the Gulp CLI with your own parameters (option, sub option, argument).
• Using alias for option and sub option.
• Command combination for many times you need.
• Using custom regular expression (RegExp) for your reason when needed. (It applies for params validation)

Examples:

• $ gulp build -s -m FlowerSite (Simple using)
• $ gulp release --site --minify FlowerSite (Using alias)
• $ gulp build --site --minify FlowerSite --move-to "/home/dev" (Combination 2 times)
• $ gulp build -s -m -o FlowerSite -t "/home/dev" -n flowersite-v1.0.0 (Combination 3 times)

4. Usage

Command line structure

The simple command line structure is used in this library:

$ gulp <task> [-option] [-subOptions] [argument]

• An option has only an alias and it has many sub options.
• An alias is used as a key in the result object.
• An argument is the end of a part in the command.

BEWARE! You should not using the options that are already using for Gulp CLI. Example: -h , -v, -f etc. Use the command gulp --help to view more about that.

Methods

| Method | Argument | Description | |---|---|---| |.setting()|Object|Custom definition (Ex: custom RegExp)| |.option()|<task>, <option>, <optionAlias>, [description]|Option definition| |.subOption()|<task>, <optionAlias>, <subOption>, <subOptionAlias>, [description]|Sub option definition| |.getOptions()||It returns an option list that is an object| |.parse()|<process.argv>|Parse the command line (Ex: process.argv.slice(2))|

You can use method chaining with the following order:

|Method|Order|Description| |---|---|---| |.setting()|First|The method must be in the first position of chaining| |.option()|Between|| |.subOption()|Between|| |.parse()|Last|The method must be in the last position of chaining|

Custom definition

Regular Express (RegExp) is used for data validation. You can redefine them for your reason when needed by using the method .setting(). The general regexps are using if you don't use your own.

It just now supports regexps for option, alias and argument validation. You should only change values of the properties: regexOption, regexAlias and regexArgument.

View the example for more detail.

5. Example

View more in the example /gulpfile.js on GitHub repo.

/* gulpfile.js */

const { Command } = require('gulp-command-handling');
const gulpCommand = new Command();

// Using custom RegExp when needed
const customSettings = {
    regexOption: false, //Default is false
    regexAlias: false,
    regexArgument: [a-z]/i,
};

// Command definition
gulpCommand
    .setting(customSettings)
    .option('build', '-s', '--site', 'Building styling for a specific site')
    .subOption('build', '--site', '-m', '--minify', 'Minify files in destination');
    .subOption('build', '--site', '-o', '--overwrite', 'Overwrite files in destination')

// Using in a Gulp task
function build(cb) {
    const result = gulpCommand.parse(process.argv.slice(2));

    if (result.site) {
        if (result.site.minify) {
            console.log('Minification task -> Done!');
        }

        if (result.site.overwrite) {
            console.log('Overwriting task -> Done!');
        }
    } else {
        console.log('Nothing to do');
    }

    cb();
}

exports.build = build;

// Running the commands for testing purpose
$ gulp build -s -m -o FlowerSite
$ gulp build --site --minify --overwrite FlowerSite

6. Thank you!

Many thanks to Commander.js for the inspiration.