mixins 0.1.0.pre.20250527171116

data/spec/mixins/data_utilities_spec.rb

@@ -0,0 +1,266 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'mixins'
+
+
+RSpec.describe( Mixins::DataUtilities ) do
+
+	it "doesn't try to dup immediate objects" do
+		expect( Mixins::DataUtilities.deep_copy( nil ) ).to be( nil )
+		expect( Mixins::DataUtilities.deep_copy( 112 ) ).to be( 112 )
+		expect( Mixins::DataUtilities.deep_copy( true ) ).to be( true )
+		expect( Mixins::DataUtilities.deep_copy( false ) ).to be( false )
+		expect( Mixins::DataUtilities.deep_copy( :a_symbol ) ).to be( :a_symbol )
+	end
+
+
+	it "doesn't try to dup modules/classes" do
+		klass = Class.new
+		expect( Mixins::DataUtilities.deep_copy( klass ) ).to be( klass )
+	end
+
+
+	it "doesn't try to dup IOs" do
+		data = [ $stdin ]
+		expect( Mixins::DataUtilities.deep_copy( data[0] ) ).to be( $stdin )
+	end
+
+
+	it "doesn't try to dup Tempfiles" do
+		data = Tempfile.new( 'ravn_deepcopy.XXXXX' )
+		expect( Mixins::DataUtilities.deep_copy( data ) ).to be( data )
+	end
+
+
+	it "makes distinct copies of arrays and their members" do
+		original = [ 'foom', Set.new([ 1,2 ]), :a_symbol ]
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy ).to eq( original )
+		expect( copy ).to_not be( original )
+		expect( copy[0] ).to eq( original[0] )
+		expect( copy[0] ).to_not be( original[0] )
+		expect( copy[1] ).to eq( original[1] )
+		expect( copy[1] ).to_not be( original[1] )
+		expect( copy[2] ).to eq( original[2] )
+		expect( copy[2] ).to be( original[2] ) # Immediate
+	end
+
+
+	it "makes recursive copies of deeply-nested Arrays" do
+		original = [ 1, [ 2, 3, [4], 5], 6, [7, [8, 9], 0] ]
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy ).to eq( original )
+		expect( copy ).to_not be( original )
+		expect( copy[1] ).to_not be( original[1] )
+		expect( copy[1][2] ).to_not be( original[1][2] )
+		expect( copy[3] ).to_not be( original[3] )
+		expect( copy[3][1] ).to_not be( original[3][1] )
+	end
+
+
+	it "makes distinct copies of Hashes and their members" do
+		original = {
+			:a => 1,
+			'b' => 2,
+			3 => 'c',
+		}
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy ).to eq( original )
+		expect( copy ).to_not be( original )
+		expect( copy[:a] ).to eq( 1 )
+		expect( copy.key( 2 ) ).to eq( 'b' )
+		expect( copy.key( 2 ) ).to_not be( original.key(2) )
+		expect( copy[3] ).to eq( 'c' )
+		expect( copy[3] ).to_not be( original[3] )
+	end
+
+
+	it "makes distinct copies of deeply-nested Hashes" do
+		original = {
+			:a => {
+				:b => {
+					:c => 'd',
+					:e => 'f',
+				},
+				:g => 'h',
+			},
+			:i => 'j',
+		}
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy ).to eq( original )
+		expect( copy[:a][:b][:c] ).to eq( 'd' )
+		expect( copy[:a][:b][:c] ).to_not be( original[:a][:b][:c] )
+		expect( copy[:a][:b][:e] ).to eq( 'f' )
+		expect( copy[:a][:b][:e] ).to_not be( original[:a][:b][:e] )
+		expect( copy[:a][:g] ).to eq( 'h' )
+		expect( copy[:a][:g] ).to_not be( original[:a][:g] )
+		expect( copy[:i] ).to eq( 'j' )
+		expect( copy[:i] ).to_not be( original[:i] )
+	end
+
+
+	it "copies the default proc of copied Hashes" do
+		original = Hash.new {|h,k| h[ k ] = Set.new }
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy.default_proc ).to eq( original.default_proc )
+	end
+
+
+	it "preserves frozen-ness of copied objects" do
+		original = Object.new
+		original.freeze
+
+		copy = Mixins::DataUtilities.deep_copy( original )
+
+		expect( copy ).to_not be( original )
+		expect( copy ).to be_frozen()
+	end
+
+
+	it "can recursively transform Hash keys into Symbols" do
+		original = {
+			'id' => 'a8fd4d6f-5c0f-45b2-8732-8b8a90b595de',
+			'time' => Time.now.to_f,
+			'type' => 'sparrow.order.turning',
+			'data' => {
+				'response_type' => 'receipt',
+				'response' => 1
+			}
+		}
+
+		result = Mixins::DataUtilities.symbolify_keys( original )
+
+		expect( result.keys ).to all( be_a Symbol )
+		expect( result[:data].keys ).to all( be_a Symbol )
+	end
+
+
+	it "doesn't try to turn keys other than Strings into Symbols" do
+		original = {
+			'foo' => {
+				'bar' => 3,
+				3 => 'bar',
+			}
+		}
+
+		result = Mixins::DataUtilities.symbolify_keys( original )
+
+		expect( result[:foo].keys ).to contain_exactly( :bar, 3 )
+	end
+
+
+	it "doesn't try to turn String keys that aren't identifiers into Symbols" do
+		original = {
+			'foo' => {
+				'an arbitrary string' => 3,
+				'$punctuation_string' => 8,
+				'_underscore_string'  => 4,
+			}
+		}
+
+		result = Mixins::DataUtilities.symbolify_keys( original )
+
+		expect( result[:foo].keys ).
+			to contain_exactly( 'an arbitrary string', '$punctuation_string', :_underscore_string )
+	end
+
+
+	it "recurses into Arrays when transforming Hash keys into Symbols" do
+		original = {
+			'type' => 'Vic Checkin',
+			'text' => 'Vehicles check in',
+			'ontological_suffix' => 'conversation.headcount',
+			'components' => {
+				'recipients' => {
+					'to' => 'Vic Commanders',
+				},
+				'responses' => {
+					'responses_from' => 'Vic Commanders',
+					'send_label' => 'Send UP',
+					'steps' => [
+						{ 'type' => 'integer', 'label' => 'PAX' },
+						{ 'type' => 'select', 'label' => 'Ready', 'values' => ['yes', 'no'] },
+					],
+				}
+			}
+		}
+
+		result = Mixins::DataUtilities.symbolify_keys( original )
+
+		expect( result.keys ).to all( be_a Symbol )
+		expect( result.dig(:components, :responses, :steps) ).to all( include(:type, :label) )
+	end
+
+
+	it "can recursively transform Hash keys into Strings" do
+		original = {
+			:id => '4cc37025-fb34-47ef-b762-6abac23e0792',
+			:time => Time.now.to_f,
+			:type => 'acme.widget.model1',
+			1 => 'something',
+			:data => {
+				:response_type => 'receipt',
+				:response_id => 1
+			}
+		}
+
+		result = Mixins::DataUtilities.stringify_keys( original )
+
+		expect( result.keys ).to contain_exactly( 'id', 'time', 'type', 1, 'data' )
+		expect( result['data'].keys ).to contain_exactly( 'response_type', 'response_id' )
+	end
+
+
+	it "doesn't stringify non-Symbols when stringifying Hash keys" do
+		original = {
+			:foo => "bar",
+			18 => "something",
+		}
+
+		result = Mixins::DataUtilities.stringify_keys( original )
+
+		expect( result.keys ).to contain_exactly( 'foo', 18 )
+	end
+
+
+	it "recurses into Arrays when transforming Hash keys into Strings" do
+		original = {
+			type: 'Teddy Bear',
+			text: "What's your name?",
+			sort: 'toy.plush.animal',
+			components: {
+				route: {
+					to: 'receiving@acme.com',
+				},
+				responses: {
+					responses_from: 'warehouse1@acme.com',
+					send_label: 'BZ5556',
+					steps: [
+						{ type: 'integer', label: 'QC' },
+						{ type: 'select', label: 'conv1', values: ['yes', 'no'] },
+					],
+				}
+			}
+		}
+
+		result = Mixins::DataUtilities.stringify_keys( original )
+
+		expect( result.keys ).to all( be_a String )
+		expect( result.dig('components', 'responses', 'steps') ).to all( include('type', 'label') )
+	end
+
+end
+
+

data/spec/mixins/datadir_spec.rb

@@ -0,0 +1,86 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'mixins'
+
+
+RSpec.describe( Mixins::Datadir ) do
+
+	let( :zebra_gemspec ) do
+		Gem::Specification.new do |s|
+			s.name = "zebra"
+			s.version = Gem::Version.new("0.2.1")
+			s.installed_by_version = Gem::Version.new("0")
+			s.authors = ["Zaphod Beeblebrox"]
+			s.date = Time.utc(2024, 6, 12)
+			s.description = "So many zebras."
+			s.email = ["zaph@example.com"]
+			s.files = ["zebras.rb"]
+			s.homepage = "https://github.com/zaph/zebras"
+			s.licenses = ["Ruby", "BSD-2-Clause"]
+			s.metadata = {
+				"homepage_uri"=>"https://github.com/zaph/zebras",
+				"source_code_uri"=>"https://github.com/zaph/zebras"
+			}
+			s.require_paths = ["lib"]
+			s.required_ruby_version = Gem::Requirement.new([">= 2.5.0"])
+			s.rubygems_version = "3.5.11"
+			s.specification_version = 4
+			s.summary = "All the zebras."
+		end
+	end
+	let( :zebra_datadir ) { '/path/to/installed/gem/datadir' }
+	let( :loaded_gemspecs ) { { 'zebra' => zebra_gemspec } }
+
+
+	before( :each ) do
+		@original_env = ENV.to_h
+	end
+	after( :each ) do
+		ENV.replace( @original_env )
+	end
+
+
+	it "uses the currently-loaded gem's data directory if there is one" do
+		expect( Gem ).to receive( :loaded_specs ).
+			and_return( loaded_gemspecs ).at_least( :once )
+		expect( zebra_gemspec ).to receive( :datadir ).
+			and_return( zebra_datadir ).at_least( :once )
+		expect( File ).to receive( :exist? ).with( zebra_datadir ).and_return( true )
+
+		target_class = Class.new do
+			def self::name; 'Zebra'; end
+		end
+		target_class.extend( described_class )
+
+		expect( target_class.data_dir ).to eq( Pathname(zebra_datadir) )
+	end
+
+
+	it "uses the directory at ../../data/<gemname> if no gem is loaded" do
+		target_class = Class.new do
+			def self::name; 'Panda'; end
+		end
+		target_class.extend( described_class )
+
+		local_datadir = Pathname( __FILE__ ).parent.parent.parent / 'data' / 'panda'
+
+		expect( target_class.data_dir ).to eq( local_datadir )
+	end
+
+
+	it "allows the data dir to be overridden using an environment variable" do
+		ocelot_data = '/path/to/ocelot/data'
+		ENV['OCELOT_DATADIR'] = ocelot_data
+
+		target_class = Class.new do
+			def self::name; 'Ocelot'; end
+		end
+		target_class.extend( described_class )
+
+		expect( target_class.data_dir ).to eq( Pathname(ocelot_data) )
+	end
+
+end
+

data/spec/mixins/delegation_spec.rb

@@ -0,0 +1,186 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'mixins'
+
+
+RSpec.describe( Mixins::Delegation ) do
+
+	let( :testclass ) do
+		Class.new do
+			extend Mixins::Delegation
+
+			@data_dir = nil
+			class << self
+				attr_accessor :data_dir
+			end
+
+			def initialize( obj=nil )
+				@obj = obj
+			end
+
+			def demand_loaded_object
+				return @load_on_demand ||= @obj
+			end
+		end
+	end
+
+	let( :subobj ) { double( "delegate" ) }
+	let( :obj ) { testclass.new(subobj) }
+
+
+	describe "method delegation" do
+
+		it "can be used to set up delegation through a method" do
+			testclass.def_method_delegators( :demand_loaded_object, :delegated_method )
+
+			expect( subobj ).to receive( :delegated_method )
+
+			obj.delegated_method
+		end
+
+
+		it "passes any arguments through to the delegate object's method" do
+			testclass.def_method_delegators( :demand_loaded_object, :delegated_method )
+
+			expect( subobj ).to receive( :delegated_method ).with( :arg1, :arg2 )
+
+			obj.delegated_method( :arg1, :arg2 )
+		end
+
+
+		it "allows delegation to the delegate object's method with a block" do
+			testclass.def_method_delegators :demand_loaded_object, :delegated_method
+
+			expect( subobj ).to receive( :delegated_method ).with( :arg1 ).
+				and_yield( :the_block_argument )
+
+			blockarg = nil
+			obj.delegated_method( :arg1 ) {|arg| blockarg = arg }
+
+			expect( blockarg ).to eq( :the_block_argument )
+		end
+
+
+		it "reports errors from its caller's perspective", :ruby_1_8_only => true do
+			testclass.def_method_delegators( :nonexistant_method, :erroring_delegated_method )
+
+			begin
+				obj.erroring_delegated_method
+			rescue NoMethodError => err
+				expect( err.message ).to match( /nonexistant_method/ )
+				expect( err.backtrace.first ).to match( /#{__FILE__}/ )
+			rescue ::Exception => err
+				fail "Expected a NoMethodError, but got a %p (%s)" % [ err.class, err.message ]
+			else
+				fail "Expected a NoMethodError, but no exception was raised."
+			end
+		end
+
+
+		it "delegates setters correctly" do
+			testclass.def_method_delegators :demand_loaded_object, :delegated_setter=
+
+			expect( subobj ).to receive( :delegated_setter= ).with( 1 )
+
+			obj.delegated_setter = 1
+
+			expect( subobj ).to receive( :delegated_setter= ).with( [1, 2] )
+
+			obj.delegated_setter = 1, 2
+		end
+
+	end
+
+
+	describe "instance variable delegation (ala Forwardable)" do
+
+		let( :testclass ) do
+			Class.new do
+				extend Mixins::Delegation
+
+				def initialize( obj )
+					@obj = obj
+				end
+			end
+		end
+
+
+		it "can be used to set up delegation through a method" do
+			testclass.def_ivar_delegators( :@obj, :delegated_method )
+
+			expect( subobj ).to receive( :delegated_method )
+
+			obj.delegated_method
+		end
+
+
+		it "passes any arguments through to the delegate's method" do
+			testclass.def_ivar_delegators( :@obj, :delegated_method )
+
+			expect( subobj ).to receive( :delegated_method ).with( :arg1, :arg2 )
+
+			obj.delegated_method( :arg1, :arg2 )
+		end
+
+
+		it "allows delegation to the delegate's method with a block" do
+			testclass.def_ivar_delegators( :@obj, :delegated_method )
+
+			expect( subobj ).to receive( :delegated_method ).with( :arg1 ).
+				and_yield( :the_block_argument )
+
+			blockarg = nil
+			obj.delegated_method( :arg1 ) {|arg| blockarg = arg }
+
+			expect( blockarg ).to eq( :the_block_argument )
+		end
+
+
+		it "reports errors from its caller's perspective", :ruby_1_8_only => true do
+			testclass.def_ivar_delegators( :@glong, :erroring_delegated_method )
+
+			begin
+				obj.erroring_delegated_method
+			rescue NoMethodError => err
+				expect( err.message ).to match( /['`]erroring_delegated_method' for nil/ )
+				expect( err.backtrace.first ).to match( /#{__FILE__}/ )
+			rescue ::Exception => err
+				fail "Expected a NoMethodError, but got a %p (%s)" % [ err.class, err.message ]
+			else
+				fail "Expected a NoMethodError, but no exception was raised."
+			end
+		end
+
+
+		it "delegates setters correctly" do
+			testclass.def_ivar_delegators( :@obj, :delegated_setter= )
+
+			expect( subobj ).to receive( :delegated_setter= ).with( 1 )
+
+			obj.delegated_setter = 1
+
+			expect( subobj ).to receive( :delegated_setter= ).with( [1, 2] )
+
+			obj.delegated_setter = 1, 2
+		end
+
+	end
+
+
+	describe "class-method delegation" do
+
+		it "can be used to set up delegation through a method" do
+			testclass.def_class_delegators :data_dir
+
+			testclass.data_dir = '/path/to/the/data'
+			obj = testclass.new
+
+			expect( obj.data_dir ).to eq( '/path/to/the/data' )
+		end
+
+	end
+
+end
+

data/spec/mixins/hooks_spec.rb

@@ -0,0 +1,86 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'mixins'
+
+
+RSpec.describe( Mixins::Hooks ) do
+
+	let( :extended_object ) do
+		obj = Object.new
+		obj.extend( described_class )
+		return obj
+	end
+
+
+	it "allows a set of hooks to be declared" do
+		extended_object.define_hook( :after_fork )
+
+		hook1_called = false
+		hook2_called = false
+
+		extended_object.after_fork do
+			hook1_called = true
+		end
+		extended_object.after_fork do
+			hook2_called = true
+		end
+
+		expect {
+			extended_object.call_after_fork_hook
+		}.to change { hook1_called }.to( true ).and \
+			change { hook2_called }.to( true ).and \
+			change { extended_object.after_fork_callbacks_run? }.to( true )
+	end
+
+
+	it "ensures declared hooks are run at least once" do
+		extended_object.define_hook( :after_fork )
+
+		hook1_called = false
+		hook2_called = false
+
+		extended_object.after_fork do
+			hook1_called = true
+		end
+		extended_object.call_after_fork_hook
+		extended_object.after_fork do
+			hook2_called = true
+		end
+
+		expect( hook1_called ).to be_truthy
+		expect( hook2_called ).to be_truthy
+	end
+
+
+	it "doesn't re-register a hook callback that already exists" do
+		extended_object.define_hook( :before_fork )
+
+		callback = Proc.new {}
+		extended_object.before_fork( &callback )
+		extended_object.before_fork( &callback )
+
+		expect( extended_object.before_fork_callbacks.length ).to eq( 1 )
+	end
+
+
+	it "can declare a hook that passes arguments to its callbacks" do
+		extended_object.define_hook( :on_event )
+
+		callback_args = []
+		extended_object.on_event do |ev, *args|
+			callback_args << [ev, args]
+		end
+
+		extended_object.call_on_event_hook( :slip, 4 )
+		extended_object.call_on_event_hook( :traverse, 16 )
+
+		expect( callback_args ).to contain_exactly(
+			[:slip, [4]],
+			[:traverse, [16]]
+		)
+	end
+
+end
+

data/spec/mixins/inspection_spec.rb

@@ -0,0 +1,41 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'mixins'
+
+
+RSpec.describe( Mixins::Inspection ) do
+
+	it "handles empty details" do
+		oclass = Class.new do
+			def initialize( serial )
+				@serial = serial
+			end
+		end
+		oclass.include( described_class )
+		instance = oclass.new( 11 )
+
+		expect( instance.inspect ).to match( /#<#{oclass.inspect}:#\h+/ )
+	end
+
+
+	it "allows the inspection contents to be overridden" do
+		oclass = Class.new do
+			def initialize( serial )
+				@serial = serial
+			end
+			attr_reader :serial
+			def inspect_details
+				return "serial: %d" % [ self.serial ]
+			end
+		end
+		oclass.include( described_class )
+
+		instance = oclass.new( 13 )
+
+		expect( instance.inspect ).to match( /#<\S+ serial: 13>/ )
+	end
+
+end
+