指挥官.js
彻底解决 节点.js 命令行界面,灵感来自Ruby's 指挥官。 。 。 .
API 文档
安装
$ npm install commander --save
选项解析
带有命令的选项与 .option() 方法,也可作为选项的文档。 下面的示例从 process.argv中,留下剩余参数作为 program.args 未为选项所消耗的数组.
#!/usr/bin/env node
/**
* Module dependencies.
*/
var program = require('commander');
program
.version('0.1.0')
.option('-p, --peppers', 'Add peppers')
.option('-P, --pineapple', 'Add pineapple')
.option('-b, --bbq-sauce', 'Add bbq sauce')
.option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
.parse(process.argv);
console.log('you ordered a pizza with:');
if (program.peppers) console.log(' - peppers');
if (program.pineapple) console.log(' - pineapple');
if (program.bbqSauce) console.log(' - bbq');
console.log(' - %s cheese', program.cheese);
例如, 短旗可以作为单一的坐标传递 -abc 等同为 -a -b -c. "--template-engine"等多词选项被骆驼套入,成为"--template-engine" program.templateEngine 包括:.
请注意,从 --no 前缀否定了以下单词的布尔值。 譬如说, --no-sauce 设置值 program.sauce 以假相报.
#!/usr/bin/env node
/**
* Module dependencies.
*/
var program = require('commander');
program
.option('--no-sauce', 'Remove sauce')
.parse(process.argv);
console.log('you ordered a pizza');
if (program.sauce) console.log(' with sauce');
else console.log(' without sauce');
版本选项
呼叫电话 version 隐含地添加 -V 财务报告和审定财务报表 --version 选项.
当其中任一选项出现时,命令会打印出版本编号并退出.
$ ./examples/pizza -V
0.0.1
如果你想让你的程序响应 -v 选项而不是 -V 选项,仅将自定义标记传递到 version 方法使用与 option 方法.
program
.version('0.0.1', '-v, --version')
版本旗可以命名任何东西,但需要较长的选项.
命令特定选项
您可以在命令中附加选项.
#!/usr/bin/env node
var program = require('commander');
program
.command('rm <dir>')
.option('-r, --recursive', 'Remove recursively')
.action(function (dir, cmd) {
console.log('remove ' + dir + (cmd.recursive ? ' recursively' : ''))
})
program.parse(process.argv)
在使用命令时验证命令的选项 。 任何未知的选项都会被报告为出错. 然而,如果一个基于动作的命令没有定义一个动作,那么选项就不会被验证.
胁迫
function range(val) {
return val.split('..').map(Number);
}
function list(val) {
return val.split(',');
}
function collect(val, memo) {
memo.push(val);
return memo;
}
function increaseVerbosity(v, total) {
return total + 1;
}
program
.version('0.1.0')
.usage('[options] <file ...>')
.option('-i, --integer <n>', 'An integer argument', parseInt)
.option('-f, --float <n>', 'A float argument', parseFloat)
.option('-r, --range <a>..<b>', 'A range', range)
.option('-l, --list <items>', 'A list', list)
.option('-o, --optional [value]', 'An optional value')
.option('-c, --collect [value]', 'A repeatable value', collect, [])
.option('-v, --verbose', 'A value that can be increased', increaseVerbosity, 0)
.parse(process.argv);
console.log(' int: %j', program.integer);
console.log(' float: %j', program.float);
console.log(' optional: %j', program.optional);
program.range = program.range || [];
console.log(' range: %j..%j', program.range[0], program.range[1]);
console.log(' list: %j', program.list);
console.log(' collect: %j', program.collect);
console.log(' verbosity: %j', program.verbose);
console.log(' args: %j', program.args);
正则表达式
program
.version('0.1.0')
.option('-s --size <size>', 'Pizza size', /^(large|medium|small)$/i, 'medium')
.option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i)
.parse(process.argv);
console.log(' size: %j', program.size);
console.log(' drink: %j', program.drink);
不同论点
一个命令的最后一个论点可以是variadic的,只有最后一个论点. 为了争吵,你必须
附录 ... 以至参数名称。 以下是一个例子:
#!/usr/bin/env node
/**
* Module dependencies.
*/
var program = require('commander');
program
.version('0.1.0')
.command('rmdir <dir> [otherDirs...]')
.action(function (dir, otherDirs) {
console.log('rmdir %s', dir);
if (otherDirs) {
otherDirs.forEach(function (oDir) {
console.log('rmdir %s', oDir);
});
}
});
program.parse(process.argv);
一个 Array 用于变量参数的值。 这适用于 program.args 和通过的论点
如上所示,您的行动.
指定参数语法
#!/usr/bin/env node
var program = require('commander');
program
.version('0.1.0')
.arguments('<cmd> [env]')
.action(function (cmd, env) {
cmdValue = cmd;
envValue = env;
});
program.parse(process.argv);
if (typeof cmdValue === 'undefined') {
console.error('no command given!');
process.exit(1);
}
console.log('command:', cmdValue);
console.log('environment:', envValue || "no environment given");
尖括号(例如:. <cmd>) 指明所需投入。 方括号(如:. [env])表示可选输入.
Git 类子命令
// file: ./examples/pm
var program = require('commander');
program
.version('0.1.0')
.command('install [name]', 'install one or more packages')
.command('search [query]', 'search with optional query')
.command('list', 'list packages installed', {isDefault: true})
.parse(process.argv);
何时 .command() 引用时附有描述参数,否 .action(callback) 请求处理子命令,否则会出现错误。 这告诉指挥官,你会使用 单独的可执行文件 对于子命令,很多喜欢 git(1) 以及其他流行的工具.
指挥官将尝试在条目脚本目录中搜索可执行文件( 如 ./examples/pm名称 program-command一样 pm-install, (中文(简体) ), pm-search。 。 。 .
选项可以通过调用 .command()指定 true 页:1 opts.noHelp 将删除生成的帮助输出中的选项。 指定 true 页:1 opts.isDefault 如果没有指定其他子命令,则将运行子命令.
如果程序被设计在全球安装, 确保可执行文件有合适的模式, 如 755。 。 。 .
--harmony
您可以启用 --harmony 选择的两种方式:
- 使用
#! /usr/bin/env node --harmony在子命令脚本中。 请注意一些 Os 版本不支持此模式 . - 使用
--harmony选项,例如node --harmony examples/pm publish编辑--harmony选项将在生成子命令进程时保存.
自动 -- 帮助
帮助信息是自动生成的,基于信息指挥官已经知道您的程序,所以如下 --help 信息是免费的:
$ ./examples/pizza --help
Usage: pizza [options]
An application for pizzas ordering
Options:
-h, --help output usage information
-V, --version output the version number
-p, --peppers Add peppers
-P, --pineapple Add pineapple
-b, --bbq Add bbq sauce
-c, --cheese <type> Add the specified type of cheese [marble]
-C, --no-cheese You do not want any cheese
自定义帮助
您可以显示任意 -h, --help 资料
-帮助。 指挥官会自动
完成后退出, 以便完成剩余程序
不执行导致不受欢迎的行为,例如
在以下可执行文件“ stuff”中,当
--help 已使用.
#!/usr/bin/env node
/**
* Module dependencies.
*/
var program = require('commander');
program
.version('0.1.0')
.option('-f, --foo', 'enable some foo')
.option('-b, --bar', 'enable some bar')
.option('-B, --baz', 'enable some baz');
// must be before .parse() since
// node's emit() is immediate
program.on('--help', function(){
console.log(' Examples:');
console.log('');
console.log(' $ custom-help --help');
console.log(' $ custom-help -h');
console.log('');
});
program.parse(process.argv);
console.log('stuff');
使用下列帮助输出时 node script-name.js -h 或者说 node script-name.js --help 运行中 :
Usage: custom-help [options]
Options:
-h, --help output usage information
-V, --version output the version number
-f, --foo enable some foo
-b, --bar enable some bar
-B, --baz enable some baz
Examples:
$ custom-help --help
$ custom-help -h
输出帮助( cb)
输出帮助信息而不退出. 可选的回调cb允许在显示前对帮助文本进行后处理.
如果您想要默认显示帮助( 如未提供命令), 您可以使用诸如 :
var program = require('commander');
var colors = require('colors');
program
.version('0.1.0')
.command('getstream [url]', 'get stream URL')
.parse(process.argv);
if (!process.argv.slice(2).length) {
program.outputHelp(make_red);
}
function make_red(txt) {
return colors.red(txt); //display the help text in red on the console
}
帮助(cb)
输出帮助信息并立即退出. 可选的回调cb允许在显示前对帮助文本进行后处理.
实例
var program = require('commander');
program
.version('0.1.0')
.option('-C, --chdir <path>', 'change the working directory')
.option('-c, --config <path>', 'set config path. defaults to ./deploy.conf')
.option('-T, --no-tests', 'ignore test hook');
program
.command('setup [env]')
.description('run setup commands for all envs')
.option("-s, --setup_mode [mode]", "Which setup mode to use")
.action(function(env, options){
var mode = options.setup_mode || "normal";
env = env || 'all';
console.log('setup for %s env(s) with %s mode', env, mode);
});
program
.command('exec <cmd>')
.alias('ex')
.description('execute the given remote cmd')
.option("-e, --exec_mode <mode>", "Which exec mode to use")
.action(function(cmd, options){
console.log('exec "%s" using %s mode', cmd, options.exec_mode);
}).on('--help', function() {
console.log(' Examples:');
console.log();
console.log(' $ deploy exec sequential');
console.log(' $ deploy exec async');
console.log();
});
program
.command('*')
.action(function(env){
console.log('deploying "%s"', env);
});
program.parse(process.argv);
更多演示词可见于 实例 目录.
许可证
麻省理工学院