Easy command-line executable utilities built on nopt.
- Easy to write
- Easy to test
- Easy to maintain
Node.js >= 0.10
is required. Type this at the command line:
npm install nopter --save-dev
Options are defined with config()
and serve as documentation for the help screen. The example below parses args and options from process.argv
, leaving any remaining args not consumed by options as input()._remain
.
#!/usr/bin/env node
var nopter = new (require("nopter"))();
nopter.config({
title: "Image Compressor",
name: "imgc",
version: "1.0.0",
options: {
"compression": {
short: "c",
info: "Compression level (0–100, default=80).",
type: Number,
default: 80
},
"input": {
info: "Input image.",
type: require("path")
}
}
});
var args = nopter.input();
if (args.compression) console.log("Compression :: "+args.compression);
if (args.input) console.log("Input File :: "+args.input);
if (args._remain.length) console.log("Unparsed args :: "+args._remain);
Shorthand flags may be passed as a single arg, for example -abc
is equivalent to -a -b -c
. Multi-word options such as "--template-engine" are camel-cased, becoming input().templateEngine
etc. unless overridden with option.rename
.
For more ideas, check out the test fixture.
Via the
help()
function.
// app-cli.js ::::::::::::::::::::
var nopter = require("nopter");
function cli() {
this.nopter = new nopter();
this.nopter.config({/* See above example */});
}
cli.prototype.input = function(args, showArgs) {
var testing = !!args;
args = this.nopter.input(args);
if (testing && showArgs) return args;
if (args.compression) console.log("Compression :: "+args.compression);
if (args.input) console.log("Input File :: "+args.input);
};
module.exports = cli;
// test.js ::::::::::::::::::::
var appCLI = require("./app-cli.js");
var nopter = require("nopter");
nopter.util.forceColors();
function test1() {
var cli = new appCLI();
var options = cli.input("--input file1 --compression 100", true);
assert.equal(options.input, "path/to/file1");
assert.deepEqual(options, {compression:100, input:"path/to/file1"});
}
function test2() {
var cli = new appCLI();
var helpScreen = nopter.util.readHelpFile("./help.txt");
helpScreen = nopter.util.replaceColorVars(helpScreen);
assert.equal( cli.input("--help"), helpScreen );
}
For more ideas, check out the test suite.
Gets or sets the configuration.
object
[optional].
Merges a new configuration with the existing one.
object
[optional].
Gets a (red) colored error message with a default "Error"
prefix, but does not display/log it.
error
can be anError
orString
. If anError
,error.name
will override the default prefix.additional
[optional] is a second, uncoloredString
sentence.prefix
[optional] overrides the default prefix.
Gets an uncolored error message with a default "Notice"
prefix, but does not display/log it.
See error.fatal for arguments info.
Gets a (yellow) colored error message with a default "Warning"
prefix, but does not display/log it.
See error.fatal for arguments info.
Gets the help screen, but does not display/log it.
Gets the indent value for custom additions to the help screen.
Gets user input parsed by nopt.
nopter.input();
nopter.input(process.argv, 2); // same as above
nopter.input("app --option value", 1);
nopter.input(["--option","value"]);
args
[optional] can be anArray
orString
. Default value isprocess.argv
.slice
[optional] is aNumber
. See nopt docs. Unlike nopt, the default value of2
only applies whenargs===process.argv
; otherwise the default value is0
.
Forces colors in situations where they would normally be disabled such as a child_process
and some CI (Continuous Integration) systems. Due to the singleton design of the color library, this value applies to all nopter instances. Colors are not forced by default.
value
[optional] is aBoolean
. Ifundefined
, it will default totrue
.
Synchronously reads the contents of a text file and converts to LF line endings for cross-platform support. Useful in testing the output of help()
.
console.log( nopter.util.readHelpFile("path/to/file.txt") );
//-> This is a text file.
filepath
is a requiredString
path, relative to the current module (likerequire("./")
).
Replace easy-to-read variables in a String
with their ANSI counterparts. Useful in testing the output of help()
.
var str = "{{green}}This is a {{bold}}colored{{/bold}} sentence.{{/green}}";
console.log( nopter.util.replaceColorVars(str) );
//-> \u001b[32mThis is a \u001b[1mcolored\u001b[22m sentence.\u001b[39m
str
is a requiredString
. Possible color variables.
Remove all ANSI characters. Useful in testing the output of help()
.
var str = "\u001b[32mThis is a \u001b[1mcolored\u001b[22m sentence.\u001b[39m";
console.log( nopter.util.stripColors(str) );
//-> This is a colored sentence.
str
is a requiredString
.
Type: Array
Default value: ["red","green","magenta"]
The colors used in the help screen. Possible color values, [null,…]
to disable a color and null
to disable all colors.
Type: String
Default value: ""
The app description.
Type: String
Default value: "noname"
The app name used in the command line.
Type: String
Default value: config.name.toUpperCase()
The app title, which is sometimes slightly different from config.name
.
Type: String
Default value: "0.0.0"
The app version.
Type: Object
Default value: {}
The command line options.
options: {
"option-name": {
short: "o",
info: "Description of option.",
type: String
}
}
option.default
can be any value that is applied when no user value has been supplied.option.hidden
is aBoolean
that hides the option from the help screen.option.info
is a descriptiveString
used in the help screen.option.rename
can be aString
orBoolean
.false
will disable auto camel-casing. The default value istrue
.option.short
can be aString
orArray
.option.sort
is aString
for categorizing the help screen.option.type
can be any of these types. The default type isString
.
Type: Array
Default value: []
Argument shortcuts to options.
aliases: ["option1","option2"]
This would allow something like app foo bar
to be a CLI shortcut to app --option1 foo --option2 bar
.
- add
"safe colors",cell-span and word-wrap features to cli-table - add "before" and "after" (table?) content for
help()
- add
option.alias
shortcut:
"option": {
alias: "--option1 value -xyz"
}
- add
config.commands
for nested options:
commands: {
"command": {
info: "A command with specific options.",
options: {
"input": {
info: "The input file."
type: path
},
"output": {
info: "The output file."
type: path
}
},
aliases: ["input","output"]
}
}
//$ app command input.ext output.ext
- rename
options.aliases
tooptions.arguments
? - add
util.shell()
for easier project testing?
- 0.3.0
- added option auto camel-casing;
option.rename
supports booleans - added
input()._remain
option.info
no longer requires a valueoption.type
defaults to typeString
- added option auto camel-casing;
- 0.2.1 fixed bug with
util.forceColors(false)
- 0.2.0
- added
input(args)
,util.forceColors()
,util.readHelpFile()
,util.replaceColorVars()
,util.stripColors()
for easier project testing - added support for multiple instances (no singleton)
- added
- 0.1.9 avoided
String.prototype
colors - 0.1.8 simplified color test
- 0.1.7 added
config.colors
,config.merge()
,help.indent()
- 0.1.6 tested on Windows
- 0.1.5 added
option.sort
- 0.1.4 added
option.rename
- 0.1.3 added
option.hidden
- 0.1.2 added
option.default
, help screen cleanup - 0.1.1 added custom error messages
- 0.1.0 initial release