Resurrect bin/ec2, update documentation.

Updated the documentation with an example of how to use the current API.
Updated `launch.js` with example from documentation.

Tidy of `bin/ec2` and `lib/amazon.js`.

bin/ec2

@@ -1,100 +1,100 @@
 #!/usr/bin/env node
 
-var argv, build, client, command, configuration, display, ec2, file, format, fs, key, labels, match, parameters, parse, rest, _ref;
-fs = require("fs");
-ec2 = require("ec2");
-argv = process.argv.slice(2);
-command = argv.shift();
-parameters = {};
+var configuration, display, file, format, labels, $, rest, _ref;
+
+var fs = require("fs")
+  , ec2 = require("ec2")
+  , argv = process.argv.slice(2)
+  , command = argv.shift()
+  , parameters = {}
+  , key
+  ;
+
 while (argv.length) {
   key = argv.shift();
-  if (match = /^\s*\+(.*)/.exec(key)) {
-    format = match[1];
-  } else {
-    parameters[key] = argv.shift();
-  }
+  if ($ = /^\s*\+(.*)/.exec(key)) format = $[1];
+  else parameters[key] = argv.shift();
 }
-build = function(fields, child) {
+
+function build (fields, child) {
   return function(lines, line, context) {
-    var copy, field, item, n, _i, _len, _len2, _results;
-    _results = [];
-    for (_i = 0, _len = context.length; _i < _len; _i++) {
-      item = context[_i];
+    var copy, field, item, i, I, j, J, results = [];
+    for (i = 0, I = context.length; i < I; i++) {
+      item = context[i];
       copy = line.slice(0);
-      for (n = 0, _len2 = fields.length; n < _len2; n++) {
-        field = fields[n];
-        if (child && n === fields.length - 1) {
+      for (j = 0, J = fields.length; j < J; j++) {
+        field = fields[j];
+        if (child && j === fields.length - 1) {
           child(lines, copy, item[field]);
         } else {
           copy.push(item[field]);
         }
       }
-      _results.push(!child ? lines.push(copy) : void 0);
+      results.push(!child ? lines.push(copy) : void 0);
     }
-    return _results;
+    return results;
   };
-};
-parse = function(labels, rest, nested) {
-  var child, field, fields, label, proc, _ref, _ref2, _ref3;
-  fields = [];
+}
+
+function parse (labels, rest, nested) {
+  var child, field, fields = [], label, proc;
   while (!proc) {
-    if (nested && (match = /^\s*\](.*)$/.exec(rest))) {
-      rest = match[1];
+    if (nested && ($ = /^\s*\](.*)$/.exec(rest))) {
+      rest = $[1];
       proc = build(fields, null);
     } else {
-      match = /^\s*(\w[\w\d]*)(.*)$/.exec(rest);
-      if (!match) {
+      $ = /^\s*(\w[\w\d]*)(.*)$/.exec(rest);
+      if (!$) {
         throw new Error("invalid pattern");
       }
-      _ref = match.slice(1), field = _ref[0], rest = _ref[1];
+      field = $[1], rest = $[2];
       label = field;
-      if (match = /^\[(.*)$/.exec(rest)) {
+      if ($ = /^\[(.*)$/.exec(rest)) {
         fields.push(field);
-        _ref2 = parse(labels, match[1], true), child = _ref2[0], rest = _ref2[1];
+        $ = parse(labels, $[1], true), child = $[0], rest = $[1];
         proc = build(fields, child);
       } else {
-        if (match = /^\/(\w[\w\d]*)$/.exec(rest)) {
-          _ref3 = match.slice(1), label = _ref3[0], rest = _ref3[1];
+        if ($ = /^\/(\w[\w\d]*)(.*)$/.exec(rest)) {
+          label = $[1], rest = $[2];
         }
         labels.push(label);
         fields.push(field);
         rest = rest.replace(/^\s*,/, '');
+        if (!rest) proc = build(fields, null);
       }
     }
   }
   return [proc, rest];
-};
+}
+
 labels = [];
 if (format) {
-  _ref = parse(labels, format), display = _ref[0], rest = _ref[1];
+  $ = parse(labels, format), display = $[0], rest = $[1];
   if (rest && rest.trim().length !== 0) {
     throw new Error("invalid pattern.");
   }
 }
+
 file = process.env["AWS_CONFIG"] || ("" + process.env["HOME"] + "/.aws");
 configuration = JSON.parse(fs.readFileSync(file, "utf8"));
-client = ec2.createClient(configuration);
-client.on("error", function(error) {
-  console.log("error", error);
-  throw error;
-});
-client.call(command, parameters, function(response) {
-  var line, lines, _i, _len, _results;
+
+ec2 = ec2(configuration);
+
+ec2(command, parameters, response);
+
+function response (error, response) {
+  var line, lines, i, I, results;
+  if (error) throw error;
   if (display) {
     lines = [];
     display(lines, [], [response]);
-    _results = [];
-    for (_i = 0, _len = lines.length; _i < _len; _i++) {
-      line = lines[_i];
-      process.stdout.write(line.join(" "));
-      _results.push(process.stdout.write("\n"));
+    for (i = 0, I = lines.length; i < I; i++) {
+      line = lines[i];
+      process.stdout.write(line.join(" ") + "\n");
     }
-    return _results;
+    return results;
   } else {
     process.stdout.write(JSON.stringify(response, null, 2));
     return process.stdout.write("\n");
   }
-});
-client.execute();
-
-# vim: set ft=javascript:
+}

ec2.idl

@@ -36,72 +36,35 @@ ec2 = ec2(configuration)
 // Run an instance and wait for it to become ready.
 ec2("RunInstances", {
   ImageId: "ami-2d4aa444", KeyName: "launch_key"
-}, function (error, response) {
-  if (error) {
-    throw error
-  }
-  reservationId   = response.reservationId;
-  instanceId      = response.instancesSet[0].instanceId;
-  ready = function () {
-    ec2("DescribeInstances", function (error, struct) {
-      if (error) {
-        throw error;
-      }
-      var reservation = struct.reservationSet.filter(function (reservation) {
-        return reservation.reservationId == reservationId;
-      })[0];
-      var instance = reservation.instancesSet.filter(function (instance) {
-        return instance.instanceId == instanceId;
-      })[0];
-      return instance.instanceState.name == "running";
-      if (instance.instanceState.name == "running") {
-        console.log("Instance created with id: " + instanceId);
-      } else {
-        setTimeout(ready, 500);
-      }
-    });
-  };
-  ready();
-});
-```
-
-```
-// Require EC2.
-var ec2 = require("ec2");
-
-// Read in the configuration above.
-var configuration = JSON.parse(fs.readFileSync("configuration.json", "utf8"));
-
-// Create an ec2 function that uses your configuration.
-ec2 = ec2(configuration)
+}, running);
 
-var response = ec2("RunInstances", {
-  ImageId: "ami-2d4aa444", KeyName: "launch_key"
-}, _);
 
-var reservationId   = response.reservationId;
-var instanceId      = response.instancesSet[0].instanceId;
-var duration        = 0;
+var reservationId, instanceId;
+function running (error, response) {
+  if (error) throw error;
+  reservationId = response.reservationId
+  instanceId = response.instancesSet[0].instanceId;
+  ec2("DescribeInstances", starting);
+}
 
-// Therefore, we poll the  "DescribeInstances" action, calling it once every
-// second until the instance state indicates that it is running.
-for (;;) {
-  response = ec2("DescribeInstances", _);   
-  var reservation = struct.reservationSet.filter(function (reservation) {
+function starting (error, response) {
+  if (error) throw error;
+  var reservation = response.reservationSet.filter(function (reservation) {
     return reservation.reservationId == reservationId;
   })[0];
   var instance = reservation.instancesSet.filter(function (instance) {
     return instance.instanceId == instanceId;
   })[0];
+  if (instance.instanceState.name == "running") ready();
+  else setTimeout(starting, 2500);
   if (instance.instanceState.name == "running") {
-    break;
-  }
-  setTimeout(_, 500);
-}
-
-client.poll("DescribeInstances", function (struct) {
 });
+
+function ready () {
+  console.log("Instance created with id: " + instanceId);
+}
 ```
+
 ## Installing
 
 The easiest way to install is using npm.
@@ -110,15 +73,12 @@ The easiest way to install is using npm.
 npm install ec2
 ```
 
-You can also checkout the source code for incusion in your `NODE_PATH` using
-`git`. 
+You can also checkout the source code for using `git`. It has only one
+dependency, the wonderful little XML parser `node-xml`.
 
 ## Reference
 
-@ ec2
-
-Node EC2 exports the ec2 namespace, which includes a single factory method to
-crate the Amazon EC2 Query API client object.
+Node EC2 exports a function you can use to build an EC2 function.
 
 ```javascript
 var ec2 = require("ec2");

launch.js

@@ -1,72 +1,46 @@
-var ec2 = require("ec2"), sys = require("sys");
+// Require EC2.
+var ec2 = require("ec2")
+  , fs = require("fs")
+  , path = require("path")
+  , configuration = path.resolve(process.env.HOME, ".aws")
+  ;
 
-var AMI = "ami-2d4aa444";
-var VOLUME = "vol-d6bf23bf";
+// Read in the configuration above.
+var configuration = JSON.parse(fs.readFileSync(configuration, "utf8"));
 
-function createRequest() {
-  return ec2.request(
-  { key: process.env["AWS_ACCESS_KEY_ID"]
-  , secret: process.env["AWS_SECRET_ACCESS_KEY"]
-  });
+// Create an ec2 function that uses your configuration.
+ec2 = ec2(configuration)
+
+// Run an instance and wait for it to become ready.
+ec2("RunInstances", {
+  ImageId: "ami-2d4aa444", KeyName: "syntechdev_aws_key", MinCount: 1, MaxCount: 1
+}, running);
+
+
+var reservationId, instanceId;
+function running (error, response) {
+  if (error) throw error;
+  reservationId = response.reservationId
+  instanceId = response.instancesSet[0].instanceId;
+  describe();
 }
 
-function launch () {
-  var state = {};
-  var amazon = ec2.createClient(
-  { key: process.env["AWS_ACCESS_KEY_ID"]
-  , secret: process.env["AWS_SECRET_ACCESS_KEY"]
-  });
-  amazon.on("error", function (error, statusCode) {
-    console.log(arguments);
-    if (error.message) {
-      console.log(sys.inspect(error.message, true, 100));
-      console.log(sys.inspect(error.stack, true, 100));
-    } else {
-      console.log(sys.inspect(error, true, 100));
-    }
-  });
-  amazon.call("DescribeVolumes", function (struct) {
-    var volume = struct.volumeSet.filter(function (volume) { return volume.volumeId == VOLUME; })[0];
-    if (/^in-use|attaching$/.test(volume.status)) {
-      throw new Error("Volume is already attached.");
-    }
-  });
-  amazon.call("RunInstances",
-  { ImageId: AMI
-  , KeyName: "backup_key"
-  , MinCount: 1
-  , MaxCount: 1
-  , "Placement.AvailabilityZone": "us-east-1b"
-  }, function (struct) {
-    state.reservationId = struct.reservationId; 
-    state.instanceId = struct.instancesSet[0].instanceId;
-  });
-  amazon.poll("DescribeInstances", function (struct) {
-    var reservation = struct.reservationSet.filter(function (reservation) {
-      return reservation.reservationId == state.reservationId;
-    }).pop():
-    var instance = reservation.instancesSet.filter(function (instance) {
-      return instance.instanceId == state.instanceId;
-    }).pop();
-    return instance.instanceState.name == "running";
-  });
-  amazon.call("AttachVolume",
-  { VolumeId: VOLUME
-  , InstanceId: function () { return state.instanceId; }
-  , Device: "/dev/sdh"
-  });
-  amazon.poll("DescribeVolumes", { "VolumeId.1": VOLUME }, function (struct) {
-    var attachment = struct.volumeSet[0].attachmentSet.filter(function (attachment) {
-      return attachment.instanceId == state.instanceId;
-    })[0];
-    return attachment.status == "attached";
-  });
-  amazon.on("end", function () {
-    console.log("Volume attached and running with instance: " + state.instanceId);
-  });
-  amazon.execute();
+function describe () {
+  ec2("DescribeInstances", {}, starting);
 }
 
-launch();
+function starting (error, response) {
+  if (error) throw error;
+  var reservation = response.reservationSet.filter(function (reservation) {
+    return reservation.reservationId == reservationId;
+  })[0];
+  var instance = reservation.instancesSet.filter(function (instance) {
+    return instance.instanceId == instanceId;
+  })[0];
+  if (instance.instanceState.name == "running") ready();
+  else setTimeout(describe, 2500);
+}
 
-// vim: set ts=2 sw=2 et nowrap:
+function ready () {
+  console.log("Instance created with id: " + instanceId);
+}