golly-utils 0.0.1 → 0.6.0

data/lib/golly-utils/ruby_ext/enumerable.rb

@@ -0,0 +1,16 @@
+module Enumerable
+
+  # Creates a map of all elements by the frequency that they occur.
+  #
+  # @example
+  #   %w[big house big car].frequency_map  # => {"big"=>2, "car"=>1, "house"=>1}
+  #
+  # @return [Hash<Object,Fixnum>] Map of element to frequency.
+  def frequency_map
+    inject Hash.new do |h,e|
+      h[e]= (h[e] || 0) + 1
+      h
+    end
+  end
+
+end

data/lib/golly-utils/ruby_ext/env_helpers.rb

@@ -1,6 +1,19 @@
 module GollyUtils
+  # Mixin that enriches Ruby's `ENV`.
+  #
+  # @note This is mixed-in to `ENV` automatically.
   module EnvHelpers
 
+    # Parses an environment variable that is expected to be a boolean.
+    #
+    # Regardless of case,
+    #
+    # * the following values are interpretted as positive: `1, y, yes, t, true, on, enabled`
+    # * the following values are interpretted as negative: `0, n, no, f, false, off, disabled`
+    #
+    # @param [String] key The `ENV` key. The environment variable name.
+    # @param [Boolean, nil] default The value to return if there is no environment variable of given key.
+    # @return [Boolean,nil] The result of parsing the env var value, else `default`.
     def boolean(key, default=nil)
       return default unless self.has_key?(key)
       v= self[key]
@@ -14,6 +27,10 @@ module GollyUtils
     alias on? boolean
     alias enabled? boolean
 
+    # Parses an environment variable and checks if it indicates a negative boolean value.
+    #
+    # @param (see #boolean)
+    # @return [Boolean,nil] The result of parsing the env var value and it indicating the negative, else `default`.
     def no?(key, default=nil)
       !boolean(key, default)
     end

data/lib/golly-utils/ruby_ext/kernel.rb

@@ -0,0 +1,18 @@
+module Kernel
+
+  # Alternate implementation of `at_exit` that preserves the exit status (unless you call `exit` yourself and an error
+  # is raised).
+  #
+  # The initial driver for this was that using `at_exit` to clean up global resources in RSpec tests, RSpec's exit
+  # status would be lost which means CI processes and such were unable to tell whether there were test failures.
+  #
+  # @return [Proc] Whatever `at_exit` returns.
+  def at_exit_preserving_exit_status(&block)
+    at_exit {
+      status= $!.is_a?(::SystemExit) ? $!.status : nil
+      block.()
+      exit status if status
+    }
+  end
+end
+

data/lib/golly-utils/ruby_ext/options.rb

@@ -0,0 +1,28 @@
+class Hash
+
+  # Checks that all keys in this hash are part of a specific set; fails if not.
+  #
+  # @param [Array] valid_keys A set of valid keys.
+  # @param [String] error_msg A message to include in the error when raised.
+  # @return [self]
+  # @raise Invalid keys are present.
+  def validate_keys(valid_keys, error_msg = "Invalid hash keys")
+    invalid= self.keys - [valid_keys].flatten
+    unless invalid.empty?
+      raise "#{error_msg}: #{invalid.sort_by(&:to_s).map(&:inspect).join ', '}"
+    end
+    self
+  end
+
+  # Checks that all keys in this hash are part of a specific set; fails if not.
+  #
+  # Differs from {#validate_keys} by providing an option-related error message.
+  #
+  # @param valid_keys A set of valid keys.
+  # @return [self]
+  # @raise Invalid keys are present.
+  def validate_option_keys(*valid_keys)
+    validate_keys valid_keys, "Invalid options provided"
+  end
+
+end

data/lib/golly-utils/ruby_ext/pretty_error_messages.rb

@@ -2,7 +2,7 @@ class StandardError
 
   # Creates a string that provides more information (a backtrace) than the default `to_s` method.
   #
-  # @return String
+  # @return [String]
   def to_pretty_s
     "#{self.inspect}\n#{self.backtrace.map{|b| "  #{b}"}.join "\n"}"
   end

data/lib/golly-utils/singleton.rb

@@ -0,0 +1,130 @@
+require 'singleton'
+
+module GollyUtils
+  # Makes the including class a singleton.
+  # Much like Ruby's `Singleton` module, with extra features.
+  #
+  # Features:
+  #
+  # * Target class includes Ruby's `Singleton` module too.
+  # * Class methods are added to the target class that delegate to the singleton instance.
+  # * A convenience method {ClassMethods#def_accessor def_accessor} is provided to create an accessor in the calling
+  #   class, as per `attr_accessor`, except that the value defaults to the singleton instance.
+  #
+  # @example
+  #   class Stam1na
+  #     include GollyUtils::Singleton
+  #
+  #     def band_rating
+  #       puts 'AWESOME!!'
+  #     end
+  #   end
+  #
+  #   Stam1na.instance.band_rating  #=> AWESOME!!
+  #   Stam1na.band_rating           #=> AWESOME!!
+  module Singleton
+
+    # @!visibility private
+    def self.included(base)
+      base.send :include, ::Singleton
+      base.extend ClassMethods
+      base.class_eval <<-EOB
+        class << self
+
+          alias :method_missing_before_gu_singleton :method_missing
+
+          def method_missing(method, *args, &block)
+            if method != :__gu_singleton_method_missing
+
+              r= __gu_singleton_method_missing(self, method, *args, &block)
+              unless ::GollyUtils::Singleton::NO_MATCH == r
+                return r
+              end
+
+            end
+            method_missing_before_gu_singleton method, *args, &block
+          end
+
+          def __default_singleton_attr_name
+            '#{base.to_s.sub(/^.*::/,'').gsub(/(?<=[a-z])(?=[A-Z])/,'_').downcase}'
+          end
+
+        end
+      EOB
+    end
+
+    module ClassMethods
+
+      # Creates an instance accessor as `attr_accessor` does, execpt that the default value will be the singleton
+      # instance.
+      #
+      # @example
+      #   class HappyDays
+      #     include GollyUtils::Singleton
+      #   end
+      #
+      #   class A
+      #     # @!attribute [rw] happy_days
+      #     #   @return [HappyDays]
+      #     HappyDays.def_accessor self
+      #   end
+      #
+      #   A.new.happy_days == HappyDays.instance  #=> true
+      #
+      # @param [Class|Module] target The object definition to add the attribute methods to.
+      # @param [String|Symbol] name The attribute name. Defaults to the singleton class name, with underscores and in
+      #   lowercase.
+      # @return [nil]
+      def def_accessor(target, name=nil)
+        name ||= __default_singleton_attr_name
+        target.class_eval <<-EOB
+          def #{name}
+             @#{name} ||= ::#{self}.instance
+          end
+          def #{name}=(v)
+             @#{name}= v
+          end
+        EOB
+        nil
+      end
+
+      # Prevents class-level delegate methods from being created for certain instance methods.
+      #
+      # @param [Array<Regexp|String>] matchers Either the name of the method, or a regex that matches methods.
+      # @return [nil]
+      def hide_singleton_methods(*matchers)
+        r=  __gu_singleton_rejects
+        r.concat matchers
+        r.flatten!
+        r.uniq!
+        nil
+      end
+
+      private
+
+      def __gu_singleton_rejects
+        @__gu_singleton_rejects ||= []
+      end
+
+      # Called on `method_missing`. Rather than simply delegating the method call, it will instead see if there are any
+      # delegate methods that haven't been created yet and if so, creates them. This results in improved performance and
+      # less hits to `method_missing`.
+      def __gu_singleton_method_missing(singleton_class ,method, *args, &block)
+        methods= (singleton_class.instance.public_methods - singleton_class.methods)
+        if rej= __gu_singleton_rejects
+          methods.reject!{|m| m= m.to_s; rej.any?{|r| r === m }}
+        end
+        unless methods.empty?
+          code= methods.map {|m| "def self.#{m}(*a,&b); self.instance.send :#{m},*a,&b; end" }
+          singleton_class.class_eval(code.join "\n")
+          return singleton_class.send(method,*args,&block) if methods.include?(method)
+        end
+        ::GollyUtils::Singleton::NO_MATCH
+      end
+
+    end
+
+    # @!visibility private
+    NO_MATCH= Object.new
+  end
+end

data/lib/golly-utils/testing/dynamic_fixtures.rb

@@ -0,0 +1,268 @@
+require 'golly-utils/ruby_ext/kernel'
+require 'golly-utils/ruby_ext/options'
+require 'fileutils'
+require 'monitor'
+require 'thread'
+require 'tmpdir'
+
+module GollyUtils
+  module Testing
+
+    # Provides globally-shared, cached, lazily-loaded fixtures that are generated once on-demand, and copied when access
+    # is required.
+    #
+    # @example
+    #     describe 'My Git Utility' do
+    #       include GollyUtils::Testing::DynamicFixtures
+    #
+    #       def_fixture :git do                             # Dynamic fixture definition.
+    #         system 'git init'                             # Expensive to create.
+    #         File.write 'test.txt', 'hello'                # Only runs once.
+    #         system 'git add -A && git commit -m x'
+    #       end
+    #
+    #       run_each_in_dynamic_fixture :git                # RSpec helper for fixture usage.
+    #
+    #       it("detects deleted files") {                   # Runs in a copy of the fixture.
+    #         File.delete 'test.txt'                        # Free to modify its fixture copy.
+    #         subject.deleted_files.should == %w[test.txt]  # Other tests isolated from these these changes.
+    #       }
+    #
+    #       it("detects new files") {                       # Runs in a clean copy of the fixture.
+    #         File.create 'new.txt'                         # Generated quickly by copying cache.
+    #         subject.new_files.should == %w[new.txt]       # Unaffected by other tests' fixture modification.
+    #       }
+    #
+    #     end
+    module DynamicFixtures
+
+      # @!visibility private
+      def self.included(base)
+        base.extend ClassMethods
+      end
+      module ClassMethods
+
+        # Defines a dynamic fixture.
+        #
+        # @param [Symbol|String] name The dynamic fixture name.
+        # @param [Hash] options
+        # @option options [nil|String] :cd_into (nil) A fixture subdirectory to change directory into by default when
+        #   using the fixture.
+        # @option options [nil|String] :dir_name (nil) A specific name to call the temporary directory used when first
+        #   creating the fixture. If `nil` then the name will non-deterministic.
+        # @param [Proc] block Code that when run in an empty, temporary directory, will create the fixture contents.
+        # @yield Yields control in an empty directory at a later point in time.
+        # @return [void]
+        def def_fixture(name, options={}, &block)
+          raise "Block not provided." unless block
+          options.validate_option_keys :cd_into, :dir_name
+
+          name= DynamicFixtures.normalise_dynfix_name(name)
+          STDERR.warn "Dyanmic fixture being redefined: #{name}." if $gu_dynamic_fixtures[name]
+          $gu_dynamic_fixtures[name]= options.merge(block: block)
+
+          nil
+        end
+
+        # RSpec helper that directs that each example be run in it's own clean copy of a given dynamic fixture.
+        #
+        # @param [Symbol|String] name The dynamic fixture name.
+        # @param [Hash] options Options to pass to {DynamicFixtures#inside_dynamic_fixture}. See that method for option
+        #   details.
+        # @return [void]
+        # @see DynamicFixtures#inside_dynamic_fixture
+        def run_each_in_dynamic_fixture(name, options={})
+          raise "Block not supported." if block_given?
+          options.validate_option_keys DynamicFixtures::INSIDE_DYNAMIC_FIXTURE_OPTIONS
+
+          class_eval <<-EOB
+            around :each do |ex|
+              inside_dynamic_fixture(#{name.inspect}, #{options.inspect}){ ex.run }
+            end
+          EOB
+
+          nil
+        end
+
+        # RSpec helper that directs that all examples be run in the same (initially-clean) copy of a given dynamic
+        # fixture.
+        #
+        # @param [Symbol|String] name The dynamic fixture name.
+        # @param [Hash] options
+        # @option options [nil|String] :dir_name (nil) A specific name to call the empty directory basename.
+        # @option options [nil|String] :cd_into (nil) A fixture subdirectory to change directory into when running
+        #   examples.
+        # @yield Invokes the given block (if one given) once before any examples run, inside the empty dir, to perform
+        #   any additional initialisation required.
+        # @return [void]
+        # @see GollyUtils::Testing::Helpers::ClassMethods#run_all_in_empty_dir
+        def run_all_in_dynamic_fixture(name, options={}, &block)
+          options.validate_option_keys :cd_into, :dir_name
+
+          require 'golly-utils/testing/rspec/files'
+          name= DynamicFixtures.normalise_dynfix_name(name) # actually just wanted dup
+          run_all_in_empty_dir(options[:dir_name]) {
+            copy_dynamic_fixture name
+            block.() if block
+          }
+
+          if cd_into= options[:cd_into]
+            class_eval <<-EOB
+              around(:each){|ex|
+                Dir.chdir(#{cd_into.inspect}){ ex.run }
+              }
+            EOB
+          end
+        end
+
+      end
+
+      #------------------------------------------------------------------------------------------------------------------
+
+      # Callback invoked just before creating a dynamic fixture for the first time.
+      #
+      # Override to customise.
+      #
+      # @param [Symbol] name The name of the dynamic fixture being created.
+      # @return [void]
+      def before_dynamic_fixture_creation(name)
+      end
+
+      # Callback invoked just after creating a dynamic fixture for the first time.
+      #
+      # Override to customise.
+      #
+      # @param [Symbol] name The name of the dynamic fixture being created.
+      # @param [Float] creation_time_in_sec The number of seconds taken to create the fixture.
+      # @return [void]
+      def after_dynamic_fixture_creation(name, creation_time_in_sec)
+      end
+
+      # Copies the contents of a dynamic fixture to a given directory.
+      #
+      # @param [Symbol|String] name The name of the dynamic fixture to copy.
+      # @param [String] target_dir The (existing) directory to copy the fixture to.
+      # @return [void]
+      def copy_dynamic_fixture(name, target_dir = '.')
+        FileUtils.cp_r "#{dynamic_fixture_dir name}/.", target_dir
+      end
+
+      # Creates a clean copy of a predefined dynamic fixture, changes directory into it and yields. The fixture copy
+      # is removed from the file system after the yield block returns.
+      #
+      # @param [Symbol|String] name The name of the dynamic fixture.
+      # @param [Hash] options
+      # @option options [nil|String] :cd_into (nil) A fixture subdirectory to change directory into before yielding.
+      # @yield Yields control in the directory of a fixture copy.
+      # @return The value of the given block.
+      def inside_dynamic_fixture(name, options={}, &block)
+        options.validate_option_keys INSIDE_DYNAMIC_FIXTURE_OPTIONS
+
+        Dir.mktmpdir {|dir|
+          copy_dynamic_fixture name, dir
+          df= get_dynamic_fixture_data(name)
+
+          if cd_into= options[:cd_into] || df[:cd_into]
+            dir= File.join dir, cd_into
+          end
+
+          $gu_dynamic_fixture_chdir_lock.synchronize {
+            return Dir.chdir dir, &block
+          }
+        }
+      end
+
+      # @!visibility private
+      INSIDE_DYNAMIC_FIXTURE_OPTIONS= [:cd_into].freeze
+
+      private
+
+      def get_dynamic_fixture_data(name)
+        name= DynamicFixtures.normalise_dynfix_name(name)
+        $gu_dynamic_fixtures[name]
+      end
+
+      # Creates and provides the global, temporary directory that will serve as the base directory for generating and
+      # storing all dynamic fixtures.
+      #
+      # Once created it will be automatically removed on process exit.
+      #
+      # @return [String] A directory.
+      def dynamic_fixture_root
+        $gu_dynamic_fixture_root || DYNAMIC_FIXTURE_ROOT_LOCK.synchronize {
+          $gu_dynamic_fixture_root ||= (
+            at_exit_preserving_exit_status {
+              FileUtils.remove_entry_secure $gu_dynamic_fixture_root if $gu_dynamic_fixture_root
+              $gu_dynamic_fixtures= $gu_dynamic_fixture_root= nil
+            }
+            Dir.mktmpdir
+          )
+        }
+      end
+
+      DYNAMIC_FIXTURE_ROOT_LOCK= Mutex.new
+
+      # Provides the directory name of a generated dynamic fixture. If the fixture hasn't been generated yet, then this
+      # will generate it first.
+      #
+      # @param [Symbol|String] name The dynamic fixture name.
+      # @return [String] A directory.
+      def dynamic_fixture_dir(name)
+        df= get_dynamic_fixture_data(name)
+        raise "Undefined dynamic fixture: #{name}" unless df
+
+        if df[:block]
+          $gu_dynamic_fixture_chdir_lock.synchronize {
+          # df[:lock].synchronize {
+            if df[:block]
+
+              # Start creating dynamic fixture
+              before_dynamic_fixture_creation name
+              dir= "#{dynamic_fixture_root}/#{name}"
+              Dir.mkdir dir
+
+              if subdir= df[:dir_name]
+                dir+= "/#{subdir}"
+                Dir.mkdir dir
+              end
+
+              start_time_stack= (Thread.current[:gu_dynamic_fixture_start_times] ||= [])
+              start_time_stack<< Time.now
+              begin
+                # Create fixture
+                Dir.chdir(dir){ instance_eval &df[:block] }
+                df.delete :block
+                df[:dir]= dir
+
+                dur= Time.now - start_time_stack.last
+                start_time_stack.map!{|t| t + dur}
+                after_dynamic_fixture_creation name, dur
+              ensure
+                start_time_stack.pop
+              end
+
+            end
+          }
+        end
+
+        df[:dir].dup
+      end
+
+      #-----------------------------------------------------------------------------------------------------------------
+
+      extend ClassMethods
+
+      # @!visibility private
+      def self.normalise_dynfix_name(name)
+        name.to_sym
+      end
+
+      unless $gu_dynamic_fixtures
+        $gu_dynamic_fixtures= {}
+        $gu_dynamic_fixture_root= nil
+        $gu_dynamic_fixture_chdir_lock= Monitor.new
+      end
+
+    end
+  end
+end