commandable 0.2.3 → 0.3.1

data/.rbenv-gemsets

@@ -0,0 +1,2 @@
+commandable
+global

data/{README.markdown → README.md}

@@ -14,31 +14,14 @@ The whole process can take as little as four lines of code:
 
 Now any method you want to make accessible from the command line requires just a single line of code and it's right where your method is so it's easy to find when you do want to change some functionality.
 
-Don't think of **Commandable** as a way to add command line switches, it's much more than that. Think of it as a way to allow your app to be driven directly from the command line. 
+Don't think of **Commandable** as a way to add command line switches, think of it as a way to allow your app to be driven directly from the command line in a natural language kind of way. 
 
 You can now "use your words" to let people interact with your apps in a natural way. No more confusing switches that mean one thing in one program and something completely different in another. Can you believe some apps actually use `-v` for something other than "version" and `-h` for something other than "help?" Madness I say! Madness!
 
 
-## Testing for a Better Tomorrow ##
-
-In an effort to make the best possible software I'm asking anyone that would like to help out to run the BDD/TDD tests included with the gem. If you don't already have the `rubygems-test` gem installed please install it:
-
-    $ gem install rubygems-test
-
-And then run the tests on your machine:
-
-    $ gem test commandable
-
-And of course upload them when it asks you if it can. You can take a look at the test results yourself here:
-
-<http://test.rubygems.org/gems/commandable/v/0.2.0>
-
-Thanks for your help.
-
-
 ## Latest version
 
-2011-09-27 - Version: 0.2.3  
+2012-02-07 - Version: 0.3.1  
 
 See change history for specific changes.  
 
@@ -48,8 +31,8 @@ I've tried to follow the principle of least surprise so Commandable should just
 
 ## Requirements ##
 
-* Ruby 1.9.2
-* OS X or any Posix OS (It works, mostly, on Windows but ironically some of the tests won't run because of some Unix commands I use in the tests)
+* Ruby 1.9.2 or greater
+* OS X or any Posix OS (It works, mostly, on Windows but it won't pass the tests because of some Unix commands I use in the tests but no in the code base)
 
 ## Installation  
 From the command line:  
@@ -65,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
 
@@ -218,20 +211,13 @@ A typical help output looks something like this:
       readme            : displays the readme file (default)
            v            : <xor> Application Version
      version            : <xor> Application Version
-      widget [path]     : Downloads a fully working app demonstrating how
-                          to use Commandable with RSpec and Cucumber
-        help            : you're looking at it now
-
+        help            : you're looking at it now 
 
 
 ### Complete demonstration app and some example classes ###
-For a fully working example with RSpec and Cucumber tests run this command:
+**Commandable** uses **Commandable** for its own command line options so you can look at the `lib/commandable/app_controller.rb` class for an example.  
 
-    $ commandable widget [path]
-
-In addition **Commandable** uses **Commandable** for its own command line options so you can also look at the `lib/commandable/app_controller.rb class` for an example.  
-
-If you would like to see a bunch of simple classes that demonstrate **Commandable**'s uses run:
+If you would like to see a bunch of simple classes that demonstrate how to use **Commandable** run:
 
     $ commandable examples [path]
 
@@ -260,20 +246,30 @@ 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-hi` gem. The `term-ansicolor-hi` gem it installed as a dependency but just in case you have problems you can install it yourself by running:
+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:
 
-    $ [sudo] gem install term-ansicolor-hi
+    $ [sudo] gem install term-ansicolor
 
 Then you can do something like this:
 
-    require 'term/ansicolorhi'
+    require 'term/ansicolor'
     
-    c = Term::ANSIColorHI
+    c = Term::ANSIColor
     
     Commandable.color_app_info           = c.intense_white  + c.bold
-    Commandable.color_app_exe           = c.intense_green  + c.bold
+    Commandable.color_app_exe            = c.intense_green  + c.bold
     Commandable.color_command            = c.intense_yellow
     Commandable.color_description        = c.intense_white
     Commandable.color_parameter          = c.intense_cyan
@@ -286,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  
@@ -322,13 +318,11 @@ _default = intense\_cyan_
 The color the friendly name of the error will be in error messages
 
 **Commandable.color\_error\_description**  
-_default = intense\_black_ + bold  
+\_default = intense\_black_ + bold  
 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.
@@ -400,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)
     
@@ -410,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... ##
 
@@ -427,6 +418,24 @@ Most of all it should be simple to use so if you have any problems please drop m
 
 ## Version History ##
 
+2012-02-07 - Version: 0.3.1
+
+* Fixed bug where an error was raised if a non-commandable method was before a commandable method (uninitialized class variable @@command_options)
+
+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 neither, 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 gem example - it was making the examples too tightly coupled to HashModel.
+* Removed Cucumber features.
+
+
 2011-09-27 - Version: 0.2.3  
 
 * Removed annoying error message print out.
@@ -447,28 +456,19 @@ Most of all it should be simple to use so if you have any problems please drop m
 
 * 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...
 
 
 .

data/Rakefile

@@ -2,7 +2,7 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 
 require 'rake'
-require 'rake/rdoctask'
+require 'rdoc/task'
 require 'rspec/core/rake_task'
 require 'cucumber/rake/task'
 
@@ -12,12 +12,8 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.verbose = true
 end
 
-Cucumber::Rake::Task.new(:cucumber) do |t|
-  t.cucumber_opts = %w{--tags ~@jruby} unless defined?(JRUBY_VERSION)
-end
-
 task :default => [:test, :build]
-task :test =>[:cucumber, :spec]
+task :test =>[:spec]
 
 task :clobber do
   rm_rf 'pkg'

data/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 =  

data/commandable.gemspec

@@ -19,11 +19,9 @@ EOF
 
   s.license = 'MIT'
 
-  s.add_dependency("term-ansicolor-hi", "~>1.0.7")
+  s.add_dependency("term-ansicolor", "~>1.0.7")
   
   s.add_development_dependency("rspec", "~>2.5")
-  s.add_development_dependency("cucumber", "~>0.10")
-  s.add_development_dependency("aruba", "~>0.3")
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {spec,autotest}/*`.split("\n")

data/lib/commandable.rb

@@ -1,4 +1,17 @@
-require 'monkey_patch/file_utils'
+# 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)
+# website::    http://mikbe.kt
+
 require 'commandable/version'
 require 'commandable/exceptions'
-require 'commandable/commandable'
+
+require 'commandable/argument_parser'
+require 'commandable/coloring'
+require 'commandable/help_text'
+require 'commandable/command_parser'
+require 'commandable/execution_controller'
+require 'commandable/controller'

data/lib/commandable/app_controller.rb

@@ -1,57 +1,32 @@
+# 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
-  
+
   # A helper to display the read me file and generate an example app
   class AppController
-    WIDGET_GITHUB ||= "://github.com/mikbe/widget"
 
     class << self
       extend Commandable
- 
+
       # Displays the readme file
       command "displays the readme file", :default
       def readme
-        `open #{File.expand_path((File.dirname(__FILE__) + '/../../readme.markdown'))}`
-      end
-      
-      command "Downloads a fully working app demonstrating how\nto use Commandable with RSpec and Cucumber"
-      # Creates a simple example app demonstrating a fully working app
-      def widget(path="./widget")
-        # Test for Git
-        unless git_installed?
-          puts "Git must be installed to download Widget (You're a developer and you don't have Git installed?)"
-          return
-        end
-        # Git already has all of its own error trapping so
-        # it would be horrible coupling and duplication
-        # of effort to do anything on my end for failures.
-        puts "\nUnable to download Widget. You can find the souce code here:\nhttps#{WIDGET_GITHUB}" unless download_widget(path) == 0
+        `open #{File.expand_path((File.dirname(__FILE__) + '/../../readme.md'))}`
       end
 
-      # Downloads Widget from the git repository
-      # This is external to the widget command so it can be stubbed for testing
-      def download_widget(path)
-        `git clone git#{WIDGET_GITHUB}.git #{path}`
-        $?.exitstatus
-      end
-
-      # Checks to see if Git is installed
-      # This is external to the widget command so it can be stubbed for testing
-      def git_installed?
-        !`git --version`.chomp.match(/^git version/i).nil?
-      end
-      
       command "Copies the test classes to a folder so\nyou can see a bunch of small examples"
       # Copies the test classes to a folder so you can see a bunch of small examples
       def examples(path="./examples")
-        FileUtils.copy_dir(File.expand_path(File.dirname(__FILE__) + '/../../spec/source_code_examples'),path)
+        copy_dir(File.expand_path(File.dirname(__FILE__) + '/../../spec/source_code_examples'),path)
       end
 
       command "Will raise a programmer error, not a user error\nso you can see what happens when you have bad code"
       # Causes an error so you can see what it will look like if you have an error in your code.
       def error
-        raise Exception, "An example of a non-user error caused by your bad code trapped in Commandable.execute()"
+        raise Exception, "An example of what an error looks like if you make a mistake using Commandable."
       end
- 
+
       command "Application Version", :xor
       # Version
       def v
@@ -59,11 +34,18 @@ module Commandable
       end
       command "Application Version", :xor
       alias :version :v
-      
+
+      private 
+
+      # Copy a directy and its contents
+      def copy_dir(source, dest)
+        files = Dir.glob("#{source}/**")
+        mkdir_p dest
+        cp_r files, dest
+      end
+
     end
-    
-  end
-  
-end
 
+  end
 
+end

data/lib/commandable/argument_parser.rb

@@ -0,0 +1,45 @@
+module Commandable
+  
+  # Parse a method's parameters building the argument list for printing help/usage
+  def parse_arguments(parameters)
+    parameter_string = ""
+    method_definition = nil
+    parameters.each do |parameter|
+      arg_type = parameter[0]
+      arg = parameter[1]
+      case arg_type
+        when :req
+          parameter_string += " #{arg}"
+        when :opt
+          if Commandable.verbose_parameters
+            # figure out what the default value is
+            method_definition ||= readline(@@method_file, @@method_line)
+            default = parse_optional(method_definition, arg)
+            parameter_string += " [#{arg}=#{default}]"
+          else
+            parameter_string += " [#{arg}]"
+          end
+        when :rest
+          parameter_string += " *#{arg}"
+        when :block
+          parameter_string += " &#{arg}"
+      end
+    end
+    parameter_string.strip
+  end
+
+  # Reads a line from a source code file.
+  def readline(file, line_number)
+    current_line = 0
+    File.open(file).each do |line_text|
+      current_line += 1
+      return line_text.strip if current_line == line_number
+    end
+  end
+  
+  # Parses a method defition for the optional values of given argument.
+  def parse_optional(method_def, argument)
+    method_def.scan(/#{argument}\s*=\s*("[^"\r\n]*"|'[^'\r\n]*'|[0-9]*)/)[0][0]
+  end
+  
+end

data/lib/commandable/coloring.rb

@@ -0,0 +1,100 @@
+require 'term/ansicolor'
+
+module Commandable
+
+  class << self
+
+    # If the output will be colorized or not
+    attr_accessor :color_output
+
+    # What color the app_info text will be in the help message
+    attr_accessor :color_app_info
+    # What color the app_exe will be in the usage line in the help message
+    attr_accessor :color_app_exe
+    # What color the word "command" and the commands themselves will be in the help message
+    attr_accessor :color_command
+    # What color the description column header and text will be in the help message
+    attr_accessor :color_description
+    # What color the word "parameter" and the parameters themselves will be in the help message
+    attr_accessor :color_parameter
+    # What color the word "Usage:" will be in the help message
+    attr_accessor :color_usage
+
+    # What color the word "Error:" text will be in error messages
+    attr_accessor :color_error_word
+    # What color the friendly name of the error will be in error messages
+    attr_accessor :color_error_name
+    # What color the error description will be in error messages
+    attr_accessor :color_error_description
+
+    # If the screen should be cleared before printing help
+    attr_accessor :clear_screen
+
+    # What escape code will be used to clear the screen
+    attr_accessor :clear_screen_code
+    
+    # Resets colors to their default values and disables color output
+    def reset_colors
+      @color_output = false
+
+      #Term::ANSIColor.coloring = true
+      c = Term::ANSIColor
+      @color_app_info           = c.intense_white  + c.bold
+      @color_app_exe            = c.intense_green  + c.bold
+      @color_command            = c.intense_yellow
+      @color_description        = c.intense_white
+      @color_parameter          = c.intense_cyan
+      @color_usage              = c.intense_black   + c.bold
+    
+      @color_error_word         = c.intense_black   + c.bold
+      @color_error_name         = c.intense_red     + c.bold
+      @color_error_description  = c.intense_white   + c.bold
+    
+      @color_bold               = c.bold
+      @color_reset              = c.reset
+    end
+    
+    # Resets the escape code used for screen clearing and disables screen clearing.
+    def reset_screen_clearing
+      @clear_screen = false
+      @clear_screen_code = "\e[H\e[2J"
+    end
+
+    private
+    
+    # Changes the colors used when printing the help/usage instructions to those set by the user.
+    def set_colors
+      if @color_output 
+        @c_app_info           = @color_app_info
+        @c_app_exe            = @color_app_exe
+        @c_command            = @color_command
+        @c_description        = @color_description
+        @c_parameter          = @color_parameter
+        @c_usage              = @color_usage
+      
+        @c_error_word         = @color_error_word
+        @c_error_name         = @color_error_name
+        @c_error_description  = @color_error_description
+      
+        @c_bold               = @color_bold
+        @c_reset              = @color_reset
+      else
+        @c_app_info, @c_app_exe, @c_command, 
+        @c_description, @c_parameter, @c_usage, 
+        @c_bold, @c_reset, @c_error_word, 
+        @c_error_name, @c_error_description = [""]*11
+      end
+    end
+
+    # Changes the screen clearing code used when printing the help/usage instructions to the one set by the user.
+    def set_screen_clear
+      if @clear_screen
+        @s_clear_screen_code = @clear_screen_code 
+      else
+        @s_clear_screen_code = ""
+      end
+    end
+
+  end
+  
+end