[api bin doc test] Added stop, stopall, and list command line functio…

…nality. Forever now tracks all daemons running on the system using *.fvr files

README.md

@@ -55,7 +55,7 @@ There are several samples designed to test the fault tolerance of forever. Here'
   forever samples/error-on-timer.js -m 5
 </pre>
 
-### Using forever from node.js 
+### Using an instance of Forever from node.js 
 You can also use forever from inside your own node.js code. 
 
 <pre>
@@ -71,6 +71,27 @@ You can also use forever from inside your own node.js code.
   child.start();
 </pre>
 
+### Using forever module from node.js
+In addition to using a Forever object, the forever module also exposes some useful methods. Each method returns an instance of an EventEmitter which emits when complete. See the [forever binary script][1] for sample usage.
+
+## forever.load (config, callback)
+Sets the specified configuration (config) for the forever module. In addition to the callback, this method also returns an event emitter which will raise the 'load' event when complete. There are two important options:
+
+* root:    Directory to put all default forever log files 
+* pidPath: Directory to put all forever *.pid files
+
+## forever.stop (index)
+Stops the forever daemon script at the specified index. These indices are the same as those returned by forever.list(). This method returns an EventEmitter that raises the 'stop' event when complete.
+
+## forever.stopAll (format)
+Stops all forever scripts currently running. This method returns an EventEmitter that raises the 'stopAll' event when complete.
+
+## forever.list (format, procs)
+Returns a list of metadata objects about each process that is being run using forever. This method is synchronous and will return the list of metadata as such.
+
+## forever.cleanup ()
+Cleans up any extraneous forever *.pid or *.fvr files that are on the target system. This method returns an EventEmitter that raises the 'cleanUp' event when complete.
+
 ### Options available when using Forever in node.js
 There are several options that you should be aware of when using forever:
 
@@ -79,25 +100,31 @@ There are several options that you should be aware of when using forever:
     'max': 10,                  // Sets the maximum number of times a given script should run
     'forever': true,            // Indicates that this script should run forever 
     'silent': true,             // Silences the output from stdout and stderr in the parent process
-    'logfile': 'path/to/file',  // Path to log output from forever process (when in daemon)
-    'pidfile': 'path/to/file',  // Path to put pid information for the process(es) started
-    'outfile': 'path/to/file',  // Path to log output from child stdout
-    'errfile': 'path/to/file',  // Path to log output from child stderr
+    'logFile': 'path/to/file',  // Path to log output from forever process (when in daemon)
+    'pidFile': 'path/to/file',  // Path to put pid information for the process(es) started
+    'outFile': 'path/to/file',  // Path to log output from child stdout
+    'errFile': 'path/to/file',  // Path to log output from child stderr
   }
 </pre>
 
-### Events available when using Forever in node.js
+### Events available when using an instance of Forever in node.js
 Each forever object is an instance of the node.js core EventEmitter. There are several core events that you can listen for:
 
+* error   [err]:          Raised when an error occurs
+* stop    [process]:      Raised when the target script is stopped by the user
 * restart [err, forever]: Raised each time the target script is restarted
 * exit    [err, forever]: Raised when the call to forever.run() completes
 * stdout  [err, data]:    Raised when data is received from the child process' stdout
 * stderr  [err, data]:    Raised when data is received from the child process' stderr
 
 ## Run Tests
+The test coverage for 0.3.0 is currently lacking, but will be improved in 0.3.1.
 <pre>
   vows test/*-test.js --spec
 </pre>
 
 #### Author: [Charlie Robbins](http://www.charlierobbins.com)
 #### Contributors: [Fedor Indutny](http://github.com/donnerjack13589)
+
+[0]: http://nodejitsu.com
+[1]: https://github.com/indexzero/forever/blob/master/bin/forever

bin/forever

@@ -49,17 +49,22 @@ var help = [
 
 var mappings = {
   'm':      'max',
-  'l':      'logfile',
+  'l':      'logFile',
   'p':      'path',
   's':      'silent',
   'silent': 'silent',
-  'o':      'outfile',
-  'e':      'errfile'
+  'o':      'outFile',
+  'e':      'errFile'
+};
+
+function isSimpleAction () {
+  return ['list', 'stopall'].indexOf(action) !== -1;
 };
 
 // Show help prompt if requested or if the 
 // incorrect usage options are supplied
-if (argv.h || argv.help || argv._.length === 0) {
+if (argv.h || argv.help || 
+  (argv._.length === 0 && !isSimpleAction())) {
   sys.puts(help);
   return;
 }
@@ -75,7 +80,7 @@ options.options = process.argv.splice(process.argv.indexOf(file)).splice(1);
 
 // Now that we've removed the target script options
 // reparse the options and setup the forever settings
-argv = require('optimist').argv;
+argv = require('optimist')(process.argv).argv;
 Object.keys(argv).forEach(function (key) {
   if (mappings[key]) {
     options[mappings[key]] = argv[key];
@@ -92,34 +97,58 @@ var config = {
   root: argv.p
 };
 
-forever.load(config, function () {
-  // Run all of the files forever
-  if (action) {
-    switch (action) {
-      case 'start': 
-        var uid = forever.randomString(16);
-        options.uid = uid;
-        options.pidfile = 'forever' + uid + '.pid';
-        options.logfile = argv.l || 'forever' + uid + '.log'
-        forever.startDaemon(file, options);
-        break;
-      case 'stop':
-        sys.puts('Remark: stop not implemented in 0.2.1');
-        sys.puts('   Try: killall -9 node');
-        sys.puts('        ps axl | grep node');
-        break;
-      case 'stopall':
-        sys.puts('Remark: stop not implemented in 0.2.1');
-        sys.puts('   Try: killall -9 node');
-        sys.puts('        ps axl | grep node');
-        break;
-      case 'list':
-        sys.puts('Remark: stop not implemented in 0.2.1');
-        sys.puts('   Try: ps axl | grep node');
-        break;
+var loader = forever.load(config);
+loader.on('load', function () {
+  var tidy = forever.cleanUp(); 
+  tidy.on('cleanUp', function () {
+    // Run all of the files forever
+    if (action) {
+      switch (action) {
+        case 'start': 
+          var uid = forever.randomString(16);
+          options.uid = uid;
+          options.pidFile = 'forever' + uid + '.pid';
+          options.logFile = argv.l || 'forever' + uid + '.log'
+          forever.startDaemon(file, options);
+          break;
+
+        case 'stop':
+          if (!(/(\d+)/.test(file))) {
+            sys.puts(file + ' is not a valid index for a forever process.');
+            process.exit(0);
+          }
+
+          var runner = forever.stop(parseInt(file), true);
+          runner.on('stop', function (process) {
+            sys.puts('Forever stopped process:');
+            sys.puts(process);
+          });
+          runner.on('error', function (err) {
+            sys.puts('Forever cannot find process with index: ' + file)
+          })
+          break;
+
+        case 'stopall':
+          var runner = forever.stopAll(true);
+          runner.on('stopAll', function (processes) {
+            if (processes) {
+              sys.puts('Forever stopped processes:');
+              sys.puts(processes);
+            }
+            else {
+              sys.puts('No forever processes running');
+            }
+          });
+          break;
+
+        case 'list':
+          var processes = forever.list(true);
+          sys.puts(processes ? processes : 'No forever processes running');
+          break;
+      }
     }
-  }
-  else {
-    forever.start(file, options);
-  }
-});
+    else {
+      forever.start(file, options);
+    }
+  });
+});