delano-drydock 0.3.3 → 0.4.0

data/CHANGES.txt

@@ -1,15 +1,30 @@
 DRYDOCK, CHANGES
 
-TODO:
-* Fix '-' '_' ambiguity for option names
-* Calls valid? method (if present) before calling command block.
+#### 0.4 (2009-02-28) ###############################
+
+* FIX: Bug, "interning empty string" error when bare "option" is used
+* NEW: Calls valid? method (if present) before calling command block.
+* NEW: "capture" method. Auto capture STDOUT to obj.stdout etc...
+* NEW: Automatically calls init and print_header methods before the command
+       and print_footer after the command (if available)
+* NEW: Tries to call obj.command if available when no block is supplied
+* NEW: "show_commands" command built-in. Displays commands with descriptions
+* NEW: A default usage help msg for every command: "#{$0} command-name"
+* NEW: "usage" work multiple times for the same command. 
+* NEW: "desc" method for per command descriptions
+* CHANGE: options are now stored as obj.option.name instead of obj.name
+* CHANGE: global options are now stored as obj.globals.name
+* CHANGE: removed auto importing methods
+    OLD: require 'drydock'
+    NEW: require 'drydock'
+         extend Drydock
 
 
 #### 0.3.3 (2009-02-14) ###############################
 
 * NEW: init method hook for subclasses of Drydock::Command
 * UPDATED: Rdocs
-
+* CHANGE: added method command_aliaz to mirror aliaz_command
 
 #### 0.3 (2009-02-05) ###############################
 

data/README.rdoc

@@ -1,4 +1,4 @@
-= Drydock - v0.3
+= Drydock - v0.4
 
 Inspired by github-gem and bmizerany-frylock.
 
@@ -31,40 +31,49 @@ See bin/example for more.
   # variables defined here will be available to all commands.
   end
 
-  command :welcome do
-  # Example: ruby bin/example
-    
-    puts "Welcome to Drydock. You have the following commands:"
-    
-    # The commands method returns a hash of Drydock::Command objects
-    puts commands.keys.inject([]) { |list, command| list << command.to_s }.sort.join(', ')
-  end
+  desc "A friendly welcome to the Drydock"
+	command :welcome do
+	  puts "Welcome to Drydock."
+	  puts "For available commands:"
+	  puts "#{$0} show-commands"
+	end
+	
+  
+	usage "USAGE: #{$0} laugh [-f]"
+	desc "The captain commands his crew to laugh"
+	option :f, :faster, "A boolean value. Go even faster!"
+	command :laugh do |obj|
+	# +obj+ is an instance of Drydock::Command. The options you define are available
+	# via obj.option.name 
+
+	  answer = !obj.option.faster ? "Sort of" : "Yes! I'm literally laughing as fast as possible."
+
+	  puts "Captain Stubing: Are you laughing?"
+	  puts "Dr. Bricker: " << answer
+	end
+	
   
-  usage "Example: #{$0} laugh [-f]"
-  option :f, :faster, "A boolean value. Go even faster!"
-  command :laugh do |obj|
-  # +obj+ is an instance of Drydock::Command. The options you define are available
-  # via accessors in this object. 
+	class JohnWestSmokedOysters < Drydock::Command 
+	  # You can write your own command classes by inheriting from Drydock::Command
+	  # and referencing it in the command definition.
+	  def ahoy!; p "matey"; end
+	end
 
-    answer = !obj.faster ? "Sort of" : "Yes! I'm literally laughing as fast as possible."
+	desc "Do something with John West's Smoked Oysters"
+	command :oysters => JohnWestSmokedOysters do |obj|
+	  p obj  # => #<JohnWestSmokedOysters:0x42179c ... >
+	end
 
-    puts "Captain Stubing: Are you laughing?"
-    puts "Dr. Bricker: " << answer
-  end
-  
-  class JohnWestSmokedOysters < Drydock::Command; end;
-  # You can write your own command classes by inheriting from Drydock::Command
-  # and referencing it in the command definition.
+	desc "My way of saying hello!"
+	command :ahoy! => JohnWestSmokedOysters
+	# If you don't provide a block, Drydock will call JohnWestSmokedOysters#ahoy!
 
-  command :oysters => JohnWestSmokedOysters do |obj|
-    p obj  # => #<JohnWestSmokedOysters:0x42179c ... >
-  end
   
 == More Information
 
-* http://github.com/delano/drydock
-* http://drydock.rubyforge.org/ (rdocs)
-* http://www.youtube.com/watch?v=m_wFEB4Oxlo
+* GitHub[http://github.com/delano/drydock]
+* RDocs[http://drydock.rubyforge.org/]
+* Inspiration[http://www.youtube.com/watch?v=m_wFEB4Oxlo]
 
 == Credits
 

data/bin/example

@@ -13,8 +13,14 @@
 $:.unshift File.expand_path(File.join(File.dirname(__FILE__), '..')), 'lib'
 
 require 'drydock'
+extend Drydock     # Tell Drydock you want its methods! 
 
-default :welcome
+
+default :welcome   # The welcome command will be run if no command is given
+capture :stderr    # Drydock will capture STDERR and keep it in the hold.
+                   # You can use this to suppress errors. 
+
+project "Drydock Example"  # An optional name
 
 before do
 # You can execute a block before the requests command is executed. Instance
@@ -25,30 +31,29 @@ after do
 # And this will be called after the command. 
 end
 
+desc "A friendly welcome to the Drydock"
 command :welcome do
-# Example: ruby bin/example
-  
-  puts "Welcome to Drydock. You have the following commands:"
-  
-  # The commands method returns a hash of Drydock::Command objects
-  puts commands.keys.inject([]) { |list, command| list << command.to_s }.sort.join(', ')
+  puts "Welcome to Drydock."
+  puts "For available commands:"
+  puts "#{$0} show-commands"
 end
 
-usage "Example: #{$0} laugh [-f]"
+usage "USAGE: #{$0} laugh [-f]"
+desc "The captain commands his crew to laugh"
 option :f, :faster, "A boolean value. Go even faster!"
 command :laugh do |obj|
 # +obj+ is an instance of Drydock::Command. The options you define are available
-# via accessors in this object. 
+# via obj.option.name 
 
-  answer = !obj.faster ? "Sort of" : "Yes! I'm literally laughing as fast as possible."
+  answer = !obj.option.faster ? "Sort of" : "Yes! I'm literally laughing as fast as possible."
 
   puts "Captain Stubing: Are you laughing?"
   puts "Dr. Bricker: " << answer
 end
 
 global_usage "USAGE: #{File.basename($0)} [global options] command [command options]"
-global_option :s, :seconds, "Display values in seconds"
-global_option :v, :verbose, "Verbosity level (i.e. -vvv is greater than -v)" do |v|
+global :s, :seconds, "Display values in seconds"
+global :v, :verbose, "Verbosity level (i.e. -vvv is greater than -v)" do |v|
 # Use instance variables to maintain values between option blocks. 
 # This will increment for every -v found (i.e. -vvv)
   @val ||= 0
@@ -57,17 +62,19 @@ end
 
 
 usage "#{$0} [-s] [-vv] date"
+desc "Display the current date"
 command :date do |obj, argv| 
 # +argv+ is an array containing the unnamed arguments
   require 'time'
   now = Time.now
-  puts "(Not verbose enough. Try adding a -v.)" if (obj.verbose || 0) == 1
-  puts "More verbosely, the date is now: " if (obj.verbose || 0) >= 2
-  puts (obj.seconds) ? now.to_i : now.to_s
+  puts "(Not verbose enough. Try adding a -v.)" if (obj.global.verbose || 0) == 1
+  puts "More verbosely, the date is now: " if (obj.global.verbose || 0) >= 2
+  puts (obj.global.seconds) ? now.to_i : now.to_s
 end
 
-usage "#{$0} rogue"
+
 ignore :options
+desc "This command ignores options"
 command :rogue do |obj, argv|
 # You can use ignore :options to tell Drydock to not process the 
 # command-specific options. 
@@ -79,14 +86,26 @@ command :rogue do |obj, argv|
   end
 end
 
-class JohnWestSmokedOysters < Drydock::Command; end;
-# You can write your own command classes by inheriting from Drydock::Command
-# and referencing it in the command definition.
+class JohnWestSmokedOysters < Drydock::Command 
+  # You can write your own command classes by inheriting from Drydock::Command
+  # and referencing it in the command definition.
+  def ahoy!; p "matey"; end
+end
 
+desc "Do something with John West's Smoked Oysters"
 command :oysters => JohnWestSmokedOysters do |obj|
   p obj  # => #<JohnWestSmokedOysters:0x42179c ... >
 end
 
+desc "My way of saying hello!"
+command :ahoy! => JohnWestSmokedOysters
+# If you don't provide a block, Drydock will call JohnWestSmokedOysters#ahoy!
+
+
+
+usage 'ruby bin/example process -c -d " " -t 15 http://solutious.com/'
+usage 'echo "http://solutious.com/" | ruby bin/example process -c -d " " -t 15'
+desc "Check for broken URIs"
 option :c, :check, "Check response codes for each URI"
 option :d, :delim, String, "Output delimiter"
 option :t, :timeout, Float, "Timeout value for HTTP request" do |v|
@@ -95,9 +114,7 @@ option :t, :timeout, Float, "Timeout value for HTTP request" do |v|
   v = 10 if (v > 10)
   v
 end
-
-usage 'echo "http://github.com/" | ruby bin/example process -c -d " " -t 15 http://solutious.com/'
-command :processuri do |obj, argv, stdin|
+command :uri do |obj, argv, stdin|
 # +cmd+ is the string used to evoke this command. Useful with alias_command (see below).
 # +stdin+ is either an IO object or a custom object defined with a stdin block (see below)
 
@@ -106,8 +123,8 @@ command :processuri do |obj, argv, stdin|
   require 'timeout'
   
   uris = [stdin, argv].flatten        # Combine the argv and stdin arrays
-  delim = obj.delim || ','
-  timeout = obj.timeout || 5
+  delim = obj.option.delim || ','
+  timeout = obj.option.timeout || 5
   code = :notchecked                  # The default code when :check is false
   
   if uris.empty?
@@ -117,12 +134,11 @@ command :processuri do |obj, argv, stdin|
   end
   
   uris.each_with_index do |uri, index|
-    code = response_code(uri, timeout) if (obj.check)
+    code = response_code(uri, timeout) if (obj.option.check)
     puts [index+1, uri, code].join(delim)
   end
 end
-alias_command :checkuri, :processuri
-
+alias_command :checkuri, :uri
 
 
 

data/drydock.gemspec

@@ -1,6 +1,6 @@
 @spec = Gem::Specification.new do |s|
   s.name = %q{drydock}
-  s.version = "0.3.3"
+  s.version = "0.4.0"
   s.specification_version = 1 if s.respond_to? :specification_version=
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
@@ -16,30 +16,6 @@
     bin/example
     drydock.gemspec
     lib/drydock.rb
-    test/command_test.rb
-    doc
-    doc/classes
-    doc/classes/Drydock
-    doc/classes/Drydock/Command.html
-    doc/classes/Drydock/InvalidArgument.html
-    doc/classes/Drydock/MissingArgument.html
-    doc/classes/Drydock/NoCommandsDefined.html
-    doc/classes/Drydock/UnknownCommand.html
-    doc/classes/Drydock.html
-    doc/created.rid
-    doc/files
-    doc/files/bin
-    doc/files/bin/example.html
-    doc/files/CHANGES_txt.html
-    doc/files/lib
-    doc/files/lib/drydock_rb.html
-    doc/files/LICENSE_txt.html
-    doc/files/README_rdoc.html
-    doc/fr_class_index.html
-    doc/fr_file_index.html
-    doc/fr_method_index.html
-    doc/index.html
-    doc/rdoc-style.css
   )
   s.has_rdoc = true
   s.homepage = %q{http://github.com/delano/drydock}

data/lib/drydock.rb

@@ -1,8 +1,7 @@
 require 'optparse'
 require 'ostruct'
+require 'stringio'
 
-#
-#
 module Drydock
   # The base class for all command objects. There is an instance of this class
   # for every command defined. Global and command-specific options are added
@@ -10,11 +9,11 @@ module Drydock
   # 
   # i.e. "example -v date -f yaml"
   #
-  #     global_option :v, :verbose, "I want mooooore!"
+  #     global :v, :verbose, "I want mooooore!"
   #     option :f, :format, String, "Long date format"
   #     command :date do |obj|
-  #         puts obj.verbose  #=> true
-  #         puts obj.format  #=> "yaml"
+  #         puts obj.global.verbose  #=> true
+  #         puts obj.option.format  #=> "yaml"
   #     end
   #
   # You can inherit from this class to create your own: EatFood < Drydock::Command.
@@ -23,7 +22,22 @@ module Drydock
   #     command :eat => EatFood do |obj|; ...; end
   #
   class Command
-    attr_reader :cmd, :alias
+    VERSION = 0.4
+      # The canonical name of the command (the one used in the command definition). If you 
+      # inherit from this class and add a method named +cmd+, you can leave omit the block
+      # in the command definition. That method will be called instead. See bin/examples.
+    attr_reader :cmd
+      # The name used to evoke this command (it's either the canonical name or the alias used).
+    attr_reader :alias
+      # A friendly description of the command. 
+    attr_accessor :desc
+      # The block that will be executed when this command is evoked. If the block is nil
+      # it will check if there is a method named +cmd+. If so, that will be executed.
+    attr_reader :b
+      # An OpenStruct object containing the command options specified at run-time.
+    attr_reader :option
+      # An OpenStruct object containing the global options specified at run-time.
+    attr_reader :global
     
     # The default constructor sets the short name of the command
     # and stores a reference to the block (if supplied).
@@ -35,6 +49,16 @@ module Drydock
     def initialize(cmd, &b)
       @cmd = (cmd.kind_of?(Symbol)) ? cmd : cmd.to_sym
       @b = b
+      @option = OpenStruct.new
+      @global = OpenStruct.new
+      
+      @global.verbose = 0
+      @global.quiet = false
+    end
+    
+    # Returns the command name (not the alias)
+    def name
+      @cmd
     end
     
     # Execute the block.
@@ -50,14 +74,55 @@ module Drydock
     # +options+ a hash of the command-specific options specific on the command-line.
     def call(cmd_str=nil, argv=[], stdin=[], global_options={}, options={})
       @alias = cmd_str.nil? ? @cmd : cmd_str
-      global_options.merge(options).each_pair do |n,v|
-        self.send("#{n}=", v)
+
+      global_options.each_pair do |n,v|
+        self.global.send("#{n}=", v)    # Populate the object's globals
       end
       
-      self.init if respond_to? :init
+      options.each_pair do |n,v|
+        self.option.send("#{n}=", v)    # ... and also the command options
+      end
+      
+      self.init         if self.respond_to? :init     # Must be called first!
+      self.print_header if respond_to? :print_header
+      self.valid?       if respond_to? :'valid?'
       
-      block_args = [self, argv, stdin] # TODO: review order
-      @b.call(*block_args[0..(@b.arity-1)]) # send only as many args as defined
+      block_args = [self, argv, stdin]
+      
+      if @b 
+        @b.call(*block_args[0..(@b.arity-1)]) # send only as many args as defined
+      elsif self.respond_to? @cmd.to_sym
+        self.send(@cmd)
+      else
+        raise "The command #{@alias} has no block and #{self.class} has no #{@cmd} method!"
+      end
+      
+      self.print_footer if respond_to? :print_footer
+      
+    end
+    
+    # Print the list of available commands to STDOUT. This is used as the 
+    # "default" command unless another default commands is supplied. You 
+    # can also write your own Drydock::Command#show_commands to override
+    # this default behaviour. 
+    def show_commands
+      project = " for #{Drydock.project}" if Drydock.project?
+      puts "Available commands#{project}:", ""
+      Drydock.commands.keys.sort{ |a,b| a.to_s <=> b.to_s }.each do |cmd|
+        msg = Drydock.commands[cmd].desc
+        
+        # Out to sea
+        unless cmd === Drydock.commands[cmd].cmd
+          msg = "See: #{Drydock.decanonize(Drydock.commands[cmd].cmd)} (this is an alias)" 
+        end
+        
+        puts " %16s: %s" % [Drydock.decanonize(cmd), msg]
+      end
+
+      puts 
+      puts "%6s: %s" % ["Try", "#{$0} -h"] 
+      puts "%6s  %s" % ["", "#{$0} COMMAND -h"]
+      puts
     end
     
     # The name of the command
@@ -103,34 +168,52 @@ end
 module Drydock
   extend self
   
-  VERSION = 0.3
+  VERSION = 0.4
   
  private
+  # Disabled. We're going basic, using a module and include/extend. 
   # Stolen from Sinatra!
-  def delegate(*args)
-    args.each do |m|
-      eval(<<-end_eval, binding, "(__Drydock__)", __LINE__)
-        def #{m}(*args, &b)
-          Drydock.#{m}(*args, &b)
-        end
-      end_eval
-    end
-  end
+  #def delegate(*args)
+  #  args.each do |m|
+  #    eval(<<-end_eval, binding, "(__Drydock__)", __LINE__)
+  #      def #{m}(*args, &b)
+  #        Drydock.#{m}(*args, &b)
+  #      end
+  #    end_eval
+  #  end
+  #end
+  #
+  #delegate :before, :after, :alias_command, :desc
+  #delegate :global_option, :global_usage, :usage, :commands, :command
+  #delegate :debug, :option, :stdin, :default, :ignore, :command_alias
   
-  delegate :before, :after, :alias_command, :commands
-  delegate :global_option, :global_usage, :usage, :command
-  delegate :debug, :option, :stdin, :default, :ignore, :command_alias
+  @@project = nil
   
   @@debug = false
   @@has_run = false
   @@run = true
+  
+  @@global_opts_parser = OptionParser.new
+  @@global_option_names = []
+
+  @@command_opts_parser = []
+  @@command_option_names = []
+  
   @@default_command = nil
   
+  @@commands = {}
+  @@command_descriptions = []
+  @@command_index = 0
+  @@command_index_map = {}
+  
+  @@capture = nil     # contains one of :stdout, :stderr
+  @@captured = nil
+  
  public
   # Enable or disable debug output.
   #
-  #    debug :on
-  #    debug :off
+  #     debug :on
+  #     debug :off
   #
   # Calling without :on or :off will toggle the value. 
   #
@@ -142,17 +225,44 @@ module Drydock
       @@debug = (!@@debug)
     end
   end
+  
   # Returns true if debug output is enabled. 
   def debug?
     @@debug
   end
   
-  # Define a default command. 
+  # The project of the script. This is currently only used when printing
+  # list of commands (see: Drydock::Command#show_commands). It may be 
+  # used elsewhere in the future. 
+  def project(txt=nil)
+    return @@project unless txt
+    @@project = txt
+  end
+  
+  # Has the project been set?
+  def project?
+    (defined?(@@project) && !@@project.nil?)
+  end
+  
+  # Define a default command. You can specify a command name that has 
+  # been or will be defined in your script:
   #
   #     default :task
   #
-  def default(cmd)
-    @@default_command = canonize(cmd)
+  # Or you can supply a block which will be used as the default command:
+  #
+  #     default do |obj|            # This command will be named "default"
+  #       # ...
+  #     end
+  #
+  #     default :hullinspector do   # This one will b named "hullinspector"
+  #       # ...
+  #     end
+  #
+  def default(cmd=nil, &b)
+    raise "Calling default requires a command name or a block" unless cmd || b
+    # Creates the command and returns the name or just stores given name
+    @@default_command = (b) ? command(cmd || :default, &b).cmd : canonize(cmd)
   end
   
   # Define a block for processing STDIN before the command is called. 
@@ -180,30 +290,26 @@ module Drydock
   # Define the default global usage banner. This is displayed
   # with "script -h". 
   def global_usage(msg)
-    @@global_options ||= OpenStruct.new
-    global_opts_parser.banner = "USAGE: #{msg}"
+    @@global_opts_parser.banner = "USAGE: #{msg}"
   end
   
   # Define a command-specific usage banner. This is displayed
   # with "script command -h"
   def usage(msg)
-    get_current_option_parser.banner = "USAGE: #{msg}"
+    # The default value given by OptionParser starts with "Usage". That's how
+    # we know we can clear it. 
+    get_current_option_parser.banner = "" if get_current_option_parser.banner =~ /^Usage:/
+    get_current_option_parser.banner << "USAGE: #{msg}" << $/
   end
   
-  # Grab the options parser for the current command or create it if it doesn't exist.
-  def get_current_option_parser
-    @@command_opts_parser ||= []
-    @@command_index ||= 0
-    (@@command_opts_parser[@@command_index] ||= OptionParser.new)
-  end
   
   # Tell the Drydock parser to ignore something. 
   # Drydock will currently only listen to you if you tell it to "ignore :options", 
   # otherwise it will ignore you!
   # 
   # +what+ the thing to ignore. When it equals :options Drydock will not parse
-  # the command-specific arguments. It will pass the Command object the list of
-  # arguments. This is useful when you want to parse the arguments in some a way
+  # the command-specific arguments. It will pass the arguments directly to the
+  # Command object. This is useful when you want to parse the arguments in some a way
   # that's too crazy, dangerous for Drydock to handle automatically.  
   def ignore(what=:nothing)
     @@command_opts_parser[@@command_index] = :ignore if what == :options || what == :all
@@ -211,25 +317,38 @@ module Drydock
   
   # Define a global option. See +option+ for more info. 
   def global_option(*args, &b)
-    args.unshift(global_opts_parser)
-    global_option_names << option_parser(args, &b)
+    args.unshift(@@global_opts_parser)
+    @@global_option_names << option_parser(args, &b)
   end
+  alias :global :global_option
   
   # Define a command-specific option. 
   # 
   # +args+ is passed directly to OptionParser.on so it can contain anything
-  # that's valid to that method. Some examples:
-  # [:h, :help, "Displays this message"]
-  # [:m, :max, Integer, "Maximum threshold"]
-  # ['-l x,y,z', '--lang=x,y,z', Array, "Requested languages"]
-  # If a class is included, it will tell OptionParser to expect a value 
-  # otherwise it assumes a boolean value.
+  # that's valid to that method. If a class is included, it will tell 
+  # OptionParser to expect a value otherwise it assumes a boolean value. 
+  # Some examples:
+  #
+  #     option :h, :help, "Displays this message"
+  #     option '-l x,y,z', '--lang=x,y,z', Array, "Requested languages"
+  #
+  #     You can also supply a block to fiddle with the values. The final 
+  #     value becomes the option's value:
+  #
+  #     option :m, :max, Integer, "Maximum threshold" do |v|
+  #       v = 100 if v > 100
+  #       v
+  #     end
   #
   # All calls to +option+ must come before the command they're associated
   # to. Example:
   # 
-  #     option :l, :longname, String, "Description" do; ...; end
-  #     command :task do |obj|; ...; end
+  #     option :t, :tasty,          "A boolean switch"
+  #     option     :reason, String, "Requires a parameter"
+  #     command :task do |obj|; 
+  #       obj.options.tasty       # => true
+  #       obj.options.reason      # => I made the sandwich!
+  #     end
   #
   # When calling your script with a specific command-line option, the value
   # is available via obj.longname inside the command block. 
@@ -239,6 +358,9 @@ module Drydock
     current_command_option_names << option_parser(args, &b)
   end
   
+
+  
+  
   # Define a command. 
   # 
   #     command :task do
@@ -253,20 +375,27 @@ module Drydock
   #     end
   #
   def command(*cmds, &b)
-    @@command_index ||= 0
-    @@command_opts_parser ||= []
-    @@command_option_names ||= []
-    cmds.each do |cmd| 
-      if cmd.is_a? Hash
-        c = cmd.values.first.new(cmd.keys.first, &b)
-      else
-        c = Drydock::Command.new(cmd, &b)
-      end
-      commands[c.cmd] = c
-      command_index_map[c.cmd] = @@command_index
-      @@command_index += 1
+    cmd = cmds.first
+    if cmd.is_a? Hash
+      c = cmd.values.first.new(cmd.keys.first, &b)
+    else
+      c = Drydock::Command.new(cmd, &b)
     end
     
+    @@command_descriptions[@@command_index] ||= ""
+    
+    c.desc = @@command_descriptions[@@command_index]
+    
+    # Default Usage Banner. 
+    # Without this, there's no help displayed for the command. 
+    option_parser = get_option_parser(@@command_index)
+    usage "#{$0} #{c.cmd}" if option_parser.is_a?(OptionParser) && option_parser.banner !~ /^USAGE/
+    
+    @@commands[c.cmd] = c
+    @@command_index_map[c.cmd] = @@command_index
+    @@command_index += 1 # This will point to the next command
+    
+    c  # Return the Command object
   end
   
   # Used to create an alias to a defined command. 
@@ -284,13 +413,32 @@ module Drydock
   # command name that was used via obj.alias. 
   def alias_command(aliaz, cmd)
     return unless commands.has_key? cmd
-    @@commands[aliaz] = commands[cmd]
+    commands[canonize(aliaz)] = commands[cmd]
   end
-  alias :command_alias :alias_command
   
-  # An array of the currently defined Drydock::Command objects
+  # Identical to +alias_command+ with reversed arguments. 
+  # For whatever reason I forget the order so Drydock supports both. 
+  # Tip: the argument order matches the method name. 
+  def command_alias(cmd, aliaz)
+    return unless commands.has_key? cmd
+    commands[canonize(aliaz)] = commands[cmd]
+  end
+  
+  # A hash of the currently defined Drydock::Command objects
   def commands
-    @@commands ||= {}
+    @@commands
+  end
+  
+  # An array of the currently defined commands names
+  def command_names
+    @@commands.keys.collect { |cmd| decanonize(cmd); }
+  end
+  
+  # Provide a description for a command
+  def desc(txt)
+    @@command_descriptions += [txt]
+    return if get_current_option_parser.is_a?(Symbol)
+    get_current_option_parser.on "ABOUT: #{txt}"
   end
   
   # Returns true if automatic execution is enabled. 
@@ -318,7 +466,7 @@ module Drydock
     return if has_run?
     @@has_run = true
     raise NoCommandsDefined.new if commands.empty?
-    @@global_options, cmd_name, @@command_options, argv = process_arguments(argv)
+    global_options, cmd_name, command_options, argv = process_arguments(argv)
     
     cmd_name ||= default_command
     
@@ -327,7 +475,9 @@ module Drydock
     stdin = (defined? @@stdin_block) ? @@stdin_block.call(stdin, []) : stdin
     @@before_block.call if defined? @@before_block
     
-    call_command(cmd_name, argv, stdin)
+    command_portion = lambda { call_command(cmd_name, argv, stdin, global_options, command_options) }
+
+    capture? ? (@@captured = capture_io(@@capture, &command_portion)) : command_portion.call
     
     @@after_block.call if defined? @@after_block
     
@@ -337,33 +487,85 @@ module Drydock
     raise Drydock::MissingArgument.new(ex.args)
   end
   
- private 
+  def capture(io)
+    @@capture = io
+  end
   
-  # Executes the block associated to +cmd+
-  def call_command(cmd, argv=[], stdin=nil)
-    return unless command?(cmd)
-    get_command(cmd).call(cmd, argv, stdin, @@global_options || {}, @@command_options || {})
+  def captured
+    @@captured
   end
   
-  # Returns the Drydock::Command object with the name +cmd+
-  def get_command(cmd)
-    return unless command?(cmd)
-    @@commands[canonize(cmd)]
-  end 
+  def capture?
+    !@@capture.nil?
+  end
+  
+  # Grab the options parser for the current command or create it if it doesn't exist.
+  # Returns an instance of OptionParser.
+  def get_current_option_parser
+    (@@command_opts_parser[@@command_index] ||= OptionParser.new)
+  end
+  
+  # Grabs the options parser for the given command. 
+  # +arg+ can be an index or command name.
+  # Returns an instance of OptionParser.
+  def get_option_parser(arg)
+    index = arg.is_a?(String) ? get_command_index(arg) : arg
+    (@@command_opts_parser[index] ||= OptionParser.new)
+  end
   
   # Returns true if a command with the name +cmd+ has been defined. 
   def command?(cmd)
     name = canonize(cmd)
-    (@@commands || {}).has_key? name
+    @@commands.has_key? name
   end
   
-  # Canonizes a string to the symbol format for command names
+  # Canonizes a string (+cmd+) to the symbol for command names
+  # '-' is replaced with '_'
   def canonize(cmd)
     return unless cmd
     return cmd if cmd.kind_of?(Symbol)
-    cmd.tr('-', '_').to_sym
+    cmd.to_s.tr('-', '_').to_sym
+  end
+  
+  # Returns a string version of +cmd+, decanonized.
+  # Lowercase, '_' is replaced with '-'
+  def decanonize(cmd)
+    return unless cmd
+    cmd.to_s.tr('_', '-')
+  end
+  
+  # Capture STDOUT or STDERR to prevent it from being printed. 
+  #
+  #    capture(:stdout) do
+  #      ...
+  #    end
+  #
+  def capture_io(stream)
+    raise "We can only capture STDOUT or STDERR" unless stream == :stdout || stream == :stderr
+    begin
+      eval "$#{stream} = StringIO.new"
+      yield
+      eval("$#{stream}").rewind                  # Otherwise we'll get nil 
+      result = eval("$#{stream}").read
+    ensure
+      eval "$#{stream} = #{stream.to_s.upcase}"  # Put it back!
+    end
+  end
+  
+ private 
+  
+  # Executes the block associated to +cmd+
+  def call_command(cmd, argv=[], stdin=nil, global_options={}, command_options={})
+    return unless command?(cmd)
+    get_command(cmd).call(cmd, argv, stdin, global_options || {}, command_options || {})
   end
   
+  # Returns the Drydock::Command object with the name +cmd+
+  def get_command(cmd)
+    return unless command?(cmd)
+    @@commands[canonize(cmd)]
+  end 
+  
   # Processes calls to option and global_option. Symbols are converted into 
   # OptionParser style strings (:h and :help become '-h' and '--help'). 
   def option_parser(args=[], &b)
@@ -405,14 +607,13 @@ module Drydock
     global_options = command_options = {}
     cmd = nil     
     
-    global_options = global_opts_parser.getopts(argv)
-          
+    global_options = @@global_opts_parser.getopts(argv)
     cmd_name = (argv.empty?) ? @@default_command : argv.shift
     raise UnknownCommand.new(cmd_name) unless command?(cmd_name)
     
     cmd = get_command(cmd_name) 
     
-    command_parser = @@command_opts_parser[get_command_index(cmd_name)]
+    command_parser = @@command_opts_parser[get_command_index(cmd.cmd)]
     command_options = {}
     
     # We only need to parse the options out of the arguments when
@@ -422,59 +623,47 @@ module Drydock
       command_options = command_parser.getopts(argv)
     end
     
+    # TODO: Remove this chunk for method creation. We now use OpenStruct. 
     # Add accessors to the Drydock::Command object 
     # for the global and command specific options
-    [global_option_names, (command_option_names[get_command_index(cmd_name)] || [])].flatten.each do |n|
-      unless cmd.respond_to?(n)
-        cmd.class.send(:define_method, n) do
-          instance_variable_get("@#{n}")
-        end
-      end
-      unless cmd.respond_to?("#{n}=")
-        cmd.class.send(:define_method, "#{n}=") do |val|
-          instance_variable_set("@#{n}", val)
-        end
-      end
-    end
+    #[global_option_names, (command_option_names[get_command_index(cmd_name)] || [])].flatten.each do |n|
+    #  unless cmd.respond_to?(n)
+    #    cmd.class.send(:define_method, n) do
+    #      instance_variable_get("@#{n}")
+    #    end
+    #  end
+    #  unless cmd.respond_to?("#{n}=")
+    #    cmd.class.send(:define_method, "#{n}=") do |val|
+    #      instance_variable_set("@#{n}", val)
+    #    end
+    #  end
+    #end
     
     [global_options, cmd_name, command_options, argv]
   end
   
-  def global_option_names
-    @@global_option_names ||= []
-  end
-  
+
   # Grab the current list of command-specific option names. This is a list of the
   # long names. 
   def current_command_option_names
-    @@command_option_names ||= []
-    @@command_index ||= 0
     (@@command_option_names[@@command_index] ||= [])
   end
   
-  def command_index_map
-    @@command_index_map ||= {}
-  end
-  
   def get_command_index(cmd)
-    command_index_map[canonize(cmd)] || -1
-  end
-  
-  def command_option_names
-    @@command_option_names ||= []
-  end
-  
-  def global_opts_parser
-    @@global_opts_parser ||= OptionParser.new
+    @@command_index_map[canonize(cmd)] || -1
   end
   
-  def default_command
-    @@default_command ||= nil
-  end
+  #
+  # These are the "reel" defaults
+  #
+  @@global_opts_parser.banner = "USAGE: #{$0} [global options] COMMAND [command options]"
+  @@global_opts_parser.on "  TRY: #{$0} show-commands #{$/}"
+  @@command_descriptions = ["Display available commands with descriptions"]
+  @@default_command = Drydock.command(:show_commands).cmd
   
 end
 
-include Drydock
+
 
 trap ("SIGINT") do
   puts "#{$/}Exiting..."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: delano-drydock
 version: !ruby/object:Gem::Version 
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors: 
 - Delano Mandelbaum
@@ -31,30 +31,6 @@ files:
 - bin/example
 - drydock.gemspec
 - lib/drydock.rb
-- test/command_test.rb
-- doc
-- doc/classes
-- doc/classes/Drydock
-- doc/classes/Drydock/Command.html
-- doc/classes/Drydock/InvalidArgument.html
-- doc/classes/Drydock/MissingArgument.html
-- doc/classes/Drydock/NoCommandsDefined.html
-- doc/classes/Drydock/UnknownCommand.html
-- doc/classes/Drydock.html
-- doc/created.rid
-- doc/files
-- doc/files/bin
-- doc/files/bin/example.html
-- doc/files/CHANGES_txt.html
-- doc/files/lib
-- doc/files/lib/drydock_rb.html
-- doc/files/LICENSE_txt.html
-- doc/files/README_rdoc.html
-- doc/fr_class_index.html
-- doc/fr_file_index.html
-- doc/fr_method_index.html
-- doc/index.html
-- doc/rdoc-style.css
 has_rdoc: true
 homepage: http://github.com/delano/drydock
 post_install_message: 

data/test/command_test.rb

@@ -1,40 +0,0 @@
-require File.dirname(__FILE__) + "/../lib/drydock"
-require "rubygems"
-require "test/spec"
-require "mocha"
-
-class Test::Unit::TestCase
-  def test_command_direct(cmd, argv, &b)
-    Drydock::Command.new(cmd, &b).call(*argv)
-  end
-  def test_command(*args, &b)
-    command(*args, &b)
-  end
-end
-
-class JohnWestSmokedOysters < Drydock::Command; end;
-
-Drydock.run = false
-
-context "command" do
-  
-  setup do 
-    @mock = mock() 
-  end
-  
-  specify "should know a command alias" do
-    @mock.expects(:called).with(:eat_alias)
-    test_command_direct(:eat, [:eat_alias]) { |obj,argv| 
-      @mock.called(obj.alias) 
-    }
-  end
-  
-  specify "should accept a custom command class" do
-    @mock.expects(:called).with(JohnWestSmokedOysters)
-    test_command(:eat => JohnWestSmokedOysters) { |obj,argv| 
-      @mock.called(obj.class) 
-    }
-    Drydock.run!(['eat'])
-  end
-  
-end