protogram


!protogram title image

A node.js module to recursively create command-line programs and sub-programs. Easily handle command line arguments and sub arguments and sub sub arguments and sub sub sub arguments, etc... with just a little bit of fat. Some things this module provides:

- a minimal, yet easily scalable interface
- flexible control over the handling of argument flags and sub-commands
- ability to handle sub-contexts as arguments a la subarg.
- autogenerate help information via protogram-help

Installation

``bash
npm install --save protogram
`

Basic Usage

$3

`javascript
var program = require('protogram').create();
`

$3

Add option flags to your program. Shortcuts will automatically be made based on the first available character of the specified option name.

`javascript
program
.option('--optionA') // shortcut will be -o
.option('--optionB'); // shortcut will be -O
`

$3

`javascript
program.action = function(args, flags){
if(flags.optionA) console.log("optionA set to:", flags.optionA)
if(flags.optionB) console.log("optionB set to:", flags.optionB)
console.log("passed in arguments:", args)
};
`

$3

Finally, the most important step! Now that you've set everything up, you're ready to parse your program's arguments.

`javascript
program.parse(process.argv);
`

$3

`bash
node example.js 198787 "Arg 2" --optionA [ A 29787 "b C" -A -B 29872 ] --optionB "This Is A Long String"
`

Will output:

`
optionA set to: { _: [ "A", 29787, "b C"], A: true, B: 29872 }
optionB set to: "This Is A Long String"
passed in arguments: [ 198787, "Arg 2" ]
`




Advanced Usage

The above was just to get you started. The API is super flexible and you can control the flow of your program to near infinite specificity.

$3

Take more control over how flags are specified and handled by passing in options to your option setting. Aside from the first argument specifying the flag name, all of the flag settings below are of course optional.

`javascript
program.option('--optionA', {
shortcut: '-a',
description: 'Use a generic flag to do anything',
required: 'a value'
action: function(value){
// called if the flag is set and there are no errors
console.log("optionA was set to:", value);
},
error: function(err, value){
// called if the 'required' value is not specified when executing
console.error(err.message);
}
});
`

$3

Recursively add git-style commands to your program, and build them as you would your main program.

`javascript
var sub_program = program.command('run', {
description: 'execute a command',
required: 'path name',
action: function(args, flags){
// executed if there are no errors
console.log("path to execute:", args[0]);
if(flags.now) // executing now
},
error: function(err, args){
// called if the required argument is missing
// or if any flags' required arguments are missing.
console.error(err.message);
}
});

sub_program.option('--now')
`




$3

`javascript
program.command('*', {
includeRoot: true // also apply all these settings to the root program
}).option('--version', {
action: function(value){
console.log("My Program v4.0.0")
}
});
`




$3

Want to output usage instructions automatically for your program? Use the protogram-help module. Refer to the documentation for how to use.

$3

By default the execution of action methods of a program does not bubble up to the parent commands.

For example, let's say we create a program with a system of sub commands:

`javascript
var program = protogram.create({
action: function(args, flags) {
console.log("main program activated"); // will not be executed
}
});

var sub_program = program.command('sub-command', {
action: function(args, flags) {
console.log("sub-command activated"); // will not be executed
}
});

sub_program.command('sub-sub-command', {
action: function(args, flags) {
console.log("sub-sub-command activated"); // will be executed
}
});
`

And execute:

`bash
node example.js sub-command sub-sub-command
`

Only the sub-sub-command action method would be trigged. We can change this by setting the bubbleUp option on any parent command.

`javascript
var program = protogram.create({
action: function(args, flags) {
console.log("main program activated"); // will not be executed
}
});

var sub_program = program.command('sub-command', {
bubbleUp: true,
action: function(args, flags) {
console.log("sub-command activated"); // will be executed
}
});

sub_program.command('sub-sub-command', {
action: function(args, flags) {
console.log("sub-sub-command activated"); // will be executed
}
});
`

Now both the sub-command and the sub-sub-command actions will be executed.

$3


By default if there is an error (ie. a required argument is missing) for a parent command, the program will continue to parse and evaluate sub-commands and flags. Prevent this by setting the haltOnError option to true when you create your program.

`javascript
var program = protogram.create({haltOnError: true});
`

or apply to specific sub-commands:

`javascript
var sub_program = program.command('run', {
haltOnError: true,
required: 'path name',
action: function(args, flags){ },
error: function(err, args){ }
})

sub_program.command('at', {
required: 'a time',
action: function(args, flags){ },
error: function(err, args){ }
});
`

`bash
node example.js run at "13:34"
`

Now in the above example, even though the sub-command at is specified, it will not execute because the required argument path name is missing for the run command. The error will be handled by the run's error property.




$3

If you'd prefer the good ol' fashioned way of testing your flags, instead of using handlers, just test their existence after you've parsed your arguments:

`javascript
if(program.flagged['generic']){
console.log('the --generic flag has been used!')
}
`




API

$3


Returns a new Protogram command object.

- options Object:
- description String: Specify a description for the sub-command.
- required String: Describe a required value that must be be passed in by the user if this sub-command is used.
- optional String: Describe an optional value that can be passed in when this sub-command is used. If required is set, optional will be ignored.
- action Function(args, program): A handler method called if the sub-command is set without any errors. Receives all args passed in.
- error Function(error, value, program): A handler method called if the flag is set but has an error (ie. required was set and no value was passed in by the user).
- haltOnError Boolean: Set whether the program should stop parsing if there is an error.
- bubbleUp Boolean: Set whether the program's action method should be executed along with sub-commands.

`javascript
var program = protogram.create({
action: function(args, flags) {
console.log("running your program");
}
});
`

$3


Returns a new Protogram command object.

Add a sub-command to your program. The sub-command is a new instance of Protogram.

- command_name String: Name of the sub-command to your program. Use the * command name to apply this setting to all sub-commands of the program.
- options Object: Since the Protogram.command method returns a new Protogram object, you can set the same options as Protogram.create().

#### Minimal Example
`javascript
program.command('run', {
action: function(args, flags) {
console.log("executed the run command");
}
});
`

#### Example with a Required Argument

`javascript
program.command('run', {
required: 'file path',
action: function(args, flags) {
console.log("executed the run command successfully");
},
error: function(err, args){
console.log(err.message); // missing required
}
});
`

#### The Special * Wildcard Command Setting
Set the command_name to '*' to apply universal settings to all sub-commands on your program. You can use the includeRoot option.

`javascript
program.command('*', {
includeRoot: true // also apply all these settings to the root program
error: function(err, args){
console.log("A universal error message");
}
}).option('--version', {
action: function(value){
console.log("My Program v4.0.0")
}
});

program.command('run');
`

The run command, as well as the main program will inherit the settings from the * command configuration, as well as the flag options specified (ie. version).




$3


Add a Flag as an option to your program.

- flag_name String: Name of the option of your program.
- options Object:
- shortcut String: Specify a shortcut letter for the flag. Defaults to the first available letter of the flag_name.
- description String: Specify a description for the flag.
- required String: Describe a required value that must be be passed in when this flag is set.
- optional String: Describe an optional value that can be passed in when this flag is set. If required is set, optional will be ignored.
- action Function(value, program): A handler method called if the flag is set without any errors.
- error Function(error, value, program): A handler method called if the flag is set but has an error (ie. required was set and no value was passed in by the user).
- added Function(program, flag): A method called when your option has been added to the program.

returns the parent Protogram command object.

#### Minimal Example
Add an option (--name) to your program. Protogram will automatically create a shortcut (-n) to your program.
`javascript
program.option('--name');
`

#### The Works

`javascript
program.option('--name', {
shortcut: '-n',
description: 'Set the name of the user',
required: 'username',
action: function(err, value){
if(err) console.error('Required value needed when using the --name flag');
else console.log("Name set to:", value);
}
});
`




$3


After your program is configured, pass in your full process.argv array into the Protogram.parse() method to begin parsing the command-line arguments.

`javascript
program.parse(process.argv);
`

$3


An object you can use to check to see whether the user has used a flag, and retrieve the passed in value. This will only work after the arguments have been parsed by program.parse.

`javascript
if(program.flagged['name']){
console.log('the --name flag has been set to', program.flagged['name'])
}
`




License

`
The MIT License (MIT)
Copyright (c) 2014 Arjun Mehta
``