nrser-rash 0.2.0

data/lib/nrser/rash/functions.rb

@@ -0,0 +1,154 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+module NRSER::Rash
+  # Users money-patch class methods into this call to expose them to Rash.
+  module Functions; end
+  
+  # @!group Rash Function Class Methods
+  # ==========================================================================
+  
+  def self.load_functions
+    path = config('FUNCTIONS').to_pn
+    require path
+  end
+  
+  
+  def self.stub_function?(mod, method_name)
+    return false unless mod.method(method_name)
+    return false if method_name.to_s[0] == '_'[0]
+    true
+  end
+  
+  
+  def self.stub_name namespace, method_name
+    (
+      (namespace.map {|s| s.downcase}) +
+      [method_name]
+    ).join(config('STUB_NAMESPACE_SEPERATOR'))
+  end
+  
+  
+  def self.submodule? obj
+    obj.is_a?(Module) && (not obj.is_a?(Class))
+  end
+  
+
+  # TODO: doesn't work. was try to prevent overriding non-rash functions
+  #       (without some yet to be implemented way of doing so explicitly)
+  #       'cause this can cause accidental CHAOS with other scripts
+  def self.conflict? name
+    return false
+    type = `type #{ name } 2>&1`
+    if name == 'blah'
+      raise type
+    end
+    return false if $?.exitstatus != 0
+    return true
+    not type =~ /rash\ call/
+  end
+
+  # Stub out all the singleton methods under {NRSER::Rash::Functions}
+  def self.function_names
+    call_args = []
+    # method to recursivly stub singleton functions in a module
+    from_module = -> mod do
+      # when the name is split, 'Rash' and 'Functions' take up the
+      # first two elements, so drop those to get the namespace
+      # as an array of strings
+      namespace = mod.name.split( '::' ).drop( 3 )
+      # get each singleton method (`def self.*` style)
+      mod.singleton_methods.select {|method_name|
+        # throw out those that should not be stubbed
+        stub_function? mod, method_name
+      }.each do |method_name|
+
+        call_arg = if namespace.empty?
+          method_name.to_s
+        else
+          "#{ namespace.join('.') }.#{ method_name }"
+        end
+
+        call_args << call_arg.downcase
+      end
+
+      # descend into submodules
+      mod.constants.map {|name|
+        mod.const_get(name)
+      }.select {|const|
+        # exclude any TestCase classes
+        # (const.is_a? Module) && (not const < Minitest::Test)
+        submodule? const
+      }.each {|submod|
+        from_module.call submod
+      }
+    end # from_module
+
+    from_module.call NRSER::Rash::Functions
+    call_args
+  end # .function_names
+  
+  
+  # stub out all the singleton methods under {NRSER::Rash::Functions}
+  def self.function_map
+    results = []
+    # method to recursively stub singleton functions in a module
+    from_module = lambda do |mod|
+      # when the name is split, 'Rash' and 'Functions' take up the
+      # first two elements, so drop those to get the namespace
+      # as an array of strings
+      namespace = mod.name.split('::').drop(2)
+      # get each singleton method (`def self.*` style)
+      mod.singleton_methods.select {|method_name|
+        # throw out those that should not be stubbed
+        stub_function? mod, method_name
+      }.each do |method_name|
+
+        # the function name is the namespace plus the method name
+        # with segments seperated by `'.'`, ex:
+        #
+        #     namespace       = ['Nrser', Url']
+        #     method_name     = 'parse'
+        #     function_name   = 'Nrser.Url.parse'
+        #
+        # funcs << (namespace.clone << method_name)
+        function_name = stub_name namespace, method_name
+
+        call_arg = if namespace.empty?
+          method_name.to_s
+        else
+          "#{ namespace.join('.') }.#{ method_name }"
+        end
+
+        results << {'name' => function_name, 'sig' => call_arg}
+      end
+
+      # descend into submodules
+      mod.constants.map {|name|
+        mod.const_get(name)
+      }.select {|const|
+        # exclude any TestCase classes
+        # (const.is_a? Module) && (not const < Minitest::Test)
+        submodule? const
+      }.each {|submod|
+        from_module.call submod
+      }
+    end
+
+    from_module.call NRSER::Rash::Functions
+    results
+  end # .function_map
+  
+  # @!endgroup Rash Function Class Methods
+  
+end # module NRSER::Rash

data/lib/nrser/rash/helpers.rb

@@ -0,0 +1,53 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# Helpful and not so helpful things.
+# 
+module NRSER::Rash::Helpers
+  
+  include SemanticLogger::Loggable
+  
+  class << self
+    def quote(value)
+      double_quote(value)
+    end
+    alias_method :q, :quote
+
+    # single-quote a string for bash
+    # reaplces `'` with `'\''`
+    def single_quote(string)
+      "'" + string.gsub(/'/, {"'" => "'\\''"}) + "'"
+    end
+    alias_method :sq, :single_quote
+
+    # double-quote a string for bash
+    # replaces `"` with `\"` and `\` with `\\`
+    def double_quote(string)
+      '"' + string.gsub(/["\\]/, {'"' => '\"', '\\' => '\\\\'}) + '"'
+    end
+    alias_method :dq, :double_quote
+
+    def block(start, finish, &body)
+      $stdout.block start, finish, &body
+    end
+
+    def user name = nil, &body
+      # if no name is provided, it just means 'not root'
+      if name.nil?
+        body.() if ENV['USER'] != 'root'
+      else
+        body.() if ENV['USER'] == name
+      end
+    end
+  end # class << self
+end # module NRSER::Rash::Helpers

data/lib/nrser/rash/testing.rb

@@ -0,0 +1,305 @@
+require 'minitest'
+
+module NRSER::Rash
+  
+  # @!group Testing Class Methods
+  # ==========================================================================
+
+  # @todo
+  #   It seems like testing doesn't work in the state I came back to it
+  #   2018.02.22
+  # 
+  # 
+  # runs tests declared for functions using the `_test_case` and
+  # `_test_functions` macros. this is hackety-hack-hackety.
+  #
+  # rational:
+  # 
+  # i'm using `Test::Unit`. because it comes with the stdlib. `Test::Unit`
+  # looks to be based on [MiniTest][https://github.com/seattlerb/minitest],
+  # but i can't find great docs on using that either, and i though the
+  # `Test::Unit` API might be better known, so i went with that.
+  # 
+  # the only way i can really find using `Test::Unit` documented is
+  # to `require 'test/unit'`, which runs all declared `Test::Unit::TestCase`
+  # subclasses, reading options off the command line and spitting results
+  # back to `STDOUT`.
+  # 
+  # there is an optional `--name <pattern>` arg that you can supply on the
+  # command line when invoking a script with a `require 'test/unit' line
+  # in it, but it seems like it only matches against method names, not
+  # `TestCase` subclasses or anything. under this assumption, the necessary
+  # pattern would need to be a part of all test method names. and i don't
+  # really want a ton of method names like `test_project_dir_name_space_sub`
+  # so that i can turn `rash test Project.dir_name` into a pattern that
+  # runs the {NRSER::Rash::Functions::Project.dir_name} tests.
+  #
+  # the hack:
+  #
+  # this gets around it by providing macros that will dynamically define
+  # `Test::Unit::TestCase` subclasses if and only if those tests are being
+  # run.
+  #
+  # NOTE: why does this start with an '_'?
+  def self._test_function(module_or_function_name)
+    # if the *first* arg to `rash test` is `--all`, then all test will be run,
+    # which is done by supplying an empty `module_or_function_name` to
+    # `Testing.start`.
+    #
+    # TODO: I just realized that it's currently impossible to test all the
+    #       functions defined in {NRSER::Rash::Functions} without testing all
+    #       the submodules as well. ugh. solutions include requiring an
+    #       explicit (never finished I guess...)
+    #       
+    #       
+    if module_or_function_name == '--all'
+      module_or_function_name = ''
+    end
+    NRSER::Rash::Testing.start module_or_function_name
+    # going to need the functions loaded to find it
+    load_functions
+    if NRSER::Rash::Testing._test_cases.length == 0
+      raise NRSER::Rash::Testing::NoTestCasesError.new(module_or_function_name)
+    end
+    require 'minitest/autorun'
+  end
+end # module NRSER::Rash
+
+# @!endgroup Testing Class Methods
+
+
+# @todo
+#   It seems like testing doesn't work in the state I came back to it
+#   2018.02.22
+# 
+module NRSER::Rash::Testing
+  class << self
+    attr_accessor :module_or_function_name
+    attr_accessor :_test_cases
+    attr_accessor :ref_path
+  end
+
+  def self.test
+    NRSER::Rash.logger.info "self: #{self.inspect}"
+  end
+
+  def self.start(module_or_function_name)
+    
+    define_test_class
+
+    self.module_or_function_name = module_or_function_name
+    self.ref_path = NRSER::Rash.ref_path(module_or_function_name)
+    self._test_cases = []
+  end
+
+  # used to figure out if we're testing
+  def self.testing?
+    !!module_or_function_name
+  end
+
+  # raised when filtering byt the function name doens't produce any
+  # test cases
+  class NoTestCasesError < StandardError
+    def initialize(name)
+      super "no test cases were found for '#{ name }'."
+    end
+  end
+
+  class FunctionTestCase < ::Minitest::Test
+    class Raises
+      attr_reader :cls, :msg
+
+      def initialize cls, msg = nil
+        @cls = cls
+        @msg = msg
+      end
+    end
+
+    def raises cls, msg = nil
+      Raises.new cls, msg
+    end
+
+    def assert_map(hash)
+      hash.each do |input, output|
+        input = [input] unless input.is_a?(Array)
+        # allow mapping to an Exception class as an assert_raise
+        if output.is_a?(Raises)
+          if output.msg.nil?
+            assert_raise output.cls do
+              apply_target *input
+            end
+          else
+            assert_raise_with_message(output.cls, output.msg) do
+              apply_target *input
+            end
+          end
+        else
+          assert_equal output, apply_target(*input)
+        end
+      end
+    end
+
+    # this was added sometime after 1.9.3, backport:
+    def assert_raise_with_message(exception, expected, msg = nil, &block)
+      case expected
+      when String
+        assert = :assert_equal
+      when Regexp
+        assert = :assert_match
+      else
+        raise TypeError, "Expected #{expected.inspect} to be a kind of String or Regexp, not #{expected.class}"
+      end
+
+      ex = assert_raise(exception, *msg) {yield}
+      msg = message(msg, "") {"Expected Exception(#{exception}) was raised, but the message doesn't match"}
+
+      if assert == :assert_equal
+        assert_equal(expected, ex.message, msg)
+      else
+        msg = message(msg) { "Expected #{mu_pp expected} to match #{mu_pp ex.message}" }
+        assert expected =~ ex.message, msg
+        block.binding.eval("proc{|_|$~=_}").call($~)
+      end
+      ex
+    end
+  end
+
+  # create and run a `Minitest::Test` with `&block` as the body,
+  # supplying `target_method` as an instance method under it's name
+  # and also the name 'target_method'
+  def self.test_case(target_method, &block)
+    # bail out if we're not in a testing state. this prevents the code
+    # from going any further for other commands like `profile` and `call`.
+    return unless NRSER::Rash::Testing.testing?
+
+    method_name = target_method.name.to_s
+
+    # since we're testing, `Testing.pattern` will be a string the user
+    # supplied on the command line, like `Project.dir_name`. we're going
+    # to compare it to the method path we're being asked to define
+    # the test case for to see if we should acutally create the
+    # `Minitest::Test` class.
+    method_ref_path = NRSER::Rash.ref_path(target_method.receiver.name,
+                                    target_method.name.to_s)[2..-1]
+
+    # go through each segment in the ref path we're testing and bail if
+    # it doesn't match the coresponding segment in the method's ref path.
+    #
+    # this only goes up until the testing ref path runs out, which allows
+    # the user to specify something like `Url.Parse` to test all the
+    # functions under the `NRSER::Rash::Functions::Url::Parse` module.
+    Testing.ref_path.each_with_index do |segment, index|
+      return unless segment == method_ref_path[index]
+    end
+
+    # if we made it to this point, we should be testing the function and
+    # will define the `Test::Unit` subclass:
+    _test_case = Class.new NRSER::Rash::Testing::FunctionTestCase do
+
+      # allow easy access to the target method inside the test methods
+      # by defining a method with the same name that points
+      # to the target method
+      define_method method_name, &target_method
+
+      # the proxy method should be private so that functions that
+      # start with `'test'` aren't run by `Test::Unit`
+      private method_name
+
+      # also define a version named `apply_target` to provide a
+      # shortcut for programtic access in helpers like
+      # `FunctionTestCase.assert_map` and what not.
+      #
+      # NOTE: i did this instead of just using `self.class.target_method`
+      #       as defined below because i wanted the method to be exactly
+      #       the same as when calling with the previous alias. i might
+      #       remove it, not sure. it seems redundant.
+      define_method :apply_target, &target_method
+
+      # and include a direct reference the target method in a class
+      # instance variable with an attribute reader so it's accessible
+      # in case it's needed at some point (it's not at the moment).
+      # 
+      # it can be accessed from inside `FunctionTestCase` subclasses like:
+      # 
+      #    self.class.target_method
+      #
+      @target_method = target_method
+      class << self
+        attr_reader :target_method
+      end
+    end
+    
+    # i ran into some "warning: class variable access from toplevel" shit
+    # at some point, and this was a part of fixing it. though it no longer
+    # seems necessary, i'm going to leave it for a moment:
+    # _test_case.instance_eval do
+    #   @test_method = test_method
+    # end
+
+    # add the user-supplied methods
+    _test_case.class_eval &block
+
+    # programtically create a name for the class and use that to create
+    # a constant referencing it in the invoking module, which causes the
+    # class to assume that name and module as far as it's `name` method
+    # and printing and such, which is nice for the unit test output.
+    #
+    # names are created by appending the `method_name` to 'Test_', with
+    # '!' converted to '_bang' and '?' converted to '_q' (since constants
+    # can't have '!' or '?' in them).
+    #
+    # example:
+    #
+    # say you had a module like
+    #     
+    #     module NRSER::Rash::Functions::SomeNamespace
+    #       extend NRSER::Rash::Testing::Extensions
+    #       
+    #       def self.some_function
+    #         "hooray!"
+    #       end
+    #       
+    #       _test_case :some_function do
+    #         def test_some_function
+    #           assert_equal some_function, "horray!"
+    #         end
+    #       end
+    #     end
+    # 
+    # then you would get a `Minitest::Test` subclass named
+    # 
+    #     NRSER::Rash::Functions::SomeNamespace::Test_some_function
+    #
+    # which seems reasonable enough.
+    class_name =  "Test_" +
+                  method_name.to_s.gsub('!', '_bang').gsub('?', '_q')
+    const_set class_name, _test_case
+
+    # and finally, add the class to the `_test_cases` array, which allows
+    # us to see what classes were defined after the modules are loaded.
+    NRSER::Rash::Testing._test_cases << _test_case
+  end
+
+  # create a `Minitest::Test` subclass with a single test method
+  # for `target_method` with `&block` as the body.
+  def self.test_function(target_method, &block)
+    test_case target_method do
+      define_method "test_#{ target_method.name }", &block
+    end
+  end
+
+  def self.temp_env hash, &block
+    old = Hash[hash.keys.map {|key| ENV[key] }]
+    begin
+      hash.each do |key, value|
+        ENV[key] = value
+      end
+      block.()
+    ensure
+      old.each do |key, value|
+        ENV[key] = value
+      end
+    end
+  end
+  
+end # NRSER::Rash::Testing