Node-commandline

What is this project about?

The smart Node JS command line parser module provides an easy API that makes an abstraction of a command line. It allows you to specify the order and type of the expected (required) arguments, and the names and types of the optional (named) arguments.

It uses a json-style notation for command lines, for example:

node example.js -debug -encoding:ascii -value:4.5 some ordered arguments -flag:false -otherFlag

All arguments are parsed, and the resulting object will have the following properties:

• _executable = node
• _script = example.js
• debug=true
• enoding="ascii"
• value=4.5
• flag=false
• otherFlag=true
• orderedArguments = ["some","ordered","arguments"]

It is possible to map the ordered arguments to property names by specifying those names at object construction time.

Usage

var commandLine = new CommandLine('test2'); // Construct the model.

commandLine.addArgument('option1'); // Boolean option1, assumed optional.
commandLine.addArgument('option2',{required:true}); // Boolean option2, required.
commandLine.addArgument('option3',{type: 'string'}); // A string argument. Optional.
commandLine.addArgument('option4',{type: 'number', allowedValues: [0,1,2]}); // optional numeric 'option4', with allowed options 0, 1 and 2.
commandLine.addArgument('source',{type: 'string', required: true, sequenced: true}); // required string argument 'source', in sequenced notation.
commandLine.addArgument('target',{type: 'string', required: true, order: 0}); // First unnamed argument is the target.

console.log(commandLine); // Will print the usage syntax.
// test2 [-option1[:<{true|false}>]] -option2[:<{true|false}>] [-option3:<string>] [-option4:<{0|1|2}>] -source <string> <target(string)>

// Parse test -option1 -option2:false targetFile -option3:hello -option4:2 -source someFile
// Parses arguments. Use commandLine.parseNode for the shell invocation (with implicit 2 first arguments _executable and _script).
var command = commandLine.parse("-option1","-option2:false", "targetFile", "-option3:hello","-option4:2","-source","someFile");

console.log(JSON.stringify(command));
// {
//      "option1" : true,
//      "option2" : false,
//      "option3" : "hello",
//      "option4" : 2,
//      "source" : "someFile",
//      "target" : "targetFile",
//      "orderedArguments" : [ "targetFile" ]
// }

Examples

How to pass an object:

var commandLine = new CommandLine('test');
commandLine.addArgument('values',{type: object, required: true});

// test -values:[0,1,2,3]
var command = commandLine.parse.apply(this, arguments);

// command = { values : [0, 1, 2, 3] }

How to do 'copy -f '?

var commandLine = new CommandLine('copy');
commandLine.addArgumen('f'); // assumed boolean and optional.
commandLine.addArgument('source',{type: string, required: true, order: 0});
commandLine.addArgument('target',{type: string, required: true, order: 1});

// copy -f /tmp/fileA /tmp/fileB
var command = commandLine.parse("/tmp/fileA","/tmp/fileB");

// command = { f: true, source : "/tmp/fileA", target : "/tmp/fileB" }

How does it work?

The command line class will after construction expose all argument values as normal JavaScript properties. It can also output the resulting usage syntax, and validate the input. In JavaScript, you can extend objects with properties and functions at run time. node-commandline uses this technique in order to create a model of the command line and it's arguments.

Installation

The easiest way to install node-commandline is to use the NPM package manager:

npm install node-commandline

Where does it come from?

This project is derived from my previous work for the node js serial-to-tcp server.