JavaScript Process API proposal

Process API.md

Process API

The ServerJS system api might help: https://wiki.mozilla.org/ServerJS/System

Ideally Titanium would stick as close to existing standards as much as possible.

All processes, like the current process, could have: environment, arguments, stdin, stdout & stderr.

When creating a process I'd like to be able to define a process, along with its environment and arguments. Then hook up the stdin, stdout & stderr to some sort of IO objects. If you don't define the objects yourself, they could instantiate STDIN, STDOUT & STDERR constructors which are subclasses of some kind of IO. EG:

Arguments

• string — The script to run. The script is parsed and converted into the args array.
• object — Optional properties: env, args, stdin, stdout & stderr

Internally this could be the equivalent of the default when running new Process();

var myProcess = new Process({
	env: new Env(),
	args: new Args(),
	stdin: new STDIN(),
	stdout: new STDOUT(),
	stderr: new STDERR() 
});

Properties

Then you could be able to change each property manually before running the process.

myProcess.env = new Env();
myProcess.args = new Args();
myProcess.stdin = new STDIN();
myProcess.stdout = new STDOUT();
myProcess.stderr = new STDERR();

Once you run the process, trying to modify some things could throw an error.

myProcess.run();
myProcess.args = []; // error

Access the properties at any time.

myProcess.env;
myProcess.args;
myProcess.stdin;
myProcess.stdout;
myProcess.stderr;

Callbacks

Add callback functions.

myProcess.stdinCallback = function(text){ this === myProcess; /* true */};
myProcess.stdoutCallback = function(text){ this === myProcess; /* true */};
myProcess.stderrCallback = function(text){ this === myProcess; /* true */};

Run Synchronously

Execute a process synchronously by calling it as a function.

var listHome = new Process('ls -lapsh ~/');
var home_list = listHome();

Execute the process multiple times. Doing so should reset the stdin, stdout & stderr before execution.

var home_list1 = listHome();

Run Asynchronously

Execute a process asynchronously by calling its run method.

var listHome = new Process({ args:['ls', '-lapsh', '~/'] });
var home_list = [];
listHome.stdoutCallback = function(text){
	home_list.push(text);
};
listHome.exitCallback = function(){
	home_list = home_list.join('\n');
};
listHome.run();

Methods

Write to stdin.

myProcess.write('hello stdin');

Close stdin to further writes.

myProcess.close();

Sent the process signals.

myProcess.kill(); // same as myProcess.send(Process.SIGNAL_KILL);
myProcess.send(Process.SIGNAL_TYPE);

Clone the process.

var myProcess2 = myProcess.clone(); // new process with cloned environment and arguments and new blank stdin, stdout & stderr
var myProcess2 = myProcess.clone(true); // new process with cloned environment, arguments, stdin, stdout & stderr