drydock 0.5.6 → 0.6.0

data/CHANGES.txt

@@ -3,7 +3,17 @@ DRYDOCK, CHANGES
 #### TODO ###############################
 
 * Support putting descriptions into resource file (or __END__)
-* Inline commands aliases. command :cmd1, :cmd2 do; ...; end
+
+
+#### 0.6.0 (2009-04-22) #############################
+
+* CHANGE: Cleaner default error message for UnknownCommand exceptions
+* CHANGE: 'desc' is now 'about' (desc works, but it prints a notice)
+* CHANGE: I now recommend implementing the Drydock DSL in a module.
+bin/example was updated to reflect the change. This prevents Drydock
+keywords from being included in the global namespace. 
+* ADDED: Inline commands aliases. command :cmd1, :cmd2 do; ...; end
+* ADDED: Unknown commands can be directed to a trawler. 
 
 
 #### 0.5.6 (2009-04-22) #############################
@@ -11,23 +21,19 @@ DRYDOCK, CHANGES
 * CHANGED: Interrupts now handled in rescue rather than a trap. 
 * ADDED: Drydock::ArgError and Drydock::OptError are rescued at runtime by default
 
-
 #### 0.5.5 (2009-04-19) #############################
 
 * CHANGED: Improved help screen formatting. 
 
-
 #### 0.5.4 (2009-04-15) #############################
 
 * ADDED: Better error handling with new Drydock::ArgError and Drydock::OptError
 
-
 #### 0.5.3 (2009-04-05) #############################
 
 * FIXED: Command actions were not being handled correctly. Added rdocs to 
 clarify the code.
 
-
 #### 0.5.2 (2009-04-04) #############################
 
 * ADDED: before and after blocks now receive a primed reference to the 
@@ -102,4 +108,6 @@ and sending to other methods manually.
 #### 0.2 (2008-12-27) ###############################
 
 * Initial release
-* Forked from bmizerany/frylock
+* Forked from bmizerany/frylock
+
+

data/README.rdoc

@@ -1,10 +1,8 @@
-= Drydock - v0.5
-
-Inspired by github-gem and bmizerany-frylock.
+= Drydock - v0.6
 
 == Overview
 
-Drydock is a seaworthy DSL for command line apps. It's contained in a single .rb file so it's easy to copy directly into your project. 
+Drydock is a seaworthy DSL for really powerful command line applications. It's contained in a single .rb file so it's easy to copy directly into your project. See below for examples. 
 
 == Install
 
@@ -38,7 +36,6 @@ See bin/example for more.
     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!"
@@ -75,6 +72,11 @@ See bin/example for more.
 * RDocs[http://drydock.rubyforge.org/]
 * Inspiration[http://www.youtube.com/watch?v=m_wFEB4Oxlo]
 
+== Thanks
+
+* Solutious Inc for putting up with my endless references to the sea! (http://solutious.com)
+* Blake Mizerany for the inspiration via bmizerany-frylock[http://github.com/bmizerany/frylock]
+
 == Credits
 
 * Delano Mandelbaum (delano@solutious.com)

data/bin/example

@@ -8,188 +8,201 @@
 #
 # If you're reading this via the Rdocs you won't see the code. See:
 #
-# http://github.com/delano/drydock/blob/drydock-0.5.0/bin/example
+# http://github.com/delano/drydock/blob/master/bin/example
 #
 # For an example of a complex command-line application using 
 # Drydock, see:
 #
-# http://github.com/solutious/rudy
+# http://github.com/solutious/rudy/blob/master/bin/rudy
 #
 
 $:.unshift File.expand_path(File.join(File.dirname(__FILE__), '..')), 'lib'
 
 require 'drydock'
-extend Drydock     # Tell Drydock you want its methods! 
 
+module Example
+  extend Drydock     # Tell Drydock you want its methods! 
+  
+  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. 
+
+  about "A friendly welcome to the Drydock"
+  command :welcome do
+    puts "Welcome to Drydock.", $/
+    puts "For available commands: #{$0} show-commands"
+  end
 
-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. 
-
-
-desc "A friendly welcome to the Drydock"
-command :welcome do
-  puts "Welcome to Drydock.", $/
-  puts "For available commands: #{$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 
+  usage "USAGE: #{$0} laugh [-f]"
+  about "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."
+    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
+    puts "Captain Stubing: Are you laughing?"
+    puts "Dr. Bricker: " << answer
+  end
 
-global_usage "USAGE: #{File.basename($0)} [global options] command [command options]"
-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
-  @val += 1
-end
+  global_usage "USAGE: #{File.basename($0)} [global options] command [command options]"
+  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
+    @val += 1
+  end
 
-before do |obj|
-# You can execute a block before the requests command is executed. Instance
-# variables defined here will be available to all commands. 
-# +obj+ is a reference to the command object, just like in command blocks. 
-end
+  before do |obj|
+  # You can execute a block before the requests command is executed. Instance
+  # variables defined here will be available to all commands. 
+  # +obj+ is a reference to the command object, just like in command blocks. 
+  end
 
-after do |obj|
-# And this will be called after the command. 
-end
+  after do |obj|
+  # And this will be called after the command. 
+  end
 
-usage "#{$0} [-s] [-vv] date"
-desc "Display the current date"
-command :date do |obj| 
-  require 'time'
-  now = Time.now
-  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} [-s] [-vv] date"
+  about "Display the current date"
+  command :date do |obj| 
+    require 'time'
+    now = Time.now
+    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
 
 
-ignore :options
-desc "This command ignores options"
-command :rogue do |obj|
-# You can use ignore :options to tell Drydock to not process the 
-# command-specific options. 
-# Unnamed arguments are available from obj.argv
-  if obj.argv.empty?
-    puts "Had you supplied some arguments, I would have ignored them."
-  else
-    puts "Hi! You supplied some arguments but I ignored them."
-    puts "They're all still here in this array: %s" % obj.argv.join(', ')
+  ignore :options
+  about "This command ignores options"
+  command :rogue do |obj|
+  # You can use ignore :options to tell Drydock to not process the 
+  # command-specific options. 
+  # Unnamed arguments are available from obj.argv
+    if obj.argv.empty?
+      puts "Had you supplied some arguments, I would have ignored them."
+    else
+      puts "Hi! You supplied some arguments but I ignored them."
+      puts "They're all still here in this array: %s" % obj.argv.join(', ')
+    end
   end
-end
 
-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
+  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
+  about "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!
+  about "My way of saying hello!"
+  command :ahoy! => JohnWestSmokedOysters
+  # If you don't provide a block, Drydock will call JohnWestSmokedOysters#ahoy!
 
 
-require 'yaml'
+  require 'yaml'
 
-usage 'ruby bin/example uri -c -d " " -t 15 http://solutious.com/'
-usage 'echo "http://solutious.com/" | ruby bin/example uri -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|
-  # You can provide an block to process the option value. 
-  # This block must return the final value. 
-  v = 10 if (v > 10)
-  v
-end
-argv :uris
-command :uri do |obj|
-# This command processes the output of the stdin block (below this definition).
-# The output of that block is available as obj.stdin. If there is no stdin block
-# obj.stdin will be STDIN's IO object.
-
-  require 'net/http'
-  require 'uri'
-  require 'timeout'
-  
-  uris = []
-  uris += obj.stdin if obj.stdin
-  uris += obj.argv.uris if obj.argv.uris
+  usage 'ruby bin/example uri -c -d " " -t 15 http://solutious.com/'
+  usage 'echo "http://solutious.com/" | ruby bin/example uri -c -d " " -t 15'
+  about "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|
+    # You can provide an block to process the option value. 
+    # This block must return the final value. 
+    v = 10 if (v > 10)
+    v
+  end
+  argv :uris
   
-  delim = obj.option.delim || ','
-  timeout = obj.option.timeout || 5
-  code = :notchecked                      # The default code when :check is false
+  command :uri do |obj|
+  # This command processes the output of the stdin block (below this definition).
+  # The output of that block is available as obj.stdin. If there is no stdin block
+  # obj.stdin will be STDIN's IO object.
+
+    require 'net/http'
+    require 'uri'
+    require 'timeout'
   
-  if uris.empty?
-    puts "Frylock: You didn't provide any URIs. "
-    puts "Master Shake: Ya, see #{$0} #{obj.alias} -h"
-    exit 0
-  end
+    uris = []
+    uris += obj.stdin if obj.stdin
+    uris += obj.argv.uris if obj.argv.uris
   
-  uris.each_with_index do |uri, index|
-    code = response_code(uri, timeout) if (obj.option.check)
-    puts [index+1, uri, code].join(delim)
-  end
+    delim = obj.option.delim || ','
+    timeout = obj.option.timeout || 5
+    code = :notchecked                      # The default code when :check is false
   
-  # NOTE: The alias used to evoke this command is available
-  # via obj.alias
+    if uris.empty?
+      puts "Frylock: You didn't provide any URIs. "
+      puts "Master Shake: Ya, see #{$0} #{obj.alias} -h"
+      exit 0
+    end
   
-end
-alias_command :checkuri, :uri
-
-
+    uris.each_with_index do |uri, index|
+      code = response_code(uri, timeout) if (obj.option.check)
+      puts [index+1, uri, code].join(delim)
+    end
+    
+  end
 
-stdin do |stdin, output|
-# Pre-process STDIN for all commands. This example returns an array of lines. 
-# The command processuris uses this array.
+  about "Prints the alias used to access the command"
+  # We can define command aliases by providing a list of command 
+  # names. The first name is still consider to be the main name.
+  command :printalias, :reveal do |obj|
+    puts "This is printalias!"
+      if (obj.alias == obj.cmd)
+    puts "You did not use an alias"
+      else 
+    puts "You used the alias " << obj.alias
+      end
+  end
+  
+  stdin do |stdin, output|
+  # Pre-process STDIN for all commands. This example returns an array of lines. 
+  # The command processuris uses this array.
   
-  # We only want piped data. If this is not included  
-  # execution will wait for input from the user.
-  unless stdin.tty?   
+    # We only want piped data. If this is not included  
+    # execution will wait for input from the user.
+    unless stdin.tty?   
     
-    while !stdin.eof? do
-      line = stdin.readline
-      line.chomp!
-      (output ||= []) << line
-    end
+      while !stdin.eof? do
+        line = stdin.readline
+        line.chomp!
+        (output ||= []) << line
+      end
     
+    end
+    output
   end
-  output
-end
 
-
-
-# response_code
-#
-# return the HTTP response code for the given URI
-# +uri+ A valid HTTP URI
-# +duration+ The timeout threshold (in seconds) for the request. 
-def response_code(uri_str, duration=5) #:nodoc:
-  response = :unavailable
-  begin 
-    uri = (uri_str.kind_of? URI::HTTP) ? uri_str : URI.parse(uri_str) 
-    timeout(duration) do
-      response = Net::HTTP.get_response(uri).code
-    end 
-  rescue Exception => ex
+  
+  # And one final feature for the intrepid swabbies like myself.
+  # Drydock can handle unknown commands by catching them with a 
+  # trawler. It's like the captain of all aliases. Just specify
+  # the command name to direct all unknown commands to. Simple!
+  trawler :printalias
+  
+  
+  # Return the HTTP response code for the given URI. Used by 
+  # uri command.
+  #
+  # +uri+ A valid HTTP URI
+  # +duration+ The timeout threshold (in seconds) for the request. 
+  def response_code(uri_str, duration=5) #:nodoc:
+    response = :unavailable
+    begin 
+      uri = (uri_str.kind_of? URI::HTTP) ? uri_str : URI.parse(uri_str) 
+      timeout(duration) do
+        response = Net::HTTP.get_response(uri).code
+      end 
+    rescue Exception => ex
+    end
+    response
   end
-  response
 end
-

data/drydock.gemspec

@@ -1,7 +1,7 @@
 @spec = Gem::Specification.new do |s|
   s.name = %q{drydock}
-  s.version = "0.5.6"
-  s.date = %q{2009-04-22}
+  s.version = "0.6.0"
+  s.date = %q{2009-04-28}
   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=
 

data/lib/drydock.rb

@@ -75,7 +75,7 @@ module Drydock
   #     end
   #
   class Command
-    VERSION = 0.5
+    VERSION = 0.6
       # 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.
@@ -266,7 +266,6 @@ module Drydock
     
       cmd_names_sorted = cmds.keys.sort{ |a,b| a.to_s <=> b.to_s }
       
-      
       if @global.quiet
         puts "Commands: "
         line = []
@@ -351,7 +350,7 @@ end
 module Drydock
   extend self
   
-  VERSION = 0.5
+  VERSION = 0.6
   
   @@project = nil
   
@@ -374,9 +373,11 @@ module Drydock
   @@command_index_map = {}
   @@command_argv_names = []  # an array of names for values of argv
   
-  @@capture = nil     # contains one of :stdout, :stderr
+  @@capture = nil            # contains one of :stdout, :stderr
   @@captured = nil
   
+  @@trawler = nil
+  
  public
   # Enable or disable debug output.
   #
@@ -494,7 +495,6 @@ module Drydock
     get_current_option_parser.banner << "USAGE: #{msg}" << $/
   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!
@@ -581,7 +581,7 @@ module Drydock
   #     end
   #
   def command(*cmds, &b)
-    cmd = cmds.first # Should we accept aliases here?
+    cmd = cmds.shift # Should we accept aliases here?
     
     if cmd.is_a? Hash
       raise "#{cmd.values.first} is not a subclass of Drydock::Command" unless cmd.values.first.ancestors.member?(Drydock::Command)
@@ -612,6 +612,10 @@ module Drydock
     @@command_index_map[c.cmd] = @@command_index
     @@command_index += 1 # This will point to the next command
     
+    # Created aliases to the command using any additional command names 
+    # i.e. command :something, :sumpin => Something
+    cmds.each { |aliaz| command_alias(cmd, aliaz); } unless cmds.empty?
+    
     c  # Return the Command object
   end
   
@@ -651,12 +655,32 @@ module Drydock
     @@commands.keys.collect { |cmd| decanonize(cmd); }
   end
   
+  # The trawler catches any and all unknown commands that pass through
+  # Drydock. It's like the captain of aliases. 
+  # +cmd+ is the name of the command to direct unknowns to. 
+  #
+  #     trawler :command_name
+  #
+  def trawler(cmd)
+    @@trawler = cmd
+  end
+  
+  # Has the trawler been set?
+  def trawler?
+    !@@trawler.nil? && !@@trawler.empty?
+  end
+  
   # Provide a description for a command
-  def desc(txt)
+  def about(txt)
     @@command_descriptions += [txt]
     return if get_current_option_parser.is_a?(Symbol)
     get_current_option_parser.on "ABOUT: #{txt}"
   end
+  # Deprecated. Use about.
+  def desc(txt)
+    STDERR.puts "'desc' is deprecated. Please use 'about' instead."
+    about(txt) 
+  end
   
   # Returns true if automatic execution is enabled. 
   def run?
@@ -683,12 +707,8 @@ 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)
-    
-    cmd_name ||= default_command
-    
-    raise UnknownCommand.new(cmd_name) unless command?(cmd_name)
     
+    global_options, cmd_name, command_options, argv = process_arguments(argv)
     stdin = (defined? @@stdin_block) ? @@stdin_block.call(stdin, []) : stdin
     
     command_obj = get_command(cmd_name)
@@ -811,7 +831,12 @@ module Drydock
     
     global_options = @@global_opts_parser.getopts(argv)
     cmd_name = (argv.empty?) ? @@default_command : argv.shift
-    raise UnknownCommand.new(cmd_name) unless command?(cmd_name)
+    
+    unless command?(cmd_name)
+      raise UnknownCommand.new(cmd_name)  unless trawler?
+      raise UnknownCommand.new(@@trawler) unless command?(@@trawler)
+      command_alias(@@trawler, cmd_name)
+    end
     
     cmd = get_command(cmd_name) 
     
@@ -825,22 +850,6 @@ 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_options, cmd_name, command_options, argv]
   end
   
@@ -895,6 +904,9 @@ at_exit {
   rescue Drydock::ArgError, Drydock::OptError=> ex
     STDERR.puts ex.message
     STDERR.puts ex.usage
+  rescue Drydock::UnknownCommand => ex  
+    STDERR.puts ex.message
+    STDERR.puts ex.backtrace if Drydock.debug?
   rescue => ex
     STDERR.puts "ERROR (#{ex.class.to_s}): #{ex.message}"
     STDERR.puts ex.backtrace if Drydock.debug?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: drydock
 version: !ruby/object:Gem::Version 
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors: 
 - Delano Mandelbaum
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-22 00:00:00 -04:00
+date: 2009-04-28 00:00:00 -04:00
 default_executable: 
 dependencies: []