replconsole

REPL console allows custom commands/tasks to be run in a typical Read-Eval-Print-Loop on node. This allows you to create your own interactive console for your custom tasks sharing a common context for your application. Example usage may include admin console that allow the user to run different administrative commands to manage your node application.

Custom commands/tasks need to created as JavaScript files, each of which need to have the following functions:

exports.action = function(context, options, arg1, arg2) {
	//contex - shared common context for one replconsole session
	//options - see options below
	//arg1, arg2 - see command line below

	//handle your command/task invocation here
};

exports.description = function() {
	//return a friendly description of your command/task
	return "description";	
};

exports.commandLine = function() {
	//return the command name an required and optional arguments. by default, 'commander' library is used to parse this
	return "command1 <arg1> [arg2]"
};

exports.options = function() {
	//return the options available or your command/task. by default, 'commander' library is used to parse these
	return [
		['-p, --opt1 <val>', 'opt1 and required value'],
		['-q, --opt2 [val]', 'opt2 and optional value']
	];
};

The custom commands/tasks can be loaded from one or more paths. Below are the steps to configure and start replconsole

var replconsole = require('replconsole');

//optional - set the prompt. default is 'repl>'
replconsole.prompt = "myconsole: ";

//optional - set the path(s) to load custom commands/tasks from. default is 'commands'
replconsole.paths = ['mytasks/admin', 'mytasks/db'];

//optional - set commands loader. if not specified the commands_loader module is used - see loader below
//replconsole.commandsLoader = require('./someloader');

//optional - set commands adapter. if not specified the commander_adapter is used - see adapter below
//replconsole.commandsAdapter = require('./someadapter');

//start the REPL console
replconsole.console();

###Loader

A loader is responsible for resolving the configured custom commands/tasks path(s) and load the commands. If not specified, the default loader from 'commands_loader' is used.

If you need to use your own loader, it should have the following functions:

exports.loadCommands = function(paths, outputStream, adapter) {
	//paths - the paths to load the custom commands/tasks from
	//use the output stream to write you messages
	//adapter - commands adapter - see adapter below
}

The loader must emit the following events based on error or success

this.emit('error', 'some error happened');
or	
this.emit('loaded', loadedCommands);

###Adapter

An adapter is a bridge between what is needed by replconsole and your favorite command line parser. If not specified, the default adapter from 'commander_adapter' is used which, in turn, uses 'commander' library.

If you need to use your own adapter, it should have the following functions:

exports.createCommand = function (commandsPath, commandName) {
	// commandsPath - the path to load the command from
	// commandName - the name of command to load
	return createdCommand;	
};

exports.executeCommand = function executeCommand(command, argsv, context) {
	// command - the command the execute
	// argv - array of command line arguments include command name, options and arguments
	// context - the shared context
	// throw an Error object if there are errors executing the command
}

exports.getCommandDetails = function (command) {
	// command - the command for which the details are needed
	// return a simple one line string describing the command, typically name + "\t" + description
};

exports.getCommandHelp = function (command) {
	// command - the command for which the details are needed
	// return the command usage help string, typically name, description, options + details, arguments + details
}

###Development

The replconsole project uses grunt, jshint, mocha, chai, sinon, blanket and travis for code development.

The default grunt tasks run jslint on the src and test folders, and run mocha tests for the specs in the test folder. See Gruntfile.js for more details.

The current code coverage is 100%