Created a readme, updated the todo and added some examples

README.markdown

@@ -0,0 +1,101 @@
+== trollopjs
+
+[Trollop](http://trollop.rubyforge.org) is a commandline option parser for Ruby.
+
+trollopjs is a port of that to work with the Node library.
+
+Almost everything is working except for the formatting of the help message.
+View the differences before.
+
+== DESCRIPTION
+
+trollopjs is a commandline option parser for Node that just gets out of your
+way. One line of code per option is all you need to write. For that, you get a
+nice automatically-generated help page, robust option parsing, command
+subcompletion, and sensible defaults for everything you don't specify.
+
+== DOCUMENTATION/QUICK START
+
+I have no documentation.  But if you are curious you can consult the Ruby docs
+for the original Trollop:
+
+[http://trollop.rubyforge.org/](http://trollop.rubyforge.org/)
+
+Or you can checkout the files in the examples dir.
+
+== QUICK EXAMPLE
+
+    var trollopjs = require('trollopjs');
+
+    var opts = trollopjs.options(function() {
+      this.opt('monkey', "Use monkey mode");                     // a flag --monkey, defaulting to false
+      this.opt('goat', "Use goat mode", {dflt: true});           // a flag --goat, defaulting to true
+      this.opt('num_limbs', "Number of limbs", {dflt: 4});       // an integer --num-limbs <i>, defaulting to 4
+      this.opt('num_thumbs', "Number of thumbs", {type: 'int'}); // an integer --num-thumbs <i>, defaulting to nil
+    });
+
+    var sys = require('sys');
+    sys.puts(sys.inspect(opts));
+    /* prints:
+    {
+     "monkey": false,
+     "goat": true,
+     "num_limbs": 4,
+     "help": false
+    }
+    */
+
+== INSTALLING/RUNNING
+
+Checkout out the code and make sure it is in your [node path](http://nodejs.org/api.html#_modules).
+
+Run a file with the following command:
+
+    node filename.js
+
+Pass it parameters:
+
+    node filename.js --monkey
+
+The `node` command has a tendency to steal 'help' and 'version' arguments, so if you 
+follow it up with `--` you won't run into any problems:
+
+    node -- filename.js --help
+
+== FEATURES/PROBLEMS
+
+- Dirt-simple usage.
+- Sensible defaults. No tweaking necessary, much tweaking possible.
+- Support for long options, short options, short option bundling, and
+  automatic type validation and conversion.
+- Support for subcommands.
+- Automatic help message generation, wrapped to current screen width.
+- Lots of unit tests.
+
+== REQUIREMENTS
+
+* A burning desire to write less code.
+
+== DIFFERENCES FROM THE RUBY TROLLOP
+
+The Ruby Trollop has an IO type.   At this time there isn't a good mapping for that
+in Node, so I removed it.
+
+'default' is a keyword in javascript, so the option has been renamed 'dflt'.
+
+I haven't implemented the Trollop::die function.
+
+== LICENSE
+
+trollopjs is distributed under the same terms as Trollop:
+
+Copyright (c) 2008--2009 William Morgan. Trollop is distributed under the same
+terms as Ruby.
+
+== ABOUT THE RUBY TROLLOP
+
+Trollop is origonally by William Morgan (http://masanjin.net/)
+
+Main page: http://trollop.rubyforge.org
+
+Release announcements and comments: http://all-thing.net/label/trollop

examples/simple.js

@@ -0,0 +1,37 @@
+var sys = require('sys');
+var trollopjs = require('../index');
+
+// no args given, so opts is just the default options
+var opts = trollopjs.options(function() {
+  this.opt('monkey', "Use monkey mode");                     // a flag --monkey, defaulting to false
+  this.opt('goat', "Use goat mode", {dflt: true});           // a flag --goat, defaulting to true
+  this.opt('num_limbs', "Number of limbs", {dflt: 4});       // an integer --num-limbs <i>, defaulting to 4
+  this.opt('num_thumbs', "Number of thumbs", {type: 'int'}); // an integer --num-thumbs <i>, defaulting to nil
+});
+
+sys.puts(sys.inspect(opts));
+/* EXAMPLES
+
+node ./examples/simple.js
+
+outputs:
+{
+  "monkey": false,
+  "goat": true,
+  "num_limbs": 4,
+  "help": false
+}
+
+node ./examples/simple.js --monkey --num-limbs 3
+
+outputs:
+{
+  "monkey": true,
+  "goat": true,
+  "num_limbs": 3,
+  "help": false,
+  "monkey_given": true,
+  "num_limbs_given": true
+}
+
+*/

examples/subcommands.js

@@ -0,0 +1,87 @@
+// Here's a program called "magic". We want this behavior:
+//
+//   magic delete <fn> => deletes a file
+//   magic copy <fn>   => copies a file
+//
+// So 'delete' and 'copy' are subcommands.
+//
+// There are some global options, which appear to the left of the subcommand.
+// There are some subcommand options, which appear to the right.
+//
+// Subcommand options can be specific to the subcommand. 'delete' might take
+// different options from 'copy'.
+//
+// We do this by calling Trollop twice; one for the global options and once for
+// the subcommand options. We need to tell Trollop what the subcommands are, so
+// that it stops processing the global options when it encounters one of them.
+
+var sys = require('sys');
+var trollopjs = require('../index');
+
+SUB_COMMANDS = ['delete', 'copy']
+
+var argv = process.ARGV.slice(2);
+global_opts = trollopjs.options(argv, function() {
+  this.banner("magic file deleting and copying utility");
+  this.opt('dry_run', "Don't actually do anything", {short: "-n"});
+  this.stop_on(SUB_COMMANDS);
+});
+
+cmd = argv.shift(); // get the subcommand
+switch(cmd) {
+case 'delete':
+  var cmd_opts = trollopjs.options(argv, function() {
+      this.opt('force', "Force deletion");
+    });
+  break;
+case 'copy':
+  var cmd_opts = trollopjs.options(argv, function() {
+      this.opt('double', "Copy twice for safety's sake");
+    });
+  break;
+default:
+  throw "unknown subcommand "+cmd;
+}
+
+sys.puts("Global options: " + sys.inspect(global_opts));
+sys.puts("Subcommand: " + cmd);
+sys.puts("Subcommand options: " + sys.inspect(cmd_opts));
+sys.puts("Remaining arguments: " + sys.inspect(argv));
+
+/* EXAMPLES
+
+node ./examples/subcommands.js delete filename.js 
+
+outputs:
+Global options: {
+  "dry_run": false,
+  "help": false
+}
+Subcommand: delete
+Subcommand options: {
+  "force": false,
+  "help": false
+}
+Remaining arguments: [
+  "filename.js"
+]
+ 
+node ./examples/subcommands.js copy --double filename.js
+
+outputs:
+Global options: {
+  "dry_run": false,
+  "help": false
+}
+Subcommand: copy
+Subcommand options: {
+  "double": true,
+  "help": false,
+  "double_given": true
+}
+Remaining arguments: [
+  "filename.js"
+]
+
+*/
+

todo.txt

@@ -1,4 +1,5 @@
- + throw actual errors (CommandError, ArgumentError)
- + fix checking for if default is integer or float (mostly allow you to override it with type parameter)
- + fix wrapping
- + fix tests for help message
+  throw actual errors (CommandError, ArgumentError)
+  fix checking for if default is integer or float (mostly allow you to override it with type parameter)
+  fix wrapping
+  fix tests for help message
+  Trollop::die