Documentation of required nodemon

README.md

@@ -78,9 +78,9 @@ A config file can take any of the command line arguments as JSON key values, for
 
 The above `nodemon.json` file might be my global config so that I have support for ruby files and processing files, and I can simply run `nodemon demo.pde` and nodemon will automatically know how to run the script even though out of the box support for processing scripts.
 
-A further example of options can be seen in [sample-nodemon.md]()
+A further example of options can be seen in [sample-nodemon.md](https://github.com/remy/nodemon/blob/master/doc/sample-nodemon.md)
 
-*This section needs better documentation, but for now you can also see `nodemon --help config` ([also here]())*.
+*This section needs better documentation, but for now you can also see `nodemon --help config` ([also here](https://github.com/remy/nodemon/blob/master/doc/cli/config.txt))*.
 
 ## Using nodemon as a module
 

doc/events.md

@@ -13,7 +13,7 @@ nodemon will emit events based on the child process.
 - start - child process has started
 - crash - child process has crashed (nodemon will not emit exit)
 - exit - child process has cleanly exited (ie. no crash)
-- restart - child process has restarted
+- restart([ array of files triggering the restart ]) - child process has restarted
 - config:update - nodemon's config has changed
 - log({ type, message (plain text log), colour (colour coded log) }) - logging from nodemon (not the child process)
 

doc/requireable.md

@@ -1,7 +1,55 @@
 # Nodemon as a required module
 
-Note that the way that nodemon is written, it is expected that nodemon is only
-used once.
+Nodemon (as of 1.0.0) also works as a required module. At present, you can only require nodemon in to your project once (as there are static config variables), but you can re-run with new settings for a different application to monitor.
 
-This is because nodemon has a single bus for communication. I'd welcome a
-re-factor on this recent re-factor, so for now, it's a limitation. Sorry.
+By requiring nodemon, you can extend it's functionality. Below is a simple example of using nodemon in your project:
+
+```js
+var nodemon = require('nodemon');
+
+nodemon({
+  script: 'app.js',
+  ext: 'js json'
+});
+
+nodemon.on('start', function () {
+  console.log('App has started');
+}).on('quit', function () {
+  console.log('App has quit');
+}).on('restart', function (files) {
+  console.log('App restarted due to: ', files);
+});
+```
+
+Nodemon will emit a number of [events](https://github.com/remy/nodemon/blob/master/doc/events.md) by default, and when in verbose mode will also emit a `log` event (which matches what the nodemon cli tool echos).
+
+## Arguments
+
+The `nodemon` function takes either an object (that matches the [nodemon config](https://github.com/remy/nodemon#config-files)) or can take a string that matches the arguments that would be used on the command line:
+
+```js
+var nodemon = require('nodemon');
+
+nodemon('-e "js json" app.js');
+```
+
+## Methods & Properties
+
+The `nodemon` object also has a few methods and properties. Some are exposed to help with tests, but have been listed here for completeness:
+
+### Event handling
+
+This is simply the event emitter bus that exists inside nodemon exposed at the top level module (ie. it's the `events` api):
+
+- `nodemon.on(event, fn)`
+- `nodemon.addListener(event, fn)`
+- `nodemon.once(event, fn)`
+- `nodemon.emit(event)`
+- `nodemon.removeAllListners([event])`
+
+Note: there's no `removeListner` (happy to take a pull request if it's needed).
+
+### Test utilities
+
+- `nodemon.reset()` - reverts nodemon's internal state to a clean slate
+- `nodemon.config` - a reference to the internal config nodemon uses

doc/sample-nodemon.md

@@ -3,26 +3,20 @@
 Here is an example (of a contrived) `nodemon.json` file:
 
     {
-      "script": "./test/fixtures/app.js",
       "restartable": "rs",
       "ignore": [
-        "\\.git",
-        "node_modules/.*.*/node_modules"
+        ".git",
+        "node_modules/**/node_modules"
       ],
       "verbose": true,
       "execMap": {
-        "py": "python",
-        "rb": "ruby"
+        "js": "node --harmony"
       },
       "watch": [
-        ".js$"
+        "test/fixtures/",
+        "test/samples/"
       ],
-      "stdin": true,
-      "exec": "node"
-      "execOptions": {
-        "script": "./test/fixtures/app.js",
-        "exec": "node",
-        "ext": ".js$",
-        "execArgs": []
-      }
-    }
+      "ext": "js json"
+    }
+
+Note that the `ignore` used is nodemon's default ignore rule. The complete defaults can be seen here: [defaults.js](https://github.com/remy/nodemon/blob/master/lib/config/defaults.js).

lib/monitor/watch.js

@@ -145,14 +145,15 @@ function filterAndRestart(files) {
       }
       restartTimer = setTimeout(function () {
         utils.log.status('restarting due to changes...');
-        matched.result.forEach(function (file) {
+        matched.result.map(function (file) {
           utils.log.detail(path.relative(process.cwd(), file));
         });
+
         if (config.options.verbose) {
           utils.log._log('');
         }
 
-        bus.emit('restart');
+        bus.emit('restart', matched.result);
 
       }, config.options.delay);
       return;

lib/nodemon.js

@@ -17,7 +17,16 @@ config.required = utils.isRequired;
 function nodemon(settings) {
   nodemon.reset();
 
+  // allow the cli string as the argument to nodemon, and allow for
+  // `node nodemon -V app.js` or just `-V app.js`
   if (typeof settings === 'string') {
+    settings = settings.trim();
+    if (settings.indexOf('node') !== 0) {
+      if (settings.indexOf('nodemon') !== 0) {
+        settings = 'nodemon ' + settings;
+      }
+      settings = 'node ' + settings;
+    }
     settings = cli.parse(settings);
   }
 

test/monitor/watch-restart.test.js

@@ -39,8 +39,8 @@ describe('nodemon monitor child restart', function () {
         setTimeout(function () {
           touch.sync(tmpjs);
         }, 1500);
-      }).on('restart', function () {
-        assert(true, 'nodemon restarted');
+      }).on('restart', function (files) {
+        assert(files[0] === tmpjs, 'nodemon restarted because of change to our file' + files);
         nodemon.once('exit', function () {
           nodemon.reset();
           done();
@@ -62,7 +62,6 @@ describe('nodemon monitor child restart', function () {
           touch.sync(tmpmd);
         }, 1500);
       }).on('log', function (event) {
-        // console.log(event.message);
         var msg = event.message;
         if (utils.match(msg, 'changes after filters')) {
           var changes = msg.trim().slice(-5).split('/');
@@ -90,17 +89,12 @@ describe('nodemon monitor child restart', function () {
         setTimeout(function () {
           touch.sync(tmpmd);
         }, 1000);
-      }).on('log', function (event) {
-        var msg = event.message;
-        if (utils.match(msg, 'changes after filters')) {
-          var changes = msg.trim().slice(-5).split('/');
-          var restartedOn = changes.pop();
-          assert(restartedOn === '1', 'nodemon restarted when watched directory');
-          nodemon.once('exit', function () {
-            nodemon.reset();
-            done();
-          }).emit('quit');
-        }
+      }).on('restart', function (files) {
+        assert(files.length === 1, 'nodemon restarted when watching directory');
+        nodemon.once('exit', function () {
+          nodemon.reset();
+          done();
+        }).emit('quit');
       });
     }, 2000);
   });