nopter
Easy command-line executable utilities for Node.js
- Easy to write
- Easy to test
- Easy to maintain
- Built on nopt (npm's option parser)
Installation
Node.js ~0.10
is required. Type this at the command line:
npm install nopter --save-dev
Option Parsing
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 ; nopter; var args = nopterinput; if argscompression console;if argsinput console;if args_remainlength console;
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.
Customizable Help Screen
Via the help()
function.
Testing
// app-cli.js :::::::::::::::::::: var nopter = ; { thisnopter = ; thisnopter;} cliprototype { var testing = !!args; args = thisnopterinputargs; if testing && showArgs return args; if argscompression console; if argsinput console;}; moduleexports = cli; // test.js :::::::::::::::::::: var appCLI = ;var nopter = ; nopterutil; { var cli = ; var options = cliinput"--input file1 --compression 100" true; assert; assert;} { var cli = ; var helpScreen = nopterutil; helpScreen = nopterutil; assert;}
For more ideas, check out the test suite.
Documentation
Methods
config(object)
Gets or sets the configuration.
object
[optional].
config.merge(object)
Merges a new configuration with the existing one.
object
[optional].
error.fatal(error, additional, prefix)
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.
error.notice(error, additional, prefix)
Gets an uncolored error message with a default "Notice"
prefix, but does not display/log it.
See error.fatal for arguments info.
error.warn(error, additional, prefix)
Gets a (yellow) colored error message with a default "Warning"
prefix, but does not display/log it.
See error.fatal for arguments info.
help()
Gets the help screen, but does not display/log it.
help.indent()
Gets the indent value for custom additions to the help screen.
input(args, slice)
Gets user input parsed by nopt.
nopterinput;nopterinputprocessargv 2; // same as above nopterinput"app --option value" 1;nopterinput"--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
.
util.forceColors(value)
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
.
util.readHelpFile(filepath)
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;//-> This is a text file.
filepath
is a requiredString
path, relative to the current module (likerequire("./")
).
util.replaceColorVars(str)
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;//-> \u001b[32mThis is a \u001b[1mcolored\u001b[22m sentence.\u001b[39m
str
is a requiredString
. Possible color variables.
util.stripColors(str)
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;//-> This is a colored sentence.
str
is a requiredString
.
Configuration
config.colors
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.
config.description
Type: String
Default value: ""
The app description.
config.name
Type: String
Default value: "noname"
The app name used in the command line.
config.title
Type: String
Default value: config.name.toUpperCase()
The app title, which is sometimes slightly different from config.name
.
config.version
Type: String
Default value: "0.0.0"
The app version.
config.options
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
.
config.aliases
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
.
Roadmap Features
- 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?
Release History
- 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