documenting optparse.coffee and repl.coffee

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

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.

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: []

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