From d46daa1d7cd40a4ec5249c99027f379e4fbf88df Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sun, 7 Mar 2010 13:41:15 -0500 Subject: [PATCH] documenting optparse.coffee and repl.coffee --- documentation/docs/cake.html | 2 +- documentation/docs/command.html | 6 ++-- documentation/docs/optparse.html | 55 ++++++++++++++++++------------ documentation/docs/repl.html | 15 ++++++--- lib/cake.js | 2 +- lib/command.js | 6 ++-- lib/optparse.js | 53 +++++++++++++++++------------ lib/repl.js | 23 +++++++------ src/cake.coffee | 2 +- src/command.coffee | 6 ++-- src/optparse.coffee | 57 ++++++++++++++++++++------------ src/repl.coffee | 29 ++++++++++------ 12 files changed, 154 insertions(+), 102 deletions(-) diff --git a/documentation/docs/cake.html b/documentation/docs/cake.html index ba9e7c37..479b91d2 100644 --- a/documentation/docs/cake.html +++ b/documentation/docs/cake.html @@ -24,7 +24,7 @@ asynchrony may cause tasks to execute in a different order than you'd expect. If no tasks are passed, print the help screen.

exports.run: ->
   path.exists 'Cakefile', (exists) ->
     throw new Error("Cakefile not found in ${process.cwd()}") unless exists
-    args: process.ARGV[2...process.ARGV.length]
+    args: process.argv[2...process.argv.length]
     eval coffee.compile fs.readFileSync 'Cakefile'
     oparse: new optparse.OptionParser switches
     return print_tasks() unless args.length
diff --git a/documentation/docs/command.html b/documentation/docs/command.html
index eb3cb9ff..962de542 100644
--- a/documentation/docs/command.html
+++ b/documentation/docs/command.html
@@ -28,7 +28,7 @@ interactive REPL.
                          
 sources: []
 option_parser: null
#

Run coffee by parsing passed options and determining what action to take. Many flags cause us to divert before compiling anything. Flags passed after --- will be passed verbatim to your script as arguments in process.ARGV

exports.run: ->
+-- will be passed verbatim to your script as arguments in process.argv
                                         
exports.run: ->
   parse_options()
   return usage()                              if options.help
   return version()                            if options.version
@@ -101,9 +101,9 @@ any errors or warnings that arise.
                          [tag, value]: [token[0], token[1].toString().replace(/\n/, '\\n')]
     "[$tag $value]"
   puts strings.join(' ')
                                                                                   
                 #               
               
Use the OptionParser module to extract all options from
-process.ARGV that are specified in SWITCHES.
                                         
parse_options: ->
+process.argv that are specified in SWITCHES.
                                         
parse_options: ->
   option_parser: new optparse.OptionParser SWITCHES, BANNER
-  options: option_parser.parse(process.ARGV)
+  options: option_parser.parse(process.argv)
   sources: options.arguments[2...options.arguments.length]
                                                                                   
                 #               
               
The compile-time options to pass to the CoffeeScript compiler.
                                         
compile_options: ->
   if options['no-wrap'] then {no_wrap: true} else {}
                                                                                   
                 #               
               
Print the --help usage message and exit.
                                         
usage: ->
   puts option_parser.help()
diff --git a/documentation/docs/optparse.html b/documentation/docs/optparse.html
index 3af5b263..8dd08ff9 100644
--- a/documentation/docs/optparse.html
+++ b/documentation/docs/optparse.html
@@ -1,49 +1,60 @@
-      optparse.coffee           
                      
                
                        
               optparse.coffee             
           		                               
                                             
                            
                 #               
               
Create an OptionParser with a list of valid options, in the form:
-  [short-flag (optional), long-flag, description]
-And an optional banner for the usage help.
             		                            
exports.OptionParser: class OptionParser
+      optparse.coffee           
                      
                
                        
               optparse.coffee             
           		                               
                                             
                            
                 #               
               
A simple OptionParser class to parse option flags from the command-line.
+Use it like so:

 
-  constructor: (rules, banner) ->
+
parser:  new OptionParser switches, help_banner
+options: parser.parse process.argv
+
             		                            
exports.OptionParser: class OptionParser
             		           
                               
                            
                 #               
               
Initialize with a list of valid options, in the form:

+
+
[short-flag, long-flag, description]
+

+
+
Along with an an optional banner for the usage help.
             		                            
  constructor: (rules, banner) ->
     @banner:  banner
-    @rules:   build_rules(rules)
             		           
                               
                            
                 #               
               
Parse the argument array, populating an options object with all of the
-specified options, and returning it. options.arguments will be an array
-containing the remaning non-option arguments.
             		                            
  parse: (args) ->
+    @rules:   build_rules(rules)
             		           
                               
                            
                 #               
               
Parse the list of arguments, populating an options object with all of the
+specified options, and returning it. options.arguments will be an array
+containing the remaning non-option arguments. This is a simpler API than
+many option parsers that allow you to attach callback actions for every
+flag. Instead, you're responsible for interpreting the options object.
             		                            
  parse: (args) ->
     options: {arguments: []}
     args: normalize_arguments args
     while arg: args.shift()
       is_option: !!(arg.match(LONG_FLAG) or arg.match(SHORT_FLAG))
       matched_rule: no
       for rule in @rules
-        if rule.letter is arg or rule.flag is arg
+        if rule.short_flag is arg or rule.long_flag is arg
           options[rule.name]: if rule.has_argument then args.shift() else true
           matched_rule: yes
           break
       throw new Error "unrecognized option: $arg" if is_option and not matched_rule
       options.arguments.push arg unless is_option
-    options
             		           
                               
                            
                 #               
               
Return the help text for this OptionParser, for --help and such.
             		                            
  help: ->
+    options
             		           
                               
                            
                 #               
               
Return the help text for this OptionParser, listing and describing all
+of the valid options, for --help and such.
             		                            
  help: ->
     lines: ['Available options:']
     lines.unshift "$@banner\n" if @banner
     for rule in @rules
-      spaces:   15 - rule.flag.length
+      spaces:   15 - rule.long_flag.length
       spaces:   if spaces > 0 then (' ' for i in [0..spaces]).join('') else ''
-      let_part: if rule.letter then rule.letter + ', ' else '    '
-      lines.push "  $let_part${rule.flag}$spaces${rule.description}"
-    "\n${ lines.join('\n') }\n"
             		           
                               
                            
                 #               
               
Regex matchers for option flags.
             		                            
LONG_FLAG:  /^(--\w[\w\-]+)/
+      let_part: if rule.short_flag then rule.short_flag + ', ' else '    '
+      lines.push "  $let_part${rule.long_flag}$spaces${rule.description}"
+    "\n${ lines.join('\n') }\n"
             		           
                               
                            
                 #               
               
Helpers
             		                            
             		           
                               
                            
                 #               
               
Regex matchers for option flags.
             		                            
LONG_FLAG:  /^(--\w[\w\-]+)/
 SHORT_FLAG: /^(-\w)/
 MULTI_FLAG: /^-(\w{2,})/
-OPTIONAL:   /\[(.+)\]/
             		           
                               
                            
                 #               
               
Build rules from a list of valid switch tuples in the form:
-[letter-flag, long-flag, help], or [long-flag, help].
             		                            
build_rules: (rules) ->
+OPTIONAL:   /\[(.+)\]/
             		           
                               
                            
                 #               
               
Build and return the list of option rules. If the optional short-flag is
+unspecified, leave it out by padding with null.
             		                            
build_rules: (rules) ->
   for tuple in rules
     tuple.unshift null if tuple.length < 3
-    build_rule tuple...
             		           
                               
                            
                 #               
               
Build a rule from a short-letter-flag, long-form-flag, and help text.
             		                            
build_rule: (letter, flag, description) ->
-  match: flag.match(OPTIONAL)
-  flag:  flag.match(LONG_FLAG)[1]
+    build_rule tuple...
             		           
                               
                            
                 #               
               
Build a rule from a -o short flag, a --output [DIR] long flag, and the
+description of what the option does.
             		                            
build_rule: (short_flag, long_flag, description) ->
+  match:      long_flag.match(OPTIONAL)
+  long_flag:  long_flag.match(LONG_FLAG)[1]
   {
-    name:         flag.substr 2
-    letter:       letter
-    flag:         flag
+    name:         long_flag.substr 2
+    short_flag:   short_flag
+    long_flag:    long_flag
     description:  description
     has_argument: !!(match and match[1])
-  }
             		           
                               
                            
                 #               
               
Normalize arguments by expanding merged flags into multiple flags.
             		                            
normalize_arguments: (args) ->
+  }
             		           
                               
                            
                 #               
               
Normalize arguments by expanding merged flags into multiple flags. This allows
+you to have -wl be the same as --watch --lint.
             		                            
normalize_arguments: (args) ->
   args: args.slice 0
   result: []
   for arg in args
diff --git a/documentation/docs/repl.html b/documentation/docs/repl.html
index 12b46dd0..89495bb1 100644
--- a/documentation/docs/repl.html
+++ b/documentation/docs/repl.html
@@ -1,12 +1,17 @@
-      repl.coffee           
                      
                
                        
               repl.coffee             
           		                               
                                             
                            
                 #               
               
A CoffeeScript port/version of the Node.js REPL.
             		                            
             		           
                               
                            
                 #               
               
Required modules.
             		                            
coffee: require 'coffee-script'
             		           
                               
                            
                 #               
               
Shortcut variables.
             		                            
prompt: 'coffee> '
-quit:   -> process.exit(0)
             		           
                               
                            
                 #               
               
The main REPL function. Called everytime a line of code is entered.
-Attempt to evaluate the command. If there's an exception, print it.
             		                            
readline: (code) ->
+      repl.coffee           
                      
                
                        
               repl.coffee             
           		                               
                                             
                            
                 #               
               
A very simple Read-Eval-Print-Loop. Compiles one line at a time to JavaScript
+and evaluates it. Good for simple tests, or poking around the Node.js API.
+Using it looks like this:

+
+
coffee> puts "$num bottles of beer" for num in [99..1]
+
             		                            
             		           
                               
                            
                 #               
               
Require the coffee-script module to get access to the compiler.
             		                            
CoffeeScript: require 'coffee-script'
             		           
                               
                            
                 #               
               
Our prompt.
             		                            
prompt: 'coffee> '
             		           
                               
                            
                 #               
               
Quick alias for quitting the REPL.
             		                            
quit: -> process.exit(0)
             		           
                               
                            
                 #               
               
The main REPL function. run is called every time a line of code is entered.
+Attempt to evaluate the command. If there's an exception, print it out instead
+of exiting.
             		                            
run: (code) ->
   try
-    val: eval coffee.compile code, {no_wrap: true, globals: true}
+    val: eval CoffeeScript.compile code, {no_wrap: true, globals: true}
     p val if val isnt undefined
   catch err
     puts err.stack or err.toString()
-  print prompt
             		           
                               
                            
                 #               
               
Start up the REPL.
             		                            
process.stdio.addListener 'data', readline
+  print prompt
             		           
                               
                            
                 #               
               
Start up the REPL by opening stdio and listening for input.
             		                            
process.stdio.addListener 'data', run
 process.stdio.open()
 print prompt
 
diff --git a/lib/cake.js b/lib/cake.js
index c7c2972d..1a4d59e9 100755
--- a/lib/cake.js
+++ b/lib/cake.js
@@ -51,7 +51,7 @@
       if (!(exists)) {
         throw new Error("Cakefile not found in " + (process.cwd()));
       }
-      args = process.ARGV.slice(2, process.ARGV.length);
+      args = process.argv.slice(2, process.argv.length);
       eval(coffee.compile(fs.readFileSync('Cakefile')));
       oparse = new optparse.OptionParser(switches);
       if (!(args.length)) {
diff --git a/lib/command.js b/lib/command.js
index d23568d9..e73548e4 100644
--- a/lib/command.js
+++ b/lib/command.js
@@ -20,7 +20,7 @@
   option_parser = null;
   // Run `coffee` by parsing passed options and determining what action to take.
   // Many flags cause us to divert before compiling anything. Flags passed after
-  // `--` will be passed verbatim to your script as arguments in `process.ARGV`
+  // `--` will be passed verbatim to your script as arguments in `process.argv`
   exports.run = function run() {
     var flags, separator;
     parse_options();
@@ -197,10 +197,10 @@
     return puts(strings.join(' '));
   };
   // Use the [OptionParser module](optparse.html) to extract all options from
-  // `process.ARGV` that are specified in `SWITCHES`.
+  // `process.argv` that are specified in `SWITCHES`.
   parse_options = function parse_options() {
     option_parser = new optparse.OptionParser(SWITCHES, BANNER);
-    options = option_parser.parse(process.ARGV);
+    options = option_parser.parse(process.argv);
     return sources = options.arguments.slice(2, options.arguments.length);
   };
   // The compile-time options to pass to the CoffeeScript compiler.
diff --git a/lib/optparse.js b/lib/optparse.js
index ca2e921c..4095b885 100755
--- a/lib/optparse.js
+++ b/lib/optparse.js
@@ -1,17 +1,23 @@
 (function(){
   var LONG_FLAG, MULTI_FLAG, OPTIONAL, OptionParser, SHORT_FLAG, build_rule, build_rules, normalize_arguments;
-  // Create an OptionParser with a list of valid options, in the form:
-  //   [short-flag (optional), long-flag, description]
-  // And an optional banner for the usage help.
+  // A simple **OptionParser** class to parse option flags from the command-line.
+  // Use it like so:
+  //     parser:  new OptionParser switches, help_banner
+  //     options: parser.parse process.argv
   exports.OptionParser = (function() {
     OptionParser = function OptionParser(rules, banner) {
       this.banner = banner;
       this.rules = build_rules(rules);
       return this;
     };
-    // Parse the argument array, populating an options object with all of the
-    // specified options, and returning it. options.arguments will be an array
-    // containing the remaning non-option arguments.
+    // Initialize with a list of valid options, in the form:
+    //     [short-flag, long-flag, description]
+    // Along with an an optional banner for the usage help.
+    // Parse the list of arguments, populating an `options` object with all of the
+    // specified options, and returning it. `options.arguments` will be an array
+    // containing the remaning non-option arguments. This is a simpler API than
+    // many option parsers that allow you to attach callback actions for every
+    // flag. Instead, you're responsible for interpreting the options object.
     OptionParser.prototype.parse = function parse(args) {
       var _a, _b, _c, arg, is_option, matched_rule, options, rule;
       arguments = Array.prototype.slice.call(arguments, 0);
@@ -25,7 +31,7 @@
         _a = this.rules;
         for (_b = 0, _c = _a.length; _b < _c; _b++) {
           rule = _a[_b];
-          if (rule.letter === arg || rule.flag === arg) {
+          if (rule.short_flag === arg || rule.long_flag === arg) {
             options[rule.name] = rule.has_argument ? args.shift() : true;
             matched_rule = true;
             break;
@@ -40,7 +46,8 @@
       }
       return options;
     };
-    // Return the help text for this OptionParser, for --help and such.
+    // Return the help text for this **OptionParser**, listing and describing all
+    // of the valid options, for `--help` and such.
     OptionParser.prototype.help = function help() {
       var _a, _b, _c, _d, _e, _f, _g, _h, i, let_part, lines, rule, spaces;
       lines = ['Available options:'];
@@ -50,7 +57,7 @@
       _a = this.rules;
       for (_b = 0, _c = _a.length; _b < _c; _b++) {
         rule = _a[_b];
-        spaces = 15 - rule.flag.length;
+        spaces = 15 - rule.long_flag.length;
         spaces = spaces > 0 ? (function() {
           _d = []; _g = 0; _h = spaces;
           for (_f = 0, i = _g; (_g <= _h ? i <= _h : i >= _h); (_g <= _h ? i += 1 : i -= 1), _f++) {
@@ -58,20 +65,22 @@
           }
           return _d;
         }).call(this).join('') : '';
-        let_part = rule.letter ? rule.letter + ', ' : '    ';
-        lines.push("  " + let_part + (rule.flag) + spaces + (rule.description));
+        let_part = rule.short_flag ? rule.short_flag + ', ' : '    ';
+        lines.push("  " + let_part + (rule.long_flag) + spaces + (rule.description));
       }
       return "\n" + (lines.join('\n')) + "\n";
     };
     return OptionParser;
   }).call(this);
+  // Helpers
+  // -------
   // Regex matchers for option flags.
   LONG_FLAG = /^(--\w[\w\-]+)/;
   SHORT_FLAG = /^(-\w)/;
   MULTI_FLAG = /^-(\w{2,})/;
   OPTIONAL = /\[(.+)\]/;
-  // Build rules from a list of valid switch tuples in the form:
-  // [letter-flag, long-flag, help], or [long-flag, help].
+  // Build and return the list of option rules. If the optional *short-flag* is
+  // unspecified, leave it out by padding with `null`.
   build_rules = function build_rules(rules) {
     var _a, _b, _c, _d, tuple;
     _a = []; _b = rules;
@@ -86,20 +95,22 @@
     }
     return _a;
   };
-  // Build a rule from a short-letter-flag, long-form-flag, and help text.
-  build_rule = function build_rule(letter, flag, description) {
+  // Build a rule from a `-o` short flag, a `--output [DIR]` long flag, and the
+  // description of what the option does.
+  build_rule = function build_rule(short_flag, long_flag, description) {
     var match;
-    match = flag.match(OPTIONAL);
-    flag = flag.match(LONG_FLAG)[1];
+    match = long_flag.match(OPTIONAL);
+    long_flag = long_flag.match(LONG_FLAG)[1];
     return {
-      name: flag.substr(2),
-      letter: letter,
-      flag: flag,
+      name: long_flag.substr(2),
+      short_flag: short_flag,
+      long_flag: long_flag,
       description: description,
       has_argument: !!(match && match[1])
     };
   };
-  // Normalize arguments by expanding merged flags into multiple flags.
+  // Normalize arguments by expanding merged flags into multiple flags. This allows
+  // you to have `-wl` be the same as `--watch --lint`.
   normalize_arguments = function normalize_arguments(args) {
     var _a, _b, _c, _d, _e, _f, arg, l, match, result;
     args = args.slice(0);
diff --git a/lib/repl.js b/lib/repl.js
index 344ff766..862758b9 100644
--- a/lib/repl.js
+++ b/lib/repl.js
@@ -1,19 +1,22 @@
 (function(){
-  var coffee, prompt, quit, readline;
-  // A CoffeeScript port/version of the Node.js REPL.
-  // Required modules.
-  coffee = require('coffee-script');
-  // Shortcut variables.
+  var CoffeeScript, prompt, quit, run;
+  // A very simple Read-Eval-Print-Loop. Compiles one line at a time to JavaScript
+  // and evaluates it. Good for simple tests, or poking around the **Node.js** API.
+  // Require the **coffee-script** module to get access to the compiler.
+  CoffeeScript = require('coffee-script');
+  // Our prompt.
   prompt = 'coffee> ';
+  // Quick alias for quitting the REPL.
   quit = function quit() {
     return process.exit(0);
   };
-  // The main REPL function. Called everytime a line of code is entered.
-  // Attempt to evaluate the command. If there's an exception, print it.
-  readline = function readline(code) {
+  // The main REPL function. `run` is called every time a line of code is entered.
+  // Attempt to evaluate the command. If there's an exception, print it out instead
+  // of exiting.
+  run = function run(code) {
     var val;
     try {
-      val = eval(coffee.compile(code, {
+      val = eval(CoffeeScript.compile(code, {
         no_wrap: true,
         globals: true
       }));
@@ -26,7 +29,7 @@
     return print(prompt);
   };
   // Start up the REPL.
-  process.stdio.addListener('data', readline);
+  process.stdio.addListener('data', run);
   process.stdio.open();
   print(prompt);
 })();
diff --git a/src/cake.coffee b/src/cake.coffee
index e744e2dd..5141e6a5 100644
--- a/src/cake.coffee
+++ b/src/cake.coffee
@@ -45,7 +45,7 @@ process.mixin {
 exports.run: ->
   path.exists 'Cakefile', (exists) ->
     throw new Error("Cakefile not found in ${process.cwd()}") unless exists
-    args: process.ARGV[2...process.ARGV.length]
+    args: process.argv[2...process.argv.length]
     eval coffee.compile fs.readFileSync 'Cakefile'
     oparse: new optparse.OptionParser switches
     return print_tasks() unless args.length
diff --git a/src/command.coffee b/src/command.coffee
index d52582a5..19049f73 100644
--- a/src/command.coffee
+++ b/src/command.coffee
@@ -42,7 +42,7 @@ option_parser: null
 
 # Run `coffee` by parsing passed options and determining what action to take.
 # Many flags cause us to divert before compiling anything. Flags passed after
-# `--` will be passed verbatim to your script as arguments in `process.ARGV`
+# `--` will be passed verbatim to your script as arguments in `process.argv`
 exports.run: ->
   parse_options()
   return usage()                              if options.help
@@ -139,10 +139,10 @@ print_tokens: (tokens) ->
   puts strings.join(' ')
 
 # Use the [OptionParser module](optparse.html) to extract all options from
-# `process.ARGV` that are specified in `SWITCHES`.
+# `process.argv` that are specified in `SWITCHES`.
 parse_options: ->
   option_parser: new optparse.OptionParser SWITCHES, BANNER
-  options: option_parser.parse(process.ARGV)
+  options: option_parser.parse(process.argv)
   sources: options.arguments[2...options.arguments.length]
 
 # The compile-time options to pass to the CoffeeScript compiler.
diff --git a/src/optparse.coffee b/src/optparse.coffee
index 6ebf0d3c..17f80b10 100644
--- a/src/optparse.coffee
+++ b/src/optparse.coffee
@@ -1,15 +1,24 @@
-# Create an OptionParser with a list of valid options, in the form:
-#   [short-flag (optional), long-flag, description]
-# And an optional banner for the usage help.
+# A simple **OptionParser** class to parse option flags from the command-line.
+# Use it like so:
+#
+#     parser:  new OptionParser switches, help_banner
+#     options: parser.parse process.argv
 exports.OptionParser: class OptionParser
 
+  # Initialize with a list of valid options, in the form:
+  #
+  #     [short-flag, long-flag, description]
+  #
+  # Along with an an optional banner for the usage help.
   constructor: (rules, banner) ->
     @banner:  banner
     @rules:   build_rules(rules)
 
-  # Parse the argument array, populating an options object with all of the
-  # specified options, and returning it. options.arguments will be an array
-  # containing the remaning non-option arguments.
+  # Parse the list of arguments, populating an `options` object with all of the
+  # specified options, and returning it. `options.arguments` will be an array
+  # containing the remaning non-option arguments. This is a simpler API than
+  # many option parsers that allow you to attach callback actions for every
+  # flag. Instead, you're responsible for interpreting the options object.
   parse: (args) ->
     options: {arguments: []}
     args: normalize_arguments args
@@ -17,7 +26,7 @@ exports.OptionParser: class OptionParser
       is_option: !!(arg.match(LONG_FLAG) or arg.match(SHORT_FLAG))
       matched_rule: no
       for rule in @rules
-        if rule.letter is arg or rule.flag is arg
+        if rule.short_flag is arg or rule.long_flag is arg
           options[rule.name]: if rule.has_argument then args.shift() else true
           matched_rule: yes
           break
@@ -25,43 +34,49 @@ exports.OptionParser: class OptionParser
       options.arguments.push arg unless is_option
     options
 
-  # Return the help text for this OptionParser, for --help and such.
+  # Return the help text for this **OptionParser**, listing and describing all
+  # of the valid options, for `--help` and such.
   help: ->
     lines: ['Available options:']
     lines.unshift "$@banner\n" if @banner
     for rule in @rules
-      spaces:   15 - rule.flag.length
+      spaces:   15 - rule.long_flag.length
       spaces:   if spaces > 0 then (' ' for i in [0..spaces]).join('') else ''
-      let_part: if rule.letter then rule.letter + ', ' else '    '
-      lines.push "  $let_part${rule.flag}$spaces${rule.description}"
+      let_part: if rule.short_flag then rule.short_flag + ', ' else '    '
+      lines.push "  $let_part${rule.long_flag}$spaces${rule.description}"
     "\n${ lines.join('\n') }\n"
 
+# Helpers
+# -------
+
 # Regex matchers for option flags.
 LONG_FLAG:  /^(--\w[\w\-]+)/
 SHORT_FLAG: /^(-\w)/
 MULTI_FLAG: /^-(\w{2,})/
 OPTIONAL:   /\[(.+)\]/
 
-# Build rules from a list of valid switch tuples in the form:
-# [letter-flag, long-flag, help], or [long-flag, help].
+# Build and return the list of option rules. If the optional *short-flag* is
+# unspecified, leave it out by padding with `null`.
 build_rules: (rules) ->
   for tuple in rules
     tuple.unshift null if tuple.length < 3
     build_rule tuple...
 
-# Build a rule from a short-letter-flag, long-form-flag, and help text.
-build_rule: (letter, flag, description) ->
-  match: flag.match(OPTIONAL)
-  flag:  flag.match(LONG_FLAG)[1]
+# Build a rule from a `-o` short flag, a `--output [DIR]` long flag, and the
+# description of what the option does.
+build_rule: (short_flag, long_flag, description) ->
+  match:      long_flag.match(OPTIONAL)
+  long_flag:  long_flag.match(LONG_FLAG)[1]
   {
-    name:         flag.substr 2
-    letter:       letter
-    flag:         flag
+    name:         long_flag.substr 2
+    short_flag:   short_flag
+    long_flag:    long_flag
     description:  description
     has_argument: !!(match and match[1])
   }
 
-# Normalize arguments by expanding merged flags into multiple flags.
+# Normalize arguments by expanding merged flags into multiple flags. This allows
+# you to have `-wl` be the same as `--watch --lint`.
 normalize_arguments: (args) ->
   args: args.slice 0
   result: []
diff --git a/src/repl.coffee b/src/repl.coffee
index 064ebbdb..ab98d93e 100644
--- a/src/repl.coffee
+++ b/src/repl.coffee
@@ -1,23 +1,30 @@
-# A CoffeeScript port/version of the Node.js REPL.
+# A very simple Read-Eval-Print-Loop. Compiles one line at a time to JavaScript
+# and evaluates it. Good for simple tests, or poking around the **Node.js** API.
+# Using it looks like this:
+#
+#     coffee> puts "$num bottles of beer" for num in [99..1]
 
-# Required modules.
-coffee: require 'coffee-script'
+# Require the **coffee-script** module to get access to the compiler.
+CoffeeScript: require 'coffee-script'
 
-# Shortcut variables.
+# Our prompt.
 prompt: 'coffee> '
-quit:   -> process.exit(0)
 
-# The main REPL function. Called everytime a line of code is entered.
-# Attempt to evaluate the command. If there's an exception, print it.
-readline: (code) ->
+# Quick alias for quitting the REPL.
+quit: -> process.exit(0)
+
+# The main REPL function. **run** is called every time a line of code is entered.
+# Attempt to evaluate the command. If there's an exception, print it out instead
+# of exiting.
+run: (code) ->
   try
-    val: eval coffee.compile code, {no_wrap: true, globals: true}
+    val: eval CoffeeScript.compile code, {no_wrap: true, globals: true}
     p val if val isnt undefined
   catch err
     puts err.stack or err.toString()
   print prompt
 
-# Start up the REPL.
-process.stdio.addListener 'data', readline
+# Start up the REPL by opening **stdio** and listening for input.
+process.stdio.addListener 'data', run
 process.stdio.open()
 print prompt
\ No newline at end of file