Updated readme

Author: mikbe

README.md

@@ -48,16 +48,26 @@ After installing the **Commandable** gem require it somewhere that gets loaded b
 
 Extend your class with the **Commandable** module:  
 
-    class Widget
+    require 'commandable'
+    
+    class Foo
       extend Commandable
+      
+    end
 
 Then put `command` and a description above the method you want to make accessible. The description is optional but can be helpful
 since it's used when automatically building your help/usage instructions.  
 
-      command "create a new widget"
-      def new(name)
-        ...
+    require 'commandable'
+    
+    class Foo
+      extend Commandable
+      
+      command "Explain what the command does"
+      def bar
+        puts "Foo::bar"
       end
+    end
 
 ### The "`command`" command and its options
 
@@ -201,8 +211,7 @@ A typical help output looks something like this:
       readme            : displays the readme file (default)
            v            : <xor> Application Version
      version            : <xor> Application Version
-        help            : you're looking at it now
-
+        help            : you're looking at it now 
 
 
 ### Complete demonstration app and some example classes ###
@@ -237,6 +246,16 @@ If set to true help instructions will include the default values in the paramete
     # Will print:
     command arg1 [arg2]
 
+###Screen Clearing Options
+
+**Commandable.clear\_screen**  
+_default = false_  
+Set to true to enable clearing the screen when printing help/usage instructions.  
+
+**Commandable.color\clear\_screen\_code**  
+_default = "\e[H\e[2J"
+The escape codes used to clear the screen.
+
 ### Colorized Output Options
 
 The help information can be colored using the standard ANSI escape commands found in the `term-ansicolor` gem. The `term-ansicolor` gem is installed as a dependency but just in case you have problems you can install it yourself by running:
@@ -263,8 +282,8 @@ Then you can do something like this:
 ###Color options 
 
 **Commandable.color\_output**  
-_default = true_  
-Set to false to disable colorized help/usage instructions. You might find the colors really, really annoying...
+_default = false_  
+Set to true to enable colorized help/usage instructions.  
 
 **Commandable.color\_app\_info**  
 _default = intense\_white_ + bold  
@@ -302,13 +321,8 @@ The color the friendly name of the error will be in error messages
 \_default = intense\_black_ + bold  
 The color the error description will be in error messages
 
-**Commandable.color\screen\_clear_code**  
-_default = "\e[H\e[2J"
-The color the error description will be in error messages
-
 The best way to see what all this means it just type `commandable help` and you'll see the help instructions in color.
 
-
 ### Executing the Command Line
 
 There are two ways of using **Commandable** to run your methods. You can use its built in execute method to automatically run whatever is entered on the command line or you can have **Commandable** build an array of procs that you can execute yourself. This allows you to have finer grain control over the execution of the commands as you can deal with the return values as you run each command.
@@ -380,7 +394,6 @@ You just need to configure your bin file with the app settings and then run `Com
 
     # Make sure you require your app after Commandable, or use
     # a configuration file to load the settings then your app
-    # See the Widget app for an example of this.
     require 'yourappname'
     Commandable.execute(ARGV)
 
@@ -390,9 +403,7 @@ You just need to configure your bin file with the app settings and then run `Com
     # Commandable.execute(ARGV, :silent)
 
 
-I actually prefer to create a separate file for my **Commandable** configuration and load it in my main app  file in the `lib` directory. Again, take a look at `Widget` to see what I mean. 
-
-You can get a copy of widget by running `commandable widget [path]` and it will copy the example app to the directory you specify.
+I actually prefer to create a separate file for my **Commandable** configuration and load it in my main app file in the `lib` directory.
 
 ## In closing... ##
 
@@ -409,20 +420,17 @@ Most of all it should be simple to use so if you have any problems please drop m
 
 2012-01-20 - Version: 0.3.0 
 
+* All features are off by default to make Commandable more friendly across platforms.
 * Added ability to disable screen clearing and to set your own screen clear escape code. (Based on [John Sumsion](https://github.com/jdsumsion)'s idea)
 * Decoupled screen clearing from coloring; you can have either or both.
 * Fixed bug that disabled help output in silent mode. (fixed by [John Sumsion](https://github.com/jdsumsion))
 * Fixed bug that didn't label the default method if screen colors were off.
 * Removed monkey patch from FileUtils. It was more philosophical than necessary.
 * Changed terminal coloring gem back to official the term-ansicolor from my own fork now that my changes have been pulled into it.
 * Code clean up. While mostly not a real refactor I've separated out the code into functional groups (aka files).
-* Removed Widget example - it was making the examples too tightly coupled to HashModel.
+* Removed Widget gem example - it was making the examples too tightly coupled to HashModel.
 * Removed Cucumber features.
 
-To do
-
-* Added some more examples.
-* Updated docs to reflect changes.
 
 2011-09-27 - Version: 0.2.3  
 
@@ -444,28 +452,19 @@ To do
 
 * First public release. It's 0.2.0 because 0.1.0, going by the name of Cloptions, wasn't released.
 
-## To Do
-
-Add ability to easily use nested argument trees without hard-coding case blocks. For instance a command that takes set of commands like `foo remote set "ftp_svr" 10.250.1.100` or `foo remote delete "ftp_svr"`.
-
-### Next major version:
+### Possible future upgrades/improvements
 
+* See if there's a elegant way to add nested argument trees without case blocks. e.g. a command that takes set of commands like `foo remote set "ftp_svr" 10.250.1.100` and `foo remote delete "ftp_svr"`.
 * Add a way to use or discover version numbers. Might have to force standardization and not allow configuration since it should be DRY.
-* Needs a massive refactoring.
 * Add a generator to automatically add Commandable support to your app.
-* Reorganize docs to be more logical and less the result of my scribblings as I develop.
-* Try to figure out how to trap `alias` so I don't you don't have to use  an additional `command`.
-* Better formatting of help/usage instructions, the existing one is fairly ugly.
-* Use comments below `command` as the description text so you don't have to repeat yourself to get RDoc to give you docs for your functions.
+* Try to figure out how to trap `alias` so you don't have to use  an additional `command`.
+* Use comments below `command` as the description text so you don't have to repeat yourself when documenting your code.
 * Clean up RSpecs. I'm doing too many ugly tests instead of specifying behavior.
-* Allow sorting of commands alphabetically or by priority
-
-###Future versions:
-
-* Accepting your suggestions...
+* Allow sorting of commands alphabetically or by priority in the help output
 * Make the help/usage directions format available to programmers without having to hack the code.
 * More edge case testing.
 * Allow optional parameters values to be reloaded so changing things like verbose_parameters makes the command list change. (**very** low priority)
+* Accepting your suggestions...
 
 
 .

bin/commandable

@@ -2,6 +2,7 @@
 $LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
 require 'commandable'
 Commandable.color_output = true
+Commandable.clear_screen = true
 Commandable.verbose_parameters = false
 Commandable.app_exe = "commandable"
 Commandable.app_info =  

commandable.gemspec

@@ -22,7 +22,6 @@ EOF
   s.add_dependency("term-ansicolor", "~>1.0.7")
 
   s.add_development_dependency("rspec", "~>2.5")
-  #buns.add_development_dependency("aruba", "~>0.3")
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {spec,autotest}/*`.split("\n")

lib/commandable.rb

@@ -1,10 +1,10 @@
 # This library allows you to incredibly easily make 
 # your methods directly available from the command line.
 #
-# Author::    Mike Bethany  (mailto:mikbe.tk@gmail.com)
-# Copyright:: Copyright (c) 2012 Mike Bethany
-# License::   Distributed under the MIT licence (See LICENCE file)
-
+# Author::     Mike Bethany  (mailto:mikbe.tk@gmail.com)
+# Copyright::  Copyright (c) 2012 Mike Bethany
+# License::    Distributed under the MIT licence (See LICENCE file)
+# website::    http://mikbe.kt
 
 require 'commandable/version'
 require 'commandable/exceptions'
@@ -13,4 +13,5 @@
 require 'commandable/coloring'
 require 'commandable/help_text'
 require 'commandable/command_parser'
+require 'commandable/execution_controller'
 require 'commandable/controller'

lib/commandable/command_parser.rb

@@ -36,117 +36,6 @@ def each(&block)
         yield key => value
       end
     end
-    
-    # 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, 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
-      #puts "method_hash: #{method_hash}" if method_hash.to_s.include?("required_default")
-      
-      # 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