rubycom 0.3.2 → 0.4.0

data/lib/rubycom/sources.rb

@@ -0,0 +1,99 @@
+module Rubycom
+  module Sources
+    require 'method_source'
+
+    # Calls #source_commands and filters to the source string of the first command returned
+    #
+    # @param [Array] command the commands whose source should be returned
+    # @return [String] the source code string if the command was a Module or Method. Returns the command otherwise
+    def self.source_command(command)
+      self.source_commands([command]).first[:source]
+    end
+
+    # Checks commands then calls #map_sources
+    #
+    # @param [Array] commands the commands whose source should be returned
+    # @return [Hash] :command => the command from commands, :source => the source code string if the command was a Module or Method
+    def self.source_commands(commands)
+      com = self.check(commands)
+      self.map_sources(com)
+    end
+
+    # Provides upfront checking for this inputs to #source_commands
+    def self.check(commands)
+      raise ArgumentError, "#{commands} should be an Array but was #{commands.class}" unless commands.class == Array
+      commands.each { |cmd|
+        raise ArgumentError, "#{cmd} should be a Module, Method, Symbol, or String but was #{cmd.class}" unless [Module, Method, Symbol, String].include?(cmd.class)
+      }
+    end
+
+    # Maps each command in commands to a hash containing the command and the source string for that command.
+    # Uses #module_source and #method_source to look up source strings when command is a Module or Method.
+    #
+    # @param [Array] commands the commands whose source should be returned
+    # @return [Hash] :command => the command from commands, :source => the source code string if the command was a Module or Method
+    def self.map_sources(commands)
+      commands.map { |cmd|
+        {
+            command: cmd,
+            source: if cmd.class == Module
+                      self.module_source(cmd)
+                    elsif cmd.class == Method
+                      self.method_source(cmd)
+                    elsif cmd.class == Symbol || cmd.class == String
+                      mod = cmd.to_s.split('::').reduce(Kernel){|last_mod, next_mod|
+                        last_mod.const_get(next_mod.to_s.to_sym)
+                      } rescue cmd
+                      self.module_source(mod)
+                    else
+                      cmd
+                    end
+        }
+      }
+    end
+
+    # Searches for the source location of the given module. Since modules can be defined in many locations, all source files
+    # containing a definition for the given module will be joined.
+    #
+    # @param [Module] mod the module to be sourced
+    # @return [String] a string representing the source of the given module or an empty string if no source file could be located
+    def self.module_source(mod)
+      return mod unless mod.class == Module
+      method_sources = mod.singleton_methods(true).select { |sym| ![:included, :extended].include?(sym) }.map { |sym|
+        mod.method(sym).source_location.first rescue nil
+      }
+      feature_sources = $LOADED_FEATURES.select{|file|
+        name_match = File.dirname(file) == File.dirname(File.realpath($0))
+        parent_match = File.dirname(File.dirname(file)) == File.dirname(File.dirname(File.realpath($0)))
+        ancestor_match = File.dirname(File.dirname(File.dirname(file))) == File.dirname(File.dirname(File.dirname(File.realpath($0))))
+        pwd_match = File.absolute_path(file).include?(Dir.pwd)
+        final = if name_match || parent_match || ancestor_match || pwd_match # prevents unnecessary file reading
+          (!File.read(file).match(/(class|module)\s+#{mod.name}/).nil?) rescue false
+        else
+          false
+        end
+        final
+      }
+      source_files = (method_sources + feature_sources).compact.uniq
+      unless source_files.include?($0) # prevents unnecessary file reading
+        source_files << $0 unless File.read($0).match(/(class|module)\s+#{mod.name}/).nil?
+      end
+
+      return '' if source_files.empty?
+      source_files.reduce(''){|source_str, next_file|
+        source_str << File.read(next_file)
+        source_str << "\n" unless source_str.end_with?("\n")
+        source_str
+      } || ''
+    end
+
+    # Discovers the source code for the given method.
+    #
+    # @param [Method] method the method to be source
+    # @return [String] the source of the specified method
+    def self.method_source(method)
+      return method unless method.class == Method
+      method.comment + method.source
+    end
+  end
+end

data/lib/rubycom/version.rb

@@ -1,3 +1,3 @@
 module Rubycom
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/rubycom/yard_doc.rb

@@ -0,0 +1,146 @@
+module Rubycom
+  module YardDoc
+    require 'yard'
+
+    # Transforms the command to a Hash representing the command and it's documentation
+    #
+    # @param [Array] command a Module or Method to be documented
+    # @param [Module] source_method a Module which will be used to retrieve module and method source code
+    # @return [Array] a Hash which is the result calling #map_doc
+    def self.document_command(command, source_method)
+      self.document_commands([command], source_method).first[:doc]
+    end
+
+    # Transforms each command in commands to a Hash representing the command and it's documentation
+    #
+    # @param [Array] commands a set of Modules and Methods to be documented
+    # @param [Module] source_method a Module which will be used to retrieve module and method source code
+    # @return [Array] a set of Hashes which are the result calling #map_doc
+    def self.document_commands(commands, source_method)
+      commands, source_method = self.check(commands, source_method)
+      self.map_doc(commands, source_method)
+    end
+
+    # Provides upfront checking for this inputs to #document_commands
+    def self.check(commands, source_fn)
+      YARD::Logger.instance.level = YARD::Logger::FATAL
+      raise ArgumentError, "#{source_fn} should be a Method or Proc but was #{source_fn.class}" unless [Method, Proc].include?(source_fn.class)
+      raise ArgumentError, "#{commands} should be an Array but was #{commands.class}" unless commands.class == Array
+      [commands, source_fn]
+    end
+
+    # Transforms each command in commands to a Hash representing the command and it's documentation
+    #
+    # @param [Array] commands a set of Modules and Methods to be documented
+    # @param [Method|Proc] source_method used to retrieve module and method source code
+    # @return [Array] a set of Hashes which are the result of calls to #module_doc and #method_doc
+    def self.map_doc(commands, source_method)
+      commands.map { |cmd|
+        {
+            command: cmd,
+            doc: if cmd.class == Module
+                   self.module_doc(cmd, source_method)
+                 elsif cmd.class == Method
+                   self.method_doc(cmd, source_method)
+                 else
+                   {short_doc: '', full_doc: ''}
+                 end
+        }
+      }
+    end
+
+    # Extracts elements of source code documentation for the given module. Calls #source_command on the given
+    # source_plugin to retrieve the method's source code.
+    #
+    # @param [Module] mod a Module instance representing the module whose documentation should be parsed
+    # @param [Method] source_method a Module which will be used to retrieve module and method source code
+    # @return [Hash] :short_doc => String, :full_doc => String, :sub_command_docs => [ { sub_command_name_symbol => String } ]
+    def self.module_doc(mod, source_method)
+      module_source = source_method.call(mod)
+      YARD::Registry.clear
+      YARD.parse_string(module_source.to_s)
+      doc_obj = YARD::Registry.at(mod.to_s)
+      return {short_doc: '', full_doc: ''} if doc_obj.nil?
+      {
+          short_doc: doc_obj.docstring.summary,
+          full_doc: doc_obj.docstring.to_s,
+          sub_command_docs: doc_obj.meths(:visibility => :public, :scope => :class).map { |doc_method|
+            {
+                doc_method.name => self.method_doc(mod.public_method(doc_method.name), doc_method)[:short_doc]
+            }
+          }.reduce({}, &:merge).merge(
+              doc_obj.mixins.select { |doc_mod| doc_mod.name != :Rubycom }.map { |doc_mod|
+                namespaced_mod_name = "#{doc_mod.namespace}::#{doc_mod.name}"
+                mod_source = source_method.call(namespaced_mod_name)
+                mod_source = source_method.call(doc_mod.name) if mod_source == namespaced_mod_name
+                YARD.parse_string(mod_source.to_s)
+                sub_doc_obj = YARD::Registry.at(doc_mod.to_s)
+                {
+                    doc_mod.name => (sub_doc_obj.nil?) ? '' : sub_doc_obj.docstring.summary.to_s
+                }
+              }.reduce({}, &:merge)
+          )
+      }
+    end
+
+    # Extracts elements of source code documentation for the given method. Calls #source_command on the given source_plugin
+    # to retrieve the method's source code.
+    #
+    # @param [Method] method a Method instance representing the method whose documentation should be parsed
+    # @param [Method|Proc|YARD::CodeObjects::MethodObject] source_method called to retrieve the method's source code.
+    # Alternately this parameter can be a YARD::CodeObjects::MethodObject which will be used instead of looking
+    # up the method's source code
+    # @return [Hash] :short_doc => String, :full_doc => String,
+    # :tags => [ { :tag_name => String, :name => String, :types => [String], :text => String  } ],
+    # :parameters => [ { :param_name => String, :type => :req|:opt|:rest, :default => Object, :doc_type => String, :doc => String } ]
+    def self.method_doc(method, source_method)
+      raise ArgumentError, "method should be a Method but was #{method.class}" unless method.class == Method
+      method_param_types = method.parameters.map { |type, sym| {sym => type} }.reduce({}, &:merge)
+      if source_method.class == YARD::CodeObjects::MethodObject
+        doc_obj = source_method
+      elsif source_method.is_a?(Proc) || source_method.is_a?(Method)
+        YARD::Registry.clear
+        YARD.parse_string(source_method.call(method))
+        method_name = method.name
+        doc_obj = YARD::Registry.at(method_name.to_s)
+        doc_obj = YARD::Registry.at("::#{method_name.to_s}") if doc_obj.nil?
+        doc_obj = YARD::Registry.at("\##{method_name.to_s}") if doc_obj.nil?
+        doc_obj = YARD::Registry.at(method_name.to_s.split('.').last) if doc_obj.nil?
+        raise ArgumentError, "No such method #{method_name} in the given source." if doc_obj.nil?
+      else
+        raise ArgumentError, "source_plugin should be YARD::CodeObjects::MethodObject|Method but was #{source_method.class}"
+      end
+      {
+          parameters: doc_obj.parameters.map { |k, v|
+            # YARD's parsing returns pairs of params and values
+            # if the param has a default value then the value is wrapped in a string
+            # required arguments have a value of nil
+            param_type = method_param_types[k.reverse.chomp('*').reverse.to_sym]
+            param_default = if param_type == :rest
+                              []
+                            else
+                              (v.class == String) ? method.receiver.module_eval(v) : v
+                            end
+            {
+                param_name: k,
+                type: param_type,
+                default: param_default,
+                doc_type: doc_obj.tags.select { |tag| tag.name == k.to_s }.map { |tag| tag.types }.join(','),
+                doc: doc_obj.tags.select { |tag| tag.name == k.to_s }.map { |tag| tag.text }.join("\n")
+            }
+          },
+          short_doc: doc_obj.base_docstring.summary.to_s,
+          full_doc: doc_obj.base_docstring.to_s,
+          tags: doc_obj.tags.map { |tag|
+            {
+                tag_name: tag.tag_name,
+                name: tag.name,
+                types: tag.types,
+                text: tag.text
+            }
+          }
+      }
+    end
+
+  end
+end

data/rubycom.gemspec

@@ -1,26 +1,24 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'rubycom/version'
+require "#{File.dirname(__FILE__)}/lib/rubycom/version.rb"
 
 Gem::Specification.new do |spec|
-  spec.name          = "rubycom"
+  spec.name          = 'rubycom'
   spec.version       = Rubycom::VERSION
-  spec.authors       = ["Danny Purcell"]
-  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"
-  spec.license       = "MIT"
+  spec.authors       = ['Danny Purcell']
+  spec.email         = %w(d.purcell.jr+rubycom@gmail.com)
+  spec.description   = %q{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.}
+  spec.summary       = %q{Turn your library into a command-line app by simply including Rubycom.}
+  spec.homepage      = 'http://dannypurcell.github.io/rubycom'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = %w(lib)
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "test-unit"
-  spec.add_development_dependency "yard"
-  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'test-unit'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rake'
   spec.add_dependency 'method_source'
+  spec.add_dependency 'parslet'
 end

data/test/rubycom/arg_parse_test.rb

@@ -0,0 +1,247 @@
+require "#{File.dirname(__FILE__)}/../../lib/rubycom/arg_parse.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 ArgParseTest < Test::Unit::TestCase
+
+  def test_parse_string
+    test_arg = "test_arg"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["test_arg"]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_empty
+    test_arg = []
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_bad_arg
+    test_arg = ["[1,2,\"3]"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["[1,2,\"3]"]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_fixnum
+    test_arg = ["1234512415435"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => [1234512415435]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_float
+    test_arg = ["12345.67890"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => [12345.6789]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_timestamp
+    time = Time.new
+    test_arg = ["#{time.to_s}"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => [YAML.load(time.to_s)]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_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::ArgParse.parse_command_line(test_arg)
+    expected = {:args => [YAML.load(date.to_s)]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_array
+    test_arg = "[\"1\", 2, \"a\", 'b']"
+    result = Rubycom::ArgParse.parse_command_line(test_arg.to_s)
+    expected = {:args => [["1", 2, "a", "b"]]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_hash
+    time = Time.new.to_s
+    test_arg = "{a: \"#{time}\"}"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {args: [{'a' => time}]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_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::ArgParse.parse_command_line(test_arg.to_s)
+    expected = {:args => [{: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_yaml
+    time_str = Time.now.to_s
+    test_arg = {:a => ["1", 2, "a", 'b'], :b => 1, :c => "test", :d => "#{time_str}"}
+    result = Rubycom::ArgParse.parse_command_line("#{test_arg.to_yaml}")
+    expected = {:args => [{:a => ["1", 2, "a", "b"], :b => 1, :c => "test", :d => "#{time_str}"}]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_code
+    test_arg = "def self.test_code_method; raise \"Fail - test_parse_code\";end"
+    result = Rubycom::ArgParse.parse_command_line(test_arg.to_s)
+    expected = {:args => ["def self.test_code_method; raise \"Fail - test_parse_code\";end"]}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_array_opt
+    test_arg = ['--test_opt', "1,2,3"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts=>{"test_opt"=>[1,2,3]}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_alternate_array_opt
+    test_arg = ['--test_opt', "[1,2,3]"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts=>{"test_opt"=>[1,2,3]}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_unrecognized_array_opt
+    test_arg = ['--test_opt', "[1,2,\"3]"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts=>{"test_opt"=>"[1,2,\"3]"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_string_eq
+    test_arg = ["-test_arg", "=", "test"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_arg" => "test"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_string_eq_quoted
+    test_arg = ["-test_arg", "=", "\"test\""]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_arg" => "test"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_string_sp
+    test_arg = ["-test_arg", "test"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_arg" => "test"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_long_string_eq
+    test_arg = ['--test_arg', '=', 'test']
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_arg" => "test"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_opt_long_string_sp
+    test_arg = ["--test_arg", "test"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_arg" => "test"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_multi_mention
+    test_arg = ["--other", "=", 'testing', "--test_arg", "test", "--test_arg", "thing"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"other" => "testing", "test_arg" => ["test", "thing"]}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_multi_mention_mixed
+    test_arg = ["--test_arg", "--other", "=", 'testing', "--test_arg", "test", "--test_arg", "thing"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"other" => "testing", "test_arg" => [true, "test", "thing"]}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_true_short
+    test_arg = "-t"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"t" => true}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_true_short_multi
+    test_arg = "-tuv"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"t" => true, "u" => true, "v" => true}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_true_short_multi_mention
+    test_arg = ["-tuv", "-no-tuv"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"t" => [true, false], "u" => [true, false], "v" => [true, false]}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_true_long
+    test_arg = "--test_flag"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_flag" => true}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_false_short
+    test_arg = "-no-t"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"t" => false}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_false_short_multi
+    test_arg = "-no-abc"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"a" => false, "b" => false, "c" => false}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_flag_false_long
+    test_arg = "--no-test_flag"
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:opts => {"test_flag" => false}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_command_run
+    test_arg = ["UtilTestModule", "test_command_with_return", "testing_argument", "--test_option_int=10"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["UtilTestModule", "test_command_with_return", "testing_argument"], :opts => {"test_option_int" => 10}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_command_run_mixed
+    test_arg = ["UtilTestModule", "test_command_mixed_options", "testing_arg", "[test1, test2]", "-test_opt='testing_option'", "{a: 'test_hsh_arg'}", "-test_bool=true", "some", "other", "args"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["UtilTestModule", "test_command_mixed_options", "testing_arg", ["test1", "test2"], {"a" => "test_hsh_arg"}, "some", "other", "args"], :opts => {"test_bool" => true, "test_opt" => "testing_option"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_command_run_mixed_args_opts
+    test_arg = ["-test_opt", "testing_option", "UtilTestModule", "-test_bool", "true", "test_command_mixed_options", "testing_arg", "[test1, test2]", "{a: 'test_hsh_arg'}", "some", "other", "args"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["UtilTestModule", "test_command_mixed_options", "testing_arg", ["test1", "test2"], {"a" => "test_hsh_arg"}, "some", "other", "args"], :opts => {"test_bool" => true, "test_opt" => "testing_option"}}
+    assert_equal(expected, result)
+  end
+
+  def test_parse_command_run_mixed_opts_flag
+    test_arg = ["--test_bool", "-test_opt", "testing_option", "UtilTestModule", "test_command_mixed_options", "testing_arg", "[test1, test2]", "{a: 'test_hsh_arg'}", "some", "other", "args"]
+    result = Rubycom::ArgParse.parse_command_line(test_arg)
+    expected = {:args => ["UtilTestModule", "test_command_mixed_options", "testing_arg", ["test1", "test2"], {"a" => "test_hsh_arg"}, "some", "other", "args"], :opts => {"test_bool" => true, "test_opt" => "testing_option"}}
+    assert_equal(expected, result)
+  end
+
+end