subcommander 1.0.0

data/README.markdown

@@ -0,0 +1,54 @@
+Subcommander is a wrapper around Ruby's OptionParser class that allows you to have sub-commands like we see in Git and other tools. To get help for your tool, just type in the tool name with no sub-command (or the word "help" as a sub-command).  To get help for a sub-command type:
+
+    your-tool help sub-command
+
+More description coming... this is basically a placeholder for now.
+
+### Simple Example:
+
+    require 'subcommander'
+    include Subcommander
+    
+    subcommander.version = '1.0.0'
+    subcommander.desc = "SimpleTool is ephemeral and only here to demonstrate Subcommander."
+    
+    subcommand :run, "Runs the simple tool" do |sc|
+      sc.opt :just_kidding, '-k', '--just-kidding', "Don't really run the simple tool"
+      sc.exec {
+	      # This is where the subcommand has its implementation
+	      if sc[:just_kidding]
+	        puts "Not really running"
+	      else
+	        puts "Running!"
+	      end
+      }
+    end
+    
+    subcommander.go!
+
+---------------------------
+
+# subcommander #
+
+Properties you can set:
+
+__version__ - The version of the tool you're making.  It's printed at the bottom of help.
+
+__desc__ - A description of the tool you're using.  It's printed at the beginning of help.
+
+
+---------------------------
+# subcommand #
+
+Properties you can set:
+
+__arity__ - This says how many arguemnts are expected to be passed to this sub-command, excluding options and their arguemnts.
+
+__help__ - Help that shows up when the user asks for help about the sub-command
+
+__usage__ - The typical usage pattern like "simple-tool [options] args"
+
+__opt__ - These are exactly the same as OptionParser opt.on() argument lists except the first argument is a token.  When the option is invoked, it will put any option arguemnts that were passed into the subcommand keyed by that token.  So subcommand[:yoursymbol] is where you'll find it when you're looking for it in your exec block.
+
+__exec__ - The implementation for your sub-command should be in a block that's passed to this method.
+

data/lib/subcommander.rb

@@ -0,0 +1,154 @@
+
+require 'optparse'
+
+module Subcommander
+  
+  def pop! stack
+    [stack[0], stack[1..-1]]
+  end
+    
+  class Subcommander
+    attr_accessor :desc,
+                  :args,
+                  :version
+    
+    def initialize
+      @commands = {}
+      @descriptions = {}
+      @file_order = []
+      unless ARGV.empty?
+        args = ARGV.clone
+        @sub_cmd, @args = pop!(args)
+      else
+        @args = []
+      end
+      @desc = "This command needs a description"
+    end
+        
+    def subcommand cmd_name, desc, &block
+      name = cmd_name.to_s
+      sub_cmd = Subcommand.new(@args.clone, cmd_name, desc, &block)
+      @commands[name] = sub_cmd
+      @file_order << name
+    end
+    
+    def go!
+      if @sub_cmd && @sub_cmd == "help"
+        print_help()
+      end
+      sub_cmd = @commands[@sub_cmd]
+      unless sub_cmd # no subcommand
+        print_usage()
+      end
+      sub_cmd.go!
+    end
+    
+    private    
+    def print_usage
+      puts "\n#{@desc}\n\n"
+      puts "  Subcommands:"
+      @file_order.each do |cmd|
+        puts "    #{slop(cmd)}  #{@commands[cmd].desc}" 
+      end
+      puts "\nv " + @version if @version
+      exit
+    end
+    
+    def slop cmd_name
+      cmd_name + ' ' * (@file_order.max.length - cmd_name.length)
+    end
+    
+    def print_help
+      if @args.empty?
+        print_usage
+      else
+        sub_cmd = @commands[@args[0]]
+        if sub_cmd
+          sub_cmd.print_help()
+        end
+        exit
+      end
+    end    
+  end
+    
+  def subcommander
+    unless defined?(@@subcommander)
+      @@subcommander = Subcommander.new
+    end
+    @@subcommander
+  end
+  
+  def subcommand name, desc, &block
+    @@subcommander.subcommand(name, desc, &block)
+  end
+  
+  class Subcommand
+    attr_accessor :arity,
+                  :name,
+                  :desc,
+                  :help,
+                  :usage,
+                  :block
+    
+    def initialize args, cmd_name, desc, &block
+      @args = args
+      @name = cmd_name
+      @desc = desc
+      @opts = OptionParser.new
+      @opts.banner = ""
+      @arity = -1 # Don't care how many args
+      @props = {}
+      block.call(self)
+    end
+    
+    def [] key
+      @props[key]
+    end
+    
+    def banner= str
+      @opts.banner = "Usage: #{str}"
+    end
+        
+    def opt *orig_args
+      args = orig_args.clone()
+      prop, args = pop!(args)
+      @opts.on *args do |arg|
+        @props[prop] = arg
+      end
+    end
+    
+    def exec &block
+      @block = block
+    end
+    
+    def go!
+      parse_args()
+      num_remaining = @props[:remaining_args].length
+      if @arity > -1 && num_remaining != @arity
+        puts "We expected #{@arity} arguments and #{num_remaining} were provided."
+        exit
+      end
+      @block.call if @block
+    end
+    
+    def print_help
+      if @help
+        puts
+        puts @help
+      end
+      if (@usage)
+        @opts.banner = "Usage: #{@usage}"
+        puts
+      end
+      puts @opts.to_s
+      puts
+    end
+    
+    private
+    def parse_args
+      @props[:remaining_args] = @opts.parse(@args)
+    end
+  end
+end
+
+# vim: set expandtab tabstop=2 shiftwidth=2 autoindent smartindent:

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: subcommander
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Tom Santos
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-12 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A library for cleanly handling subcommands (and options)
+email: santos.tom@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- lib/subcommander.rb
+has_rdoc: true
+homepage: http://github.com/tsantos/subcommander
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A library for cleanly handling subcommands (and options)
+test_files: []
+