visionmedia-commander 1.2.2

data/History.txt

@@ -0,0 +1,48 @@
+
+=== 1.2.2 / 2008-11-06
+
+  * 1 Bug Fix:
+
+    * Forgot to add array.rb
+
+=== 1.2.0 / 2008-11-06
+
+  * 2 Major Enhancements:
+
+    * Added paging ability (similar to 'less')
+    * Added coloring to default help generator
+
+=== 1.1.0 / 2008-11-06
+
+  * 1 Major Enhancements:
+
+    * Added dependency for Highline gem, which replaces Commander's user interaction lib
+
+=== 1.0.4 / 2008-11-04
+
+  * 1 Minor Enhancements:
+
+    * Added support for --help and --version flags
+
+=== 1.0.3 / 2008-11-01
+
+  * 1 Bug Fix:
+
+    * Typo causing the gem to fail build on github
+
+=== 1.0.2 / 2008-11-01
+
+  * 1 Minor Enhancements:
+
+    * Added gemspec for github
+
+=== 1.0.1 / 2008-10-31
+
+  * 2 Minor Enhancements:
+
+    * Added shebang line to commander init
+    * Added require 'rubygems' 
+
+=== 1.0.0 / 2008-10-31
+
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,17 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/commander
+commander.gemspec
+lib/commander.rb
+lib/commander/command.rb
+lib/commander/commander.rb
+lib/commander/core_ext/array.rb
+lib/commander/help_generators.rb
+lib/commander/help_generators/default.rb
+lib/commander/manager.rb
+lib/commander/version.rb
+spec/all_spec.rb
+spec/commander_spec.rb
+spec/manager_spec.rb

data/README.txt

@@ -0,0 +1,76 @@
+
+== DESCRIPTION:
+
+  Commander is a small framework for creating a sub-command utility. 
+  For example a sub command would be 'git add' or 'git rm', where 'add' and
+  'rm' are sub commands.
+
+== FEATURES:
+
+  * Sub-commands
+  * Auto-generated help documentation globally and per sub-command
+  * Simple syntax and implementation
+  * Extensible help generators for various output formats
+  * Use the 'commander' command to initialize a commander driven program
+  * Dependent on highline for terminal interaction (ask, choose, etc)
+  
+== USAGE:
+
+  require 'commander'
+  
+  init_commander(
+      :name => 'Commander', 
+      :version => Commander::VERSION, 
+      :description => 'Commander utility program.'
+    )
+  
+  command :init do |c|
+    c.syntax = 'commander init <filepath>'
+    c.description = 'Initialize an empty file with a commander skeleton.'
+    c.example 'Apply commander to a blank file.', 'commander init ./bin/my_executable'
+    c.option('-r', '--recursive', 'Do something recursively') { puts "I am recursive." } 
+    c.option('-v', '--verbose', 'Do something verbosely') { puts "I am verbose." } 
+    c.when_called do |args|
+       list = ask 'List some items:', Array
+       # Do something with list
+    end
+  end
+
+== KNOWN ISSUES:
+  
+  * none
+
+== TODO:
+
+  * look at newgem gem and copy the whole 'create   ./path' verbose listing conventions
+  * do testing for these apps like highline does with mock IO
+  * look at highline examples and change commander commands to work without new-lines etc
+  * more / better documentation
+  * help generator options (such as large option description etc)
+  * help generators should use erb
+  * refactor
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIX
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,34 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/commander.rb'
+
+Hoe.new('commander', Commander::VERSION) do |p|
+  p.developer('TJ Holowaychuk', 'tj@vision-media.ca')
+  p.extra_deps << ['highline', '>= 1.5.0']
+end
+
+desc 'Build and install gem.'
+task :build => [:remove, :install_gem] do
+  sh "clear"
+end
+
+desc 'Remove build data.'
+task :remove => [:clean] do
+  sh "clear"
+end
+
+desc 'Run rspec suite.'
+task :spec do
+  sh "clear"
+  sh "spec ./spec/all_spec.rb"
+end
+
+desc 'Run rspec suite with specdoc format.'
+task :specd do
+  sh "clear"
+  sh "spec ./spec/all_spec.rb --format specdoc"
+end
+
+# vim: syntax=Ruby

data/bin/commander

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+require 'commander'
+
+init_commander(
+    :name => 'Commander', 
+    :version => Commander::VERSION, 
+    :description => 'Commander utility program.'
+  )
+
+command :init do |c|
+	c.syntax = 'commander init <filepath>'
+	c.description = 'Initialize an empty file with a commander skeleton.'
+	c.example 'Create a new file with a commander skeleton.', 'commander init ./bin/my_executable'
+	c.when_called do |args|
+	  abort "Provide a filepath." if args.empty?
+	  puts
+		name = ask 'What is your programs machine name?'
+		description = ask 'Describe your program:'
+		commands = ask 'List the sub-commands you wish to create:', Array
+		begin
+		  filepath = args.shift
+      File.open(filepath, 'w') do |f|
+        f.write <<-CODE
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'commander'
+
+init_commander(
+    :name => '#{name.capitalize}', 
+    :version => #{name.capitalize}::VERSION, 
+    :description => '#{description}'
+  )
+  
+CODE
+        commands.each do |command|
+          f.write <<-CODE
+command :#{command} do |c|
+  c.syntax = ''
+  c.description = ''
+  c.example 'description', 'code'
+  c.when_called do |args|
+    # Do something
+  end
+end
+
+CODE
+        end
+       end
+       say "Created commander skeleton at '#{filepath}'."
+       puts
+		 rescue Exception => e
+       abort e
+		 end
+	end
+end

data/lib/commander.rb

@@ -0,0 +1,9 @@
+
+$:.unshift(File.expand_path(File.dirname(__FILE__)))
+
+require 'commander/commander'
+require 'highline/import'
+ 
+class Object
+  include Commander
+end

data/lib/commander/command.rb

@@ -0,0 +1,34 @@
+
+module Commander
+	class Command 
+		
+		attr_accessor :description, :syntax, :examples, :options, :command, :manual
+		attr_reader :when_called_proc
+		
+		def initialize(command)
+			@command, @options, @examples = command, [], []
+		end
+		
+		# Adds an example in the help documentation of this sub-command. 
+		def example(description, code) 
+			@examples << { :description => description, :code => code }
+		end
+		
+		# Adds an option or 'flag'. These are parsed with +OptionParser+
+		# so please view its documentation for help.
+		def option(*args, &block)
+			@options << { :args => args, :proc => block }
+		end
+		
+		# This proc is called when the sub-command is invoked. 
+		# The proc has instant access to all methods found in 
+		# interaction.rb
+		def when_called(&block)
+		  @when_called_proc = block
+		end
+		
+		def invoke(method_name, *args)
+		  send(method_name).call *args
+		end
+	end
+end

data/lib/commander/commander.rb

@@ -0,0 +1,35 @@
+
+require 'commander/version'
+require 'commander/command'
+require 'commander/manager'
+require 'commander/help_generators'
+require 'commander/core_ext/array'
+require 'optparse'
+
+module Commander
+  	
+	def init_commander(options = {})
+		Commander::Manager.instance options
+	end
+	
+	def add_command(command, &block)
+		_command = command
+		command = Commander::Command.new(_command)
+		yield command
+		Commander::Manager.instance.add_command command
+	end
+	alias :command :add_command
+	
+	def get_command(command)
+		Commander::Manager.instance.get_command command
+	end
+	
+	def command_exists?(command)
+		Commander::Manager.instance.include? command
+	end
+	
+	def info(option)
+		Commander::Manager.instance.info[option]
+	end
+end
+

data/lib/commander/help_generators.rb

@@ -0,0 +1,2 @@
+
+require 'commander/help_generators/default'

data/lib/commander/help_generators/default.rb

@@ -0,0 +1,126 @@
+
+module Commander
+  module HelpGenerators
+    
+    # Default help generator.
+    #
+    # Example formatting:
+    #   
+    #   NAME:
+    #   
+    #       Commander-init 
+    #   
+    #   DESCRIPTION:
+    #   
+    #       Initialize an empty file with a commander skeleton.
+    #   
+    #   EXAMPLES:
+    #   
+    #       # Apply commander to a blank file.
+    #       commander init ./bin/my_executable
+    #   
+    #   OPTIONS:
+    #   
+    #       -r,  --recursive,  Do something recursively
+    #       -v,  --verbose,  Do something verbosely
+    #
+    class Default
+      
+      attr_reader :manager
+      
+      def initialize(manager)
+        $terminal.page_at = 22
+        @manager = manager
+        @command = @manager.user_command
+        render
+      end
+      
+      # -----------------------------------------------------------
+
+        protected
+
+      # -----------------------------------------------------------
+      
+      def render 
+        say(render_command(@command)) if @command
+        say(render_global) unless @command
+      end
+      
+      def render_global
+        %w[ name description command_list copyright ].collect { |v| send("render_#{v}") }.join
+      end
+      
+      def render_name
+        o = head 'name'
+        o += row 6, @manager.info[:name]
+        o += "\n"
+        o
+      end
+      
+      def render_description
+        o = head 'description'
+        o += row 6, @manager.info[:description] unless @manager.info[:description].nil?
+        o += "\n"
+        o
+      end
+      
+      def render_command_list
+        o = head 'sub-commands'
+        o += @manager.commands.collect { |c, command| row(6, c.to_s, command.description) }.join
+        o += row 6, "help", "Display this help information, or help for the trailing sub-command."
+        o += "\n"
+        o
+      end
+      
+      def render_command(command)
+        o = head 'name'
+        o += row 6, "#{@manager.info[:name]}-#{command.command}"
+        o += "\n"
+        
+        o += head 'description'
+        o += row 6, command.description
+        o += "\n"
+        
+        o += head('examples') unless command.examples.empty?
+        o += render_command_examples command
+        o += "\n"
+        
+        o += head('options') unless command.options.empty?
+        o += render_command_options command
+        o += "\n\n"
+        o
+      end
+      
+      def render_command_options(command)
+        command.options.collect { |option| row(6, option[:args].join(',  '))  }.join
+      end
+      
+      def render_command_examples(command)
+        command.examples.collect do |example|
+          o = row 6, "# #{example[:description]}"
+          o += row 6, "#{example[:code]}"
+        end.join "\n"
+      end
+            
+      def render_copyright
+        @manager.info[:copyright].nil? ? "\n" : head('copyright') + row(6, @manager.info[:copyright]) + "\n\n";
+      end
+      
+      def head(text)
+        "\n  <%= color('#{text.upcase}', BOLD) %>:\n"
+      end
+      
+      def row(lpad, *args)
+        "\n" + (' ' * lpad) + args.collect { |a| a.to_s.ljust(15, ' ') }.join 
+      end
+    end
+  end
+end
+
+class Hash
+  def collect(&block)
+    o = []
+    self.each_pair { |k, v| o << block.call(k, v)} 
+    o
+  end
+end

data/lib/commander/manager.rb

@@ -0,0 +1,129 @@
+
+module Commander
+  
+  # = Manager
+  #
+  # Controls management and invocation of sub-commands.
+	class Manager
+				
+		attr_reader :command_options, :commands, :info
+		attr_reader :user_command, :user_args
+		
+		# Initialize commander singleton.
+    #
+    # == Keys:
+    #
+    #  * name (required)
+    #  * version (required)
+    #  * description
+    #  * copyright
+    #
+    # == Examples:
+    #    
+    #   init_commander(
+    #     :name => 'Commander', 
+    #     :version => Commander::VERSION, 
+    #     :description => 'Commander utility program.'
+    #   )
+    #
+		def self.instance(options = {})
+			@@instance ||= Commander::Manager.new options
+		end
+		
+		def self.kill_instance!
+		  @@instance = nil
+		end
+		
+		def initialize(options)
+			@info, @command_options = options, {}
+			@user_args = ARGV.dup
+			@info[:help_generator] ||= Commander::HelpGenerators::Default
+			init_version
+			at_exit { run }
+		end
+		
+		def add_command(command)
+			@commands ||= {} and @commands[command.command] = command
+		end
+		
+		def get_command(command)
+			@commands[command.to_sym]
+		end
+		
+		def execute_command
+		  abort "Invalid command." if not @user_command
+		  unless @user_command.options.empty?
+		    opts = OptionParser.new
+		    @user_command.options.each { |option| opts.on(*option[:args], &option[:proc]) }
+		    opts.parse! @user_args 
+	    end
+    rescue OptionParser::MissingArgument => e
+      debug_abort e
+    else
+		  @user_command.invoke(:when_called_proc, @user_args) 
+		end
+		
+		def valid_command?(command)
+			!@commands[command.to_sym].nil? unless command.nil?
+		end
+		alias :include? :valid_command?
+		
+		def empty?
+			@commands.empty?
+		end
+		
+		def length
+			@commands.length
+		end
+		alias :size :length
+		
+		def valid_version?(version)
+			version.split('.').length == 3 if version.is_a? String
+		end
+		
+		def parse_version(version)
+		  version.split('.').collect { |v| v.to_i } if version.is_a? String
+		end
+		
+		def debug_abort(msg, exception = nil)
+		  abort msg
+		end
+				
+		def init_version
+		  raise "Your program must have a version tuple ('x.x.x')." unless valid_version?(@info[:version])
+		  @info[:major], @info[:minor], @info[:tiny] = parse_version(@info[:version])
+		end
+		
+		def run
+		  parse_options!
+		  abort "Invalid arguments." if @user_args.empty?
+		  @command_options[:help] = true and @user_args.shift if @user_args[0] == 'help'
+		  set_user_command
+	    case 
+        when (@command_options[:help] and @user_args.empty?) then output_help
+        when @command_options[:help] then output_help
+        else execute_command
+      end
+		end
+		
+		def parse_options!
+		  opts = OptionParser.new
+		  opts.on('--help') { output_help; exit }
+		  opts.on('--version') { output_version; exit }
+		  opts.parse! @user_args rescue nil
+		end
+		
+		def set_user_command
+		  @user_command = get_command(@user_args[0]) unless @user_args.empty?
+		  @user_args.shift
+		end
+		
+		def output_help
+		  @info[:help_generator].new self
+		end
+		
+		def output_version
+		  puts "#{@info[:name]} #{@info[:version]}"
+		end
+	end
+end

data/lib/commander/version.rb

@@ -0,0 +1,7 @@
+
+module Commander
+  MAJOR = 1
+  MINOR = 2
+  TINY = 2
+  VERSION = [MAJOR, MINOR, TINY].join('.')  
+end

data/spec/all_spec.rb

@@ -0,0 +1,6 @@
+
+require File.expand_path(File.dirname(__FILE__) + '/../lib/commander')
+
+Dir['./spec/**/*.rb'].each do |file|
+  require file unless file == './spec/all_spec.rb'
+end

data/spec/commander_spec.rb

@@ -0,0 +1,42 @@
+
+describe Commander do
+	
+	before :each do
+		init_commander :version => '1.3.2', :name => 'My Program'
+		command :test_command do |c|
+			c.syntax = 'test_command [options]'
+			c.description = 'Just a test command.'
+			c.option '-h', '--help', 'View help information.'
+			c.option '--version', 'View program version.'
+			c.option '-v', '--verbose', 'Verbose output.'
+			c.example 'View help', 'test_command --help'
+			c.example 'View version', 'test_command --version'
+		end
+		@manager = Commander::Manager.instance
+	end
+	
+	it "should add commands" do
+		@manager.length.should == 1
+	end
+	
+	it "should fetch commands with the #get_command method" do
+		get_command(:test_command).syntax.should == 'test_command [options]'
+	end
+	
+	it "should test existance of a command using #command_exists?" do
+		command_exists?(:test_command).should == true
+		command_exists?(:test).should == false
+	end
+	
+	it "should inialize and set the version" do
+		info(:version).should == '1.3.2'
+		info(:major).should == 1
+		info(:minor).should == 3
+		info(:tiny).should == 2
+	end
+	
+	it "should set program name" do
+		info(:name).should == 'My Program'
+	end
+end
+

data/spec/manager_spec.rb

@@ -0,0 +1,19 @@
+
+describe Commander::Manager do
+  before :each do
+    @manager = Commander::Manager.instance 
+  end
+  
+  it "should parse version numbers" do
+    @manager.parse_version('1.2.3').should == [1, 2, 3]
+  end
+  
+  it "should validate version numbers" do
+    @manager.valid_version?('1.2.3').should == true
+  end
+  
+  it "should invalidate version numbers" do
+    @manager.valid_version?('1.2').should_not == true
+  end
+
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: visionmedia-commander
+version: !ruby/object:Gem::Version 
+  version: 1.2.2
+platform: ruby
+authors: 
+- TJ Holowaychuk
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-06 00:00:00 -08:00
+default_executable: commander
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: highline
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.5.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.2
+    version: 
+description: Commander is a small framework for creating a sub-command utility. For example a sub command would be 'git add' or 'git rm', where 'add' and 'rm' are sub commands.
+email: 
+- tj@vision-media.ca
+executables: 
+- commander
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/commander
+- lib/commander.rb
+- lib/commander/command.rb
+- lib/commander/commander.rb
+- lib/commander/help_generators.rb
+- lib/commander/help_generators/default.rb
+- lib/commander/manager.rb
+- lib/commander/version.rb
+- spec/all_spec.rb
+- spec/commander_spec.rb
+- spec/manager_spec.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: commander
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Commander is a small framework for creating a sub-command utility
+test_files: []
+