release 2.0.0

- docs: add new api docs
- test: split test into files for each api method
- dev: separate module into add, get, remove, reset and start

Author: stringparser

README.md

@@ -9,25 +9,40 @@ Simple repl for gulp compatible with gulp#3.x and the future gulp#4.x.
 ```js
 // gulpfile example
 var gulp = require('gulp');
-gulp.repl = require('gulp-repl')(gulp);
+var repl = require('gulp-repl');
 
-gulp.task('foo', function (cb) {
-	// do foo stuff
+gulp.task('repl-start', function (cb) {
+  gulp.repl = repl(gulp);
+});
+
+gulp.task('repl-stop', function (cb) {
+  if (gulp.repl) {
+    gulp.repl.close(); // same as nodejs.org/api/readline.html#readline_rl_close
+  }
 	cb();
 });
 
+
+gulp.task('foo', function (cb) {
+  // do foo stuff
+  cb();
+});
+
 gulp.task('bar', function (cb) {
-	// do bar stuff
-	cb();
+  // do bar stuff
+  cb();
 });
 
 gulp.task('default');
+```
 
-// same as writing foo bar on the command line
-gulp.repl.emit('line', 'foo bar');
+Then, on your terminal write:
+
+```
+gulp repl-start
 ```
 
-Then, on your terminal, you'll have a repl
+and you'll have a repl with:
 
 1. Press <kbd>Enter</kbd> to see the prompt
 1. write the tasks you want to run
@@ -48,9 +63,69 @@ foo      bar      default
 
 ### API
 
-The module exports a `readline` interface.
+The module exports a function
+
+```js
+var repl = require('gulp-repl');
+```
+
+Calling the function with `gulp` creates a `readline` instance using `gulp` tasks as commands for a REPL.
+
+```js
+var gulp = require('gulp');
+var gulpREPL = require('repl');
+
+// to start the repl
+gulp.repl = gulpREPL.start(gulp);
+```
+
+#### gulpREPL.add
+
+```js
+function add(Gulp gulp)
+```
+
+Adds the given `gulp` instance for the REPL to be able to lookup and _returns_ the module again.
+
+#### gulpREPL.remove
+
+```js
+function remove(Gulp gulp)
+```
+
+Removes the given `gulp` instance for the REPL to be able to lookup and _returns_ the module again.
+
+#### gulpREPL.reset
+
+```js
+function reset()
+```
+
+Removes all of the previously added instances and _returns_ the module again.
+
+#### gulpREPL.get
+
+```js
+function get(Gulp gulp)
+```
+
+Takes a `gulp` instance as argument
+
+_returns_
+- `null` if the `gulp` instance wasn't stored yet
+- all of the stored instances if no arguments are given
+- metadata stored for the given `gulp` instance if was already stored
+
+#### gulpREPL.start
+
+```js
+function start(Gulp gulp)
+```
+
+Starts a REPL listening on `stdin` and writing on `stdout` and _returns_ a `readline.Interface` instance. Each of the commands typed to the REPL are looked up in each of the instances given on `add`.
+
+[See node's core module `readline` documentation about the `readline.Interface`](https://nodejs.org/api/readline.html).
 
-For more information [see node's core module `readline` documentation](https://nodejs.org/api/readline.html).
 
 ### install
 
@@ -60,6 +135,11 @@ $ npm install --save-dev gulp-repl
 
 ## Changelog
 
+[v2.0.0][v2.0.0]:
+- docs: add new api docs
+- test: split test into files for each api method
+- dev: separate module into add, get, remove, reset and start
+
 [v1.1.2][v1.1.2]:
 
 - docs: add changelog
@@ -95,6 +175,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 [badge-downloads]: http://img.shields.io/npm/dm/gulp-repl.svg?style=flat-square
 
 
+[v2.0.0]: https://github.com/stringparser/gulp-repl/commit/572df8ce7cd9d4edd3a2190de021381671a295f0
 [v1.1.2]: https://github.com/stringparser/gulp-repl/commit/572df8ce7cd9d4edd3a2190de021381671a295f0
 [v1.1.1]: https://github.com/stringparser/gulp-repl/commit/6f4655ca1a667ca04d2a668a175055f9b4437d65
 [v1.1.0]: https://github.com/stringparser/gulp-repl/commit/71a2301233a92d68dbfd7e7a1493a38be72d0a0e

index.js

@@ -2,90 +2,115 @@
 
 var util = require('./lib/util');
 
-exports = module.exports = gulpRepl;
-exports.instances = [];
-
-/**
- * create a readline interface
-**/
-var repl = require('readline').createInterface({
-  input: process.stdin,
-  output: process.stdout,
-  completer: function onCompletion(line){
-    return util.completer(line, exports.instances);
+var repl = null;
+var instances = [];
+
+// add the instance to the repl and start it
+exports = module.exports = function (_gulp_) {
+  return exports.start(_gulp_);
+};
+
+// get the instance properties used by the REPL
+exports.get = function (gulp) {
+  if (!arguments.length) {
+    return instances.concat();
   }
-});
-
-/**
- * queue tasks when line is not empty
-**/
-repl.on('line', function onLine(input){
-  var line = input.trim();
-  if(!line){ return repl.prompt(); }
-
-  var queue = {
-    found: [],
-    notFound: line.split(/[ ]+/)
-  };
-
-  exports.instances.forEach(function(inst){
-    var tasks = util.getQueue(queue.notFound.join(' '), inst.tasks);
-    if(tasks.found.length){
-      queue.found.push({
-        inst: inst,
-        tasks: tasks.found
-      });
+
+  var length = instances.length;
+
+  for (var index = 0; index < length; ++index) {
+    var instance = instances[index] || {};
+    if (instance.gulp === gulp) {
+      return instance;
     }
-    queue.notFound = tasks.notFound;
-  });
+  }
 
-  if(queue.notFound.length){
-    var plural = queue.notFound.length > 1;
+  return null;
+};
 
-    console.log(' `%s` task%s %s not defined yet',
-      queue.notFound.join(', '),
-      plural ? 's' : '',
-      plural ? 'are' : 'is'
-    );
+// add the given instance to the REPL lookup
+exports.add = function (_gulp_) {
+  if (_gulp_ && !this.get(_gulp_)) {
+    var gulp = util.getGulp(_gulp_);
 
-    return repl.prompt();
+    instances.push({
+      gulp: gulp,
+      index: instances.length,
+      tasks: util.getTasks(gulp),
+      runner: gulp.start || gulp.parallel
+    });
   }
+  return this;
+};
+
+// reset the instances array
+exports.reset = function () {
+  instances = [];
+  return this;
+};
+
+// remove the instance from the instances array
+exports.remove = function (_gulp_) {
+  var instance = this.get(_gulp_);
+  if (instance) {
+    instances.splice(instance.index, 1);
+  }
+  return this;
+};
+
+// create a readline instance if there is none
+exports.start = function (_gulp_) {
+  exports.add(_gulp_);
 
-  queue.found.forEach(function(found){
-    var result = found.inst.runner.apply(found.inst.gulp, found.tasks);
-    if(typeof result === 'function'){
-      result(); // gulp#4.0
+  // only create one repl listening on stdin
+  if (repl) { return repl; }
+
+  repl = require('readline').createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    completer: function onComplete (line) {
+      return util.completer(line, instances);
+    }
+  });
+
+  // queue tasks when line is not empty
+  repl.on('line', function onLine (input) {
+    var line = input.trim();
+    if (!line) { return repl.prompt(); }
+
+    var queue = {
+      found: [],
+      notFound: line.split(/[ ]+/)
+    };
+
+    instances.forEach(function (inst) {
+      var tasks = util.getQueue(queue.notFound.join(' '), inst.tasks);
+      if (tasks.found.length) {
+        queue.found.push({ inst: inst, tasks: tasks.found });
+      }
+      queue.notFound = tasks.notFound;
+    });
+
+    if (queue.notFound.length) {
+      console.log(' `%s` not found', queue.notFound.join(' '));
+      return repl.prompt();
     }
+
+    queue.found.forEach(function (found) {
+      var result = found.inst.runner.apply(found.inst.gulp, found.tasks);
+      if (typeof result === 'function') {
+        result(); // gulp#4.0
+      }
+    });
+
+    return this;
   });
-});
-
-/**
- * exit on SIGINT with a timestamp
-**/
-repl.on('SIGINT', function onSIGINT(){
-  process.stdout.write('\n');
-  console.log(new Date());
-  process.exit(0);
-});
-
-/**
- * add the given gulp instance to the instances array
-**/
-function gulpRepl(_gulp_){
-  var gulp = util.getGulp(_gulp_);
-
-  var inInstances = Boolean(
-    exports.instances.filter(function(instance){
-      return instance.gulp === gulp;
-    }).length
-  );
-  if(inInstances){ return repl; }
-
-  exports.instances.push({
-    gulp: gulp,
-    tasks: util.getTasks(gulp),
-    runner: gulp.start || gulp.parallel
+
+  // exit on SIGINT
+  repl.on('SIGINT', function onSIGINT () {
+    process.stdout.write('\n');
+    process.exit(0);
   });
 
   return repl;
-}
+};

lib/util.js

@@ -4,6 +4,7 @@ var uniq = require('lodash.uniq');
 
 exports = module.exports = {};
 
+// return a gulp-like instance, require gulp if not given
 exports.getGulp = function (gulp) {
   if (!gulp || typeof gulp.task !== 'function') {
     try {
@@ -17,6 +18,7 @@ exports.getGulp = function (gulp) {
   return gulp;
 };
 
+// get the tasks for the given instance
 exports.getTasks = function (gulp) {
   var tasks = {
     obj: (
@@ -42,6 +44,7 @@ exports.getTasks = function (gulp) {
   return tasks;
 };
 
+// get an object with of found/not found tasks to run
 exports.getQueue = function (line, tasks) {
   var queue = {found: [], notFound: []};
 
@@ -61,6 +64,7 @@ exports.getQueue = function (line, tasks) {
   return queue;
 };
 
+// return all instances completion for the given line
 exports.completer = function (line, instances) {
   var match = line.match(/([\s]+|^)\S+$/);
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "gulp-repl",
   "author": "Javier Carrillo <[email protected]>",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "license": "MIT",
   "repository": "https://github.com/stringparser/gulp-repl",
   "description": "a simple repl for gulp",