mixins 0.1.0.pre.20250527171116

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 931a539b8bc837e347f9e8daaaa3bbf457f48e4c320512be024bc591852f6ddd
+  data.tar.gz: 94ae6c7269ce07c2578499e51da76641b2b4df11caa5f76bc4dbd691ae61d43e
+SHA512:
+  metadata.gz: 25a3c87aa1e640ecc6f9b05c48717434d184a0987b35b78e38c19c5c57b399e2f63be87be3239e56f01800bd17dadefe79dfaabf0cad9b3e4274513f473fe2fa
+  data.tar.gz: 56b6973f4de6917808a36e134575fe30c125f3ac6a9e03f3b507f4b2cae7c8b42ae40d032500d8c8e7f01d106c94811945e2dbd775ca70a2951eba9e141ae239

data/History.md

@@ -0,0 +1,7 @@
+# Release History for mixins
+
+---
+
+## v0.0.1 [2025-05-27] Michael Granger <ged@faeriemud.org>
+
+First release.

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2025, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,89 @@
+# mixins
+
+home
+: https://hg.sr.ht/~ged/Mixins
+
+code
+: https://hg.sr.ht/~ged/Mixins
+
+github
+: https://github.com/ged/mixins
+
+docs
+: https://deveiate.org/code/mixins
+
+
+## Description
+
+This is a collection of zero-dependency mixins. They're intended to be generically useful for building other software, well-tested, and not add any non-stdlib dependencies.
+
+The current mixins are:
+
+- Mixins::DataUtilities
+- Mixins::Datadir
+- Mixins::Delegation
+- Mixins::Hooks
+- Mixins::Inspection
+- Mixins::MethodUtilities
+
+
+## Prerequisites
+
+* Ruby 3+
+
+
+## Installation
+
+    $ gem install mixins
+
+
+## Contributing
+
+You can check out the current development source with Mercurial via its
+[project page](https://hg.sr.ht/~ged/Mixins). Or if you prefer Git, via
+[its Github mirror](https://github.com/ged/mixins).
+
+After checking out the source, run:
+
+    $ gem install -Ng
+    $ rake setup
+
+This will install dependencies, and do any other necessary setup for development.
+
+
+## Authors
+
+- Michael Granger <ged@faeriemud.org>
+
+
+## License
+
+Copyright (c) 2025, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/lib/mixins/data_utilities.rb

@@ -0,0 +1,88 @@
+# -*- ruby -*-
+
+require 'tempfile'
+
+require 'mixins' unless defined?( Mixins )
+
+
+# A collection of miscellaneous functions that are useful for manipulating
+# complex data structures.
+#
+#   include Ravn::DataUtilities
+#   newhash = deep_copy( oldhash )
+#
+module Mixins::DataUtilities
+
+	###############
+	module_function
+	###############
+
+
+	### Recursively copy the specified +obj+ and return the result.
+	def deep_copy( obj )
+
+		# Handle mocks during testing
+		return obj if obj.class.name == 'RSpec::Mocks::Mock'
+
+		# rubocop:disable Layout/IndentationWidth, Layout/IndentationStyle
+		return case obj
+			when NilClass, Numeric, TrueClass, FalseClass, Symbol,
+			     Module, Encoding, IO, Tempfile
+				obj
+
+			when Array
+				obj.map {|o| deep_copy(o) }
+
+			when Hash
+				newhash = {}
+				newhash.default_proc = obj.default_proc if obj.default_proc
+				obj.each do |k,v|
+					newhash[ deep_copy(k) ] = deep_copy( v )
+				end
+				newhash
+
+			else
+				obj.clone
+			end
+			# rubocop:enable Layout/IndentationWidth, Layout/IndentationStyle
+	end
+
+
+	### Return a duplicate of the given +object+ with its Symbol keys transformed
+	### into Strings.
+	def stringify_keys( object )
+		case object
+		when Hash
+			return object.each_with_object( {} ) do |(key,val), newhash|
+				key = key.to_s if key.is_a?( Symbol )
+				newhash[ key ] = stringify_keys( val )
+			end
+		when Array
+			return object.map {|el| stringify_keys(el) }
+		else
+			return object
+		end
+	end
+
+
+	### Return a duplicate of the given +object+ with its identifier-like String keys
+	### transformed into Symbols.
+	def symbolify_keys( object )
+		case object
+		when Hash
+			return object.each_with_object( {} ) do |(key,val), newhash|
+				key = key.to_sym if key.respond_to?( :to_sym ) &&
+					key.match?( /\A\w+\Z/ )
+				newhash[ key ] = symbolify_keys( val )
+			end
+		when Array
+			return object.map {|el| symbolify_keys(el) }
+		else
+			return object
+		end
+	end
+	alias_method :internify_keys, :symbolify_keys
+
+end # module Mixins::DataUtilities
+
+

data/lib/mixins/datadir.rb

@@ -0,0 +1,59 @@
+# -*- ruby -*-
+
+require 'pathname'
+require 'rubygems'
+
+require 'mixins' unless defined?( Mixins )
+
+
+# When extended in a class, automatically set the path to a DATA_DIR
+# constant, derived from the class name.  Prefers environmental
+# override, Gem path, then local filesystem pathing.
+#
+# This can also be called manually if the including class name doesn't
+# match the gem, or something else esoteric.
+#
+# DATA_DIR is a Pathname object.
+#
+module Mixins::Datadir
+
+	### Extend hook: Set the DATA_DIR constant in the extending
+	### class.
+	###
+	def self::extended( obj )
+		name = obj.name.downcase.gsub( '::', '-' )
+		dir = self.find_datadir( name )
+
+		obj.const_set( :DATA_DIR, dir )
+		obj.singleton_class.attr_accessor :data_dir
+		obj.data_dir = dir
+	end
+
+
+	### Return a pathname object for the extended class DATA_DIR.  This
+	### allows for the DATA_DIR constant to be used transparently between
+	### development (local checkout) and production (gem installation)
+	### environments.
+	###
+	def self::find_datadir( gemname, env: nil )
+		unless env
+			comps = gemname.split( '-' )
+			env = comps.size > 1 ? comps.last : comps.first
+			env = "%s_DATADIR" % [ env.upcase ]
+		end
+
+		loaded_gemspec = Gem.loaded_specs[ gemname ]
+
+		dir = if ENV[ env ]
+				Pathname( ENV[ env ] )
+			elsif loaded_gemspec && File.exist?( loaded_gemspec.datadir )
+				Pathname( loaded_gemspec.datadir )
+			else
+				caller_path = caller_locations( 2, 1 ).first.absolute_path
+				Pathname( caller_path ).dirname.parent.parent + "data/#{gemname}"
+			end
+
+		return dir
+	end
+
+end # module Mixins::Datadir

data/lib/mixins/delegation.rb

@@ -0,0 +1,95 @@
+# -*- ruby -*-
+
+require 'mixins' unless defined?( Mixins )
+
+
+# A collection of various delegation code-generators that can be used to define
+# delegation through other methods, to instance variables, etc.
+module Mixins::Delegation
+
+	### Define the given +delegated_methods+ as delegators to the like-named method
+	### of the return value of the +delegate_method+.
+	###
+	###    class MyClass
+	###      extend Strelka::Delegation
+	###
+	###      # Delegate the #bound?, #err, and #result2error methods to the connection
+	###      # object returned by the #connection method. This allows the connection
+	###      # to still be loaded on demand/overridden/etc.
+	###      def_method_delegators :connection, :bound?, :err, :result2error
+	###
+	###      def connection
+	###        @connection ||= self.connect
+	###      end
+	###    end
+	###
+	def def_method_delegators( delegate_method, *delegated_methods )
+		delegated_methods.each do |name|
+			body = Mixins::Delegation.make_method_delegator( delegate_method, name )
+			define_method( name, &body )
+		end
+	end
+
+
+	### Define the given +delegated_methods+ as delegators to the like-named method
+	### of the specified +ivar+. This is pretty much identical with how 'Forwardable'
+	### from the stdlib does delegation, but it's reimplemented here for consistency.
+	###
+	###    class MyClass
+	###      extend Strelka::Delegation
+	###
+	###      # Delegate the #each method to the @collection ivar
+	###      def_ivar_delegators :@collection, :each
+	###
+	###    end
+	###
+	def def_ivar_delegators( ivar, *delegated_methods )
+		delegated_methods.each do |name|
+			body = Mixins::Delegation.make_ivar_delegator( ivar, name )
+			define_method( name, &body )
+		end
+	end
+
+
+	### Define the given +delegated_methods+ as delegators to the like-named class
+	### method.
+	def def_class_delegators( *delegated_methods )
+		delegated_methods.each do |name|
+			define_method( name ) do |*args|
+				self.class.__send__( name, *args )
+			end
+		end
+	end
+
+
+	###############
+	module_function
+	###############
+
+	### Make the body of a delegator method that will delegate to the +name+ method
+	### of the object returned by the +delegate+ method.
+	def make_method_delegator( delegate, name )
+		return ->( *args, **kwargs, &block ) do
+			self.__send__( delegate ).__send__( name, *args, **kwargs, &block )
+		rescue => err
+			bt = err.backtrace_locations
+			bt.shift
+			raise( err, err.message, bt, cause: err )
+		end
+	end
+
+
+	### Make the body of a delegator method that will delegate calls to the +name+
+	### method to the given +ivar+.
+	def make_ivar_delegator( ivar_name, name )
+		return ->( *args, **kwargs, &block ) do
+			ivar = self.instance_variable_get( ivar_name )
+			ivar.__send__( name, *args, **kwargs, &block )
+		rescue => err
+			bt = err.backtrace_locations
+			bt.shift
+			raise( err, err.message, bt, cause: err )
+		end
+	end
+
+end # module Delegation

data/lib/mixins/hooks.rb

@@ -0,0 +1,84 @@
+# -*- ruby -*-
+
+require 'mixins' unless defined?( Mixins )
+
+
+# Methods for declaring hook methods.
+#
+#    class MyClass
+#        extend Mixins::Hooks
+#
+#        define_hook :before_fork
+#        define_hook :after_fork
+#    end
+#
+#    MyClass.before_fork do
+#        @socket.close
+#    end
+#    MyClass.after_fork do
+#        @socket = Socket.new
+#    end
+#
+#    MyClass.run_before_fork_hook
+#    fork do
+#        MyClass.run_after_fork_hook
+#    end
+#
+#
+module Mixins::Hooks
+
+	### Extension callback -- also extend it with MethodUtilities
+	def self::extended( obj )
+		super
+		obj.extend( Mixins::MethodUtilities )
+	end
+
+
+	### Create the body of a method that can register a callback for the specified +hook+.
+	def self::make_registration_method( callbackset, **options )
+		return lambda do |&callback|
+			raise LocalJumpError, "no callback given" unless callback
+			set = self.public_send( callbackset ) or raise "No hook registration set!"
+			set.add( callback )
+
+			callback.call if self.public_send( "#{callbackset}_run?" )
+		end
+	end
+
+
+	### Create the body of a method that calls the callbacks of the given +hook+.
+	def self::make_hook_method( callbackset, **options )
+		return lambda do |*args|
+			set = self.public_send( callbackset ) or raise "No hook callback registration set!"
+
+			self.public_send( "#{callbackset}_run=", true )
+
+			set.to_a.each do |callback|
+				callback.call( *args )
+			end
+		end
+	end
+
+
+	### Define a hook with the given +name+ that can be registered by calling the
+	### method of the same +name+ and then run by calling #call_<name>_hooks.
+	def define_hook( name, **options )
+		callbacks_name = "#{name}_callbacks"
+		self.instance_variable_set( "@#{callbacks_name}", Set.new )
+		self.singleton_attr_reader( callbacks_name )
+		self.instance_variable_set( "@#{callbacks_name}_run", false )
+		self.singleton_predicate_accessor( "#{callbacks_name}_run" )
+
+		register_body = Mixins::Hooks.
+			make_registration_method( callbacks_name, **options )
+		self.singleton_class.define_method( name, &register_body )
+
+		calling_body = Mixins::Hooks.
+			make_hook_method( callbacks_name, **options )
+		self.singleton_class.define_method( "call_#{name}_hook", &calling_body )
+		self.singleton_method_alias( "run_#{name}_hook", "call_#{name}_hook" )
+	end
+
+end # module Mixins::Hooks
+
+

data/lib/mixins/inspection.rb

@@ -0,0 +1,28 @@
+# -*- ruby -*-
+
+require 'mixins' unless defined?( Mixins )
+
+
+# An extensible #inspect.
+module Mixins::Inspection
+
+	### Return a human-readable representation of the object suitable for debugging.
+	def inspect
+		details = self.inspect_details
+		details = ' ' + details unless details.empty? || details.start_with?( ' ' )
+
+		return "#<%p:#%x%s>" % [
+			self.class,
+			self.object_id,
+			details,
+		]
+	end
+
+
+	### Return the detail portion of the inspect output for this object.
+	def inspect_details
+		return ''
+	end
+
+end # module Mixins::Inspection
+

data/lib/mixins/method_utilities.rb

@@ -0,0 +1,92 @@
+# -*- ruby -*-
+
+require 'mixins' unless defined?( Mixins )
+
+
+# A collection of methods for declaring other methods.
+#
+#     class MyClass
+#         extend Mixins::MethodUtilities
+#
+#         singleton_attr_accessor :types
+#         singleton_method_alias :kinds, :types
+#     end
+#
+#     MyClass.types = [ :pheno, :proto, :stereo ]
+#     MyClass.kinds # => [:pheno, :proto, :stereo]
+#
+module Mixins::MethodUtilities
+
+	### Creates instance variables and corresponding methods that return their
+	### values for each of the specified +symbols+ in the singleton of the
+	### declaring object (e.g., class instance variables and methods if declared
+	### in a Class).
+	def singleton_attr_reader( *symbols )
+		singleton_class.instance_exec( symbols ) do |attrs|
+			attr_reader( *attrs )
+		end
+	end
+
+
+	### Create instance variables and corresponding methods that return
+	### true or false values for each of the specified +symbols+ in the singleton
+	### of the declaring object.
+	def singleton_predicate_reader( *symbols )
+		singleton_class.extend( Mixins::MethodUtilities )
+		singleton_class.attr_predicate( *symbols )
+	end
+
+
+	### Creates methods that allow assignment to the attributes of the singleton
+	### of the declaring object that correspond to the specified +symbols+.
+	def singleton_attr_writer( *symbols )
+		singleton_class.instance_exec( symbols ) do |attrs|
+			attr_writer( *attrs )
+		end
+	end
+
+
+	### Creates readers and writers that allow assignment to the attributes of
+	### the singleton of the declaring object that correspond to the specified
+	### +symbols+.
+	def singleton_attr_accessor( *symbols )
+		symbols.each do |sym|
+			singleton_class.__send__( :attr_accessor, sym )
+		end
+	end
+
+
+	### Create predicate methods and writers that allow assignment to the attributes
+	### of the singleton of the declaring object that correspond to the specified
+	### +symbols+.
+	def singleton_predicate_accessor( *symbols )
+		singleton_class.extend( Mixins::MethodUtilities )
+		singleton_class.attr_predicate_accessor( *symbols )
+	end
+
+
+	### Creates an alias for the +original+ method named +newname+.
+	def singleton_method_alias( newname, original )
+		singleton_class.__send__( :alias_method, newname, original )
+	end
+
+
+	### Create a reader in the form of a predicate for the given +attrname+.
+	def attr_predicate( attrname )
+		attrname = attrname.to_s.chomp( '?' )
+		define_method( "#{attrname}?" ) do
+			instance_variable_get( "@#{attrname}" ) ? true : false
+		end
+	end
+
+
+	### Create a reader in the form of a predicate for the given +attrname+
+	### as well as a regular writer method.
+	def attr_predicate_accessor( attrname )
+		attrname = attrname.to_s.chomp( '?' )
+		attr_writer( attrname )
+		attr_predicate( attrname )
+	end
+
+end # module Mixins::MethodUtilities
+

data/lib/mixins.rb

@@ -0,0 +1,20 @@
+# -*- ruby -*-
+
+
+# A collection of Modules that can be mixed into other modules to make
+# common tasks easier and more intention-revealing.
+module Mixins
+
+	# Package version
+	VERSION = '0.0.1'
+
+
+	autoload :MethodUtilities, 'mixins/method_utilities'
+	autoload :DataUtilities, 'mixins/data_utilities'
+	autoload :Delegation, 'mixins/delegation'
+	autoload :Hooks, 'mixins/hooks'
+	autoload :Inspection, 'mixins/inspection'
+	autoload :Datadir, 'mixins/datadir'
+
+end # module Mixins
+