rubycom 0.3.2 → 0.4.0

data/test/rubycom/util_test_no_singleton.rb

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

data/test/rubycom/util_test_sub_module.rb

@@ -0,0 +1,13 @@
+module UtilTestComposite
+  # Sub-Module in UtilTestComposite
+  module UtilTestSubModule
+
+    # Test command in a sub-module as part of UtilTestComposite
+    #
+    # @param [String] test the testing parameter to output
+    # @return [String] a String representation of the input parameter
+    def self.sub_module_command(test)
+      "test = #{test}"
+    end
+  end
+end

data/test/rubycom/yard_doc_test.rb

@@ -0,0 +1,165 @@
+require "#{File.dirname(__FILE__)}/../../lib/rubycom/yard_doc.rb"
+
+require "#{File.dirname(__FILE__)}/../../lib/rubycom/sources.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 YardDocTest < Test::Unit::TestCase
+
+  def test_document_commands
+    test_commands = [
+        UtilTestComposite,
+        UtilTestModule,
+        UtilTestModule.public_method(:test_command),
+        "test_extra_arg"
+    ]
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_commands(test_commands, test_source_fn)
+    assert(result.class == Array, "result should be an array")
+    result.each{|h|
+      assert(h.class == Hash, "each command in the result should be a Hash. #{h}")
+      assert(h.has_key?(:command), "each command hash should respond to :command. #{h}")
+      assert([Module, Method, String].include?(h[:command].class),"each command should be a Module | Method | String. #{h[:command]}")
+      assert(h.has_key?(:doc), "each command hash should respond to :doc. #{h}")
+      assert(h[:doc].has_key?(:full_doc), "each doc hash should respond to :full_doc. #{h[:doc]}")
+      assert(h[:doc].has_key?(:short_doc), "each doc hash should respond to :short_doc. #{h[:doc]}")
+      if h[:command].class == Module
+        assert(h[:doc].has_key?(:sub_command_docs), "if the command is a module then the :doc has should respond to :sub_command_docs #{h[:doc]}")
+        assert(h[:doc][:sub_command_docs].class == Hash, "sub_command_docs should be a Hash. #{h[:doc][:sub_command_docs]}")
+        h[:doc][:sub_command_docs].each{|k,v|
+          assert(k.class == Symbol, "each sub_command_doc key should be a symbol. k: #{k}, k.class #{k.class}")
+          assert(v.class == String, "each sub_command_doc value should be a string. k: #{k}, v: #{v}, v.class: #{v.class}")
+        }
+      elsif h[:command].class == Method
+        assert(h[:doc].has_key?(:parameters), "if the command is a method then the :doc has should respond to :parameters. #{h[:doc]}")
+        assert(h[:doc].has_key?(:tags), "if the command is a method then the :doc has should respond to :tags. #{h[:doc]}")
+        assert(h[:doc][:parameters].class == Array, "parameters should be a Hash. #{h[:doc][:parameters]}")
+        assert(h[:doc][:tags].class == Array, "parameters should be a Hash. #{h[:doc][:tags]}")
+        h[:doc][:parameters].each{|ph|
+          assert(ph.class == Hash, "each parameter should be a Hash. #{ph}")
+          assert(ph.class == Hash, "each parameter should be a Hash. #{ph}")
+          assert(ph.has_key?(:default), "each parameter should respond to :default. #{ph}")
+          assert(ph.has_key?(:doc), "each parameter should respond to :doc. #{ph}")
+          assert(ph.has_key?(:doc_type), "each parameter should respond to :doc_type. #{ph}")
+          assert(ph.has_key?(:type), "each parameter should respond to :type. #{ph}")
+        }
+        h[:doc][:tags].each{|th|
+          assert(th.class == Hash, "each tag should be a Hash")
+          assert(th.has_key?(:name), "each tag should respond to :name. #{th}")
+          assert(th.has_key?(:tag_name), "each tag should respond to :tag_name. #{th}")
+          assert(th.has_key?(:text), "each tag should respond to :text. #{th}")
+          assert(th.has_key?(:types), "each tag should respond to :types. #{th}")
+        }
+      else
+        assert(([:full_doc, :short_doc] - h[:doc].keys).length == 0, "if the command is a String then :doc should only respond to :short_doc and :full_doc. #{h[:doc]}")
+      end
+    }
+  end
+
+  def test_document_command_command_run
+    test_command = UtilTestModule.public_method(:test_command_with_return)
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_command(test_command, test_source_fn)
+    assert(result.has_key?(:full_doc), "each doc hash should respond to :full_doc. #{result}")
+    assert(result.has_key?(:short_doc), "each doc hash should respond to :short_doc. #{result}")
+    assert(result.has_key?(:parameters), "if the command is a method then the :doc has should respond to :parameters. #{result}")
+    assert(result.has_key?(:tags), "if the command is a method then the :doc has should respond to :tags. #{result}")
+    assert(result[:parameters].class == Array, "parameters should be a Hash. #{result[:parameters]}")
+    assert(result[:tags].class == Array, "parameters should be a Hash. #{result[:tags]}")
+    result[:parameters].each{|ph|
+      assert(ph.class == Hash, "each parameter should be a Hash. #{ph}")
+      assert(ph.has_key?(:default), "each parameter should respond to :default. #{ph}")
+      assert(ph.has_key?(:doc), "each parameter should respond to :doc. #{ph}")
+      assert(ph.has_key?(:doc_type), "each parameter should respond to :doc_type. #{ph}")
+      assert(ph.has_key?(:type), "each parameter should respond to :type. #{ph}")
+    }
+    result[:tags].each{|th|
+      assert(th.class == Hash, "each tag should be a Hash")
+      assert(th.has_key?(:name), "each tag should respond to :name. #{th}")
+      assert(th.has_key?(:tag_name), "each tag should respond to :tag_name. #{th}")
+      assert(th.has_key?(:text), "each tag should respond to :text. #{th}")
+      assert(th.has_key?(:types), "each tag should respond to :types. #{th}")
+    }
+  end
+
+  def test_document_command_command_run_rest
+    test_command = UtilTestModule.public_method(:test_command_mixed_options)
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_command(test_command, test_source_fn)
+    assert(result.has_key?(:full_doc), "each doc hash should respond to :full_doc. #{result}")
+    assert(result.has_key?(:short_doc), "each doc hash should respond to :short_doc. #{result}")
+    assert(result.has_key?(:parameters), "if the command is a method then the :doc has should respond to :parameters. #{result}")
+    assert(result.has_key?(:tags), "if the command is a method then the :doc has should respond to :tags. #{result}")
+    assert(result[:parameters].class == Array, "parameters should be a Hash. #{result[:parameters]}")
+    assert(result[:tags].class == Array, "parameters should be a Hash. #{result[:tags]}")
+    result[:parameters].each{|ph|
+      assert(ph.class == Hash, "each parameter should be a Hash. #{ph}")
+      assert(ph.has_key?(:default), "each parameter should respond to :default. #{ph}")
+      assert(ph.has_key?(:doc), "each parameter should respond to :doc. #{ph}")
+      assert(ph.has_key?(:doc_type), "each parameter should respond to :doc_type. #{ph}")
+      assert(ph.has_key?(:type), "each parameter should respond to :type. #{ph}")
+      if ph[:type] == :rest
+        assert(ph[:param_name].start_with?("*"), "a rest parameter's name should start with a star")
+      end
+    }
+    result[:tags].each{|th|
+      assert(th.class == Hash, "each tag should be a Hash")
+      assert(th.has_key?(:name), "each tag should respond to :name. #{th}")
+      assert(th.has_key?(:tag_name), "each tag should respond to :tag_name. #{th}")
+      assert(th.has_key?(:text), "each tag should respond to :text. #{th}")
+      assert(th.has_key?(:types), "each tag should respond to :types. #{th}")
+    }
+  end
+
+  def test_document_command_run_module
+    test_command = UtilTestModule
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_command(test_command, test_source_fn)
+    assert(result.has_key?(:sub_command_docs), "if the command is a module then the :doc has should respond to :sub_command_docs #{result}")
+    assert(result[:sub_command_docs].class == Hash, "sub_command_docs should be a Hash. #{result[:sub_command_docs]}")
+    result[:sub_command_docs].each{|k,v|
+      assert(k.class == Symbol, "each sub_command_doc key should be a symbol. k: #{k}, k.class #{k.class}")
+      assert(v.class == String, "each sub_command_doc value should be a string. k: #{k}, v: #{v}, v.class: #{v.class}")
+    }
+  end
+
+  def test_document_command_run_composite
+    test_command = UtilTestComposite
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_command(test_command, test_source_fn)
+    result_sub_command_doc = result[:sub_command_docs]
+    result_sub_command_doc_keys = result_sub_command_doc.keys.map{|sub_mod|sub_mod.to_s}
+    test_command.included_modules.reject{|mod|mod.to_s=="Rubycom"}.map{|mod|mod.to_s}.each{|mod|
+      assert(result_sub_command_doc_keys.include?(mod.split("::").last), "result_sub_command_doc_keys #{result_sub_command_doc_keys} should include #{mod.split("::").last}")
+    }
+    result_sub_command_doc.each{|k,v|
+      if k.to_s == "UtilTestNoSingleton"
+        assert_equal(v, '')
+      else
+        assert(v != '', "sub_command_doc for #{k} should not be empty")
+      end
+    }
+  end
+
+  def test_document_command_run_composite_command
+    test_command = UtilTestComposite.public_method(:test_composite_command)
+    test_source_fn = Rubycom::Sources.public_method(:source_command)
+    result = Rubycom::YardDoc.document_command(test_command, test_source_fn)
+    expected = {
+        :full_doc => "A test_command in a composite console",
+        :parameters => [
+            {:default => nil, :doc => "a test argument", :doc_type => "String", :param_name => "test_arg", :type => :req}
+        ],
+        :short_doc => "A test_command in a composite console.",
+        :tags => [
+            {:name => "test_arg", :tag_name => "param", :text => "a test argument", :types => ["String"]},
+            {:name => nil, :tag_name => "return", :text => "the test arg", :types => ["String"]}
+        ]
+    }
+    assert_equal(expected, result)
+  end
+
+end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rubycom
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Danny Purcell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-20 00:00:00.000000000 Z
+date: 2013-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: test-unit
   requirement: !ruby/object:Gem::Requirement
@@ -80,10 +80,23 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: 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.
+- !ruby/object:Gem::Dependency
+  name: parslet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Enables command-line access for methods in an including module. Reads
+  method documentation for command line help output. Parses command line options and
+  flags. Turn your library into a command-line app by simply including Rubycom.
 email:
 - d.purcell.jr+rubycom@gmail.com
 executables: []
@@ -96,20 +109,36 @@ files:
 - README.md
 - Rakefile
 - lib/rubycom.rb
-- lib/rubycom/arguments.rb
-- lib/rubycom/commands.rb
-- lib/rubycom/documentation.rb
+- lib/rubycom/arg_parse.rb
+- lib/rubycom/command_interface.rb
+- lib/rubycom/completions.rb
+- lib/rubycom/error_handler.rb
+- lib/rubycom/executor.rb
+- lib/rubycom/helpers.rb
+- lib/rubycom/output_handler.rb
+- lib/rubycom/parameter_extract.rb
+- lib/rubycom/singleton_commands.rb
+- lib/rubycom/sources.rb
 - lib/rubycom/version.rb
+- lib/rubycom/yard_doc.rb
 - rubycom.gemspec
-- test/rubycom/arguments_test.rb
-- test/rubycom/commands_test.rb
-- test/rubycom/documentation_test.rb
+- test/rubycom/arg_parse_test.rb
+- test/rubycom/command_interface_test.rb
+- test/rubycom/completions_test.rb
+- test/rubycom/error_handler_test.rb
+- test/rubycom/executor_test.rb
+- test/rubycom/helpers_test.rb
+- test/rubycom/output_handler_test.rb
+- test/rubycom/parameter_extract_test.rb
 - test/rubycom/rubycom_test.rb
+- test/rubycom/singleton_commands_test.rb
+- test/rubycom/sources_test.rb
+- test/rubycom/util_test_bin.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
+- test/rubycom/util_test_sub_module.rb
+- test/rubycom/yard_doc_test.rb
 homepage: http://dannypurcell.github.io/rubycom
 licenses:
 - MIT
@@ -133,15 +162,23 @@ rubyforge_project:
 rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
-summary: Converts singleton methods to command-line functions upon inclusion.
+summary: Turn your library into a command-line app by simply including Rubycom.
 test_files:
-- test/rubycom/arguments_test.rb
-- test/rubycom/commands_test.rb
-- test/rubycom/documentation_test.rb
+- test/rubycom/arg_parse_test.rb
+- test/rubycom/command_interface_test.rb
+- test/rubycom/completions_test.rb
+- test/rubycom/error_handler_test.rb
+- test/rubycom/executor_test.rb
+- test/rubycom/helpers_test.rb
+- test/rubycom/output_handler_test.rb
+- test/rubycom/parameter_extract_test.rb
 - test/rubycom/rubycom_test.rb
+- test/rubycom/singleton_commands_test.rb
+- test/rubycom/sources_test.rb
+- test/rubycom/util_test_bin.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
+- test/rubycom/util_test_sub_module.rb
+- test/rubycom/yard_doc_test.rb
 has_rdoc: 

data/lib/rubycom/arguments.rb

@@ -1,133 +0,0 @@
-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.resolve(parameters={}, arguments=[])
-      raise CLIError, 'parameters may not be nil' if parameters.nil?
-      raise CLIError, 'arguments may not be nil' if arguments.nil?
-      parsed_args = self.parse_args(arguments)
-
-      args = parsed_args[:rubycom_non_opt_arg] || []
-      options = parsed_args.select{|key,_| key != :rubycom_non_opt_arg } || {}
-      parsed_arg_count = args.length + options.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 #{parsed_arg_count}" if parsed_arg_count < (types[:req]||0)
-      raise CLIError, "Wrong number of arguments. Expected at most #{(types[:req]||0) + (types[:opt]||0)}, received #{parsed_arg_count}" if types[:rest].nil? && (parsed_arg_count > ((types[:req]||0) + (types[:opt]||0)))
-
-      self.merge_params(parameters, parsed_args)
-    end
-
-    # Matches the given parameters to the given pre-parsed arguments
-    #
-    # @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 [Hash] parsed_args a Hash of parsed arguments where the keys are either the name of the optional argument
-    #         the value to designated for or :rubycom_non_opt_arg if the argument was not sent for a specified optional parameter
-    # @return [Hash] a Hash mapping the defined parameters to their matching argument values
-    def self.merge_params(parameters={}, parsed_args={})
-      parameters.map { |param_sym, def_hash|
-        if def_hash[:type] == :req
-          raise CLIError, "No argument available for #{param_sym}" if parsed_args[:rubycom_non_opt_arg].nil? || parsed_args[:rubycom_non_opt_arg].length == 0
-          Hash[param_sym, parsed_args[:rubycom_non_opt_arg].shift]
-        elsif def_hash[:type] == :opt
-          if parsed_args[param_sym].nil?
-            arg = (parsed_args[:rubycom_non_opt_arg].nil? || parsed_args[:rubycom_non_opt_arg].empty?) ? parameters[param_sym][:default] : parsed_args[:rubycom_non_opt_arg].shift
-          else
-            arg = parsed_args[param_sym]
-          end
-          Hash[param_sym, arg]
-        elsif def_hash[:type] == :rest
-          ret = Hash[param_sym, ((!parsed_args[param_sym].nil?) ? parsed_args[param_sym] : parsed_args[:rubycom_non_opt_arg])]
-          parsed_args[:rubycom_non_opt_arg] = []
-          ret
-        end
-      }.reduce(&:merge)
-    end
-
-    def self.parse_args(arguments)
-      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) || {}
-    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|
-          if index == 0
-            part.chomp('=').gsub(/^--/, '').gsub(/^-/, '').strip.to_sym
-          else
-            if part.start_with?("#") || part.start_with?("!")
-              "#{part}"
-            else
-              (YAML.load(part) rescue "#{part}")
-            end
-          end
-        }
-        Hash[k, v]
-      else
-        begin
-          parsed_arg = "#{arg}"
-          unless arg.start_with?("#") || arg.start_with?("!")
-            parsed_arg = YAML.load("#{arg}")
-          end
-        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