Adding the last two days worth of work

LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) 2102 individual committers of the code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Except as contained in this notice, the name(s) of the above copyright holders 
+shall not be used in advertising or otherwise to promote the sale, use or other
+dealings in this Software without prior written authorization.
+
+The end-user documentation included with the redistribution, if any, must 
+include the following acknowledgment: "This product includes software developed 
+by contributors", in the same place and form as other third-party
+acknowledgments. Alternately, this acknowledgment may appear in the software
+itself, in the same form and location as other such third-party
+acknowledgments.

OptionParameter.md

@@ -0,0 +1,157 @@
+An instance of the OptionParameter class represents a single option.  It knows
+about all of the ways that option can get specified, if it takes a value, and
+what values were passed in from the command-line.
+
+Constructor($short, $long, $message = null)
+-------------------------------------------
+
+Create a new instance of the class.  $short and $long indicate what options are
+allowed.  Multiple short and long options can be specified by passing an array
+of allowed options.  A wildcard short option of '*' or '-' will mean that this
+option should match any short or long option that didn't match anything else.
+
+$short can be an array of strings or just a single string.  Each string should
+be exactly 1 character long.
+
+$long can be an array of strings or just a single string.
+
+$message is the help message to be displayed for this option.
+
+action($callback)
+-----------------
+
+Set an action to be performed when you specify this parameter.  In PHP,
+$callback can be a closure, function name, array containing a class name and a
+method, or anything else that's acceptable to call_user_func().  In JavaScript,
+this can only be a closure.
+
+If an invalid $callback is used, an Exception is thrown.
+
+argument($name, $required = true)
+---------------------------------
+
+Specify that this parameter takes a value from the command line.
+
+$name is a string for the help message.  It isn't used anywhere else.
+
+$required is a boolean and will default to true if not passed.
+
+
+count()
+-------
+
+Returns the number of times this parameter was used on the command line.
+
+
+handleArgument($option, $value = null)
+--------------------------------------
+Performs validation with the optionally specified validation callback.  If that
+fails, will throw an Exception.  Once it passes the validation step, an action
+callback may be executed if one was assigned via action().  Lastly, this adds
+the value to the getopt version of the arguments.
+
+This is intended to be only used by OptionParser.
+
+getopt()
+--------
+
+Returns an array to be used by OptionParser->getopt().
+
+getWidth()
+----------
+
+Returns the terminal width, employing whatever tricks that might work for you.
+Defaults to 80 if it can't find an actual terminal's width.
+
+help($pad = 16, $gutter = 2, $width = null)
+-------------------------------------------
+
+Returns a string describing this option and how to invoke it.
+
+$pad is the amount of space on the left for indenting the help option.  It
+defaults to 16 spaces.
+
+$gutter is the minimum amount of space required at the end of the short and
+long options and before the beginning of the help text.  If there isn't this
+much space, the options will be put on a separate line.
+
+$width is the size of the terminal.  The default is null, which means the
+option should call getWidth() and try to figure out the terminal width itself.
+
+matchAutocomplete($arg)
+-----------------------
+
+Returns an array of options that might match if the user just didn't finish the
+entire long option.  for instance, the $arg of "lo" would match "--long".
+
+This is only intended to be called from OptionParser.
+
+matchLongArgument($arg)
+-----------------------
+
+Returns true if the argument exactly matches a long argument for this
+parameter.
+
+matchShortArgument($arg)
+------------------------
+
+Returns true if the argument exactly matches a short argument for this
+parameter.
+
+
+matchWildcard()
+---------------
+
+Returns true if this parameter is considered a "wildcard" parameter.  This
+means that a short option is either '*' or '-'.
+
+usesArgument()
+--------------
+
+Returns whether or not the parameter takes an argument.  Return value is
+language-specific.
+
+This is intended to only be called from OptionParser.
+
+validateCallback($callback)
+---------------------------
+
+Returns true if the callback is valid.  In PHP, this checks to see if it
+is_callable().  For JavaScript, we check to make typeof $callback is
+"function".
+
+Throws an Exception if an invalid callback is specified.
+
+validation($callback)
+---------------------
+
+Set a validation function to be performed when you specify this parameter.  In
+PHP, $callback can be a closure, function name, array containing a class name
+and a method, or anything else that's acceptable to call_user_func().  In
+JavaScript, this can only be a closure.
+
+The validation function will take a single parameter, which is the value
+specified for the parameter.  If the value is valid, null should be returned.
+Otherwise, return an informative message as a string, which is set as the
+Exception's message.
+
+If an invalid $callback is used, an Exception is thrown.
+
+value()
+-------
+
+For a parameter that takes values, returns the last value specified.  Otherwise
+return the number of times this parameter was specified.  Similar to values().
+
+values()
+--------
+
+For a parameter that takes values, returns an array that contains all values
+ever set on the command line.  Otherwise returns the number of times the
+parameter was specified.
+
+wrap($str, $pad, $width)
+------------------------
+
+Rewraps $str to fit within $width.  When newlines are added, indents the next
+line with $pad spaces.

OptionParser.md

@@ -0,0 +1,86 @@
+The OptionParser object handles keeping track of OptionParameters and parsing
+of options.
+
+The class also will set up named options so you can access the OptionParameter
+objects as just properties of the object directly.  In PHP, the following code
+would be equivalent for a parameter named "testThing".
+
+    $parameter = $parser->get("testThing");
+    $parameter = $parser->testThing;
+
+addOption($short, $long, $helpMessage = null, $name = null)
+-----------------------------------------------------------
+
+Creates a new OptionParameter.  $short, $long and $helpMessage are passed
+directly to OptionParameter's constructor.  $name, if specified, will assign a
+name to the object.  Named objects can be retrieved directly as properties and
+via the get() method.
+
+autocomplete($boolean)
+----------------------
+
+Turn on or off the autocomplete functionality, which lets long options match
+shorter phrases, like "--long" would match "--longOption".  By default,
+autocomplete is disabled because it could cause confusion or problems.
+
+get($name)
+----------
+
+Return a named parameter.  If no parameter exists with the given name, an
+Exception is thrown.
+
+getopt()
+--------
+
+Return an array or object similar to how PHP's getopt() function works.  It
+does this by calling all of the OptionParameter objects that were added and
+combining their results.
+
+getValue($name)
+---------------
+
+Gets the value from the named parameter.  The following three versions of PHP
+code are equivalent.
+
+    $value = $parser->get('test')->value();
+    $value = $parser->test->value();
+    $value = $parser->getValue('test');
+
+help()
+------
+
+Builds a help message that describes all of the options that are available.
+Returns it as a large string with a trailing newline.  Builds the message by
+calling help() on all of the OptionParameters available.
+
+helpAction($commandLine = '[options]')
+--------------------------------------
+
+Builds a very generic help callback that can be used with
+OptionParameter->action().  The description of parameters that can be passed on
+the command line can be overridden by providing a different $commandLine
+variable.
+
+
+parse($options = null)
+----------------------
+
+Parses the options passed to the program.  If $options is null (as I expect it
+would be), the options are grabbed from $GLOBALS['argv'] in PHP or process.argv
+in JavaScript.  The program name is also parsed out before options.
+
+If $options is an array, the program name is not parsed and the options are
+used as-is.
+
+programName()
+-------------
+
+Returns the program name, if one was parsed out by not passing anything to the
+parse() method.
+
+scanAll($boolean)
+-----------------
+
+If true, scan for options across the entire command line.  If false, stop
+parsing at the first unknown option.  The default is true.  To better emulate
+PHP's getopt() implementation, this needs to be set to false.