rubycom 0.1.1 → 0.2.0

data/README.md

@@ -21,6 +21,89 @@ by simply including Rubycom at the bottom.
 * Command consoles can be built up by including other modules before including Rubycom.
 * Included modules become commands, their public singleton methods become sub-commands.
 
+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
 ---------------
@@ -53,9 +136,7 @@ The result is a function library which can be consumed easily from other classes
 
 Coming Soon
 ---------------
-* Run Pre-configured sets of commands from a yaml file by calling <script.rb> job <job_yaml>
-* Job help/usage output will include descriptions from command for each step
-* Build a job yaml by running each command in sequence with a special option --job_add <path_to_yaml>
+* 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>
-    * --job_rm <path_to_yaml>
+    * --job_update <path_to_yaml>[:step_number]
+    * --job_remove <path_to_yaml>[:step_number]

data/Rakefile

@@ -1,8 +1,14 @@
-require "bundler/gem_tasks"
-require 'rake/testtask'
+require "#{File.expand_path(File.dirname(__FILE__))}/lib/rubycom/version.rb"
 require 'yard'
 
-task :default => [:test, :yard, :package]
+task :default => [:package]
+
+task :clean do
+  FileUtils.rm_rf('./doc')
+  FileUtils.rm_rf('./.yardoc')
+  FileUtils.rm_rf('./pkg')
+  FileUtils.rm(Dir.glob('./rubycom-*.gem'))
+end
 
 task :test do
   test_files = Dir.glob("**/test/*/test_*.rb")
@@ -14,7 +20,7 @@ end
 
 YARD::Rake::YardocTask.new
 
-task :package => [:test, :yard] do
+task :package => [:clean, :test, :yard] do
   gem_specs = Dir.glob("**/*.gemspec")
   gem_specs.each { |gem_spec|
     system("gem build #{gem_spec}")
@@ -23,9 +29,9 @@ task :package => [:test, :yard] do
 end
 
 task :install => :package do
-  system "gem install ./rubycom-#{Rubycom::VERSION}"
+  system("gem install rubycom-#{Rubycom::VERSION}")
 end
 
 task :release => :package do
-  system "gem push rubycom-#{Rubycom::VERSION}"
+  system("gem push ./rubycom-#{Rubycom::VERSION}.gem")
 end

data/lib/rubycom/version.rb

@@ -1,3 +1,3 @@
 module Rubycom
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/rubycom.rb

@@ -1,5 +1,6 @@
 require "#{File.expand_path(File.dirname(__FILE__))}/rubycom/version.rb"
 require 'yaml'
+require 'find'
 require 'method_source'
 
 # Upon inclusion in another Module, Rubycom will attempt to call a method in the including module by parsing
@@ -8,7 +9,8 @@ require 'method_source'
 # 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
+  class CLIError < StandardError;
+  end
 
   # Detects that Rubycom was included in another module and calls Rubycom#run
   #
@@ -44,6 +46,36 @@ module Rubycom
           puts cmd_usage
           return cmd_usage
         end
+      elsif command == 'job'
+        begin
+          raise CLIError, 'No job specified' if arguments[0].nil? || arguments[0].empty?
+          job_hash = YAML.load_file(arguments[0])
+          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.map { |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.map { |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
@@ -53,7 +85,8 @@ module Rubycom
       end
 
     rescue CLIError => e
-      abort "#{e}\n#{self.get_summary(base)}"
+      $stderr.puts e
+      $stderr.puts self.get_summary(base)
     end
   end
 
@@ -64,36 +97,20 @@ module Rubycom
   # @param [Array] arguments a String Array representing the arguments for the given command
   def self.run_command(base, command, arguments=[])
     raise CLIError, 'No command specified.' if command.nil? || command.length == 0
-    command_sym = command.to_sym
-    valid_commands = self.get_top_level_commands(base)
-    raise CLIError, "Invalid Command: #{command}" unless valid_commands.include? command_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
-      method = base.public_method(command_sym)
-      raise CLIError, "No public method found for symbol: #{command_sym}" if method.nil?
-      parameters = self.get_param_definitions(method)
-      params_hash = self.parse_arguments(parameters, arguments)
-      params = []
-      method.parameters.each { |type, name|
-        if type == :rest
-          if params_hash[name].class == Array
-            params_hash[name].each { |arg|
-              params << arg
-            }
-          else
-            params << params_hash[name]
-          end
-        else
-          params << params_hash[name]
-        end
-      }
-      if arguments.nil? || arguments.empty?
-        output = method.call
+    begin
+      raise CLIError, "Invalid Command: #{command}" unless self.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
-        output = method.call(*params)
+        method = base.public_method(command.to_sym)
+        raise CLIError, "No public method found for symbol: #{command.to_sym}" if method.nil?
+        param_defs = self.get_param_definitions(method)
+        args = self.parse_arguments(param_defs, arguments)
+        (arguments.nil? || arguments.empty?) ? method.call : method.call(*method.parameters.map { |arr| args[arr[1]]}.flatten)
       end
-      output
+    rescue CLIError => e
+      $stderr.puts e
+      $stderr.puts self.get_command_usage(base, command, arguments)
     end
   end
 
@@ -107,58 +124,32 @@ module Rubycom
   # @param [Array] arguments an Array of Strings representing the arguments to be parsed
   # @return [Hash] a Hash mapping the defined parameters to their matching argument values
   def self.parse_arguments(parameters={}, arguments=[])
-    arguments = (!arguments.nil? && arguments.respond_to?(:each)) ? arguments : []
-    args_l = arguments.length
-    req_l = 0
-    opt_l = 0
-    has_rest_param = false
-    parameters.each_value { |def_hash|
-      req_l += 1 if def_hash[:type] == :req
-      opt_l += 1 if def_hash[:type] == :opt
-      has_rest_param = true if def_hash[:type] == :rest
-      def_hash[:default] = self.parse_arg(def_hash[:default])[:arg] unless def_hash[:default] == :nil_rubycom_required_param
-    }
-    raise CLIError, "Wrong number of arguments. Expected at least #{req_l}, received #{args_l}" if args_l < req_l
-    unless has_rest_param
-      raise CLIError, "Wrong number of arguments. Expected at most #{req_l + opt_l}, received #{args_l}" if args_l > (req_l + opt_l)
-    end
-
-    args = []
-    arguments.each { |arg|
-      args << self.parse_arg(arg)
-    }
+    raise CLIError, 'parameters may not be nil' if parameters.nil?
+    raise CLIError, 'arguments may not be nil' if arguments.nil?
+    types = parameters.values.group_by { |hsh| hsh[:type] }.map { |type, defs_arr| Hash[type, defs_arr.length] }.reduce(&:merge) || {}
+    raise CLIError, "Wrong number of arguments. Expected at least #{types[:req]}, received #{arguments.length}" if arguments.length < (types[:req]||0)
+    raise CLIError, "Wrong number of arguments. Expected at most #{(types[:req]||0) + (types[:opt]||0)}, received #{arguments.length}" if types[:rest].nil? && (arguments.length > ((types[:req]||0) + (types[:opt]||0)))
 
-    parsed_args = []
-    parsed_options = {}
-    args.each { |item|
-      key = item.keys.first
-      val = item.values.first
-      if key == :arg
-        parsed_args << val
-      else
-        parsed_options[key]=val
-      end
-    }
+    sorted_args = arguments.map { |arg|
+      Rubycom.parse_arg(arg)
+    }.group_by { |hsh|
+      hsh.keys.first
+    }.map { |key, arr|
+      (key == :rubycom_non_opt_arg) ? Hash[key, arr.map { |hsh| hsh.values }.flatten] : Hash[key, arr.map { |hsh| hsh.values.first }.reduce(&:merge)]
+    }.reduce(&:merge) || {}
 
-    result_hash = {}
-    parameters.each { |param_name, def_hash|
+    parameters.map { |param_sym, def_hash|
       if def_hash[:type] == :req
-        raise CLIError, "No argument available for #{param_name}" if parsed_args.length == 0
-        result_hash[param_name] = parsed_args.shift
+        raise CLIError, "No argument available for #{param_sym}" if sorted_args[:rubycom_non_opt_arg].nil? || sorted_args[:rubycom_non_opt_arg].length == 0
+        Hash[param_sym, sorted_args[:rubycom_non_opt_arg].shift]
       elsif def_hash[:type] == :opt
-        result_hash[param_name] = parsed_options[param_name]
-        result_hash[param_name] = parsed_args.shift if result_hash[param_name].nil?
-        result_hash[param_name] = parameters[param_name][:default] if result_hash[param_name].nil?
+        Hash[param_sym, ((sorted_args[param_sym]) ? sorted_args[param_sym] : ((sorted_args[:rubycom_non_opt_arg].shift || parameters[param_sym][:default]) rescue parameters[param_sym][:default]))]
       elsif def_hash[:type] == :rest
-        if parsed_options[param_name].nil?
-          result_hash[param_name] = parsed_args
-          parsed_args = []
-        else
-          result_hash[param_name] = parsed_options[param_name]
-        end
+        ret = Hash[param_sym, ((sorted_args[param_sym]) ? sorted_args[param_sym] : sorted_args[:rubycom_non_opt_arg])]
+        sorted_args[:rubycom_non_opt_arg] = []
+        ret
       end
-    }
-    result_hash
+    }.reduce(&:merge)
   end
 
   # Uses YAML.load to parse the given String
@@ -166,41 +157,19 @@ module Rubycom
   # @param [String] arg a String representing the argument to be parsed
   # @return [Object] the result of parsing the given arg with YAML.load
   def self.parse_arg(arg)
-    param_name = 'arg'
-    arg_val = "#{arg}"
-    result = {}
-    return result[param_name.to_sym]=nil if arg.nil?
-    if arg.is_a? String
-      raise CLIError, "Improper option specification, options must start with one or two dashes. Received: #{arg}" if (arg.match(/^[-]{3,}\w+/) != nil)
-      if arg.match(/^[-]{1,}\w+/) == nil
-        raise CLIError, "Improper option specification, options must start with one or two dashes. Received: #{arg}" if (arg.match(/^\w+=/) != nil)
-
-      else
-        if arg.match(/^--/) != nil
-          arg = arg.reverse.chomp('--').reverse
-        elsif arg.match(/^-/) != nil
-          arg = arg.reverse.chomp('-').reverse
-        end
-
-        if arg.match(/^\w+=/) != nil
-          arg_arr = arg.split('=')
-          param_name = arg_arr.shift.strip
-          arg_val = arg_arr.join('=').lstrip
-        elsif arg.match(/^\w+\s+\S+/) != nil
-          arg_arr = arg.split(' ')
-          param_name = arg_arr.shift
-          arg_val = arg_arr.join(' ')
-        end
-      end
-    end
-
-    val = YAML.load(arg_val) rescue nil
-    if val.nil?
-      result[param_name.to_sym] = "#{arg_val}"
+    return Hash[:rubycom_non_opt_arg, nil] if arg.nil?
+    if arg.is_a?(String) && ((arg.match(/^[-]{3,}\w+/) != nil) || ((arg.match(/^[-]{1,}\w+/) == nil) && (arg.match(/^\w+=/) != nil)))
+      raise CLIError, "Improper option specification, options must start with one or two dashes. Received: #{arg}"
+    elsif arg.is_a?(String) && arg.match(/^(-|--)\w+[=|\s]{1}/) != nil
+      k, v = arg.partition(/^(-|--)\w+[=|\s]{1}/).select { |part|
+        !part.empty?
+      }.each_with_index.map { |part, index|
+        index == 0 ? part.chomp('=').gsub(/^--/, '').gsub(/^-/, '').strip.to_sym : (YAML.load(part) rescue "#{part}")
+      }
+      Hash[k, v]
     else
-      result[param_name.to_sym] = val
+      Hash[:rubycom_non_opt_arg, (YAML.load("#{arg}") rescue "#{arg}")]
     end
-    result
   end
 
   # Retrieves the summary for each command method in the given Module
@@ -208,25 +177,13 @@ module Rubycom
   # @param [Module] base the module which invoked 'include Rubycom'
   # @return [String] the summary for each command method in the given Module
   def self.get_summary(base)
-    longest_name_length = self.get_longest_command_name(base).length
     self.get_top_level_commands(base).each_with_index.map { |sym, index|
-      separator = self.get_separator(sym, longest_name_length)
-      if index == 0
-        "Commands:\n" << self.get_command_summary(base, sym, separator)
-      else
-        self.get_command_summary(base, sym, separator)
-      end
+      "#{"Commands:\n" if index == 0}" << self.get_command_summary(base, sym, self.get_separator(sym, self.get_longest_command_name(base).length))
     }.reduce(:+) or "No Commands found for #{base}."
   end
 
   def self.get_separator(sym, spacer_length=0)
-    cmd_name = sym.to_s
-    sep_length = spacer_length - cmd_name.length
-    separator = ""
-    sep_length.times {
-      separator << " "
-    }
-    separator << "  -  "
+    [].unshift(" " * (spacer_length - sym.to_s.length)).join << "  -  "
   end
 
   # Retrieves the summary for the given command_name
@@ -238,27 +195,23 @@ module Rubycom
     raise CLIError, "Can not get usage for #{command_name} with base: #{base||"nil"}" if base.nil? || !base.respond_to?(:included_modules)
     return 'No command specified.' if command_name.nil? || command_name.length == 0
     if base.included_modules.map { |mod| mod.name.to_sym }.include?(command_name.to_sym)
-      desc = "Sub-Module-Command"
+      mod_const = Kernel.const_get(command_name.to_sym)
+      desc = File.read(mod_const.public_method(mod_const.singleton_methods().first).source_location.first).split(//).reduce(""){|str,c|
+        unless str.gsub("\n",'').gsub(/\s+/,'').include?("module#{mod_const}")
+          str << c
+          end
+          str
+      }.split("\n").select{|line| line.strip.match(/^#/)}.map{|line| line.strip.gsub(/^#+/,'')}.join("\n")
     else
       raise CLIError, "Invalid command for #{base}, #{command_name}" unless base.public_methods.include?(command_name.to_sym)
-      m = base.public_method(command_name.to_sym)
-      method_doc = self.get_doc(m)
-      desc = method_doc[:desc].join("\n")
+      desc = self.get_doc(base.public_method(command_name.to_sym))[:desc].join("\n") rescue nil
     end
     (desc.nil?||desc=='nil'||desc.length==0) ? "#{command_name}\n" : self.get_formatted_summary(command_name, desc, separator)
   end
 
   def self.get_formatted_summary(command_name, command_description, separator = '  -  ')
     width = 95
-    spacer = ""
-    command_name.to_s.split(//).each {
-      spacer << " "
-    }
-    sep_space = ""
-    separator.split(//).each {
-      sep_space << " "
-    }
-    prefix = "#{spacer}#{sep_space}"
+    prefix = command_name.to_s.split(//).map { " " }.join + separator.split(//).map { " " }.join
     line_width = width - prefix.length
     description_msg = command_description.gsub(/(.{1,#{line_width}})(?: +|$)\n?|(.{#{line_width}})/, "#{prefix}"+'\1\2'+"\n")
     "#{command_name}#{separator}#{description_msg.lstrip}"
@@ -294,17 +247,17 @@ module Rubycom
       m = base.public_method(command_name.to_sym)
       method_doc = self.get_doc(m)
 
-      <<-END.gsub(/^ {6}/, '')
-      Usage: #{m.name} #{self.get_param_usage(m)}
-      #{"Parameters:" unless m.parameters.empty?}
-          #{method_doc[:param].join("\n    ") unless method_doc[:param].nil?}
-      Returns:
-          #{method_doc[:return].join("\n    ") rescue 'void'}
-      END
+      msg = "Usage: #{m.name} #{self.get_param_usage(m)}\n"
+      msg << "#{"Parameters:"}\n" unless m.parameters.empty?
+      msg << "#{method_doc[:param].join("\n    ")}\n" unless method_doc[:param].nil?
+      msg << "#{"Returns:"}\n"  unless method_doc[:return].nil?
+      msg << "#{method_doc[:return].join("\n    ")}\n" unless method_doc[:return].nil?
+      msg
     end
   end
 
   def self.get_param_usage(method)
+    return "" if method.parameters.nil? || method.parameters.empty?
     method.parameters.map { |type, param| {type => param}
     }.group_by { |entry| entry.keys.first
     }.map { |key, val| Hash[key, val.map { |param| param.values.first }]
@@ -327,35 +280,29 @@ module Rubycom
   # @return [Hash] a Hash representing the given Method's parameters
   def self.get_param_definitions(method)
     raise CLIError, 'method must be an instance of the Method class' unless method.class == Method
-    source = method.source
-    method_name = method.name.to_s
-    source_lines = source.split("\n")
-    param_names = method.parameters.map { |param| param[1].to_s }
-    param_types = {}
-    method.parameters.each { |type, name| param_types[name] = type }
-    param_def_lines = {}
-    param_names.each { |name| param_def_lines[name] = source_lines.select { |line| line.include?(name) }.first }
-    param_definitions = {}
-    param_def_lines.each { |name, param_def_line|
-      param_candidates = param_def_line.gsub(/(def\s+self\.#{method_name}|def\s+#{method_name})/, '').lstrip.chomp.chomp(')').reverse.chomp('(').reverse
-      param_definitions[name.to_sym] = {}
-      param_definitions[name.to_sym][:def] = param_candidates.split(',').select { |candidate| candidate.include?(name) }.first
-      param_definitions[name.to_sym][:type] = param_types[name.to_sym]
-      if param_definitions[name.to_sym][:def].include?('=')
-        param_definitions[name.to_sym][:default] = param_definitions[name.to_sym][:def].split('=')[1..-1].join('=')
-      else
-        param_definitions[name.to_sym][:default] = :nil_rubycom_required_param
-      end
-    }
-    param_definitions
+    method.parameters.map { |param|
+      param[1].to_s
+    }.map { |param_name|
+      {param_name.to_sym => method.source.split("\n").select { |line| line.include?(param_name) }.first}
+    }.map { |param_hash|
+      param_def = param_hash.flatten[1].gsub(/(def\s+self\.#{method.name.to_s}|def\s+#{method.name.to_s})/, '').lstrip.chomp.chomp(')').reverse.chomp('(').reverse.split(',').map { |param_n| param_n.lstrip }.select { |candidate| candidate.include?(param_hash.flatten[0].to_s) }.first
+      Hash[
+          param_hash.flatten[0],
+          Hash[
+              :def, param_def,
+              :type, method.parameters.select { |arr| arr[1] == param_hash.flatten[0] }.flatten[0],
+              :default, (param_def.include?('=') ? YAML.load(param_def.split('=')[1..-1].join('=')) : :nil_rubycom_required_param)
+          ]
+      ]
+    }.reduce(&:merge) || {}
   end
 
   # Retrieves the given method's documentation from it's source code.
   #
   # @param [Method] method the Method who's documentation should be retrieved
   # @return [Hash] a Hash representing the given Method's documentation, documentation parsed as follows:
-  #                :desc = the first general method comment, :params = each @param comment, :return  = each @return comment,
-  #                :extended = all other general method comments and unrecognized annotations
+  #                :desc = the first general method comment lines,
+  #                :word = each @word comment (i.e.- a line starting with @param will be saved as :param => ["line"])
   def self.get_doc(method)
     method.comment.split("\n").map { |line|
       line.gsub(/#\s*/, '') }.group_by { |doc|
@@ -382,17 +329,13 @@ module Rubycom
   # @return [Hash] a Hash of Symbols representing the command methods in the given base and it's included modules (if all=true)
   def self.get_commands(base, all=true)
     return {} if base.nil? || !base.respond_to?(:singleton_methods) || !base.respond_to?(:included_modules)
-    excluded_commands = [:included, :extended]
-    excluded_modules = [:Rubycom]
     {
         base.name.to_sym => {
-            commands: base.singleton_methods(true).select { |sym| !excluded_commands.include?(sym) },
-            inclusions: base.included_modules.select { |mod| !excluded_modules.include?(mod.name.to_sym) }.map { |mod|
-              if all
-                self.get_commands(mod)
-              else
-                mod.name.to_sym
-              end
+            commands: base.singleton_methods(true).select { |sym| ![:included, :extended].include?(sym) },
+            inclusions: base.included_modules.select { |mod|
+              ![:Rubycom].include?(mod.name.to_sym)
+            }.map { |mod|
+              all ? self.get_commands(mod) : mod.name.to_sym
             }
         }
     }

data/rubycom.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.name          = "rubycom"
   spec.version       = Rubycom::VERSION
   spec.authors       = ["Danny Purcell"]
-  spec.email         = ["dpurcelljr@gmail.com"]
+  spec.email         = ["d.purcell.jr+rubycom@gmail.com"]
   spec.description   = %q{Allows command-line access for all singleton methods in an including class. Reads Yard style documentation for command line help output. Uses Yaml for parsing options. Allows the user to make a command-line tool by simply including Rubycom at the bottom.}
   spec.summary       = %q{Converts singleton methods to command-line functions upon inclusion.}
   spec.homepage      = "http://dannypurcell.github.io/Rubycom"

data/test/rubycom/test_rubycom.rb

@@ -113,19 +113,20 @@ class TestRubycom < Test::Unit::TestCase
       UtilTestModule <command> [args]
 
     Commands:
-      test_command                -  A basic test command
-      test_command_with_arg       -  A test_command with one arg
-      test_command_with_args      -  A test_command with two args
-      test_command_with_options   -  A test_command with an optional argument
-      test_command_all_options    -  A test_command with all optional arguments
-      test_command_options_arr    -  A test_command with an options array
-      test_command_with_return    -  A test_command with a return argument
-      test_command_arg_timestamp  -  A test_command with a Timestamp argument and an unnecessarily
-                                     long description which should overflow when
-                                     it tries to line up with other descriptions.
-      test_command_arg_false      -  A test_command with a Boolean argument
-      test_command_arg_arr        -  A test_command with an array argument
-      test_command_arg_hash       -  A test_command with an Hash argument
+    test_command                -  A basic test command
+    test_command_with_arg       -  A test_command with one arg
+    test_command_arg_named_arg  -  A test_command with an arg named arg
+    test_command_with_args      -  A test_command with two args
+    test_command_with_options   -  A test_command with an optional argument
+    test_command_all_options    -  A test_command with all optional arguments
+    test_command_options_arr    -  A test_command with an options array
+    test_command_with_return    -  A test_command with a return argument
+    test_command_arg_timestamp  -  A test_command with a Timestamp argument and an unnecessarily
+                                   long description which should overflow when
+                                   it tries to line up with other descriptions.
+    test_command_arg_false      -  A test_command with a Boolean argument
+    test_command_arg_arr        -  A test_command with an array argument
+    test_command_arg_hash       -  A test_command with an Hash argument
 
     END
     assert_equal(expected.gsub(/\n|\r|\s/, ''), result.gsub(/\n|\r|\s/, ''))
@@ -150,14 +151,15 @@ class TestRubycom < Test::Unit::TestCase
     Commands:
     test_command                -  A basic test command
     test_command_with_arg       -  A test_command with one arg
+    test_command_arg_named_arg  -  A test_command with an arg named arg
     test_command_with_args      -  A test_command with two args
     test_command_with_options   -  A test_command with an optional argument
     test_command_all_options    -  A test_command with all optional arguments
     test_command_options_arr    -  A test_command with an options array
     test_command_with_return    -  A test_command with a return argument
     test_command_arg_timestamp  -  A test_command with a Timestamp argument and an unnecessarily
-                                   long description which should overflow when it tries to line up
-                                   with other descriptions.
+                                   long description which should overflow when
+                                   it tries to line up with other descriptions.
     test_command_arg_false      -  A test_command with a Boolean argument
     test_command_arg_arr        -  A test_command with an array argument
     test_command_arg_hash       -  A test_command with an Hash argument
@@ -178,7 +180,7 @@ class TestRubycom < Test::Unit::TestCase
   end
 
   def test_get_top_level_commands
-    test_command_list = [:test_command, :test_command_with_arg, :test_command_with_args, :test_command_with_options,
+    test_command_list = [:test_command, :test_command_with_arg, :test_command_arg_named_arg, :test_command_with_args, :test_command_with_options,
                          :test_command_all_options, :test_command_options_arr, :test_command_with_return,
                          :test_command_arg_timestamp, :test_command_arg_false, :test_command_arg_arr,
                          :test_command_arg_hash]
@@ -219,21 +221,21 @@ class TestRubycom < Test::Unit::TestCase
   def test_parse_arg_string
     test_arg = "test_arg"
     result = Rubycom.parse_arg(test_arg)
-    expected = {arg: "test_arg"}
+    expected = {rubycom_non_opt_arg: "test_arg"}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_fixnum
     test_arg = "1234512415435"
     result = Rubycom.parse_arg(test_arg)
-    expected = {arg: 1234512415435}
+    expected = {rubycom_non_opt_arg: 1234512415435}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_float
     test_arg = "12345.67890"
     result = Rubycom.parse_arg(test_arg)
-    expected = {arg: 12345.67890}
+    expected = {rubycom_non_opt_arg: 12345.67890}
     assert_equal(expected, result)
   end
 
@@ -241,8 +243,8 @@ class TestRubycom < Test::Unit::TestCase
     time = Time.new
     test_arg = time.to_s
     result = Rubycom.parse_arg(test_arg)
-    expected = {arg: time}
-    assert_equal(expected[:arg].to_i, result[:arg].to_i)
+    expected = {rubycom_non_opt_arg: time}
+    assert_equal(expected[:rubycom_non_opt_arg].to_i, result[:rubycom_non_opt_arg].to_i)
   end
 
   def test_parse_arg_datetime
@@ -250,14 +252,14 @@ class TestRubycom < Test::Unit::TestCase
     date = Date.new(time.year, time.month, time.day)
     test_arg = date.to_s
     result = Rubycom.parse_arg(test_arg)
-    expected = {arg: date}
+    expected = {rubycom_non_opt_arg: date}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_array
     test_arg = ["1", 2, "a", 'b']
     result = Rubycom.parse_arg(test_arg.to_s)
-    expected = {arg: test_arg}
+    expected = {rubycom_non_opt_arg: test_arg}
     assert_equal(expected, result)
   end
 
@@ -265,28 +267,91 @@ class TestRubycom < Test::Unit::TestCase
     time = Time.new.to_s
     test_arg = ":a: \"#{time}\""
     result = Rubycom.parse_arg(test_arg.to_s)
-    expected = {arg: {a: time}}
+    expected = {rubycom_non_opt_arg: {a: time}}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_hash_group
     test_arg = ":a: [1,2]\n:b: 1\n:c: test\n:d: 1.0\n:e: \"2013-05-08 23:21:52 -0500\"\n"
     result = Rubycom.parse_arg(test_arg.to_s)
-    expected = {arg: {:a => [1, 2], :b => 1, :c => "test", :d => 1.0, :e => "2013-05-08 23:21:52 -0500"}}
+    expected = {rubycom_non_opt_arg: {:a => [1, 2], :b => 1, :c => "test", :d => 1.0, :e => "2013-05-08 23:21:52 -0500"}}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_yaml
     test_arg = {:a => ["1", 2, "a", 'b'], :b => 1, :c => "test", :d => "#{Time.now.to_s}"}
     result = Rubycom.parse_arg(test_arg.to_yaml)
-    expected = {arg: test_arg}
+    expected = {rubycom_non_opt_arg: test_arg}
     assert_equal(expected, result)
   end
 
   def test_parse_arg_code
     test_arg = 'def self.test_code_method; raise "Fail - test_parse_arg_code";end'
     result = Rubycom.parse_arg(test_arg.to_s)
-    expected = {arg: 'def self.test_code_method; raise "Fail - test_parse_arg_code";end'}
+    expected = {rubycom_non_opt_arg: 'def self.test_code_method; raise "Fail - test_parse_arg_code";end'}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_string_eq
+    test_arg = "-test_arg=\"test\""
+    result = Rubycom.parse_arg(test_arg)
+    expected = {test_arg: "test"}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_string_sp
+    test_arg = "-test_arg \"test\""
+    result = Rubycom.parse_arg(test_arg)
+    expected = {test_arg: "test"}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_long_string_eq
+    test_arg = "--test_arg=\"test\""
+    result = Rubycom.parse_arg(test_arg)
+    expected = {test_arg: "test"}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_long_string_sp
+    test_arg = "--test_arg \"test\""
+    result = Rubycom.parse_arg(test_arg)
+    expected = {test_arg: "test"}
+    assert_equal(expected, result)
+  end
+
+  def test_get_param_definitions
+    test_method = UtilTestModule.public_method('test_command_with_args')
+    expected = {:test_arg=>{:def=>"test_arg", :type=>:req, :default=>:nil_rubycom_required_param}, :another_test_arg=>{:def=>"another_test_arg", :type=>:req, :default=>:nil_rubycom_required_param}}
+    result = Rubycom.get_param_definitions(test_method)
+    assert_equal(expected, result)
+  end
+
+  def test_get_param_definitions_no_args
+    test_method = UtilTestModule.public_method('test_command')
+    expected = {}
+    result = Rubycom.get_param_definitions(test_method)
+    assert_equal(expected, result)
+  end
+
+  def test_get_param_definitions_arr_param
+    test_method = UtilTestModule.public_method('test_command_options_arr')
+    expected = {:test_option=>{:def=>"test_option=\"test_option_default\"", :type=>:opt, :default=>"test_option_default"}, :test_options=>{:def=>"*test_options", :type=>:rest, :default=>:nil_rubycom_required_param}}
+    result = Rubycom.get_param_definitions(test_method)
+    assert_equal(expected, result)
+  end
+
+  def test_get_param_definitions_all_options
+    test_method = UtilTestModule.public_method('test_command_all_options')
+    expected = {:test_arg=>{:def=>"test_arg='test_arg_default'", :type=>:opt, :default=>"test_arg_default"}, :test_option=>{:def=>"test_option='test_option_default'", :type=>:opt, :default=>"test_option_default"}}
+    result = Rubycom.get_param_definitions(test_method)
+    assert_equal(expected, result)
+  end
+
+  def test_get_param_definitions_mixed
+    test_method = UtilTestModule.public_method('test_command_with_options')
+    expected = {:test_arg=>{:def=>"test_arg", :type=>:req, :default=>:nil_rubycom_required_param}, :test_option=>{:def=>"test_option='option_default'", :type=>:opt, :default=>"option_default"}}
+    result = Rubycom.get_param_definitions(test_method)
     assert_equal(expected, result)
   end
 
@@ -334,6 +399,7 @@ class TestRubycom < Test::Unit::TestCase
     Commands:
     test_command                -  A basic test command
     test_command_with_arg       -  A test_command with one arg
+    test_command_arg_named_arg  -  A test_command with an arg named arg
     test_command_with_args      -  A test_command with two args
     test_command_with_options   -  A test_command with an optional argument
     test_command_all_options    -  A test_command with all optional arguments
@@ -347,7 +413,7 @@ class TestRubycom < Test::Unit::TestCase
     test_command_arg_hash       -  A test_command with an Hash argument
     END
     expected_out = expected
-    assert_equal(expected, result)
+    assert_equal(expected.gsub(/\n|\r|\s/, ''), result.gsub(/\n|\r|\s/, ''))
     assert_equal(expected_out.gsub(/\n|\r|\s/, ''), tst_out.gsub(/\n|\r|\s/, ''))
   ensure
     $stdout = o_stdout
@@ -596,9 +662,13 @@ class TestRubycom < Test::Unit::TestCase
     result = Rubycom.run(base, args)
 
     expected = nil
-    expected_out = "No argument available for test_arg"
+    expected_out = "No argument available for test_arg\n"
+
     assert_equal(expected, result)
-    assert_equal(expected_out, tst_out.split(/\n|\r|\r\n/).first)
+    assert_equal(expected_out, tst_out.lines.first)
+    Rubycom.get_command_usage(base,args[0],args[1..-1]).each_line{|expected_line|
+      assert_equal(true, tst_out.lines.include?(expected_line))
+    }
   ensure
     $stdout = o_stdout
     $stderr = o_stderr

data/test/rubycom/util_test_job.yaml

@@ -0,0 +1,21 @@
+---
+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 1", world2]'
+  3:
+    Cntxt: 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]

data/test/rubycom/util_test_module.rb

@@ -1,5 +1,5 @@
 require "#{File.expand_path(File.dirname(__FILE__))}/../../lib/rubycom.rb"
-
+# A command module used for testing
 module UtilTestModule
 
   # A test non-command method
@@ -19,6 +19,13 @@ module UtilTestModule
     "test_arg=#{test_arg}"
   end
 
+  # A test_command with an arg named arg
+  #
+  # @param [String] arg a test argument whose parameter name is arg
+  def self.test_command_arg_named_arg(arg)
+    "arg=#{arg}"
+  end
+
   # A test_command with two args
   # @param [String] test_arg a test argument
   # @param [String] another_test_arg another test argument

data/test/rubycom/util_test_no_singleton.rb

@@ -1,10 +1,10 @@
-require "#{File.expand_path(File.dirname(__FILE__))}/../../lib/rubycom.rb"
-require "#{File.expand_path(File.dirname(__FILE__))}/util_test_composite.rb"
-
-module UtilTestNoSingleton
-  def test_method
-    "TEST_NON_SINGLETON_METHOD"
-  end
-
-  include Rubycom
+require "#{File.expand_path(File.dirname(__FILE__))}/../../lib/rubycom.rb"
+require "#{File.expand_path(File.dirname(__FILE__))}/util_test_composite.rb"
+
+module UtilTestNoSingleton
+  def test_method
+    "TEST_NON_SINGLETON_METHOD"
+  end
+
+  include Rubycom
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubycom
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-03 00:00:00.000000000 Z
+date: 2013-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,7 +96,7 @@ description: Allows command-line access for all singleton methods in an includin
   parsing options. Allows the user to make a command-line tool by simply including
   Rubycom at the bottom.
 email:
-- dpurcelljr@gmail.com
+- d.purcell.jr+rubycom@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -111,6 +111,7 @@ files:
 - rubycom.gemspec
 - test/rubycom/test_rubycom.rb
 - test/rubycom/util_test_composite.rb
+- test/rubycom/util_test_job.yaml
 - test/rubycom/util_test_module.rb
 - test/rubycom/util_test_no_singleton.rb
 - test/rubycom/utility_tester.rb
@@ -142,6 +143,7 @@ summary: Converts singleton methods to command-line functions upon inclusion.
 test_files:
 - test/rubycom/test_rubycom.rb
 - test/rubycom/util_test_composite.rb
+- test/rubycom/util_test_job.yaml
 - test/rubycom/util_test_module.rb
 - test/rubycom/util_test_no_singleton.rb
 - test/rubycom/utility_tester.rb