rubycom 0.2.5 → 0.3.0

data/lib/rubycom/arguments.rb

@@ -0,0 +1,102 @@
+require 'yaml'
+require 'method_source'
+
+module Rubycom
+  module Arguments
+
+    # Parses the given arguments and matches them to the given parameters
+    #
+    # @param [Hash] parameters a Hash representing the parameters to match.
+    #         Entries should match :param_name => { type: :req||:opt||:rest,
+    #                                               def:(source_definition),
+    #                                               default:(default_value || :nil_rubycom_required_param)
+    #                                              }
+    # @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=[])
+      raise CLIError, 'parameters may not be nil' if parameters.nil?
+      raise CLIError, 'arguments may not be nil' if arguments.nil?
+      sorted_args = arguments.map { |arg|
+        self.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(1)] : Hash[key, arr.map { |hsh| hsh.values.first }.reduce(&:merge)]
+      }.reduce(&:merge) || {}
+
+      sorted_arg_count = sorted_args.map { |key, val| val }.flatten(1).length
+      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 #{sorted_arg_count}" if sorted_arg_count < (types[:req]||0)
+      raise CLIError, "Wrong number of arguments. Expected at most #{(types[:req]||0) + (types[:opt]||0)}, received #{sorted_arg_count}" if types[:rest].nil? && (sorted_arg_count > ((types[:req]||0) + (types[:opt]||0)))
+
+      parameters.map { |param_sym, def_hash|
+        if def_hash[:type] == :req
+          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
+          if sorted_args[param_sym].nil?
+            arg = (sorted_args[:rubycom_non_opt_arg].nil? || sorted_args[:rubycom_non_opt_arg].empty?) ? parameters[param_sym][:default] : sorted_args[:rubycom_non_opt_arg].shift
+          else
+            arg = sorted_args[param_sym]
+          end
+          Hash[param_sym, arg]
+        elsif def_hash[:type] == :rest
+          ret = Hash[param_sym, ((!sorted_args[param_sym].nil?) ? sorted_args[param_sym] : sorted_args[:rubycom_non_opt_arg])]
+          sorted_args[:rubycom_non_opt_arg] = []
+          ret
+        end
+      }.reduce(&:merge)
+    end
+
+    # Uses YAML.load to parse the given String
+    #
+    # @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)
+      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
+        begin
+          parsed_arg = YAML.load("#{arg}")
+        rescue Exception
+          parsed_arg = "#{arg}"
+        end
+        Hash[:rubycom_non_opt_arg, parsed_arg]
+      end
+    end
+
+    # Builds a hash mapping parameter names (as symbols) to their
+    # :type (:req,:opt,:rest), :def (source_definition), :default (default_value || :nil_rubycom_required_param)
+    # for each parameter defined by the given method.
+    #
+    # @param [Method] method the Method who's parameter hash should be built
+    # @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
+      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
+
+  end
+end

data/lib/rubycom/commands.rb

@@ -0,0 +1,63 @@
+module Rubycom
+  module Commands
+
+    # Retrieves the singleton methods in the given base and included Modules
+    #
+    # @param [Module] base the module which invoked 'include Rubycom'
+    # @param [Boolean] all if true recursively search for included modules' commands, if false return only top level commands
+    # @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)
+      {
+          base.name.to_sym => {
+              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
+              }
+          }
+      }
+    end
+
+    # Discovers the commands specified in the given base without considering the commands contained in sub-modules
+    #
+    # @param [Module] base the base Module to search
+    # @return [Array] a list of command name symbols which are defined in the given Module
+    def self.get_top_level_commands(base)
+      return {} if base.nil? || !base.respond_to?(:singleton_methods) || !base.respond_to?(:included_modules)
+      excluded_commands = [:included, :extended]
+      excluded_modules = [:Rubycom]
+      base.singleton_methods(true).select { |sym| !excluded_commands.include?(sym) } +
+          base.included_modules.select { |mod| !excluded_modules.include?(mod.name.to_sym) }.map { |mod| mod.name.to_sym }.flatten
+    end
+
+    # Discovers the commands specified in the given base and included Modules
+    #
+    # @param [Module] base the base Module to search
+    # @return [Hash] a set of command name symbols mapped to containing Modules
+    def self.index_commands(base)
+      excluded_commands = [:included, :extended]
+      excluded_modules = [:Rubycom]
+      Hash[base.singleton_methods(true).select { |sym| !excluded_commands.include?(sym) }.map { |sym|
+        [sym, base]
+      }].merge(
+          base.included_modules.select { |mod| !excluded_modules.include?(mod.name.to_sym) }.map { |mod|
+            self.index_commands(mod)
+          }.reduce(&:merge) || {}
+      )
+    end
+
+    # Looks up the commands which will be available on the given base Module and returns the longest command name
+    # Used in arranging the command list format
+    #
+    # @param [Module] base the base Module to look up
+    # @return [String] the longest command name which will show in a list of commands for the given base Module
+    def self.get_longest_command_name(base)
+      return '' if base.nil?
+      self.get_commands(base, false).map { |_, mod_hash|
+        mod_hash[:commands] + mod_hash[:inclusions].flatten }.flatten.max_by(&:size) or ''
+    end
+
+  end
+end

data/lib/rubycom/documentation.rb

@@ -0,0 +1,204 @@
+require "#{File.dirname(__FILE__)}/commands.rb"
+
+module Rubycom
+  module Documentation
+
+    # Retrieves the summary for each command method in the given Module
+    #
+    # @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)
+      Commands.get_top_level_commands(base).each_with_index.map { |sym, index|
+        "#{"Commands:\n" if index == 0}" << self.get_command_summary(base, sym, self.get_separator(sym, Commands.get_longest_command_name(base).length))
+      }.reduce(:+) or "No Commands found for #{base}."
+    end
+
+    # Creates a separator with the appropriate spacing to line up a command/description pair in a command list
+    #
+    # @param [Symbol] sym
+    # @param [Integer] spacer_length
+    # @return [String] a spaced separator String for use in a command/description list
+    def self.get_separator(sym, spacer_length=0)
+      [].unshift(" " * (spacer_length - sym.to_s.length)).join << "  -  "
+    end
+
+    # Retrieves the summary for the given command_name
+    #
+    # @param [Module] base the module which invoked 'include Rubycom'
+    # @param [String] command_name the command to retrieve usage for
+    # @return [String] a summary of the given command_name
+    def self.get_command_summary(base, command_name, separator = '  -  ')
+      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)
+        begin
+          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(/^#/) && !line.strip.match(/^#!/) }.map { |line| line.strip.gsub(/^#+/, '') }.join("\n")
+        rescue
+          desc = ""
+        end
+      else
+        raise CLIError, "Invalid command for #{base}, #{command_name}" unless base.public_methods.include?(command_name.to_sym)
+        desc = self.get_doc(base.public_method(command_name.to_sym))[:desc].join("\n") rescue ""
+      end
+      (desc.nil?||desc=='nil'||desc.length==0) ? "#{command_name}\n" : self.get_formatted_summary(command_name, desc, separator)
+    end
+
+    # Arranges the given command_name and command_description with the separator in a standard format
+    #
+    # @param [String] command_name the command format
+    # @param [String] command_description the description for the given command
+    # @param [String] separator optional separator to use
+    def self.get_formatted_summary(command_name, command_description, separator = '  -  ')
+      width = 95
+      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}"
+    end
+
+    # Retrieves the usage description for the given Module with a list of command methods
+    #
+    # @param [Module] base the module which invoked 'include Rubycom'
+    # @return [String] the usage description for the module with a list of command methods
+    def self.get_usage(base)
+      return '' if base.nil? || !base.respond_to?(:included_modules)
+      return '' if Commands.get_top_level_commands(base).size == 0
+      "Usage:\n    #{base} <command> [args]\n\n" << self.get_summary(base)
+    end
+
+    # Retrieves the usage description for the given command_name
+    #
+    # @param [Module] base the module which invoked 'include Rubycom'
+    # @param [String] command_name the command to retrieve usage for
+    # @param [Array] args the remaining args other than the command_name, used of sub-command look-ups
+    # @return [String] the detailed usage description for the given command_name
+    def self.get_command_usage(base, command_name, args=[])
+      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)
+        if args.empty?
+          self.get_usage(eval(command_name.to_s))
+        else
+          self.get_command_usage(eval(command_name.to_s), args[0], args[1..-1])
+        end
+      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) || {}
+
+        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
+
+    # Discovers the given Method's parameters and uses them to build a formatted usage string
+    #
+    # @param [Method] method the Method object to generate usage for
+    def self.get_param_usage(method)
+      return "" if method.parameters.nil? || method.parameters.empty?
+      Arguments.get_param_definitions(method).group_by { |_, hsh|
+        hsh[:type]
+      }.map { |key, val_arr|
+        vals = Hash[*val_arr.flatten]
+        {
+            key => if key == :opt
+                     vals.map { |param, val_hsh| "-#{param.to_s}=#{val_hsh[:default]}" }
+                   elsif key == :req
+                     vals.keys.map { |param| " <#{param.to_s}>" }
+                   else
+                     vals.keys.map { |param| " [&#{param.to_s}]" }
+                   end
+        }
+      }.reduce(&:merge).map { |type, param_arr|
+        if type == :opt
+          " [#{param_arr.join("|")}]"
+        else
+          param_arr.join
+        end
+      }.join
+    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 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|
+        if doc.match(/^@\w+/).nil?
+          :desc
+        else
+          doc.match(/^@\w+/).to_s.gsub('@', '').to_sym
+        end
+      }.map { |key, val|
+        Hash[key, val.map { |val_line| val_line.gsub(/^@\w+/, '').lstrip }.select { |line| line != '' }]
+      }.reduce(&:merge)
+    end
+
+    # @return [String] the usage message for Rubycom's default commands
+    def self.get_default_commands_usage()
+      <<-END.gsub(/^ {6}/,'')
+
+      Default Commands:
+      help                 - prints this help page
+      job                  - run a job file
+      register_completions - setup bash tab completion
+      tab_complete         - print a list of possible matches for a given word
+      END
+    end
+
+    # @return [String] the usage message for Rubycom's job runner
+    def self.get_job_usage(base)
+      <<-END.gsub(/^ {6}/,'')
+      Usage: #{base} job <job_path>
+      Parameters:
+        [String] job_path the path to the job yaml to be run
+      Details:
+      A job yaml is any yaml file which follows the format below.
+        * The env: key shown below is optional
+        * The steps: key must contain a set of numbered steps as shown
+        * The desc: key shown below is an optional context for the job's log output
+          * Other than cmd: there may be as many keys in a numbered command as you choose
+      ---
+      env:
+        test_msg: Hello World
+        test_arg: 123
+        working_dir: ./test
+      steps:
+        1:
+          desc: Run test command with environment variable
+          test_context: Some more log context
+          cmd: ruby env[working_dir]/test.rb test_command env[test_msg]
+        2:
+          cmd: ls env[working_dir]
+      END
+    end
+
+    def self.get_register_completions_usage(base)
+      <<-END.gsub(/^ {6}/,'')
+      Usage: #{base} register_completions
+      END
+    end
+
+    def self.get_tab_complete_usage(base)
+      <<-END.gsub(/^ {6}/,'')
+      Usage: #{base} tab_complete <word>
+      Parameters:
+        [String] word the word or partial word to find matches for
+      END
+    end
+
+  end
+end

data/lib/rubycom/version.rb

@@ -1,3 +1,3 @@
 module Rubycom
-  VERSION = "0.2.5"
+  VERSION = "0.3.0"
 end

data/test/rubycom/arguments_test.rb

@@ -0,0 +1,148 @@
+require "#{File.dirname(__FILE__)}/../../lib/rubycom/arguments.rb"
+
+require "#{File.dirname(__FILE__)}/util_test_module.rb"
+require "#{File.dirname(__FILE__)}/util_test_composite.rb"
+require "#{File.dirname(__FILE__)}/util_test_no_singleton.rb"
+
+require 'test/unit'
+
+class ArgumentsTest < Test::Unit::TestCase
+
+  def test_parse_arg_string
+    test_arg = "test_arg"
+    result = Rubycom::Arguments.parse_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::Arguments.parse_arg(test_arg)
+    expected = {rubycom_non_opt_arg: 1234512415435}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_arg_float
+    test_arg = "12345.67890"
+    result = Rubycom::Arguments.parse_arg(test_arg)
+    expected = {rubycom_non_opt_arg: 12345.67890}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_arg_timestamp
+    time = Time.new
+    test_arg = time.to_s
+    result = Rubycom::Arguments.parse_arg(test_arg)
+    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
+    time = Time.new("2013-05-08 00:00:00 -0500")
+    date = Date.new(time.year, time.month, time.day)
+    test_arg = date.to_s
+    result = Rubycom::Arguments.parse_arg(test_arg)
+    expected = {rubycom_non_opt_arg: date}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_arg_array
+    test_arg = ["1", 2, "a", 'b']
+    result = Rubycom::Arguments.parse_arg(test_arg.to_s)
+    expected = {rubycom_non_opt_arg: test_arg}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_arg_hash
+    time = Time.new.to_s
+    test_arg = ":a: \"#{time}\""
+    result = Rubycom::Arguments.parse_arg(test_arg.to_s)
+    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::Arguments.parse_arg(test_arg.to_s)
+    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::Arguments.parse_arg(test_arg.to_yaml)
+    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::Arguments.parse_arg(test_arg.to_s)
+    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::Arguments.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::Arguments.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::Arguments.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::Arguments.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::Arguments.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::Arguments.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::Arguments.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::Arguments.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::Arguments.get_param_definitions(test_method)
+    assert_equal(expected, result)
+  end
+
+end