fixed; append()

it actually does something helpful now :)

we may call append with string arguments, each being another
image to append to the original source image. if a boolean `true`
is passed, the images will be appended left-to-right, otherwise
top-to-bottom.

Examples:

   img = gm(src);

   // +append means left-to-right
   img.append(img1, img2)       gm convert src img1 img2 -append
   img.append(img, true)        gm convert src img +append
   img.append(img, false)       gm convert src img -append
   img.append(img)              gm convert src img -append
   img.append(img).append()     gm convert src img -append
   img.append(img).append(true) gm convert src img +append
   img.append(img).background("#222") gm convert src img -background #222 +append

fixes #77

examples/append.js

@@ -0,0 +1,17 @@
+var gm = require('../')
+  , dir = __dirname + '/imgs'
+  , imgs = 'lost.png original.jpg'.split(' ').map(function (img) {
+      return dir + '/' + img
+    })
+  , out = dir + '/append.jpg'
+
+gm(imgs[0])
+.append(imgs[1])
+.append()
+.background('#222')
+.write(out, function (err) {
+  if (err) return console.dir(arguments)
+  console.log(this.outname + " created  ::  " + arguments[3])
+  require('child_process').exec('open ' + out)
+});
+

examples/background.js

@@ -1,6 +1,6 @@
 var gm = require('../')
   , dir = __dirname + '/imgs'
-  
+
 gm(dir + "/original.jpg")
   .crop(140,100)
   .background("#FF0000")

index.js

@@ -55,6 +55,14 @@ function gm (source, height, color) {
   }
 
   this.source = source;
+
+  this.addSrcFormatter(function (src) {
+    // must be first source formatter
+    var ret = this.sourceStream ? '-' : this.source;
+    if (ret && this.sourceFrames) ret += this.sourceFrames;
+    src.length = 0;
+    src[0] = ret;
+  });
 }
 
 var parent = gm;

lib/args.js

@@ -28,9 +28,58 @@ module.exports = function (proto) {
     return this.out("-affine", matrix);
   }
 
-  // http://www.graphicsmagick.org/GraphicsMagick.html#details-append
-  proto.append = function append (ltr) {
-    return this.out(ltr ? "+append" : "-append");
+  /**
+   * Appends images to the list of "source" images.
+   *
+   * We may also specify either top-to-bottom or left-to-right
+   * behavior of the appending by passing a boolean argument.
+   *
+   * Examples:
+   *
+   *    img = gm(src);
+   *
+   *    // +append means left-to-right
+   *    img.append(img1, img2)       gm convert src img1 img2 -append
+   *    img.append(img, true)        gm convert src img +append
+   *    img.append(img, false)       gm convert src img -append
+   *    img.append(img)              gm convert src img -append
+   *    img.append(img).append()     gm convert src img -append
+   *    img.append(img).append(true) gm convert src img +append
+   *    img.append(img).append(true) gm convert src img +append
+   *    img.append(img).background('#222) gm convert src img -background #222 +append
+   *
+   * @param {String} [img]
+   * @param {Boolean} [ltr]
+   * @see http://www.graphicsmagick.org/GraphicsMagick.html#details-append
+   */
+
+  proto.append = function append (img, ltr) {
+    if (!this._append) {
+      this._append = [];
+      this.addSrcFormatter(function (src) {
+        this.out(this._append.ltr ? '+append' : '-append');
+        src.push(this._append);
+      });
+    }
+
+    if (0 === arguments.length) {
+      this._append.ltr = false;
+      return this;
+    }
+
+    for (var i = 0; i < arguments.length; ++i) {
+      var arg = arguments[i];
+      switch (typeof arg) {
+        case 'boolean':
+          this._append.ltr = arg;
+          break;
+        case 'string':
+          this._append.push(arg);
+          break;
+      }
+    }
+
+    return this;
   }
 
   // http://www.graphicsmagick.org/GraphicsMagick.html#details-authenticate

lib/command.js

@@ -260,22 +260,58 @@ module.exports = function (proto) {
     return missingGM;
   }
 
-  proto.args = function args () {
-    var source = (this.sourceStream ? "-" : this.source);
-    if (source && this.sourceFrames) source += this.sourceFrames;
+  /**
+   * Returns arguments to be used in the command.
+   *
+   * @return {Array}
+   */
 
+  proto.args = function args () {
     var outname = this.outname || "-";
   	if (this._outputFormat) outname = this._outputFormat + ':' + outname;
 
     return [].concat(
         this._subCommand
       , this._in
-      , source
+      , this.src()
       , this._out
       , outname
     ).filter(Boolean); // remove falsey
   }
 
+  /**
+   * Adds an img source formatter.
+   *
+   * `formatters` are passed an array of images which will be
+   * used as 'input' images for the command. Useful for methods
+   * like `.append()` where multiple source images may be used.
+   *
+   * @param {Function} formatter
+   * @return {gm} this
+   */
+
+  proto.addSrcFormatter = function addSrcFormatter (formatter) {
+    if ('function' != typeof formatter)
+      throw new TypeError('sourceFormatter must be a function');
+    this._sourceFormatters || (this._sourceFormatters = []);
+    this._sourceFormatters.push(formatter);
+    return this;
+  }
+
+  /**
+   * Applies all _sourceFormatters
+   *
+   * @return {Array}
+   */
+
+  proto.src = function src () {
+    var arr = [];
+    for (var i = 0; i < this._sourceFormatters.length; ++i) {
+      this._sourceFormatters[i].call(this, arr);
+    }
+    return arr;
+  }
+
   /**
    * Image types.
    */

test/append.js

@@ -0,0 +1,42 @@
+var assert = require('assert')
+var out;
+
+module.exports = function (_, dir, next, gm) {
+  out = require('path').resolve(dir + '/append.jpg');
+
+  try {
+    require('fs').unlinkSync(out);
+  } catch (_) {}
+
+  gm(dir + '/lost.png')
+  .append(dir + '/original.jpg')
+  .append()
+  .background('#222')
+  .write(out, function (err) {
+    if (err) return next(err);
+    gm(out).size(function (err, size) {
+      if (err) return next(err);
+      assert.equal(460, size.width);
+      assert.equal(280, size.height);
+
+      horizontal(dir, next, gm);
+    })
+  });
+}
+
+function horizontal (dir, next, gm) {
+
+  gm(dir + '/original.jpg')
+  .append(dir + '/lost.png', true)
+  .write(out, function (err) {
+    if (err) return next(err);
+    gm(out).size(function (err, size) {
+      if (err) return next(err);
+      assert.equal(697, size.width);
+      assert.equal(155, size.height);
+
+      next();
+    })
+  });
+
+}