gulp-clap v1.0.0
gulp-clap
This is a fork of gulp-cli because I don't "grasp *nix command line argument parsing"
.
NixClap:
"*nix Command Line Argument Parsing"
According to certain extensively researched NixClap knowledge, some *nix commands I've been using for decades are parsing arguments wrong.
Like grep --no-filename foo. --fixed-strings file
In the above command, according to NixClap, grep
should've considered foo.
an argument
for the option --no-filename
, and file
for --fixed-strings
, but it's not. Well, dang, whoever
wrote grep, you need to work on your understanding of NixClap. Your saving grace is at least
the man page documented these quite thoroughly.
But wait, it gets better. Certain NixClap also doesn't treat foo.
as an argument
for --no-filename
, but only that one. Apparently there's something magical
to --no-filename
, like maybe that no-
prefix in there? It's beyond me because I
lack understanding of how it works.
But really, my goal is to be able to pass options to tasks verbatim, and let tasks parse them according to their NixClap knowledge. And of course, document the semantics thoroughly, rather than tell users to bugger off or go to Stack Overflow, or throw the NixClap card. Then again, certain extensively researched NixClap have no concept of the difference between syntax and semantics.
Install
$ npm install -g gulp-clap
Usage
$ gulp [flags] [--] [task [task options] task [task options] ...]
Flags
See gulp --help
Some flags only work with gulp 4 and will be ignored when invoked against gulp 3.
gulp-clap will detect the end of flags for it and the start of tasks, but you can
also use the optional indicator --
to explicitly mark the start of tasks.
Tasks
Tasks can be executed by running gulp <task> <othertask>
. Running gulp
without specifying
any task will execute the task you registered called default
. If there is no default
task, gulp will error.
Task Options
Following each task name, you can specify a list of options that are meant for the task.
In order for gulp-clap to ignore task options and figure out the task names, the convention will
be to consider any argument not start with -
a task name. This is chosen because there's no way
for gulp-clap to know if a task option should take the next non-option argument
as a value or not, so the convention is to assume that no task option does that.
This makes everything simpler and you can do:
$ gulp task_a --boolean_a task_b --boolean_b
instead of
$ gulp task_a --boolean_a=true task_b --boolean_b=true
If you have a task option that wants to take a value, then use the convention
--option=value
instead of
--option value
Considerations
This convention is chosen so the following are possible.
- Obviously, be able to pass options to tasks verbatim, so things like these are possible:
- Invoke
task_a
withgulp task_a --help
- Use a long established convention that POSIX commands use
--
to indicate pass thru options.
- Invoke
- Easy for tasks to separate their options from other tasks when being invoked at the same time.
Quirks
This convention means that task names can't start with -
. I can introduce some other convention to allow
that, but I think it's best if task names don't start with -
.
Extracting Options For A Task
With the above convention, now it's relatively easy to extract only options that are meant for your task.
gulp.task('clap', function (done) {
var i;
var j;
var argv = process.argv;
for (i = j = argv.indexOf('clap') + 1;
j < argv.length && argv[j].startsWith('-'); j++) {
}
var clapArgs = argv.slice(i, j);
var opts = yargs.usage(usage, options).parse(clapArgs);
// use opts
done();
});
Custom Metadata
When listing tasks with the gulp -T
command, gulp-clap displays some custom metadata as defined upon task functions. Currently supported properties:
task.description
- String of the description to display.
function clean() { ... }
clean.description = 'Cleans up generated files.';
task.flags
- Object with key/value pairs being flag/description to display.
function build() { ... }
build.flags = {
'--prod': 'Builds in production mode.'
};
Example Usage:
function build() { ... }
build.description = 'Build entire project.';
build.flags = {
'--prod': 'Builds in production mode (minification, etc).'
};
// gulp 3.x
gulp.task('build', build);
// gulp 4.x
gulp.task(build);
Completion
Thanks to the grunt team, specifically Tyler Kellen
To enable tasks auto-completion in shell you should add eval "$(gulp --completion=shell)"
in your .shellrc
file.
Bash:
Add eval "$(gulp --completion=bash)"
to ~/.bashrc
.
Zsh:
Add eval "$(gulp --completion=zsh)"
to ~/.zshrc
.
Powershell:
Add Invoke-Expression ((gulp --completion=powershell) -join [System.Environment]::NewLine)
to $PROFILE
.
Fish:
Add gulp --completion=fish | source
to ~/.config/fish/config.fish
.
Compilers
You can find a list of supported languages at https://github.com/js-cli/js-interpret. If you would like to add support for a new language, send pull requests/open issues on that project.
Environment
The CLI adds process.env.INIT_CWD which is the original cwd it was launched from.
Configuration
Configuration is supported through the use of a .gulp.*
file (e.g. .gulp.json
, .gulp.yml
). You can find a list of supported languages at https://github.com/js-cli/js-interpret.
Configuration from the home directory (~
) and current working directory (cwd
) are merged with cwd
taking precedence.
Supported configurations properties:
Property | Description |
---|---|
description | Top-level description of the project/gulpfile (Replaces "Tasks for ~/path/of/gulpfile.js") |
License
MIT