getopt 1.2.0 → 1.3.0

data/CHANGES

@@ -1,3 +1,11 @@
+== 4-Nov-2005 - 1.3.0
+* Added the Getopt::Long class (long.rb).  This is a complete revamp of the
+  old getoptlong package, with ideas tossed in from Perl's Getopt::Long
+  package.  See the README and example script for more detail.
+* Added an example, and renamed the "test_std.rb" example to "example_std.rb".
+* Added lots of documentation to the README file.
+* Updated the MANIFEST, test suite, etc.
+
 == 24-Oct-2005 - 1.2.0
 * Altered the way multiple occurrences of the same switch are handled, for
   those switches that accept arguments.

data/MANIFEST

@@ -1,10 +1,15 @@
 CHANGES
 MANIFEST
+README
 install.rb
 getopt.gemspec
 
-examples/test_std.rb
+examples/example_std.rb
+examples/example_long.rb
 
 lib/getopt/std.rb
+lib/getopt/long.rb
 
-test/tc_getopt_std.rb
+test/tc_getopt_std.rb
+test/tc_getopt_long.rb
+test/ts_all.rb

data/README

@@ -1,36 +1,51 @@
 == Description
-   Implements a simple Getopt::Std class for command line parsing.  It will
-   eventually add a drop-in replacement for getopt-long as well.
+   Implements a simple Getopt::Std class for command line parsing, as well
+   as a Getopt::Long class for more advanced command line parsing.
 
 == Prerequisites
    Ruby 1.8.0 or later.
    
 == Installation
 === Standard Installation
-   ruby test/tc_getopt_std.rb
+   ruby test/ts_all.rb
    ruby install.rb
+
 === Gem Installation
-   ruby test/tc_getopt_std.rb
+   ruby test/ts_all.rb
    ruby getopt.gemspec
    gem install getopt-x-y-z.gem # Where x-y-z is a version
    
 == Synopsis
-	require "getopt/std"
-	
-	# Look for -o with argument, and -I and -D boolean arguments
-	opt = Getopt::Std.getopts("o:ID")
+=== Getopt::Std
+   require "getopt/std"
 	
-	if opt["I"]
-		# Do something if -I passed
+   # Look for -o with argument, and -I and -D boolean arguments
+   opt = Getopt::Std.getopts("o:ID")
+
+   if opt["I"]
+      # Do something if -I passed
 		
-	if opt["D"]
-		# Do something if -D passed
+   if opt["D"]
+      # Do something if -D passed
 		
-	if opt["o"]
-		case opt["o"]
-			# blah, blah, blah
-	   end
-	end
+   if opt["o"]
+      case opt["o"]
+         # blah, blah, blah
+      end
+   end
+
+=== Getopt::Long
+   require "getopt/long"
+   opt = Getopt::Long.getopts(
+      ["--foo", "-f", BOOLEAN],
+      ["--bar", "-b", REQUIRED]
+   )
+
+   if opt["foo"]
+      # Do something if --foo or -f passed
+
+   if opt["b"]
+      # Do something if --bar or -b passed
 
 == Class Methods
 Std.getopts(switches)
@@ -44,10 +59,60 @@ Std.getopts(switches)
    In the event that a switch that accepts an argument appears multiple times
    the value for that key becomes an array of values.
 
+Long.getopts(switches)
+   Takes an array of switches beginning with "--" followed by one or more
+   characters, or "-w" followed by a single character.  The type of argument,
+   if any, can be specified as BOOLEAN, OPTIONAL, REQUIRED or INCREMENT.
+
+   The array should be in the form:
+
+   ["--long", "-l", OPTION]
+
+   Note that only the long form is required.  If the short switch is not
+   specified, it will automatically be set to the first letter of the long
+   switch.
+
+   If the argument type is not specified, the default is BOOLEAN.
+
+   For the truly lazy, you can also pass a string of long switches (with
+   no short switches or argument types). 
+
+   See the 'examples' directory for more examples.
+
+== Getopt::Long argument types
+REQUIRED
+   If the option is specified on the command line, it must be followed by
+   a non-blank argument.  This argument cannot be another switch. If this
+   switch appears multiple times, the values are collected into an array.
+
+BOOLEAN
+   If the option is specified on the command line, it's value is set to true.
+   It must not be followed by a non-blank argument, excluding other switches.
+   Attempting to pass a boolean switch more than once will raise an error.
+
+OPTIONAL
+   If the option is specified on the command line, it may or may not accept
+   an argument, excluding other valid switches.  If an argument is present,
+   it's value is set to that argument.  If an argument is not present, it's
+   value is set to nil.
+
+INCREMENT
+   If the option is specified on the command line, its value is incremented
+   by one for each appearance on the command line, or set to 1 if it appears
+   only once.
+
 == Future Plans
-   * Add a replacement for Getopt::Long.
-   
+   Add support for negatable options so that you can do "--no-foo", for
+   example.
+
+   Add support for numeric types, so that you don't have to manually convert
+   strings to numbers.
+
+   Allow shortcut characters for the option types, e.g. "?" for BOOLEAN, "+"
+   for INCREMENT, etc.
+
 == Known Bugs
+=== Getopt::Std
    You cannot squish switches that require arguments with the argument itself.
    For example, if you do Getopt::Std.getopts("o:ID"), it will not parse
    "-IDohello" properly.  Instead, you must do "-IDo hello".  Or, you can just
@@ -56,6 +121,33 @@ Std.getopts(switches)
    If you find any other bugs, please log them on the project
    page at http://www.rubyforge.org/projects/shards.
 
+== Other Issues
+   Neither of the classes attempts to be POSIX compliant in any way, shape
+   or form.  And I don't care!
+
+== Notes From the Author
+   My main gripe with the getoptlong library currently in the standard library
+   is that it doesn't return a hash, yet gives you partial hash behavior.  This
+   was both confusing and annoying, since the first thing I (and everyone else)
+   does is collect the results into a hash for later processing.
+
+   My main gripe with the optparse library (also in the standard library) is
+   that it treats command line processing like event processing.  It's too
+   complex, when 90% of the time all you want to do is slurp the command line
+   options into a hash.
+
+   So, I did something utterly novel with this library.  I collected the command
+   line options ... (wait for it) ... into a hash!  Then I give that hash to
+   you, aliases and all.  I did get some ideas from Perl's Getopt::Long library,
+   but this is in no way a port of that module (which supports POSIX parsing, GNU
+   parsing, more option types, etc).  My goal was to provide the functionality
+   that I felt would cover the vast majority of common cases, yet still provide
+   a little extra spice with switch types (REQUIRED, OPTIONAL, etc).
+
+   There are a few extra things I plan to add (see the 'Future Plans' above) but
+   I do not plan on this library ever becoming as feature rich as, say, Perl's
+   Getopt::Long module.
+
 == Warranty
    This package is provided "as is" and without any express or
    implied warranties, including, without limitation, the implied

data/test/tc_getopt_long.rb

@@ -0,0 +1,119 @@
+#######################################################
+# tc_getopt_long.rb
+#
+# Test suite for the getopt-long package.
+#######################################################
+base = File.basename(Dir.pwd)
+
+if base == "test" || base =~ /getopt/
+   Dir.chdir("..") if base == "test"
+   $LOAD_PATH.unshift(Dir.pwd + "/lib")
+   Dir.chdir("test") rescue nil
+end
+
+require "test/unit"
+require "getopt/long"
+include Getopt
+
+class TC_Getopt_Long < Test::Unit::TestCase
+   def setup
+      @opts = nil
+   end
+
+   def test_version
+      assert_equal("1.3.0", Long::VERSION)
+   end
+
+   def test_constants
+      assert_not_nil(BOOLEAN)
+      assert_not_nil(OPTIONAL)
+      assert_not_nil(REQUIRED)
+      assert_not_nil(INCREMENT)
+   end
+
+   def test_getopts_basic
+      assert_respond_to(Long, :getopts)
+      assert_nothing_raised{
+         Long.getopts(["--test"],["--help"],["--foo"])
+      }
+      assert_nothing_raised{
+         Long.getopts(["--test", "-x"],["--help", "-y"],["--foo", "-z"])
+      }
+      assert_nothing_raised{
+         Long.getopts(
+            ["--test", "-x", BOOLEAN],
+            ["--help", "-y", REQUIRED],
+            ["--foo",  "-z", OPTIONAL],
+            ["--more", "-m", INCREMENT]
+         )
+      }
+      assert_kind_of(Hash, Long.getopts("--test"))
+   end
+
+   def test_getopts_using_equals
+      ARGV.push("--foo=hello","-b","world")
+      assert_nothing_raised{
+         @opts = Long.getopts(
+            ["--foo", "-f", REQUIRED],
+            ["--bar", "-b", OPTIONAL]
+         )
+      }
+      assert_equal("hello", @opts["foo"])
+      assert_equal("hello", @opts["f"])
+      assert_equal("world", @opts["bar"])
+      assert_equal("world", @opts["b"])
+   end
+
+   def test_getopts_short_switch_squished
+      ARGV.push("-f", "hello", "-bworld")
+      assert_nothing_raised{
+         @opts = Long.getopts(
+            ["--foo", "-f", REQUIRED],
+            ["--bar", "-b", OPTIONAL]
+         )
+      }
+      assert_equal("hello", @opts["f"])
+      assert_equal("world", @opts["b"])
+   end
+
+   def test_getopts_increment_type
+      ARGV.push("-m","-m")
+      assert_nothing_raised{
+         @opts = Long.getopts(["--more", "-m", INCREMENT])
+      }
+      assert_equal(2, @opts["more"])
+      assert_equal(2, @opts["m"])
+   end
+
+   def test_switches_exist
+      ARGV.push("--verbose","--test","--foo")
+      assert_nothing_raised{ @opts = Long.getopts("--verbose --test --foo") }
+      assert_equal(true, @opts.has_key?("verbose"))
+      assert_equal(true, @opts.has_key?("test"))
+      assert_equal(true, @opts.has_key?("foo"))
+   end
+
+   def test_short_switch_synonyms
+      ARGV.push("--verbose","--test","--foo")
+      assert_nothing_raised{ @opts = Long.getopts("--verbose --test --foo") }
+      assert_equal(true, @opts.has_key?("v"))
+      assert_equal(true, @opts.has_key?("t"))
+      assert_equal(true, @opts.has_key?("f"))
+   end
+
+   def test_switches_with_required_arguments
+      ARGV.push("--foo","1","--bar","hello")
+      assert_nothing_raised{
+         @opts = Long.getopts(
+            ["--foo", "-f", REQUIRED],
+            ["--bar", "-b", REQUIRED]
+         )
+      }
+      assert_equal({"foo"=>"1", "bar"=>"hello", "f"=>"1", "b"=>"hello"}, @opts)
+   end
+
+   def teardown
+      @opts = nil
+      ARGV.clear
+   end
+end

data/test/tc_getopt_std.rb

@@ -18,7 +18,7 @@ include Getopt
 class TC_Getopt_Std < Test::Unit::TestCase
 
    def test_version
-      assert_equal("1.2.0", Std::VERSION)
+      assert_equal("1.3.0", Std::VERSION)
    end
 
    def test_getopts_basic

data/test/ts_all.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH.unshift(Dir.pwd)
+$LOAD_PATH.unshift(Dir.pwd + "/test")
+
+require "tc_getopt_std"
+require "tc_getopt_long"

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: getopt
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
-date: 2005-10-24 00:00:00 -06:00
+  version: 1.3.0
+date: 2005-11-04 00:00:00 -07:00
 summary: Getopt::Std for Ruby
 require_paths: 
   - lib
@@ -32,9 +32,11 @@ files:
   - CHANGES
   - MANIFEST
   - README
+  - test/tc_getopt_long.rb
   - test/tc_getopt_std.rb
+  - test/ts_all.rb
 test_files: 
-  - test/tc_getopt_std.rb
+  - test/ts_all.rb
 rdoc_options: []
 extra_rdoc_files: 
   - README