commandable 0.2.3 → 0.3.1

data/lib/commandable/command_parser.rb

@@ -0,0 +1,139 @@
+require 'set'
+
+module Commandable
+
+  class << self
+
+    # An array of methods that can be executed from the command line
+    def commands
+      @@commands.dup
+    end
+    
+    # A hash of instances created when calling instance methods
+    # It's keyed using the class name: {"ClassName"=>#<ClassName:0x00000100b1f188>}
+    def class_cache
+      @@class_cache
+    end
+    
+    # Access the command array using the method name (symbol or string)
+    def [](index)
+      raise AccessorError unless index.is_a? String or index.is_a? Symbol
+      @@commands[index.to_sym]
+    end 
+    
+    # Clears all methods from the list of available commands
+    # This is mostly useful for testing.
+    def clear_commands
+      @@command_options = nil
+      @@commands = HELP_COMMAND.dup
+    end
+    
+    # Convenience method to iterate over the array of commands using the Commandable module
+    def each(&block)
+      @@commands.each do |key, value|
+        yield key => value
+      end
+    end
+
+  end
+
+  private 
+  
+  # This is where the magic happens!
+  # It lets you add a method to the list of command line methods
+  def command(*cmd_parameters)
+
+    @@attribute = nil
+    @@method_file = nil
+    @@method_line = nil
+    @@command_options = {}
+    
+    # Include Commandable in singleton classes so class level methods work
+    include Commandable unless self.include? Commandable
+    
+    # parse command parameters
+    while (param = cmd_parameters.shift)
+      case param
+        when Symbol
+          if param == :xor
+            @@command_options.merge!(param=>:xor)
+          else
+            @@command_options.merge!(param=>true)
+          end
+        when Hash
+          @@command_options.merge!(param)
+        when String
+          @@command_options.merge!(:description=>param)
+      end
+    end
+    @@command_options[:priority] ||= 0
+    
+    # only one default allowed
+    raise ConfigurationError, "Only one default method is allowed."  if @@default_method and @@command_options[:default]
+    
+    set_trace_func proc { |event, file, line, id, binding, classname|
+
+      @@attribute = id if [:attr_accessor, :attr_writer].include?(id)
+      
+      # Traps the line where the method is defined so we can look up 
+      # the method source code later if there are optional parameters
+      if event == "line" and !@@method_file
+        @@method_file = file
+        @@method_line = line
+      end
+ 
+      # Raise an error if there is no method following a command definition
+      if event == "end"
+        set_trace_func(nil)
+        raise SyntaxError, "A command was specified but no method follows"
+      end
+    }
+  end
+
+  # Add a method to the list of available command line methods
+  def add_command(meth)
+    @@commands.delete(:help)
+    
+    if @@attribute
+      argument_list = "value"
+      meth = meth.to_s.delete("=").to_sym if @@attribute == :attr_writer
+    else
+      argument_list = parse_arguments(@@command_options[:parameters])
+    end
+    @@command_options.merge!(:argument_list=>argument_list,:class => self.name)
+    
+    @@commands.merge!(meth => @@command_options)
+    @@default_method = {meth => @@command_options} if @@command_options[:default]
+
+    @@commands.sort.each {|com| @@commands.merge!(com[0]=>@@commands.delete(com[0]))}
+    
+    @@commands.merge!(HELP_COMMAND.dup) # makes sure the help command is always last
+    @@command_options = nil
+    @@attribute = nil
+  end
+
+  # Trap method creation after a command call 
+  def method_added(meth)
+    set_trace_func(nil)
+    return super(meth) if meth == :initialize || @@command_options == nil
+    
+    if @@attribute
+      #synthesize parameter
+      @@command_options.merge!(:parameters=>[[:writer, :value]],:class_method=>false)
+    else
+      # create parameter
+      @@command_options.merge!(:parameters=>self.instance_method(meth).parameters,:class_method=>false)
+    end
+    
+    add_command(meth)
+  end
+  
+  # Trap class methods too
+  def singleton_method_added(meth)
+    set_trace_func(nil)
+    return super(meth) if meth == :initialize || @@command_options == nil
+    @@command_options.merge!(:parameters=>method(meth).parameters, :class_method=>true)
+    add_command(meth)
+  end
+
+end

data/lib/commandable/controller.rb

@@ -0,0 +1,24 @@
+module Commandable
+
+  class << self
+    
+    # Resets the class to default values clearing any commands
+    # and setting the colors back to their default values.
+    def reset_all
+      clear_commands
+      reset_colors
+      reset_screen_clearing
+      
+      @app_info = nil
+      @app_exe = nil
+      @verbose_parameters = true
+      @@default_method = nil
+      @@class_cache = {}
+    end
+  
+  end
+    
+  # Inititializes Commandable's settings when it's first loaded
+  reset_all
+
+end

data/lib/commandable/exceptions.rb

@@ -75,4 +75,4 @@ module Commandable
     end
   end
   
-end
+end

data/lib/commandable/execution_controller.rb

@@ -0,0 +1,122 @@
+require 'set'
+
+# Extending your class with this module allows you to 
+# use the #command method above your method. 
+# This makes them executable from the command line.
+module Commandable
+
+  class << self
+
+    # A wrapper for the execution_queue that runs the queue and traps errors. 
+    # If an error occurs inside this method it will print out a complete list
+    # of availavle methods with usage instructions and exit gracefully.
+    #
+    # If you do not want the output from your methods to be printed out automatically
+    # run the execute command with silent set to anything other than false or nil.
+    def execute(argv=ARGV.clone, silent=false)
+      begin
+        command_queue = execution_queue(argv)
+        command_queue.each do |com|
+          return_value = com[:proc].call
+          puts return_value if !silent || com[:method] == :help
+        end
+      rescue SystemExit => kernel_exit
+        Kernel.exit kernel_exit.status
+      rescue Exception => exception
+        if exception.respond_to?(:friendly_name)
+          set_colors
+          puts help("\n  #{@c_error_word}Error:#{@c_reset} #{@c_error_name}#{exception.friendly_name}#{@c_reset}\n  #{@c_error_description}#{exception.message}#{@c_reset}\n\n")
+        else
+          puts exception.inspect
+          puts exception.backtrace.collect{|line| " #{line}"}
+        end
+      end
+    end
+    
+    # Returns an array of executable procs based on the given array of commands and parameters
+    # Normally this would come from the command line parameters in the ARGV array.
+    def execution_queue(argv)
+      arguments = argv.dup
+      method_hash = {}
+      last_method = nil
+      
+      if arguments.empty?
+        arguments << @@default_method.keys[0] if @@default_method and !@@default_method.values[0][:parameters].flatten.include?(:req)
+      end
+      arguments << "help" if arguments.empty?
+      
+      # Parse the command line into methods and their parameters
+      
+      arguments.each do |arg|
+        if Commandable[arg]
+          last_method = arg.to_sym
+          method_hash.merge!(last_method=>[])
+        else
+          unless last_method
+            default = find_by_subkey(:default)
+
+            # Raise an error if there is no default method and the first item isn't a method
+            raise UnknownCommandError, arguments.first if default.empty?
+            
+            # Raise an error if there is a default method but it doesn't take any parameters
+            raise UnknownCommandError, (arguments.first) if default.values[0][:argument_list] == ""
+            
+            last_method = default.keys.first
+            method_hash.merge!(last_method=>[])
+          end
+          method_hash[last_method] << arg
+        end
+        # Test for missing required switches
+        @@commands.select do |key, value|
+          if value[:required] and method_hash[key].nil?
+            # If the required switch is also a default have the error be a missing parameter instead of a missing command
+            if value[:default]
+              method_hash.merge!(key=>[])
+            else
+              raise MissingRequiredCommandError, key 
+            end
+          end
+        end
+      end
+      
+      # Build an array of procs to be called for each method and its given parameters
+      proc_array = []
+      method_hash.each do |meth, params|
+        command = @@commands[meth]
+
+        if command[:parameters] && !command[:parameters].empty?
+          
+          #Change the method name for attr_writers
+          meth = "#{meth}=" if command[:parameters][0][0] == :writer
+        
+          # Get a list of required parameters and make sure all of them were provided
+          required = command[:parameters].select{|param| [:req, :writer].include?(param[0])}
+          required.shift(params.count)
+          raise MissingRequiredParameterError, {:method=>meth, :parameters=>required.collect!{|meth| meth[1]}.to_s[1...-1].gsub(":",""), :default=>command[:default]} unless required.empty?
+        end
+        
+        # Test for duplicate XORs
+        proc_array.select{|x| x[:xor] and x[:xor]==command[:xor] }.each {|bad| raise ExclusiveMethodClashError, "#{meth}, #{bad[:method]}"}
+
+        klass = Object
+        command[:class].split(/::/).each { |name| klass = klass.const_get(name) }
+        ## Look for class in class cache
+        unless command[:class_method]
+          klass = (@@class_cache[klass.name] ||= klass.new)
+        end
+        proc_array << {:method=>meth, :xor=>command[:xor], :parameters=>params, :priority=>command[:priority], :proc=>lambda{klass.send(meth, *params)}}
+      end
+      proc_array.sort{|a,b| a[:priority] <=> b[:priority]}.reverse
+    
+    end
+
+    private 
+    
+    # Look through commands for a specific subkey
+    def find_by_subkey(key, value=true)
+      @@commands.select {|meth, meth_value| meth_value[key]==value}
+    end
+
+  end
+
+end

data/lib/commandable/help_text.rb

@@ -0,0 +1,73 @@
+module Commandable
+
+  # Default command that always gets added to end of the command list
+  HELP_COMMAND = {:help => {:description => "you're looking at it now", :argument_list => "", :class=>"Commandable", :class_method=>true}}
+  
+  class << self
+    
+    # Describes your application, printed at the top of help/usage messages
+    attr_accessor :app_info
+  
+    # Used when building the usage line, e.g. Usage: app_exe [command] [parameters]
+    attr_accessor :app_exe
+  
+    # If optional parameters show default values, true by default
+    attr_accessor :verbose_parameters
+    
+    # Generates an array of the available commands with a
+    # list of their parameters and the method's description.
+    # This includes the applicaiton info and app name if given.
+    # It's meant to be printed to the command line.
+    def help(additional_info=nil)
+      
+      set_colors
+      set_screen_clear
+      
+      cmd_length = "Command".length
+      parm_length = "Parameters".length
+      max_command = [(@@commands.keys.max_by{|key| key.to_s.length }).to_s.length, cmd_length].max
+      max_parameter = @@commands[@@commands.keys.max_by{|key| @@commands[key][:argument_list].length }][:argument_list].length
+      max_parameter = [parm_length, max_parameter].max if max_parameter > 0
+
+      usage_text = "  #{@c_usage}Usage:#{@c_reset} "
+
+      if Commandable.app_exe      
+        cmd_text = "<#{@c_command + @c_bold}command#{@c_reset}>"
+        parm_text = " [#{@c_parameter + @c_bold}parameters#{@c_reset}]" if max_parameter > 0
+        usage_text += "#{@c_app_exe + app_exe + @c_reset} #{cmd_text}#{parm_text} [#{cmd_text}#{parm_text}...]"
+      end
+
+      array =  [usage_text, ""]
+      
+      array.unshift additional_info if additional_info
+      array.unshift (@c_app_info + Commandable.app_info + @c_reset) if Commandable.app_info
+      array.unshift @s_clear_screen_code
+      
+      header_text = " #{" "*(max_command-cmd_length)}#{@c_command + @c_bold}Command#{@c_reset} "
+      header_text += "#{@c_parameter + @c_bold}Parameters #{@c_reset}#{" "*(max_parameter-parm_length)}" if max_parameter > 0
+      header_text += "#{@c_description + @c_bold}Description#{@c_reset}"
+      
+      array << header_text
+
+      array += @@commands.keys.collect do |key|
+        is_default = (@@default_method and key == @@default_method.keys[0])
+        default_color =  is_default ? @c_bold : ""
+
+        help_line  = " #{" "*(max_command-key.length)}#{@c_command + default_color + key.to_s + @c_reset}"+
+                     " #{default_color + @c_parameter + @@commands[key][:argument_list] + @c_reset}"
+        help_line += "#{" "*(max_parameter-@@commands[key][:argument_list].length)} " if max_parameter > 0
+        
+        # indent new lines
+        description = @@commands[key][:description].gsub("\n", "\n" + (" "*(max_command + max_parameter + (max_parameter > 0 ? 1 : 0) + 4)))
+        
+        help_line += ": #{default_color + @c_description}#{"<#{@@commands[key][:xor]}> " if @@commands[key][:xor]}" +
+                     "#{description}" +
+                     "#{" (default)" if is_default}#{@c_reset}" 
+      end
+      array << nil
+    end
+
+
+  end
+  
+end

data/lib/commandable/version.rb

@@ -1,8 +1,9 @@
+# :nodoc:
 module Commandable
-  module VERSION # :nodoc:
+  module VERSION
     MAJOR  = 0
-    MINOR  = 2
-    TINY   = 3
+    MINOR  = 3
+    TINY   = 1
     PRE    = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')

data/spec/commandable/app_controller_spec.rb

@@ -18,37 +18,9 @@ describe Commandable do
     # or it won't be able to use the settings
     load 'commandable/app_controller.rb'
   }
-  
-  context "when running the widget command" do
     
-    context "when git isn't installed" do
-      
-      it "should inform them they need Git" do
-        Commandable::AppController.stub(:git_installed?){false}
-        execute_output_s(["widget"]).should match(/Git must be installed/)
-      end
-    
-    end
-    context "when git is installed" do
-      
-      context "and it's able to install the files" do
-        it "should download Widget from github" do
-          Commandable::AppController.stub(:download_widget){0}
-          execute_output_s(["widget"]).should_not include("Unable to download")
-        end
-      end
-      
-      context "but it's not able to install the files" do
-        it "should download Widget from github" do
-          Commandable::AppController.stub(:download_widget){1}
-          execute_output_s(["widget"]).should include("Unable to download")
-        end
-      end
-
-    
-    end
+  it "should have a test for examples"
 
-    
-  end
+  it "should have a test for the readme file"
 
 end

data/spec/commandable/coloring_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+describe Commandable do
+
+  before(:each) do 
+    Commandable.reset_all
+    load 'private_methods_bad.rb'
+    Commandable.app_exe = "mycoolapp"
+    Commandable.app_info = 
+"""  My Cool App - It does stuff and things!
+  Copyright (c) 2011 Acme Inc."""
+  end
+
+  let(:c) {Term::ANSIColor}
+
+  context "when screen clearing" do
+
+    it "should clear the screen if screen clearing is on" do
+      Commandable.clear_screen = true
+      clear_screen_code = Regexp.escape("#{Commandable.clear_screen_code}")
+      Commandable.help.join.should match(clear_screen_code)
+    end
+
+    it "should not clear the screen if screen clearing is off" do
+      Commandable.clear_screen = true
+      clear_screen_code = Regexp.escape("#{Commandable.clear_screen_code}")
+      Commandable.clear_screen = false
+      Commandable.help.join.should_not match(clear_screen_code)
+    end
+
+    it "should change how the screen is cleared" do
+      Commandable.clear_screen = true
+      clear_code = "FlabbityJibbity"
+      Commandable.clear_screen_code = clear_code
+      Commandable.help.join.should match(clear_code)
+    end
+
+    it "should not be disabled when color output is disabled" do
+      Commandable.clear_screen = true
+      clear_screen_code = Regexp.escape("#{Commandable.clear_screen_code}")
+      Commandable.color_output = false
+      Commandable.help.join.should match(clear_screen_code)
+    end
+
+  end
+
+  context "when a setting color is changed" do
+    
+    before(:each) { Commandable.color_output = true } 
+  
+    it "should include colors if colored output is enabled" do
+      Commandable.color_output = true
+      Commandable.help.join.should match(Regexp.escape(Commandable.color_app_info))
+    end
+
+    it "should not include colors if colored output is disabled" do
+      Commandable.color_output = false
+      Commandable.help.join.should_not match(Regexp.escape(Commandable.color_app_info))
+    end
+
+    # This seems ripe for meta-zation
+    context "and app_info is changed" do
+      specify {lambda {Commandable.color_app_info = c.black}.should change{Commandable.help}}
+    end
+
+    context "and app_exe is changed" do
+      specify {lambda {Commandable.color_app_exe = c.black}.should change{Commandable.help}}
+    end
+
+    context "and color_command is changed" do
+      specify {lambda {Commandable.color_command = c.black}.should change{Commandable.help}}
+    end
+
+    context "and color_description is changed" do
+      specify {lambda {Commandable.color_description = c.black}.should change{Commandable.help}}
+    end
+
+    context "and color_parameter is changed" do
+      specify {lambda {Commandable.color_parameter = c.black}.should change{Commandable.help}}
+    end
+
+    context "and color_usage is changed" do
+      specify {lambda {Commandable.color_usage = c.black}.should change{Commandable.help}}
+    end
+
+    context "and there is an error" do
+      
+      specify { lambda {Commandable.color_error_word = c.magenta}.should change{capture_output{Commandable.execute(["fly", "navy"])}}}
+      specify { lambda {Commandable.color_error_name = c.intense_red}.should change{capture_output{Commandable.execute(["fly", "navy"])}}}
+      specify { lambda {Commandable.color_error_description = c.black + c.bold}.should change{capture_output{Commandable.execute(["fly", "navy"])}}}
+      
+    end
+    
+  end
+
+end