A comfortable way to create your command line app with nodejs.
npm install cmdu
A comfortable way to create your command line app with node.js.
``bash`
$ npm install cmdu
or install a global cli to quickly start
`bash`
$ npm install cmdu-cli -g
`javascript
#!/usr/bin/env node
var app = require('cmdu');
// do something as you like
app.listen(); // listen the user input at last
`
The app.name is only used by the app.toSource() method.
Set the app version.
`javascript
#!/usr/bin/env node
var app = require('cmdu');
app.version = '0.0.1';
// node index -v
// node index --version
// prints: 0.0.1
`
By default, the app would throw an error when user typed an undefined argument or option. You can set app.allowUnknowns = true to allow this.
By default, the user must input the command exactly to execute, but you can set app.allowTolerance = true to allow a similarity.
You can set the app.language to support multiple languages. You may want to get more info from the language directory.
`javascript
// a predefined language name
app.language = 'zh-CN'; // can be 'zh-CN, en-US'
// or full language object
app.language = {};
`
Return the full input for current command.
Listen the user input and parse the process.argv, and execute the relative command.
This is not always required, you can ignore it if you have no asynchronous action, the listen will be run automatically when process exit if you didn't listen.
Define a new command and return a Command object, view Command for details.
Extends a existing command, or create a new one if not exists.
Use the render method of cubb to print strings to terminal.
A command includes the definition(cmd), name(name), description(description), configs, arguments and options.
The full syntax for defining a new command:
`javascript`
app.command(cmd, description, options);
cmd
The cmd is a string with several parts separated by space. The first part is the command name, and the rest parts are command's arguments. That means the default command if you omit the first part.
description
The description of a command is useful for building help information automatically. Also you can use options.description to specify it.
configs
The configs is used to define some extra configs for the command.
+ configs.noHelp: Boolean, true for removing this command from the auto generated help output.true
+ configs.isBase: Boolean, means the command is only a definition as a mixin but not a real one
+ configs.mixins: Array of some command's name, the command would extend their options automatically
Example:
`js
#!/usr/bin/env node
var app = require('cmdu');
app
.command('
.describe('A demo for redefine the default command')
.describe('cmd', 'Can be init, install, uninstall, publish')
.action(function (cmd, env, options) {
console.log(cmd);
console.log(env);
});
app
.command('install [name]')
.describe('install a module')
.describe('name', 'the module name')
.alias('ins, i')
.action(function(name, options) {
if (name) {
// install the specify module
} else {
// install according to package.json
}
});
app
.command('rmdir
.action(function (dir, otherDirs) {
console.log('rmdir %s', dir);
otherDirs.forEach(function (oDir) {
console.log('rmdir %s', oDir);
});
});
app.listen();
`
A argument includes the name(name), description(description), required or not, type and default value.
#### Optional or required
The argument value is required by default. And you can also declare it as [optional] or explicitly. It would throw an error if users forgot to give the required argument a value unless app.allowUnknowns = true.
Note: [optional] arguments should be defined after ones.
#### Type of arguments
Argument value can be string or array. Just prepend '...' to the argument name to declare it as an array type.
Note: only the last argument can be declared as array.
#### Default value of arguments
You can specify a default value according to append the =defaultValue to the argument name.
If you didn't specify a default value, it should be:
+ for string type, a empty string
+ for array type, a empty array
#### Passing values to arguments
When passing values, the input order of arguments and options are not limited.
String
One by one according to the order of definitions.
Array
Values are separated by space.
You can use .option() to add an option to the current command.
A option includes the definition(opt), name(name), description(description), required or not, type, parse function and default value.
The full syntax for defining a option:
`javascript`
command.option(flags, description, parseFn, defaultValue);
flags
The flags contains three parts: short flag(optional), long flag(required) and option attribute(optional).
The option's name will be the same as the long flag without -- or --no-. Multiple words connected with - such as "--template-engine" will be camel cased, becoming to app.options.templateEngine.
Option attribute is used to specify that this option is [optional] or .
description
The description of a option is useful for building help information automatically.
parseFn
A function to parse the option's value, it's optional.
defaultValue
The option's default value.
Example:
`javascript
#!/usr/bin/env node
var app = require('cmdu');
function range(val) {
return val.split('-').map(Number);
}
function list(val) {
return val.split(', ');
}
// parse and default value for options
app
.option('-i, --integer
.option('-f, --float
.option('-r, --range
.option('-l, --list
.option('-o, --optional [value]', 'An optional value', 'default value')
.option('-c, --collection <...collections>', 'A repeatable value', parseInt, [])
.action(function(options) {
console.log(' int: %j', options.integer);
console.log(' float: %j', options.float);
console.log(' range: from %j to %j', options.range[0], options.range[1]);
console.log(' list:', options.list);
console.log(' optional: %j', options.optional);
console.log(' collection:', options.collection);
});
app.listen();
`
#### Optional or required
The option value is optional by default. And you can also declare it as [optional] or explicitly. It would throw an error if users forgot to give the required option a value unless app.allowUnknowns = true.
#### Type of options
Option value can be boolean(default), string or array. Just prepend '...' to the option name to declare it as an array type.
#### Default value of options
You can specify a default value when define.
If you didn't specify a default value, it should be:
+ for boolean type, false, or true when with --no-
+ for string type, a empty string
+ for array type, a empty array
#### Passing values to options
When passing values, the input order of arguments and options are not limited.
Boolean
Suppose there is an option -o, --options, it would be true under the following condition:
* -o or --options
* or --options=true
* or --options true
or false under the following condition:
* --no-options
* or --options=false
* or --options false
String
Following the option flag.
Array
Following the option flag, values are separated by space.
You can use .alias(aliases) to specify one or more alias names for the current command.
The argument aliases can be an array or a string(in this condition you should use , or | to separate the multiple aliases).
You can use .describe(arg, description) to specify description for the command or it's arguments.
It adds the description for the current command when no arg is specified, otherwise for the arg.
You can use .action(handler) to defined a handler to response the user's input. You can pass a callback function or it's file path.
#### Arguments of the callback
The command's arguments will also be the callback's arguments, and the next argument is a json object stores all the command's options, the last argument is also a json object which contains some useful command line args object.
#### Context of the callback
Inside the callback function, this will point to the current command, which means you can use this to obtain all properties and methods of the current command.
There is an anonymous default command that takes over all undefined command inputs. This command has no handler by default, and can be redefined as needed.
The help information is auto generated based on the descriptions. So when users typed -h or --help after a command, it would display the help information automatically.
`text
$ node ./examples/npm uninstall -h
About
This uninstalls a package, completely removing everything npm installed on its behalf.
Usage
npm uninstall|remove|rm|r|un|unlink
Arguments
packages
Options
-S, --save Package will be removed from your dependencies.
-D, --save-dev Package will be removed from your devDependencies.
-O, --save-optional Package will be removed from your optionalDependencies.
-h, --help output the help information
`
You can use .customHelp() to make a custom help information. You should pass a callback to this function, and the auto generated help would be the first argument for this callback, you should return a new string as the custom help.
You can use the cubb syntax to style the help information.
`js
#!/usr/bin/env node
var app = require('cmdu');
app
.option('-f, --foo', 'enable some foo')
.option('-b, --bar', 'enable some bar')
.option('-B, --baz', 'enable some baz')
.customHelp(function(help) {
help = help + '\n\n' + [
'| [example] |',
'| $ help --help |',
'| $ help -h |'
].join('\n');
return help;
});
app.listen();
`
You can use .showHelp() to display help information manually.
`javascript
var app = require('cmdu');
app
.action(function() {
this.showHelp(); // Show help for current command
});
app.listen();
``
More examples can be found under the examples directory.
MIT