Gulp plugin skeletons

overview.js

// please consider this a work in progress

// also - https://github.com/gulpjs/gulp/blob/master/docs/writing-a-plugin/README.md
// is a great resource of which this attempts to be a summary.

// how to make a gulp plugin real quick-like

var through = require('through2');    // npm install --save through2

// it is customary for a gulp plugin to return a function, which works 
// as a factory, that outputs node transform streams.
// This makes more sense if this function is used
// to pass in configuration details and allows for very flexible and
// composable plugins.  

// returns a transform stream factory function
module.exports = function( /* optional setup params here */ ) {
  // here we can set up this instance of our plugin, any passed in parameters
  // will be closured here, and in any more-deeply nested functions within
  
  // returns a transform stream object, which will ultimately be consumed by pipe()
  // The signature is obj(chunk, encoding, cb) - we call the chunk parameter
  // 'file', because it will be a vinyl file object. 
  return through.obj(/*[options],*/ function(file, encoding, callback) {
    // here we can consider the file, and encoding, perform
    // logic and build up our ouput
    
    var someFileObj = doSomethingWith(file);
    
    // we can alsoe make calls to this.push(somefileObj) 
    // to output vinyl files.

    // **OR** we can just call callback.
    // The call back uses an error-first approach, so passing null
    // means we got this far without things blowing up. 
  
    callback(null, somefileObj);

  }, /* optional flush function here */);
};