cooloptions 0.1.0 → 1.0.0

data/History.txt

@@ -1,3 +1,9 @@
+== 1.0.0 / 
+
+* Added test for short options specification.
+* Improved the documentation.
+* Re-vamped option specification completely.
+
 == 0.1.0 / 2006-11-30
 
 * Initial Release

data/README.txt

@@ -8,26 +8,64 @@ CoolOptions is a simple wrapper around optparse that provides less options and m
 
 == SYNOPSYS:
 
+=== Declaration:
+
   options = CoolOptions.parse!("[options] PROJECTNAME") do |o|
-    o.on :svk,              "[no-]svk",              "Use svk.",                              true
-    o.on :project_path,     "project-path PATH",     "Root of project workspaces.",           File.expand_path("~/svk")
-    o.on :repository,       "repository URL",        "Remote subversion repository."          
-    o.on :repository_path,  "repository-path PATH",  "Remote repository path.",               "/",       "l"
-    o.on :mirror_path,      "mirror-path SVKPATH",   "SVK mirror path.",                      "//"
-    o.on :local_path,       "local-path SVKPATH",    "SVK local path.",                       "//local", "t"
-    o.on :create_structure, "[no-]create-structure", "Create trunk/tags/branches structure.", true
-    o.on :finish,           "[no-]finish"          , "Prep and commit the new project.",      true
-    
+    o.on "repository URL",         "Remote subversion repository."          
+    o.on "svk",                    "Use svk.",                              true
+    o.on "project-path PATH",      "Root of project workspaces.",           File.expand_path("~/svk")
+    o.on "l)repository-path PATH", "Remote repository path.",               "/"
+    o.on "mirror-path SVKPATH",    "SVK mirror path.",                      "//"
+    o.on "local-pa(t)h SVKPATH",   "SVK local path.",                       "//local"
+    o.on "create-structure",       "Create trunk/tags/branches structure.", true
+    o.on "finish",                 "Prep and commit the new project.",      true
+
     o.after do |r|
       r.project_path = File.expand_path(r.project_path)
-      raise "Invalid path." unless File.exist?(r.project_path)
+      o.error("Invalid path.") unless File.exist?(r.project_path)
       r.project_name = ARGV.shift
+      o.error("Project name is required.") unless r.project_name
+      o.error("Project name is too funky.") unless /^\w+$/ =~ r.project_name
     end
   end
+  
+=== Usage:
+
+  $ ./new_rails_project --no-svk -r http://terralien.com/svn/terralien/ --no-finish
+  
+=== Result:
+  
+  p options.svk                 # => false
+  p options.project_path        # => '/Users/ntalbott/svk'
+  p options.repository          # => 'http://terralien.com/svn/terralien/'
+  p options.finish              # => false
+  p options.create_structure    # => true
+  p options.project_name        # => 'myproject'
+
+=== Also:
+
+  $ ./new_rails_project --help                                                               
+  Usage: t.rb [options] PROJECTNAME
+      -s, --[no-]svk                   Use svk.
+                                       Default is: true
+      -p, --project-path PATH          Root of project workspaces.
+                                       Default is: /Users/ntalbott/svk
+      -r, --repository URL             Remote subversion repository.
+      -l, --repository-path PATH       Remote repository path.
+                                       Default is: /
+      -m, --mirror-path SVKPATH        SVK mirror path.
+                                       Default is: //
+      -t, --local-path SVKPATH         SVK local path.
+                                       Default is: //local
+      -c, --[no-]create-structure      Create trunk/tags/branches structure.
+                                       Default is: true
+      -f, --[no-]finish                Prep and commit the new project.
+                                       Default is: true
+      -h, --help                       This help info.
 
 == REQUIREMENTS:
 
-optparse (included in Ruby stdlib)
+optparse & ostruct (included in Ruby standard library).
 
 == INSTALL:
 

data/Rakefile

@@ -5,7 +5,7 @@ require './lib/cooloptions.rb'
 Hoe.new('cooloptions', CoolOptions::VERSION) do |p|
   p.rubyforge_name = 'cooloptions'
   p.summary = p.description = 'CoolOptions is a simple wrapper around optparse that provides less options and more convenience.'
-  p.url = 'https://rubyforge.org/projects/cooloptions/'
+  p.url = 'http://cooloptions.rubyforge.org/'
   p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
   p.author = "Nathaniel Talbott"
   p.email = "nathaniel@terralien.com"

data/lib/cooloptions.rb

@@ -1,19 +1,30 @@
-# Copyright (c) 2006 Nathaniel Talbott and Terralien, Inc. All Rights Reserved.
-# Licensed under the RUBY license.
+# Copyright:: Copyright (c) 2006 Nathaniel Talbott and Terralien, Inc. All Rights Reserved.
+# License:: Licensed under the RUBY license.
 
 require 'optparse'
 require 'ostruct'
 
+# For a high-level overview of using CoolOptions, see README.txt.
+#
+# == Usage
+#
+#   :include:samples/literate.rb
+
 class CoolOptions
-  VERSION = '0.1.0'
+  VERSION = '1.0.0' #:nodoc:
 
   class Error < StandardError #:nodoc:
   end
 
-  def self.parse!(*args)
-    o = new
+  # Takes an optional banner and the arguments you want to parse (defaults to
+  # ARGV) and yields a new CoolOptions to the supplied block. You can then
+  # declare your options in the block using the #on method, and do post-
+  # processing using #after. When processing is done, an OpenStruct
+  # containing the parsed options is returned.
+  def self.parse!(banner="[options]", argv=ARGV) #:yields: cooloptions
+    o = new(banner)
     yield o
-    o.parse!(*args)
+    o.parse!(argv)
   rescue Error => e
     out.puts e.message
     o.help true
@@ -31,59 +42,75 @@ class CoolOptions
     @out = out
   end
   
-  def initialize
-    @options = []
+  attr_reader :parser, :result
+  
+  def initialize(banner) #:nodoc:
+    @parser = OptionParser.new
+    @parser.banner = "Usage: #{File.basename($0)} #{banner}"
+
+    @required = []
+    @result = {}
     @after = nil
   end
   
-  def on(key, long, message, default=nil, short=nil)
-    unless short
-      short = if /^\[/ =~ long
-        long.split(/\]/).last
-      else
-        long
-      end[0,1]
+  NO_DEFAULT = Object.new #:nodoc:
+  
+  # Called on cooloptions within the #parse! block to add options to parse on.
+  # Long is the long option itself, description is, well, the description, and
+  # default is the default value for the option, if any.
+  def on(long, description, default=NO_DEFAULT)
+    if /^(.)\)(.+)$/ =~ long
+      short, long = $1, $2
+    elsif /^(.*)\((.)\)(.*)$/ =~ long
+      short = $2
+      long = $1 + $2 + $3
     end
-    @options << [key, short, long, message, default]
+    short = long[0,1] unless short
+
+    key = long.split(/ /).first.gsub('-', '_').to_sym
+
+    unless long =~ / /
+      long = "[no-]#{long}"
+    end
+
+    args = ["-#{short}", "--#{long}", description]
+    if default == NO_DEFAULT
+      @required << key
+    else
+      @result[key] = default
+      args << "Default is: #{default}"
+    end
+
+    @parser.on(*args){|e| self.result[key] = e}
   end
   
-  def parse!(banner="[options]", argv=ARGV)
-    result = {}
-    required = []
-    OptionParser.new do |o|
-      @o = o
-      o.banner = "Usage: #{File.basename($0)} #{banner}"
+  def parse!(argv) #:nodoc:
+    @parser.on('-h', '--help', "This help info."){help}
+    @parser.parse!(argv)
+
+    @required.reject!{|e| @result.key?(e)}
+    error "Missing required options: #{@required.join(', ')}" unless @required.empty?
 
-      @options.each do |(key, short, long, message, default)|
-        args = ["-#{short}", "--#{long}", message]
-        if default.nil?
-          required << key
-        else
-          result[key] = default
-          args << "Default is: #{default}"
-        end
-        o.on(*args){|e| result[key] = e}
-      end
-      
-      o.on('-h', '--help', "This help info."){help}
-    end.parse!(argv)
-    required.reject!{|e| result.key?(e)}
-    error "Missing required options: #{required.join(', ')}" unless required.empty?
-    result = OpenStruct.new(result)
-    @after.call(result) if @after
-    result
+    r = OpenStruct.new(@result)
+    @after.call(r) if @after
+    r
   end
   
+  # If you want to throw an option parsing error, just call #error with a
+  # message and CoolOptions will bail out and display the help message.
   def error(message)
     raise Error, message, caller
   end
   
+  # CoolOptions only handles options parsing, and it only does rudimentary
+  # option validation. If you want to do more, #after is a convenient place do
+  # it, especially since the right thing will just happen if you call #error.
   def after(&after)
     @after = after
   end
   
-  def help(error=false)
-    out.puts @o
+  def help(error=false) #:nodoc:
+    out.puts @parser
     exit(error ? 1 : 0)
   end
 end

data/test/test_cooloptions.rb

@@ -20,10 +20,10 @@ class TestCoolOptions < Test::Unit::TestCase
 
   def test_should_handle_booleans
     r = parse!(%w(-a --no-b --c)) do |o|
-      o.on :a, '[no-]a', 'a', false
-      o.on :b, '[no-]b', 'b', true
-      o.on :c, '[no-]c', 'c', false
-      o.on :d, '[no-]d', 'd', true
+      o.on 'a', 'a', false
+      o.on 'b', 'b', true
+      o.on 'c', 'c', false
+      o.on 'd', 'd', true
     end
     
     assert r.a
@@ -34,8 +34,8 @@ class TestCoolOptions < Test::Unit::TestCase
   
   def test_should_handle_strings
     r = parse!(%w(-a b --c=d)) do |o|
-      o.on :a, 'a ARG', 'a'
-      o.on :c, 'c ARG', 'c'
+      o.on 'a ARG', 'a'
+      o.on 'c ARG', 'c'
     end
     
     assert_equal 'b', r.a
@@ -44,7 +44,7 @@ class TestCoolOptions < Test::Unit::TestCase
   
   def test_should_ignore_non_options
     r = CoolOptions.parse!('', argv=%w(ab -c de)) do |o|
-      o.on :c, '[no-]c', 'c'
+      o.on 'c', 'c'
     end
     
     assert r.c
@@ -54,7 +54,7 @@ class TestCoolOptions < Test::Unit::TestCase
   def test_should_call_after
     called = false
     r = parse!(%w(-a)) do |o|
-      o.on :a, '[no-]a', 'a'
+      o.on 'a', 'a'
       o.after{|r| assert r.a; called=true}
     end
     assert called
@@ -71,7 +71,7 @@ class TestCoolOptions < Test::Unit::TestCase
   def test_should_output_help
     begin
       r = CoolOptions.parse!('details', %w(--help)) do |o|
-        o.on :a, '[no-]a', 'aa'
+        o.on 'a', 'aa'
       end
     rescue SystemExit
       rescued = true
@@ -88,8 +88,39 @@ EOH
   def test_should_require_options_with_no_default
     assert_raise(SystemExit) do
       CoolOptions.parse!([]) do |o|
-        o.on :a, 'a A', 'a'
+        o.on 'a A', 'a'
       end
     end
+    assert_nothing_raised do
+      CoolOptions.parse!([]) do |o|
+        o.on 'a A', 'a', nil
+      end
+    end
+  end
+  
+  def test_should_allow_specification_of_alternate_short_form
+    r = parse!(%w(-a -b c -c d)) do |o|
+      o.on 'a', 'a', false
+      o.on 'b)aa VALUE', 'aa'
+      o.on 'b(c) VALUE', 'bc'
+    end
+    assert_equal true, r.a
+    assert_equal 'c', r.aa
+    assert_equal 'd', r.bc
+  end
+  
+  def test_should_replace_dashes
+    r = parse!(%w(--a-b c)) do |o|
+      o.on 'a-b A', 'a'
+    end
+    assert_equal 'c', r.a_b
+  end
+  
+  def test_should_provide_access_to_the_parser
+    called = false
+    r = parse!(%w(-d)) do |o|
+      o.parser.on('-d'){called = true}
+    end
+    assert called
   end
 end

metadata

@@ -3,13 +3,13 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: cooloptions
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-12-07 00:00:00 -05:00
+  version: 1.0.0
+date: 2006-12-09 00:00:00 -05:00
 summary: CoolOptions is a simple wrapper around optparse that provides less options and more convenience.
 require_paths: 
 - lib
 email: nathaniel@terralien.com
-homepage: https://rubyforge.org/projects/cooloptions/
+homepage: http://cooloptions.rubyforge.org/
 rubyforge_project: cooloptions
 description: CoolOptions is a simple wrapper around optparse that provides less options and more convenience.
 autorequire: