rubycom 0.3.2 → 0.4.0

data/lib/rubycom/helpers.rb

@@ -0,0 +1,98 @@
+module Rubycom
+  module Helpers
+
+    # Arranges each given tag hash such that all tags will line up nicely in vertical columns.
+    #
+    # @param [Array] tag_list an Array of Hashes which include keys: :name, :tag_name, :text, :types
+    # @param [Integer] desc_width the maximum width to use for the description column
+    # @return [Array] a list of strings comprised of types, separator, name||tag_name, separator, text
+    # formatted to line up vertically
+    def self.format_tags(tag_list, desc_width = 90)
+      tag_list = [] if tag_list.nil?
+      raise ArgumentError, "tag_list should be an Array but was a #{tag_list.class}" unless tag_list.class == Array
+      tag_list.each { |h|
+        raise ArgumentError, "tag #{h} should be a Hash but was a #{h.class}" unless h.class == Hash
+        [:name, :tag_name, :text, :types].each { |t| h.fetch(t) }
+        types = h[:types]
+        raise ArgumentError, "tag[:types] #{types} should be an Array but was #{types.class}" unless types.class == Array
+      }
+
+      longest_name = tag_list.map { |tag| (tag[:name].nil?) ? tag[:tag_name] : tag[:name] }.max
+      longest_types = tag_list.map { |tag| "#{tag[:types]}" }.max
+      longest_combo_name = tag_list.map { |tag| "#{tag[:tag_name]}#{tag[:name]}" }.max
+      {
+          others: tag_list.select { |tag| !["param", "return"].include?(tag[:tag_name]) }.map { |tag|
+            combo_name = (tag[:tag_name].nil? || tag[:tag_name].empty? || tag[:name].nil? || tag[:name].empty?) ? '' : "#{tag[:tag_name]}: #{tag[:name]}"
+            "#{(tag[:types].empty?) ? '' : tag[:types]}#{self.get_separator(tag[:types], longest_types, tag[:types].empty? ? nil : ' ')}#{self.format_command_summary(combo_name, tag[:text], self.get_separator(combo_name, longest_combo_name), desc_width)}"
+          },
+          params: tag_list.select { |tag| tag[:tag_name] == "param" }.map { |tag|
+            "#{tag[:types]}#{self.get_separator(tag[:types], longest_types, ' ')}#{self.format_command_summary(tag[:name], tag[:text], self.get_separator(tag[:name], longest_name), desc_width)}"
+          },
+          returns: tag_list.select { |tag| tag[:tag_name] == "return" }.map { |tag|
+            "#{tag[:types]}#{self.get_separator(tag[:types], longest_types, ' ')}#{self.format_command_summary(tag[:tag_name], tag[:text], self.get_separator(tag[:tag_name], longest_name), desc_width)}"
+          }
+      }
+    end
+
+    # Arranges each command_name => command_description in command_doc with a separator such that all command names and
+    # descriptions will line up nicely in vertical columns.
+    #
+    # @param [Hash] command_doc a mapping of command names to documentation summaries
+    # @param [Integer] desc_width the maximum width to use for the description column
+    # @return [Array] a list of strings comprised of command_name, separator, and description
+    # formatted to line up vertically
+    def self.format_command_list(command_doc, desc_width = 90, indent ='')
+      return [] if command_doc.nil?
+      raise ArgumentError, "command_doc should be a Hash but was a #{command_doc.class}" unless command_doc.class == Hash
+      command_doc = {} if command_doc.nil?
+      longest_command_name = command_doc.keys.max { |t, n| t.to_s.length <=> n.to_s.length }
+      command_doc.map { |command_name, doc|
+        self.format_command_summary("#{indent}#{command_name}", doc, self.get_separator(command_name, longest_command_name), desc_width)
+      }
+    end
+
+    # Creates a separator with the appropriate spacing to line up a command/description pair in a command list
+    #
+    # @param [String] name the command name to create a doc separator for
+    # @param [String] longest_name the longest name which will be shown above or below the given name
+    # @param [String] sep the separator to use
+    # @return [String] a spaced separator String for use in a command/description list
+    def self.get_separator(name, longest_name='', sep='  -  ')
+      name = "#{name}" unless name.class == String
+      sep = '' if sep.nil?
+      longest_name = name if name.size > longest_name.size
+      (' ' * (longest_name.to_s.length - name.to_s.length)) << sep
+    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.format_command_summary(command_name, command_description, separator = '  -  ', max_width = 90)
+      command_name = '' if command_name.nil?
+      command_description = '' if command_description.nil?
+      separator = '' if separator == nil
+      raise ArgumentError, "command_name and separator #{command_name}#{separator} size should not be greater than max_width: #{max_width} but was #{separator.size + command_name.size}" if command_name.size+separator.size > max_width
+      $stdout.sync = true
+      prefix_space = (' ' * "#{command_name}#{separator}".length)
+      line_width = max_width - prefix_space.length
+      "#{command_name}#{separator}#{self.word_wrap(command_description, line_width, prefix_space)}\n"
+    end
+
+    # Converts a string longer than line_width to a multiline string where each line is at most line_width long.
+    #
+    # @param [String] text the text to be wrapped
+    # @param [Integer] line_width the maximum length any single line in the string should be, default: 80, minimum: 1
+    # @param [String] prefix a prefix to add the the front of any new lines created as a result of the wrap, default: ''
+    def self.word_wrap(text, line_width=80, prefix='')
+      text = "#{text}" unless text.class == String
+      prefix = "#{prefix}" unless prefix.class == String
+      line_width = 1 if line_width < 1
+      ([text.gsub("\n", ' ')].map { |line|
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip : line
+      } * "\n").gsub("\n", "\n#{prefix}")
+    end
+
+  end
+end

data/lib/rubycom/output_handler.rb

@@ -0,0 +1,15 @@
+module Rubycom
+  module OutputHandler
+
+    # Prints the command_result if it is a basic type or a Yaml representation of command_result if it is not
+    # basic types: String, NilClass, TrueClass, FalseClass, Fixnum, Float, Symbol
+    #
+    # @param [Object] command_result the result of a method call to be printed
+    def self.process_output(command_result)
+      std_output = nil
+      std_output = command_result.to_yaml unless [String, NilClass, TrueClass, FalseClass, Fixnum, Float, Symbol].include?(command_result.class)
+      $stdout.puts std_output || command_result
+    end
+
+  end
+end

data/lib/rubycom/parameter_extract.rb

@@ -0,0 +1,262 @@
+module Rubycom
+  module ParameterExtract
+
+    # Calls #resolve_params with the given parameters after calling #check to assert the state of the inputs
+    #
+    # @param [Method] command the method whose parameters should be resolved
+    # @param [Hash] parsed_command_line :args => array of arguments, :opts => { opt_key => opt_val }, :flags => { flag_key => flag_val }
+    # @param [Hash] command_doc :parameters => an array consisting of a hash for method parameter where
+    #   :param_name => the param name as a string,
+    #   :type => :req|:opt|:rest,
+    #   :default => the default value for the param
+    # @return [Hash] command.parameters.each => the value for that parameter extracted from parsed_command_line or the default in command_doc
+    def self.extract_parameters(command, parsed_command_line, command_doc)
+      command, parsed_command_line, command_doc = self.check(command, parsed_command_line, command_doc)
+      self.resolve_params(command, parsed_command_line, command_doc)
+    end
+
+    # Provides upfront checking for this inputs to #extract_parameters and raises a ParameterExtractError if
+    # parsed_command_line includes a help argument, option, or flag
+    #
+    # @param [Method] command the method whose parameters should be resolved
+    # @param [Hash] parsed_command_line :args => array of arguments, :opts => { opt_key => opt_val }, :flags => { flag_key => flag_val }
+    # @param [Hash] command_doc :parameters => an array consisting of a hash for method parameter where
+    #   :param_name => the param name as a string,
+    #   :type => :req|:opt|:rest,
+    #   :default => the default value for the param
+    # @return [Array] the given parameters if none of the checks raised an error
+    def self.check(command, parsed_command_line, command_doc)
+      has_help_optional = false
+      command.parameters.select { |type, _| type == :opt }.map { |_, name| name.to_s }.each { |param|
+        has_help_optional = ['help', 'h'].include?(param)
+      } if command.class == Method
+      help_opt = !parsed_command_line[:opts].nil? && [
+          parsed_command_line[:opts]['help'],
+          parsed_command_line[:opts]['h']
+      ].include?(true)
+      help_flag = !parsed_command_line[:flags].nil? && [
+          parsed_command_line[:flags]['help'],
+          parsed_command_line[:flags]['h']
+      ].include?(true)
+      if !has_help_optional && (help_opt || help_flag)
+        raise ParameterExtractError, 'Help Requested'
+      end
+
+      raise ParameterExtractError, "No command specified." if command.nil?
+      raise ParameterExtractError, "No command specified." if command.class == Module
+      raise ParameterExtractError, "Unrecognized command." unless [Method, Module].include?(command.class)
+      raise "#{parsed_command_line} should be a Hash but was #{parsed_command_line.class}" if parsed_command_line.class != Hash
+
+      raise ArgumentError, "command_doc should be a Hash but was #{command_doc.class}" unless command_doc.class == Hash
+      raise ArgumentError, "command_doc should have key :parameters" unless command_doc.has_key?(:parameters)
+      raise ArgumentError, "command_doc[:parameters] should be an array but was #{command_doc[:parameters].class}" unless command_doc[:parameters].class == Array
+      command_doc[:parameters].each { |param_hsh|
+        raise ArgumentError, "parameter #{param_hsh} should be a Hash but was #{param_hsh.class}" unless param_hsh.class == Hash
+        raise ArgumentError, "parameter #{param_hsh} should have key :param_name" unless param_hsh.has_key?(:param_name)
+        raise ArgumentError, "parameter #{param_hsh} should have key :type" unless param_hsh.has_key?(:type)
+        raise ArgumentError, "parameter #{param_hsh} should have key :default" unless param_hsh.has_key?(:default)
+      }
+      [command, parsed_command_line, command_doc]
+    end
+
+    # Matches parameter names in command.parameters to values from command_line or their default values in command_doc
+    #
+    # @param [Method] command the method whose parameters should be resolved
+    # @param [Hash] command_line :args => array of arguments, :opts => { opt_key => opt_val }, :flags => { flag_key => flag_val }
+    # @param [Hash] command_doc :parameters => an array consisting of a hash for method parameter where
+    #   :param_name => the param name as a string,
+    #   :type => :req|:opt|:rest,
+    #   :default => the default value for the param
+    # @return [Hash] command.parameters.each => the value for that parameter extracted from command_line or the default in command_doc
+    def self.resolve_params(command, command_line, command_doc)
+      raise ArgumentError, "command should be a Method but was #{command.class}" unless command.class == Method
+      command_line = command_line.clone.map { |type, entry|
+        {type => entry.clone}
+      }.reduce({}, &:merge)
+      command_line = self.extract_command_args!(command.name.to_s, command_line)
+      params = command.parameters
+      param_names = self.get_param_names(params)
+      raise ArgumentError, "command_doc should have key :parameters but was #{command_doc}" unless command_doc.has_key?(:parameters)
+      param_docs = command_doc[:parameters].map { |param_hsh|
+        if param_hsh[:type] == :rest
+          {param_hsh.fetch(:param_name).reverse.chomp('*').reverse.to_sym => param_hsh.reject { |k, _| k == :param_name }}
+        else
+          {param_hsh.fetch(:param_name).to_sym => param_hsh.reject { |k, _| k == :param_name }}
+        end
+      }.reduce({}, &:merge)
+
+      params.map { |type, sym|
+        case type
+          when :opt
+            unless param_docs.has_key?(sym) && param_docs[sym].has_key?(:default)
+              raise ArgumentError, "#{sym} should exist in command_doc[:parameters] and have key :default but has values #{param_docs[sym]}"
+            end
+            self.resolve_opt!(sym, param_names[sym][:long], param_names[sym][:short], param_docs[sym][:default], command_line)
+          when :rest
+            self.resolve_rest!(sym, param_docs[sym][:default], command_line)
+          else
+            self.resolve_others!(sym, type, param_docs[sym][:default], command_line)
+        end
+      }.reduce({}, &:merge).reject { |_, val| val == :rubycom_no_value }
+    end
+
+    # Trims command_line[:args] down to the entries which occur after command_name
+    #
+    # @param [Object] command_name the entry in command_line[:args] which marks the start of the args to be returned
+    # @param [Hash] command_line :args => array of arguments
+    # @return [Hash] :args => array of arguments including only the entries which occur after the command_name
+    def self.extract_command_args!(command_name, command_line)
+      raise ArgumentError, "command_name should be a String|Symbol but was #{command_name}" unless [String, Symbol].include?(command_name.class)
+      raise ArgumentError, "command_line should be a hash but was #{command_line}" unless command_line.class == Hash
+      return command_line if command_line[:args].nil?
+
+      i = command_line[:args].index(command_name.to_s)
+      command_line[:args] = (i.nil?) ? [] : command_line[:args][i..-1]
+      command_line[:args].shift if command_line[:args].first == command_name.to_s
+      command_line
+    end
+
+    # Extracts the a value from command_line for the param_name or returns the default with command_line has no values
+    #
+    # @param [Object] param_name the key in the returned hash
+    # @param [Object] default_value the value in the returned hash if no value could be extracted from command_line
+    # @param [Hash] command_line :args => array of arguments, :opts => { opt_key => opt_val }, :flags => { flag_key => flag_val }
+    # @return [Hash] param_name => extracted_value|default_value
+    def self.resolve_opt!(param_name, long_name, short_name, default_value, command_line)
+      raise ArgumentError, "command_line should be a hash but was #{command_line}" unless command_line.class == Hash
+      extraction = self.extract!(long_name, short_name, command_line[:opts], command_line[:flags], command_line[:args])
+      if extraction == :rubycom_no_value
+        {param_name => default_value}
+      else
+        {param_name => extraction}
+      end
+    end
+
+    # Creates a long and short name for each symbol in the given params
+    #
+    # @param [Array] params a list of Symbols to create names for
+    # @return [Hash] params.each symbol => a Hash where long => string form of symbol and
+    # short => the first char in symbol if unique in params or the string form of symbol if not
+    def self.get_param_names(params)
+      first_char_map = params.group_by { |_, sym| sym.to_s[0] }
+      params.map { |_, sym|
+        {
+            sym => {
+                long: sym.to_s,
+                short: (first_char_map[sym.to_s[0]].size == 1) ? sym.to_s[0] : sym.to_s
+            }
+        }
+      }.reduce({}, &:merge)
+    end
+
+    # Extracts the remaining values from command_line as an Array or returns the default with command_line has no values
+    #
+    # @param [Object] param_name the key in the returned hash
+    # @param [Object] default_value the value in the returned hash if no value could be extracted from command_line
+    # @param [Hash] command_line :args => array of arguments, :opts => { opt_key => opt_val }, :flags => { flag_key => flag_val }
+    # @return [Array] the rest of the keys/values in command_line
+    def self.resolve_rest!(param_name, default_value, command_line)
+      args = command_line[:args] || []
+      opts = command_line[:opts] || {}
+      flags = command_line[:flags] || {}
+      # TODO seems like we still can not call out a rest param on the command line, not sure if that is a problem
+      rest_arr = {
+          param_name => if args.empty? && opts.empty? && flags.empty?
+                          default_value
+                        elsif !args.empty? && opts.empty? && flags.empty?
+                          args
+                        elsif args.empty? && (!opts.empty? || !flags.empty?)
+                          joined = self.join(flags, opts)
+                          keyed = joined[param_name] || []
+                          keyed.to_a << joined.reject { |k, _| k == param_name }
+                        else
+                          joined = self.join(flags, opts)
+                          keyed = joined[param_name] || []
+                          rest = keyed.to_a << joined.reject { |k, _| k == param_name }
+                          args + rest
+                        end
+      }
+
+      command_line[:opts] = {} unless command_line[:opts].nil?
+      command_line[:flags] = {} unless command_line[:flags].nil?
+      command_line[:args] = [] unless command_line[:args].nil?
+
+      rest_arr
+    end
+
+    # Calls #update on left passing in right and resolving conflicts by combining left and right values in an array
+    #
+    # @param [Hash] left the base thing to be updated
+    # @param [Hash] right the thing whose keys will be added to left and values combined with left on key collisions
+    # @return [Hash] left.keys + right.keys where each key => values from left or right or combined in an array if both
+    def self.join(left, right)
+      left.update(right) { |_, left_val, right_val|
+        if left_val.class == Array
+          combined = left_val
+        else
+          combined = [left_val]
+        end
+
+        if right_val.class == Array
+          right_val.each { |rv|
+            combined << rv
+          }
+        else
+          combined << right_val
+        end
+
+        combined
+      }
+    end
+
+    # Extracts a value from the command_line or returns the default_value if the command_line has no values.
+    # Raises a ParameterExtractError if the type was :req and no value was found.
+    #
+    # @param [Object] param_name the key in the returned hash
+    # @param [Symbol] type :req if the parameter is required
+    # @param [Object] default_value the value in the returned hash if no value could be extracted from command_line
+    # @param [Hash] command_line :args => array of arguments
+    # @return [Hash] param_name => value extracted for param_name
+    def self.resolve_others!(param_name, type, default_value, command_line)
+      if command_line[:args].size > 0
+        {param_name => (command_line[:args].shift)}
+      else
+        raise ParameterExtractError, "Missing required argument: #{param_name}" if type == :req
+        {param_name => default_value}
+      end
+    end
+
+    # Searches opts, then flags, then args for a key matching the given long_name or short_name
+    # The first matched key will be removed from the set. The valued paired to the matched key will be returned along
+    # with a hash containing the remaining args, opts, and flags.
+    # !destructively modifies opts, flags, and args by deleting or shifting a matched value out of the Hash/Array
+    #
+    # @param [Object] long_name the first key to be searched for in each opts, flags, args
+    # @param [Object] short_name the key to be searched for if the long_key is not found in the group under search
+    # @param [Hash] opts long_key|short_key => option value for that key
+    # @param [Hash] flags long_key|short_key => true|false value for that key
+    # @param [Array] args if no matching keys for the long or short name exist in either opts or flags and at least one
+    # value is left is args then the first value in args will be pulled as the value to return
+    # @return [Hash] the extracted value or :rubycom_no_value if a value could not be matched and args was empty
+    def self.extract!(long_name, short_name, opts, flags, args)
+      opts = {} if opts.nil?
+      flags = {} if flags.nil?
+      args = [] if args.nil?
+
+      if opts.has_key?(long_name)
+        opts.delete(long_name)
+      elsif opts.has_key?(short_name)
+        opts.delete(short_name)
+      elsif flags.has_key?(long_name)
+        flags.delete(long_name)
+      elsif flags.has_key?(short_name)
+        flags.delete(short_name)
+      elsif args.size > 0
+        args.shift
+      else
+        :rubycom_no_value
+      end
+    end
+
+  end
+end

data/lib/rubycom/singleton_commands.rb

@@ -0,0 +1,78 @@
+module Rubycom
+  module SingletonCommands
+
+    # Uses #discover_commands to look up commands in parsed_command_line, filters the result to the last matched command
+    # object
+    #
+    # @param [Module] base_module the module in which to search for commands
+    # @param [Hash] parsed_command_line :args => an array of strings representing the search terms
+    # @return [Module|Method] the last matched module or method object
+    def self.discover_command(base_module, parsed_command_line)
+      self.discover_commands(base_module, parsed_command_line).select { |candidate|
+        candidate.class == Module || candidate.class == Method
+      }.last
+    end
+
+    # Performs a depth only search of included modules starting with the base_module. The first word which matches a
+    # singleton method in one of the sub modules will be a Method object in the returned array. All matched sub modules
+    # will be Module objects in the returned array. All words occurring after a method match will be returned as they
+    # appear in parsed_command_line[:args]
+    #
+    # @param [Module] base_module the module in which to search for commands
+    # @param [Hash] parsed_command_line :args => an array of strings representing the search terms
+    # @return [Array] consisting of the matched sub Modules followed by the matched Method followed by the remaining args
+    def self.discover_commands(base_module, parsed_command_line)
+      base_module, args = self.check(base_module, parsed_command_line)
+      args.reduce([base_module]) { |acc, arg|
+        if acc.last.class == Method || acc.last.class == String
+          acc << arg
+        else
+          arg_sym = arg.to_s.to_sym
+          if self.get_commands(acc.last, false)[acc.last.to_s.to_sym][arg_sym] == :method
+            acc << acc.last.public_method(arg_sym)
+          else
+            acc << acc.last.const_get(arg_sym) rescue (acc << arg)
+          end
+        end
+      }
+    end
+
+    # Provides upfront checking for this inputs to #discover_commands
+    def self.check(base_module, parsed_command_line)
+      raise ArgumentError, 'base_module should not be nil' if base_module.nil?
+      raise ArgumentError, 'parsed_command_line should not be nil' if parsed_command_line.nil?
+      raise ArgumentError, "parsed_command_line should be a Hash but was #{parsed_command_line.class}" if parsed_command_line.class != Hash
+      arguments = parsed_command_line[:args] || []
+      raise ArgumentError, "args should be an Array but was #{arguments.class}" unless arguments.class == Array
+      unless [Module, String, Symbol].include?(base_module.class)
+        raise ArgumentError, "base_module should be a Module, String, or Symbol but was #{base_module.class}"
+      end
+      base_module = Kernel.const_get(base_module) if base_module.class == Symbol
+      base_module = Kernel.const_get(base_module.to_sym) if base_module.class == String
+      [base_module, arguments.map { |arg| arg.to_s } ]
+    end
+
+    # 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.to_s.to_sym => base.singleton_methods(true).select { |sym| ![:included, :extended].include?(sym) }.map { |sym|
+            {
+                sym => :method
+            }
+          }.reduce({}, &:merge).merge(
+              base.included_modules.select { |mod| mod.name.to_sym != :Rubycom }.map { |mod|
+                {
+                    mod.to_s.to_sym => (all ? self.get_commands(mod, all)[mod.to_s.to_sym] : :module)
+                }
+              }.reduce({}, &:merge)
+          )
+      }
+    end
+
+  end
+end