rubycom 0.3.2 → 0.4.0

data/lib/rubycom/arg_parse.rb

@@ -0,0 +1,252 @@
+module Rubycom
+  module ArgParse
+    require 'parslet'
+    require 'yaml'
+
+    # Runs a parser against the given Array of arguments to match command argument, option, and flag patterns.
+    #
+    # @param [Array] command_line an array of strings representing the arguments taken from the command line
+    # @return [Hash] :args => Array of arguments, :opts => Hash mapping each unique option/flag to their values
+    def self.parse_command_line(command_line)
+      raise ArgumentError, "command_line should be String or Array but was #{command_line.class}" unless [String, Array].include?(command_line.class)
+      command_line = command_line.dup
+      command_line = [command_line] if command_line.class == String
+      command_line = self.combine_options(command_line)
+      begin
+        command_line.map { |word|
+          ArgTransform.new.apply(ArgParser.new.parse(word))
+        }.reduce({}) { |acc, n|
+          # the handlers for opt and flag accumulate all unique mentions of an option name
+          if n.has_key?(:opt)
+            acc[:opts] = {} unless acc.has_key?(:opts)
+            acc[:opts] = acc[:opts].update(n[:opt]) { |key, old, new|
+              if old.class == Array
+                acc[:opts][key] = old << new
+              else
+                acc[:opts][key] = [old] << new
+              end
+            }
+          elsif n.has_key?(:flag)
+            acc[:opts] = {} unless acc.has_key?(:opts)
+            acc[:opts] = acc[:opts].update(n[:flag]) { |key, old, new|
+              if old.class == Array
+                combined = old
+              else
+                combined = [old]
+              end
+
+              if new.class == Array
+                new.each { |new_flag|
+                  combined << new_flag
+                }
+              else
+                combined << new
+              end
+
+              acc[:opts][key] = combined
+            }
+          else
+            acc[:args] = [] unless acc.has_key?(:args)
+            acc[:args] << n[:arg]
+          end
+          acc
+        }
+      rescue Parslet::ParseFailed => failure
+        raise ArgParseError, "Arguments could not be parsed.", failure
+      end
+    end
+
+    # Matches a word representing an optional key to the separator and/or value which goes with the key
+    #
+    # @param [Array] command_line an array of strings representing the arguments taken from the command line
+    # @return [Array] an Array of Strings with matched items combined into one entry per matched set
+    def self.combine_options(command_line)
+      command_line.reduce([]) { |acc, next_word|
+        if next_word == '=' || (!next_word.start_with?('-') && acc.last.to_s.start_with?('-') && acc.last.to_s.end_with?('='))
+          acc[-1] = acc[-1].dup << next_word
+          acc
+        elsif next_word == '=' || (!next_word.start_with?('-') && acc.last.to_s.start_with?('-') && !(acc.last.to_s.include?('=') || acc.last.to_s.include?(' ')))
+          acc[-1] = acc[-1].dup << ' ' << next_word
+          acc
+        else
+          acc << next_word
+        end
+      }
+    end
+
+    # Comprised of grammar rules which determine whether a given string is an argument, option, or flag.
+    # Calling #parse with a String on an instance of this class will return a nested hash structure which identifies the
+    # patterns recognized in the given string.
+    # In order to use this parser on a command line argument array, it may be necessary to pre-join optional argument
+    # keys to their values such that each item in the array is either a complete argument, complete optional-argument,
+    # or a flag.
+    #
+    # Example:
+    #   Rubycom::ArgParse::ArgParser.new.parse("-test_arg = test")
+    #   => {:opt=>{:key=>"-test_arg"@0, :sep=>" = "@9, :val=>"test"@12}}
+    class ArgParser < Parslet::Parser
+      rule(:space) { match('\s').repeat(1) }
+      rule(:eq) { match('=') }
+      rule(:separator) { (eq | (space >> eq >> space) | (space >> eq) | (eq >> space) | space) }
+      rule(:escape_char) { match(/\\/) }
+      rule(:escaped_char) { escape_char >> any }
+      rule(:d_quote) { escape_char.absent? >> match(/"/) }
+      rule(:s_quote) { escape_char.absent? >> match(/'/) }
+
+      rule(:double_escaped) { d_quote >> (escape_char.absent? >> match(/[^"]/)).repeat >> d_quote }
+      rule(:single_escaped) { s_quote >> (escape_char.absent? >> match(/[^']/)).repeat >> s_quote }
+      rule(:escaped_word) { single_escaped | double_escaped }
+      rule(:raw_word) { (escaped_char | (separator.absent? >> any)).repeat(1) }
+      rule(:word) { raw_word | single_escaped | double_escaped }
+      rule(:list) { word >> (match(',') >> word).repeat(1) }
+
+      rule(:short) { match('-') }
+      rule(:long) { short >> short }
+      rule(:neg_opt_prefix) { (long | short) >> str('-').absent? >> (str('no-') | str('NO-')) >> word }
+      rule(:opt_prefix) { (long | short) >> str('-').absent? >> word }
+
+      rule(:arg) { any.repeat }
+      rule(:flag) { (neg_opt_prefix | opt_prefix) }
+      rule(:opt) { opt_prefix.as(:key) >> separator.as(:sep) >> any.repeat.as(:val) }
+
+      rule(:expression) { opt.as(:opt) | flag.as(:flag) | arg.as(:arg) }
+
+      root :expression
+    end
+
+    # Parslet transformer intended for use with ArgParser. Uses functions in Rubycom::ArgParse to clean up a structure
+    # identified by the parser and convert values to basic types.
+    #
+    # Example:
+    #   ArgTransform.new.apply(ArgParser.new.parse("-test_arg = test"))
+    #   => {:opt=>{"test_arg"=>"test"}}
+    class ArgTransform < Parslet::Transform
+      rule(:arg => simple(:arg)) { Rubycom::ArgParse.transform(:arg, arg) }
+      rule(:opt => subtree(:opt)) { Rubycom::ArgParse.transform(:opt, opt) }
+      rule(:flag => simple(:flag)) { Rubycom::ArgParse.transform(:flag, flag) }
+    end
+
+    # Calls one of the transform functions according to the matched_type
+    #
+    # @param [Symbol] matched_type :arg, :opt, :flag will transform the value according to the corresponding transform function.
+    # anything else will extract the value as a string
+    # @param [Hash|Parslet::Slice] val a possibly nested Hash structure or a Slice. Hashes are returned by the parser when
+    # it matches a complex pattern, a Slice will be returned when the matched pattern is not tree like.
+    # @return [Hash] :arg => value | :opt|:flag => a Hash mapping keys to values
+    def self.transform(matched_type, val, loaders={}, transformers={})
+      loader_methods = {
+          arg: Rubycom::ArgParse.public_method(:load_string),
+          opt: Rubycom::ArgParse.public_method(:load_opt_value),
+          flag: Rubycom::ArgParse.public_method(:load_flag_value)
+      }.merge(loaders)
+      transforms = {
+          arg: Rubycom::ArgParse.public_method(:transform_arg),
+          opt: Rubycom::ArgParse.public_method(:transform_opt),
+          flag: Rubycom::ArgParse.public_method(:transform_flag)
+      }.merge(transformers)
+
+      {
+          matched_type => if [:arg,:opt,:flag].include?(matched_type)
+                            transforms[matched_type].call(val, loader_methods[matched_type])
+                          else
+                            val.str.strip
+                          end
+      }
+    end
+
+    # Uses the given arg_loader to resolve the ruby type for the given string
+    #
+    # @param [String|Parslet::Slice] match_string a string identified as an argument
+    # @param [Method|Proc] arg_loader called to load the value(s)
+    # @return [Object] the result of a call to the given arg_loader
+    def self.transform_arg(match_string, arg_loader=Rubycom::ArgParse.public_method(:load_string))
+      match_string = match_string.str.strip if match_string.class == Parslet::Slice
+      arg_loader.call(match_string)
+    end
+
+    # Uses the given opt_loader to resolve the ruby type for the value in the given Hash
+    #
+    # @param [Hash] subtree a structure identified as an option, must have keys :key, :sep, :val
+    # @param [Method|Proc] opt_loader called to load the option value(s)
+    # @return [Hash] mapping the option key to it's loaded value
+    def self.transform_opt(subtree, opt_loader=Rubycom::ArgParse.public_method(:load_opt_value))
+      val = subtree[:val].str
+      val = val.split(',') unless (val.start_with?('[') && val.end_with?(']'))
+      value = opt_loader.call(val)
+      {
+          subtree[:key].str.reverse.chomp('-').chomp('-').reverse => value
+      }
+    end
+
+    # Calls the given loader to load a single string or array of strings
+    #
+    # @param [Array] value containing the string(s) to be loaded
+    # @param [Method|Proc] loader called to load the value(s)
+    # @return [Object] the result of a call to #load_string
+    def self.load_opt_value(value, loader=Rubycom::ArgParse.public_method(:load_string))
+      if value.class == Array
+        (value.length == 1) ? loader.call(value.first) : value.map { |v| loader.call(v) }
+      else
+        loader.call(value)
+      end
+    end
+
+    # Uses the given loader to resolve the ruby type for the given string
+    #
+    # @param [String] string to be loaded
+    # @param [Method|Proc] loader called to load the string
+    # @return [Object] the result of a call to the loader or the given string if it could not be parsed
+    def self.load_string(string, loader=YAML.public_method(:load))
+      if string.start_with?('#') || string.start_with?('!')
+        result = string
+      else
+        begin
+          result = loader.call(string)
+        rescue Exception
+          result = string
+        end
+      end
+      result
+    end
+
+    # Resolves the type and values for the given flag string
+    #
+    # @param [String|Parslet::Slice] match_string a string identified as a flag, should start with a - or -- and contain no spaces
+    # @return [Hash] flag_key(s) => true|false | an array of true|false if there were multiple mentions of the same short flag key
+    def self.transform_flag(match_string, loader=Rubycom::ArgParse.public_method(:load_flag_value))
+      match_string = match_string.str.strip if match_string.class == Parslet::Slice
+      if match_string.start_with?('--')
+        long_flag = match_string.reverse.chomp('-').chomp('-').reverse
+        long_flag_key = long_flag.sub(/no-|NO-/, '')
+        {
+            long_flag_key => loader.call(long_flag)
+        }
+      else
+        short_flag = match_string.reverse.chomp('-').reverse
+        short_flag_key = short_flag.sub(/no-|NO-/, '')
+        short_flag_key.split(//).map { |k|
+          {
+              k => loader.call(short_flag)
+          }
+        }.reduce({}) { |acc, n|
+          acc.update(n) { |_, old, new|
+            if old.class == Array
+              old << new
+            else
+              [old] << new
+            end
+          }
+        }
+      end
+    end
+
+    # Resolves the given flag to true or false as appropriate.
+    #
+    # @param [String] flag string representing a flag without the proceeding dashes
+    # @return [Boolean] FalseClass if the flag starts with a no- TrueClass otherwise
+    def self.load_flag_value(flag)
+      (flag.start_with?('no-') || flag.start_with?('NO-')) ? false : true
+    end
+
+  end
+end

data/lib/rubycom/command_interface.rb

@@ -0,0 +1,97 @@
+module Rubycom
+  module CommandInterface
+    require "#{File.dirname(__FILE__)}/helpers.rb"
+
+    # Uses #build_usage and #build_details to create a structured text output from the given command and doc hash
+    #
+    # @param [Module|Method|String] command the command to be named in the output
+    # @param [Hash] command_doc keys should include :full_doc and any keys required by #build_usage and #build_details
+    # @return [String] a structured string suitable for printing to the console as a command usage document
+    def self.build_interface(command, command_doc)
+      raise ArgumentError, "command should not be nil" if command.nil?
+      raise ArgumentError, "command_doc should not be nil" if command_doc.nil?
+      "#{self.build_usage(command, command_doc)}\n"+
+      "Description:\n"+
+      "#{command_doc.fetch(:full_doc, '').split("\n").map{|line| "  #{line}"}.join("\n").chomp}\n"+
+      "#{self.build_details(command, command_doc)}"
+    end
+
+    # Uses #build_options to create a usage banner for use in a command usage document
+    #
+    # @param [Module|Method|String] command the command to be named in the output
+    # @param [Hash] command_doc keys should include any keys required by #build_options
+    # @return [String] a structured text representation of usage patterns for the given command and doc hash
+    def self.build_usage(command, command_doc)
+      return '' if command.nil?
+      command_use = if File.basename($0, File.extname($0)).gsub("_", '') == command.name.to_s.downcase ||
+                        File.read($0).match(/(class|module)\s+#{command.name}/)
+                      File.basename($0)
+                    else
+                      command.name.to_s
+                    end
+      "Usage: #{command_use} #{self.build_options(command, command_doc)}"
+    end
+
+    # Creates a structured text representation of usage patterns for the given command and doc hash
+    #
+    # @param [Module|Method|String] command the class will be used to determine the overall usage pattern
+    # @param [Hash] command_doc keys should include :parameters and each parameter should be a hash including keys :type, :param_name, :default
+    # @return [String] a structured text representation of usage patterns for the given command and doc hash
+    def self.build_options(command, command_doc)
+      return '' if command_doc.nil?
+      if command.class == Module
+        "<command> [args]"
+      elsif command.class == Method
+        args, opts = command_doc.fetch(:parameters).map { |param|
+          if param.fetch(:type) == :req
+            "<#{param[:param_name]}>"
+          else
+            "[--#{param[:param_name]} #{param[:default]}]"
+          end
+        }.group_by { |p| p.start_with?('<') }.map { |_, group| group.join(' ') }
+        "#{args} #{opts}"
+      else
+        ""
+      end
+    end
+
+    # Creates a structured list of either sub commands or parameters based on the class of command
+    # Calls #build_tags if command is a Method
+    #
+    # @param [Module|Method|String] command the class will be used to determine the usage structure
+    # @param [Hash] command_doc keys should include :parameters and each parameter should be a hash including keys :type, :param_name, :default
+    # @return [String] a structured text representing a list of sub commands or a list of parameters
+    def self.build_details(command, command_doc)
+      if command.class == Module
+        sub_commands = Rubycom::Helpers.format_command_list(command_doc[:sub_command_docs], 90, '  ').join()
+        (sub_commands.empty?)? '' : "Sub Commands:\n#{sub_commands}"
+      elsif command.class == Method
+        tags = self.build_tags(Rubycom::Helpers.format_tags(command_doc[:tags]))
+        "#{tags[:others]}#{tags[:params]}#{tags[:returns]}"
+      else
+        ""
+      end
+    end
+
+    # Creates a structured text representing the given documentation tags
+    #
+    # @param [Hash] tags :params|:returns|:others => [Strings]
+    # @return [Hash] the given key => String representing the list of tags
+    def self.build_tags(tags)
+      return '' if tags.nil? || tags.empty?
+      tags.map{|k,val_arr|
+        val = val_arr.map { |line| "  #{line}" }.join.chomp
+        {
+            k => if k == :params
+                   (val.empty?)? '' : "\nParameters:\n#{val}"
+                 elsif k == :returns
+                   (val.empty?)? '' : "\nReturns:\n#{val}"
+                 else
+                   (val.empty?)? '' : "\nTags:\n#{val}"
+                 end
+        }
+      }.reduce({}, &:merge)
+    end
+
+  end
+end

data/lib/rubycom/completions.rb

@@ -0,0 +1,62 @@
+module Rubycom
+  module Completions
+
+    # 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
+    # @param [Module] command_plugin the plugin to use for retrieving commands
+    # @return [Array] a String Array including the possible matches for the given arguments
+    def self.tab_complete(base, arguments, command_plugin)
+      return [] unless base.class == Module
+      return [] unless command_plugin.class == Module
+      arguments = [] if arguments.nil?
+      args = (arguments.include?('tab_complete')) ? arguments[2..-1] : arguments
+      matches = %w()
+      if args.nil? || args.empty?
+        matches = command_plugin.get_commands(base, false)[base.to_s.to_sym].map { |sym,_| sym.to_s }
+      elsif args.length == 1
+        matches = command_plugin.get_commands(base, false)[base.to_s.to_sym].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], command_plugin)
+        end
+      elsif args.length > 1
+        begin
+          matches = self.tab_complete(Kernel.const_get(args[0].to_sym), args[1..-1], command_plugin)
+        rescue Exception
+          matches = %w()
+        end
+      end unless base.nil?
+      matches = %w() if matches.nil? || matches.include?(args[0])
+      matches
+    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(/^ {6}/, '')
+
+      _#{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
+  end
+end

data/lib/rubycom/error_handler.rb

@@ -0,0 +1,15 @@
+module Rubycom
+  module ErrorHandler
+
+    # Prints the error followed by the command line interface text
+    #
+    # @param [Error] e the error to be printed
+    # @param [String] cli_output the command line interface text to be printed
+    def self.handle_error(e, cli_output)
+      $stderr.puts e
+      $stderr.puts
+      $stderr.puts cli_output
+    end
+
+  end
+end

data/lib/rubycom/executor.rb

@@ -0,0 +1,23 @@
+module Rubycom
+  module Executor
+
+    # Calls the given method with the given parameters
+    #
+    # @param [Method] method the Method to call
+    # @param [Hash] parameters a Hash mapping parameter names to their intended values
+    # @return the result of the Method call
+    def self.execute_command(method, parameters={})
+      raise "#{method} should be a Method but was #{method.class}" if method.class != Method
+      raise "#{parameters} should be a Hash but was #{parameters.class}" if parameters.class != Hash
+      params = method.parameters.reject{|type,_|type == :rest}.map { |_, sym|
+        raise ExecutorError, "parameters should include values for all non * method parameters. Missing value for #{sym.to_s}" unless parameters.has_key?(sym)
+        parameters[sym]
+      }
+      unless method.parameters.select{|type,_|type == :rest}.first.nil? #if there is a * param
+        params = params + parameters[method.parameters.select{|type,_|type == :rest}.first[1]] #add in the values which were marked for the * param
+      end
+      (parameters.nil? || parameters.empty?) ? method.call : method.call(*params)
+    end
+
+  end
+end