rubycom 0.3.2 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NzljMjJkOTA5OGI4NTlmNTNjMjQ0NDdkMzQ1NzY5YjYxMGRkMmQxNw==
+    ZThmMjdiYjc1YjlkMDUxODYxNGQyMmI2YzYzNGI0YTQwMDQ2MGI3Mg==
   data.tar.gz: !binary |-
-    MTY3NjdiMTkyOTBhM2UyNjZiNjc4ODE5YzQ0MDJiNzQzNmNlOGJiOQ==
+    OTY2ZWQzMzI1NGNhOTEyYzM5YTVhZGUwOTgyMTcxMjAyM2Y3MzliYw==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NDRmZWFhNTRhMWFmMTBjZjY1ZjE3N2JhODFjNThiMDc3MDk3YjQzMzc3NWM4
-    OWQwNWE3NzA3ZjgzMDdlODAzZjQzZmY3NWFjNDdhYjMxNDU5YzE2ZjkyM2Jl
-    OWU4ODYzMWFlZWY0NzYzOGQ5YzQwYWZlM2VmMDlmMzcxYzdmZTk=
+    ZDhlMWRhMDNiODI2Y2RmMjMxNGVhZDU4NDk4YTc3MjljMmE2OWEyNWQ5YTBj
+    OWZkM2JiZjE2MThjMTRjMzE0NjM2YzI5YzliMmU3NzZjZmViZWE1ODgyODMw
+    MTM5YTYyZjYyYjcxNzkyY2ZjYWUzZDA1NWNjNjlmYjk0MzlhYzk=
   data.tar.gz: !binary |-
-    Njg1YWIxMzI5ODA1NGViMTA1NGMyMjYxOGViNDI0NTZjOWQyY2U1OTE3Mzgx
-    YmQ0NGNhOGVkNTg0OGE2OWNjMTBkNWI2YWE5ZjJkNjZjYWY0YzlmN2Q2ZWVm
-    ZTRmMTVlMDdhMDUxY2NjYzg4NjA1NjMwZWNkZmQyNzUxNzUxZGE=
+    ZWEyZThiOGJiMzU2NDYzYzlhMmFlZTM3Yjc2YjY3YTE3YzI5MTUzMGQyYmJh
+    Yjc3ZmE2MWE0MGJiNzY0Njg5Mzc5YzUyYmNlNDZhZDRlN2IxMmM4MTNhZGFm
+    ZDI0MWYzNDE1M2IzMjJhNjQzYmI4NjEwNjUzZjYxYWQ5NjhhZDc=

data/README.md

@@ -1,146 +1,162 @@
-Rubycom
----------------
-
-© Danny Purcell 2013 | MIT license
-
-Makes creating command line tools as easy as writing a function library.
-
-When a module is run from the terminal and includes Rubycom, Rubycom will parse ARGV for a command name,
-match the command name to a public singleton method (self.method_name()) in the including module, and run the method
-with the given arguments.
-
-Features
----------------
-
-Allows the user to write a properly documented module/class as a function library and convert it to a command line tool
-by simply including Rubycom at the bottom.
-
-* Provides a Command Line Interface for any function library simply by stating `include Rubycom` at the bottom.
-* Public singleton methods are made accessible from the terminal. Usage documentation is pulled from method comments.
-* Method parameters become required CLI arguments. Optional (defaulted) parameters become CLI options.
-* Command consoles can be built up by including other modules before including Rubycom.
-* Included modules become commands, their public singleton methods become sub-commands.
-* Built in tab completion support for all commands.
-    * Users may call `./path/to/my_command.rb register_completions` then `source ~/.bash_profile` to register completions.
-
-Usage
----------------
-
-Write your module of methods, document them as you normally would. `include Rubycom` at the bottom.
-Optionally `#!/usr/bin/env ruby` at the top.
-
-Now any singleton methods `def self.method_name` will be available to call from the terminal.
-
-Calling `ruby ./path/to/module.rb <command_name>` will automatically discover and run your `<command_name>` singleton method.
-If no method is found by the given name, a usage print out will be given including a summary of each command available
-and it's description from the corresponding method's comments.
-
-Calling a valid command with incorrect arguments will produce a usage print out for the matched method.
-Rubycom will include as much documentation on the command line as you provide in your method comments. Currently Rubycom
-only handles @param and @return annotation style comments for discovering the method comments regarding params and return values.
-All other commentary will be included as part of the command description. In the absence of @param or @return comments,
-Rubycom will also leave off the corresponding Param: and Return: markers in the usage output.
-
-#####Special commands
-
-| Command | Description | Options |
-| ------- |:-----------:| -------:|
-| `ruby ./path/to/module.rb help [command_name]` | Will print out usage for the module or optionally the specified command.||
-| `ruby ./path/to/module.rb job </path/to/job.yaml>` | Runs the specified job file. See: "Jobs" below. | `--test` Prints the steps and context without running the commands. |
-
-
-###Arguments
-
-* Arguments are automatically parsed from the command line using Ruby's core Yaml module.
-* Arguments will be passed to your method in order of their appearance on the command line.
-* If you specify a default value for a parameter in your method, then Rubycom will look for a named argument matching
-    the parameter's name.
-* Users may call out option parameters in any order using `--<param_name>=<value>` or `--<param_name> <value>`
-    * Currently Rubycom does not yet support sort names for optional parameters so specifying `-<param_name>`
-        is equivalent to `--<param_name>`
-* In the absence of a named option, any optional parameters still unfilled will be filled by unnamed arguments in
-    order of appearance.
-* Optional parameters which do not get overridden either by a named option specification or an available unnamed
-    argument will be filled by their default as usual.
-* If a rest parameter `*param_name` is defined in the method being called, any remaining arguments will be passed to the
-    rest parameter after the required and optional parameters are filled.
-
-###Jobs
-
-Jobs are a higher order orchestration mechanism for command line utilities. Rubycom provides a simple job runner to every
-command line utility. by calling `ruby ./path/to/module.rb job </path/to/job.yaml>` with a valid job yaml. Rubycom will
-run your job.
-
-* A valid job file is a Yaml file which specifies a `steps` node and any number of valid numbered child nodes
-* Optionally, an `env` node may specified.
-    * If specified, `env` should include child nodes which are `key: value` pairs Ex: `working_dir: ./test/rubycom`
-    * If an `env` is specified, values may be inserted into commands in the `steps` node as such: `env['key']`
-         * Ex: `ruby env[working_dir]/util_test_composite.rb test_composite_command env[test_msg]`
-* A valid `steps` child node is a numbered node `1:` with a `cmd:` child node and optionally several context `desc:`
-    child nodes.
-* A `cmd:` node should specify the command string to run. Ex: `cmd: ls ./test_folder`
-* A context node should specify some text to be placed with the node's key in a formatted
-    logging context Ex: `desc: Run test_composite_command`
-
-Below is an example job file which demonstrates the format Rubycom supports.
-
-    ---
-    env:
-      test_msg: Hello World
-      test_arg: 123
-      working_dir: ./test/rubycom
-    steps:
-      1:
-        desc: Run test_composite_command with environment variable
-        cmd: ruby env[working_dir]/util_test_composite.rb test_composite_command env[test_msg]
-      2:
-        Var: Run UtilTestModule/test_command_options_arr with environment variable
-        cmd: ruby env[working_dir]/util_test_composite.rb UtilTestModule test_command_options_arr '["Hello World", world2]'
-      3:
-        Context: Run test_command_with_args with environment variable
-        cmd: ruby env[working_dir]/util_test_module.rb test_command_with_args env[test_msg] env[test_arg]
-      4:
-        Cmd: Run ls for arbitrary command support
-        cmd: ls
-      5:
-        Arbitrary_Context: Run ls with environment variable
-        cmd: ls env[working_dir]
-
-
-Raison d'etre
----------------
-
-* From scratch command line scripts often include redundant ARGV parsing code, little to no testing, slim documentation.
-* OptionParser and the like help script authors define options for a script.
-  They provide structure to the redundant code and slightly easier argument parsing.
-* Thor and the like provide a framework the script author will extend to create command line tools.
-  Prescriptive approach creates consistency but requires the script author to learn the framework and conform.
-
-While these are things are nice, we are still writing redundant code and
-tightly coupling the functional code to the interface which presents it.
-
-At it's core a terminal command is a function. Rather than requiring the authors to make concessions for the presentation and
-tightly couple the functional code to the interface, it would be nice if the author could simply write a function library
-and attach the interface to it.
-
-How it works
----------------
-Rubycom attaches the CLI to the functional code. The author is free to write the functional code as any other.
-If a set of functions needs to be accessible from the terminal, just `include Rubycom` at the bottom and run the ruby file.
-
-* Public singleton methods are made accessible from the terminal.
-* ARGV is parsed for a method to run and arguments.
-* Usage documentation is pulled from method comments.
-* Method parameters become required CLI arguments.
-* Optional (defaulted) parameters become CLI options.
-* Tab completion support if the user has registered it for the file.
-
-The result is a function library which can be consumed easily from other classes/modules and which is accessible from the command line.
-
-Coming Soon
----------------
-* Support for piping.
-* Build a job yaml by running each command in sequence with a special option --job_add <path_to_yaml>[:step_number]
-* Edit job files from the command line using special options.
-    * --job_update <path_to_yaml>[:step_number]
-    * --job_remove <path_to_yaml>[:step_number]
+Rubycom
+---------------
+
+&copy; Danny Purcell 2013 | MIT license
+
+Makes creating command line tools as easy as including Rubycom.
+
+When a Module which has included Rubycom is run from the terminal, Rubycom will parse ARGV for a command name,
+match the command name to a method in the including module, and run the method with the given arguments.
+
+Features
+---------------
+
+Allows the user to write a properly documented module/class and convert it to a command line tool
+by simply including Rubycom at the bottom.
+
+* Provides a Command Line Interface for any library simply by stating `include Rubycom` at the bottom.
+* Public singleton methods are made accessible from the terminal. Usage documentation is pulled from method comments.
+* Method parameters become required CLI arguments. Optional (defaulted) parameters become CLI options.
+* Command consoles can be built up by including other modules before including Rubycom.
+* Included modules become commands, their public singleton methods become sub-commands.
+* Built in tab completion support for all commands.
+    * Users may call `./path/to/my_command.rb register_completions` then `source ~/.bash_profile` to register completions.
+* Customize Rubycom's functionality by calling `Rubycom.run_command` with custom plugin modules.
+* When calling run_command, functionality can be easily modified by providing a custom module for one of the following
+keys `:arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error` in plugins_options.
+
+Installation
+---------------
+
+#### Install with Gem
+* Available on [Rubygems](https://rubygems.org/gems/rubycom)
+* Be sure one of your gem sources is `source 'https://rubygems.org'`
+* Run `gem install rubycom`
+
+#### Building locally
+* Fork the repository if you wish
+* Clone repository locally
+    * If using the main repo: `git clone https://github.com/dannypurcell/rubycom.git`
+* Run `rake install` if installing for the first time
+* If updating to the latest version run the following commands
+    * `git checkout master`
+    * `git pull origin master`
+        * If that causes any problems `git reset --hard origin/master`
+    * `rake upgrade`
+
+Usage
+---------------
+
+Write your library, document them as you normally would. `include Rubycom` at the bottom.
+Optionally `#!/usr/bin/env ruby` at the top.
+
+Now any singleton methods `def self.method_name` will be available to call from the terminal.
+
+Calling `ruby ./path/to/module.rb <command_name>` will automatically discover and run your `<command_name>` singleton method.
+If no method is found by the given name, a usage print out will be given including a summary of each command available
+and it's description from the corresponding method's comments.
+
+Calling a valid command with incorrect arguments will produce a usage print out for the matched method.
+Rubycom will include as much documentation on the command line as you provide in your method comments. Currently Rubycom
+only handles YardDoc style comments for discovering the parameter and return documentation. All other commentary will be
+included as part of the command description. In the absence of YardDoc annotations, Rubycom will generate a clean usage
+text which may work for your method doc even though Rubycom is not specifically parsing it.
+
+
+#####Special commands
+
+| Command | Description | Options |
+| ------- |:-----------:| -------:|
+| `ruby ./path/to/module.rb help [command_name]` | Will print out usage for the module or optionally the specified command.||
+| `ruby ./path/to/module.rb register_completions ` | Setup bash tab completion ||
+| `ruby ./path/to/module.rb tab_complete [text]` | Print a list of possible matches for a given word ||
+
+###Arguments
+
+When using Rubycom's default modules:
+* Arguments are automatically parsed from the command line using Rubycom's ArgParse module and converted to Ruby types
+by Ruby's core Yaml module.
+* Arguments will be passed to your method in order of their appearance on the command line. With smart parsing for
+option arguments and flags.
+* If you specify a default value for a parameter in your method, then Rubycom will look for a named option argument in
+the command line which matches the parameter's name or the first letter in the parameter name if it is unique among the
+other method parameters.
+* Users may call out option parameters in any order using `--<param_name>=<value>`, `--<param_name> = <value>`, or
+`--<param_name> <value>`
+    * Rubycom attempts to handle short names for optional parameters so specifying `-<p> <value>` or `-<param> <value>`
+        is equivalent to `--<parameter> <value>` if the characters uniquely match a parameter name in the called method.
+* Any parameter which is not mentioned in the command line will receive one of the remaining, unnamed arguments in order
+of appearance.
+* Optional parameters which do not get overridden either by a named optional argument or an available unnamed command line
+    argument will be filled by their default as usual.
+* If a rest parameter `*param_name` is defined in the method being called, any remaining arguments will be passed to the
+    rest parameter after the required and optional parameters are filled.
+
+Raison d'etre
+---------------
+
+* Command line scripts written from scratch often include redundant ARGV parsing code, little or no testing, and slim documentation.
+  Development speed is important and setting up a properly documented and tested terminal interface takes a while.
+* OptionParser and the like help script authors define options for a script.
+  They provide structure to the redundant code and slightly easier argument specification.
+* Thor and the like provide a framework the script author will extend to create command line tools.
+  The Prescriptive approach creates consistency but requires the script author to learn the framework and conform.
+
+While these are things do help, we are still writing redundant code and tightly coupling the functional code to the
+interface which presents it. We also lack a generic command line parser which, if available, could help encourage
+Rubyists to standardize command line inputs.
+
+So, what to do?
+
+...Ruby is interpreted...use the source.
+
+Rather than making concessions for the presentation and tightly coupling the functional code
+to the interface, it would be nice if a script author could simply write their code and attach the interface to it.
+
+
+How it works
+---------------
+Rubycom attaches the CLI to the functional code. The author is free to write the functional code as any other.
+If a library needs to be accessible from the terminal, just `include Rubycom` at the bottom of the main Module and run
+the ruby file.
+
+* Methods are made accessible from the terminal.
+* ARGV is parsed for a method to run and arguments.
+* Usage documentation is pulled from method comments.
+* Method parameters become required CLI arguments.
+* Optional (defaulted) parameters become CLI options.
+* Tab completion support if the user has registered it for the file.
+
+The result is a library which can be consumed easily from other classes/modules and which is accessible from the command line.
+
+Customizing Rubycom
+---------------
+
+Note: The plugin_options hash is currently taking Modules and calling specific methods on them. This will change to a
+Symbol => Proc mapping soon. Please log an issue on [GitHub](https://github.com/dannypurcell/rubycom/issues) if you
+want this right away.
+
+Rubycom is designed to fit several different ways of calling command line utilities and to respect many of the
+strong conventions regarding command line semantics. While Rubycom's default functionality should fit many common use
+cases it is also built in a modular fashion such that the core functionality can be easily adapted to fit specific
+requirements or user preferences.
+
+* Calling Rubycom via `include Rubycom` will attempt to execute the default functionality.
+* Alternately, calling `Rubycom.run_command(base, args=[], plugins_options={})` directly enables the user to inject
+custom modules for specific portions of the execution via the plugin_options parameter.
+
+#####Plugin Module Contracts
+
+| Key | Expected Inputs | Expected Outputs |
+| -------------- |:---------------:|:----------------:|
+| :arguments | ARGV | A data structure representing the arguments, options, and flags |
+| :discover | The Module which included Rubycom and a parsed command line | A Method or Module representing the command which should be run  |
+| :documentation | The command to run and the :source plugin | The command matched to it's documentation |
+| :source | A Module or Method object | The source code for that reference |
+| :parameters | A command, a parsed command line, and the command documentation | The command parameters matched to their values for this run |
+| :executor | A command to execute and the command parameters matched to their values for this run | The result of a call to the given method with the given parameters |
+| :output | The command result | Some output handling action |
+| :interface | A command and it's documentation | A string representing the usage text to present in a terminal |
+| :error | An Error and a String representing usage text | Some error handling action |
+
+

data/Rakefile

@@ -11,11 +11,11 @@ task :clean do
 end
 
 task :bundle do
-  system("bundle install")
+  system('bundle install')
 end
 
 Rake::TestTask.new do |t|
-  t.libs << "test"
+  t.libs << 'test'
   t.test_files = FileList['test/*/*_test.rb']
   t.verbose = true
 end
@@ -23,10 +23,10 @@ end
 YARD::Rake::YardocTask.new
 
 task :package => [:clean, :bundle, :test, :yard] do
-  gem_specs = Dir.glob("**/*.gemspec")
+  gem_specs = Dir.glob('**/*.gemspec')
   gem_specs.each { |gem_spec|
     system("gem build #{gem_spec}")
-    raise "Error during build phase" if $?.exitstatus != 0
+    raise 'Error during build phase' if $?.exitstatus != 0
   }
 end
 
@@ -36,12 +36,12 @@ task :install => :package do
 end
 
 task :upgrade => :package do
-  system("gem uninstall rubycom -a")
+  system('gem uninstall rubycom -a')
   load "#{File.expand_path(File.dirname(__FILE__))}/lib/rubycom/version.rb"
   system("gem install #{File.expand_path(File.dirname(__FILE__))}/rubycom-#{Rubycom::VERSION}.gem")
 end
 
-task :version_set, [:version] do |t, args|
+task :version_set, [:version] do |_, args|
   raise "Must provide a version.\n If you called 'rake version_set 1.2.3', try 'rake version_set[1.2.3]'" if args[:version].nil? || args[:version].empty?
 
   version_file = <<-END.gsub(/^ {4}/, '')
@@ -54,21 +54,21 @@ task :version_set, [:version] do |t, args|
     file.write(version_file)
   }
   file_text = File.read("#{File.expand_path(File.dirname(__FILE__))}/lib/rubycom/version.rb")
-  raise "Could not update version file" if file_text != version_file
+  raise 'Could not update version file' if file_text != version_file
 end
 
-task :release, [:version] => [:version_set, :package] do |t, args|
-  system("git clean -f")
-  system("git add .")
+task :release, [:version] => [:version_set, :package] do |_, args|
+  system('git clean -f')
+  system('git add .')
   system("git commit -m\"Version to #{args[:version]}\"")
   if $?.exitstatus == 0
     system("git tag -a v#{args[:version]} -m\"Version #{args[:version]} Release\"")
     if $?.exitstatus == 0
-      system("git push origin master --tags")
+      system('git push origin master --tags')
       if $?.exitstatus == 0
         load "#{File.expand_path(File.dirname(__FILE__))}/lib/rubycom/version.rb"
         system("gem push #{File.expand_path(File.dirname(__FILE__))}/rubycom-#{Rubycom::VERSION}.gem")
       end
     end
   end
-end
+end

data/lib/rubycom.rb

@@ -1,226 +1,156 @@
-require "#{File.dirname(__FILE__)}/rubycom/arguments.rb"
-require "#{File.dirname(__FILE__)}/rubycom/commands.rb"
-require "#{File.dirname(__FILE__)}/rubycom/documentation.rb"
-require "#{File.dirname(__FILE__)}/rubycom/version.rb"
-
-require 'yaml'
-
-# Upon inclusion in another Module, Rubycom will attempt to call a method in the including module by parsing
-# ARGV for a method name and a list of arguments.
-# If found Rubycom will call the method specified in ARGV with the parameters parsed from the remaining arguments
-# If a Method match can not be made, Rubycom will print help instead by parsing source comments from the including
-# module or it's included modules.
-module Rubycom
-  class CLIError < StandardError;
-  end
-
-  # Detects that Rubycom was included in another module and calls Rubycom#run
-  #
-  # @param [Module] base the module which invoked 'include Rubycom'
-  def self.included(base)
-    base_file_path = caller.first.gsub(/:\d+:.+/, '')
-    if base.class == Module && (base_file_path == $0 || self.is_executed_by_gem?(base_file_path))
-      base.module_eval {
-        Rubycom.run(base, ARGV)
-      }
-    end
-  end
-
-  # Determines whether the including module was executed by a gem binary
-  #
-  # @param [String] base_file_path the path to the including module's source file
-  def self.is_executed_by_gem?(base_file_path)
-    Gem.loaded_specs.map{|k,s|
-      {k => {name: "#{s.name}-#{s.version}", executables: s.executables}}
-    }.reduce(&:merge).map{|k,s|
-      base_file_path.include?(s[:name]) && s[:executables].include?(File.basename(base_file_path))
-    }.flatten.reduce(&:|)
-  end
-
-  # Looks up the command specified in the first arg and executes with the rest of the args
-  #
-  # @param [Module] base the module which invoked 'include Rubycom'
-  # @param [Array] args a String Array representing the command to run followed by arguments to be passed
-  def self.run(base, args=[])
-    begin
-      raise CLIError, "Invalid base class invocation: #{base}" if base.nil?
-      command = args[0] || nil
-      arguments = args[1..-1] || []
-
-      case command
-        when 'register_completions'
-          puts self.register_completions(base)
-        when 'tab_complete'
-          puts self.tab_complete(base, args)
-        when 'help'
-          help_topic = arguments[0]
-          if help_topic.nil?
-            usage = Documentation.get_usage(base)
-            default_usage = Documentation.get_default_commands_usage
-            puts usage
-            puts default_usage
-            return usage+"\n"+default_usage
-          elsif help_topic == 'job'
-            usage = Documentation.get_job_usage(base)
-            puts usage
-            return usage
-          elsif help_topic == 'register_completions'
-            usage = Documentation.get_register_completions_usage(base)
-            puts usage
-            return usage
-          elsif help_topic == 'tab_complete'
-            usage = Documentation.get_tab_complete_usage(base)
-            puts usage
-            return usage
-          else
-            cmd_usage = Documentation.get_command_usage(base, help_topic, arguments[1..-1])
-            puts cmd_usage
-            return cmd_usage
-          end
-        when 'job'
-          begin
-            raise CLIError, 'No job specified' if arguments[0].nil? || arguments[0].empty?
-            job_hash = YAML.load_file(arguments[0])
-            job_hash = {} if job_hash.nil?
-            STDOUT.sync = true
-            if arguments.delete('-test') || arguments.delete('--test')
-              puts "[Test Job #{arguments[0]}]"
-              job_hash['steps'].each { |step, step_hash|
-                step = "[Step: #{step}/#{job_hash['steps'].length}]"
-                context = step_hash.select { |key| key!="cmd" }.map { |key, val| "[#{key}: #{val}]" }.join(' ')
-                env = job_hash['env'] || {}
-                env.each { |key, val| step_hash['cmd'].gsub!("env[#{key}]", "#{((val.class == String)&&(val.match(/\w+/))) ? "\"#{val}\"" : val}") }
-                cmd = "[cmd: #{step_hash['cmd']}]"
-                puts "#{[step, context, cmd].join(' ')}"
-              }
-            else
-              puts "[Job #{arguments[0]}]"
-              job_hash['steps'].each { |step, step_hash|
-                step = "[Step: #{step}/#{job_hash['steps'].length}]"
-                context = step_hash.select { |key| key!="cmd" }.map { |key, val| "[#{key}: #{val}]" }.join(' ')
-                env = job_hash['env'] || {}
-                env.each { |key, val| step_hash['cmd'].gsub!("env[#{key}]", "#{((val.class == String)&&(val.match(/\w+/))) ? "\"#{val}\"" : val}") }
-                cmd = "[cmd: #{step_hash['cmd']}]"
-                puts "#{[step, context, cmd].join(' ')}"
-                system(step_hash['cmd'])
-              }
-            end
-          rescue CLIError => e
-            $stderr.puts e
-          end
-        else
-          output = self.run_command(base, command, arguments)
-          std_output = nil
-          std_output = output.to_yaml unless [String, NilClass, TrueClass, FalseClass, Fixnum, Float, Symbol].include?(output.class)
-          puts std_output || output
-          return output
-      end
-
-    rescue CLIError => e
-      $stderr.puts e
-      $stderr.puts Documentation.get_summary(base)
-    end
-  end
-
-  # Handles the method call according to the given arguments. If the specified command is a Module then a recursive search
-  # is performed until a Method is found in the specified arguments.
-  #
-  # @param [Module] base the module which invoked 'include Rubycom'
-  # @param [String] command the name of the command to call, may be a Module name or a Method
-  # @param [Array] arguments a String Array representing the arguments for the given command
-  def self.run_command(base, command, arguments=[])
-    arguments = [] if arguments.nil?
-    raise CLIError, 'No command specified.' if command.nil? || command.length == 0
-    begin
-      raise CLIError, "Invalid Command: #{command}" unless Commands.get_top_level_commands(base).include? command.to_sym
-      if base.included_modules.map { |mod| mod.name.to_sym }.include?(command.to_sym)
-        self.run_command(eval(command), arguments[0], arguments[1..-1])
-      else
-        self.call_method(base, command, arguments)
-      end
-    rescue CLIError => e
-      $stderr.puts e
-      $stderr.puts Documentation.get_command_usage(base, command, arguments)
-    end
-  end
-
-  # Calls the given command on the given Module after parsing the given Array of arguments
-  #
-  # @param [Module] base the module wherein the specified command is defined
-  # @param [String] command the name of the Method to call
-  # @param [Array] arguments a String Array representing the arguments for the given command
-  # @return the result of the specified Method call
-  def self.call_method(base, command, arguments=[])
-    method = base.public_method(command.to_sym)
-    raise CLIError, "No public method found for symbol: #{command.to_sym}" if method.nil?
-    param_defs = Arguments.get_param_definitions(method)
-    args = Arguments.resolve(param_defs, arguments)
-    flatten = false
-    params = method.parameters.map { |arr| flatten = true if arr[0]==:rest; args[arr[1]] }
-    if flatten
-      rest_arr = params.delete_at(-1)
-      if rest_arr.respond_to?(:each)
-        rest_arr.each { |arg| params << arg }
-      else
-        params << rest_arr
-      end
-    end
-    (arguments.nil? || arguments.empty?) ? method.call : method.call(*params)
-  end
-
-  # Inserts a tab completion into the current user's .bash_profile with a command entry to register the function for
-  # the current running ruby file
-  #
-  # @param [Module] base the module which invoked 'include Rubycom'
-  # @return [String] a message indicating the result of the command
-  def self.register_completions(base)
-    completion_function = <<-END.gsub(/^ {4}/, '')
-
-    _#{base}_complete() {
-      COMPREPLY=()
-      local completions="$(ruby #{File.absolute_path($0)} tab_complete ${COMP_WORDS[*]} 2>/dev/null)"
-      COMPREPLY=( $(compgen -W "$completions") )
-    }
-    complete -o bashdefault -o default -o nospace -F _#{base}_complete #{$0.split('/').last}
-    END
-
-    already_registered = File.readlines("#{Dir.home}/.bash_profile").map { |line| line.include?("_#{base}_complete()") }.reduce(:|) rescue false
-    if already_registered
-      "Completion function for #{base} already registered."
-    else
-      File.open("#{Dir.home}/.bash_profile", 'a+') { |file|
-        file.write(completion_function)
-      }
-      "Registration complete, run 'source #{Dir.home}/.bash_profile' to enable auto-completion."
-    end
-  end
-
-  # Discovers a list of possible matches to the given arguments
-  # Intended for use with bash tab completion
-  #
-  # @param [Module] base the module which invoked 'include Rubycom'
-  # @param [Array] arguments a String Array representing the arguments to be matched
-  # @return [Array] a String Array including the possible matches for the given arguments
-  def self.tab_complete(base, arguments)
-    arguments = [] if arguments.nil?
-    args = (arguments.include?("tab_complete")) ? arguments[2..-1] : arguments
-    matches = ['']
-    if args.nil? || args.empty?
-      matches = Rubycom::Commands.get_top_level_commands(base).map { |sym| sym.to_s }
-    elsif args.length == 1
-      matches = Rubycom::Commands.get_top_level_commands(base).map { |sym| sym.to_s }.select { |word| !word.match(/^#{args[0]}/).nil? }
-      if matches.size == 1 && matches[0] == args[0]
-        matches = self.tab_complete(Kernel.const_get(args[0].to_sym), args[1..-1])
-      end
-    elsif args.length > 1
-      begin
-        matches = self.tab_complete(Kernel.const_get(args[0].to_sym), args[1..-1])
-      rescue Exception
-        matches = ['']
-      end
-    end unless base.nil?
-    matches = [''] if matches.nil? || matches.include?(args[0])
-    matches
-  end
-
-end
+require "#{File.dirname(__FILE__)}/rubycom/completions.rb"
+require "#{File.dirname(__FILE__)}/rubycom/arg_parse.rb"
+require "#{File.dirname(__FILE__)}/rubycom/singleton_commands.rb"
+require "#{File.dirname(__FILE__)}/rubycom/sources.rb"
+require "#{File.dirname(__FILE__)}/rubycom/yard_doc.rb"
+require "#{File.dirname(__FILE__)}/rubycom/parameter_extract.rb"
+require "#{File.dirname(__FILE__)}/rubycom/executor.rb"
+require "#{File.dirname(__FILE__)}/rubycom/output_handler.rb"
+require "#{File.dirname(__FILE__)}/rubycom/command_interface.rb"
+require "#{File.dirname(__FILE__)}/rubycom/error_handler.rb"
+
+require 'yaml'
+
+# Upon inclusion in another Module, Rubycom will attempt to call a method in the including module by parsing
+# ARGV for a method name and a list of arguments.
+# If found Rubycom will call the method specified in ARGV with the parameters parsed from the remaining arguments
+# If a Method match can not be made, Rubycom will print help instead by parsing code comments from the including
+# module.
+module Rubycom
+
+  # Base class for all Rubycom errors
+  class RubycomError < StandardError
+  end
+  # To be thrown in case of an error while parsing arguments
+  class ArgParseError < RubycomError;
+  end
+  # To be thrown in case of an error while executing a method
+  class ExecutorError < RubycomError;
+  end
+  # To be thrown in case of an error while extracting parameters
+  class ParameterExtractError < RubycomError;
+  end
+
+
+  # Determines whether the including module was executed by a gem binary
+  #
+  # @param [String] base_file_path the path to the including module's source file
+  # @return [Boolean] true|false
+  def self.is_executed_by_gem?(base_file_path)
+    Gem.loaded_specs.map { |k, s|
+      {k => {name: "#{s.name}-#{s.version}", executables: s.executables}}
+    }.reduce({}, &:merge).map { |_, s|
+      base_file_path.include?(s[:name]) && s[:executables].include?(File.basename(base_file_path))
+    }.flatten.reduce(&:|)
+  end
+
+  # Detects that Rubycom was included in another module and calls Rubycom#run
+  #
+  # @param [Module] base the module which invoked 'include Rubycom'
+  def self.included(base)
+    base_file_path = caller.first.gsub(/:\d+:.+/, '')
+    if base.class == Module && (base_file_path == $0 || self.is_executed_by_gem?(base_file_path))
+      base.module_eval {
+        Rubycom.run(base, ARGV)
+      }
+    end
+    nil
+  end
+
+  # Main entry point for Rubycom. Uses #run_command to discover and run commands
+  #
+  # @param [Module] base this will be used to determine available commands
+  # @param [Array] args a String Array representing the command to run followed by arguments to be passed
+  # @return [Object] the result of calling #run_command! or a String representing a default help message
+  def self.run(base, args=[])
+    begin
+      raise RubycomError, "base should should not be nil" if base.nil?
+      case args[0]
+        when 'register_completions'
+          puts Rubycom::Completions.register_completions(base)
+        when 'tab_complete'
+          puts Rubycom::Completions.tab_complete(base, args, Rubycom::SingletonCommands)
+        when 'help'
+          help_topic = args[1]
+          if help_topic == 'register_completions'
+            puts "Usage: #{base} register_completions"
+          elsif help_topic == 'tab_complete'
+            usage = "Usage: #{base} tab_complete <word>\nParameters:\n  [String] word the word or partial word to find matches for"
+            puts usage
+            return usage
+          else
+            self.run_command(base, (args[1..-1] << '-h'))
+            $stderr.puts <<-END.gsub(/^ {12}/, '')
+            Default Commands:
+              help                 - prints this help page
+              register_completions - setup bash tab completion
+              tab_complete         - print a list of possible matches for a given word
+            END
+          end
+        else
+          self.run_command(base, args)
+      end
+    rescue RubycomError => e
+      $stderr.puts e
+    end
+  end
+
+  # Calls the given process method with the given base, args, and steps.
+  #
+  # @param [Module] base the Module containing the Method or sub Module to run
+  # @param [Array] args a String Array representing the command to run followed by arguments to be passed
+  # @param [Hash] steps should have the following keys mapped to Methods or Procs which will be called by the process method
+  # :arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error
+  # @param [Method|Proc] process a Method or Proc which calls the step_methods in order to parse args and run a command on base
+  # @return [Object] the result of calling the method selected by the :discover method using the args from the :arguments method
+  # matched to parameters by the :parameters method
+  def self.run_command(base, args=[], steps={}, process=Rubycom.public_method(:process))
+    process.call(base, args, steps)
+  end
+
+  # Calls the given steps with the required parameters and ordering to locate and call a method on base or one of it's
+  # included modules. This method expresses a procedure and calls the methods in steps to execute each step in the procedure.
+  # If not overridden in steps, then method called for each step will be determined by the return from #step_methods.
+  #
+  # @param [Module] base the Module containing the Method or sub Module to run
+  # @param [Array] args a String Array representing the command to run followed by arguments to be passed
+  # @param [Hash] steps should have the following keys mapped to Methods or Procs which will be called by the process method
+  # :arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error
+  # @return [Object] the result of calling the method selected by the :discover method using the args from the :arguments method
+  # matched to parameters by the :parameters method
+  def self.process(base, args=[], steps={})
+    steps = self.step_methods.merge(steps)
+
+    parsed_command_line = steps[:arguments].call(args)
+    command = steps[:discover].call(base, parsed_command_line)
+    begin
+      command_doc = steps[:documentation].call(command, steps[:source])
+      parameters = steps[:parameters].call(command, parsed_command_line, command_doc)
+      command_result = steps[:executor].call(command, parameters)
+      steps[:output].call(command_result)
+    rescue RubycomError => e
+      cli_output = steps[:interface].call(command, command_doc)
+      steps[:error].call(e, cli_output)
+    end
+    command_result
+  end
+
+  # Convenience call for use with #process when the default Rubycom functionality is required.
+  #
+  # @return [Hash] mapping :arguments, :discover, :documentation, :source, :parameters, :executor, :output, :interface, :error
+  # to the default methods which carry out the step referred to by the key.
+  def self.step_methods()
+    {
+        arguments: Rubycom::ArgParse.public_method(:parse_command_line),
+        discover: Rubycom::SingletonCommands.public_method(:discover_command),
+        documentation: Rubycom::YardDoc.public_method(:document_command),
+        source: Rubycom::Sources.public_method(:source_command),
+        parameters: Rubycom::ParameterExtract.public_method(:extract_parameters),
+        executor: Rubycom::Executor.public_method(:execute_command),
+        output: Rubycom::OutputHandler.public_method(:process_output),
+        interface: Rubycom::CommandInterface.public_method(:build_interface),
+        error: Rubycom::ErrorHandler.public_method(:handle_error)
+    }
+  end
+
+end