types 0.2.0 → 0.4.0

data/lib/types/class.rb

@@ -1,56 +1,71 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
+require_relative "generic"
 
 module Types
+	# Represents a class type, optionally constrained to a base class.
+	#
+	# ```ruby
+	# type = Types::Class(String)
+	# type.parse("Array") # => Array
+	# ```
 	class Class
 		extend Generic
 		include Generic
 		
+		# @parameter base [Class] The base class constraint.
 		def initialize(base)
 			@base = base
 		end
 		
+		# @returns [Class] the base class constraint.
 		attr :base
 		
+		# @returns [Boolean] true if this is a composite type.
 		def composite?
 			true
 		end
 		
+		# Resolve the base class if possible.
+		# @returns [Class] the resolved base class.
+		def resolve
+			Object.const_get(@base.to_s)
+		rescue NameError
+			nil
+		end
+		
+		# Parses the input as a class, optionally checking the base class constraint.
+		# @parameter input [String] The class name to parse.
+		# @returns [Class] the parsed class.
+		# @raises [ArgumentError] if the class is not a subclass of the base.
 		def parse(input)
 			klass = Object.const_get(input)
+			base = self.resolve
 			
-			if @base and !klass.ancestors.include?(@base)
-				raise ArgumentError, "Class #{klass} is not a subclass of #{@base}!"
+			if base and !klass.ancestors.include?(base)
+				raise ArgumentError, "Class #{klass} is not a subclass of #{base}!"
 			end
 			
 			return klass
 		end
 		
+		# @returns [Boolean] false for the class type itself.
 		def self.composite?
 			false
 		end
 		
+		# @returns [String] the RBS type string, e.g. `Class`.
+		def to_rbs
+			"Class"
+		end
+		
+		# Parses the input as a class, raising if not a class.
+		# @parameter input [String] The class name to parse.
+		# @returns [Class] the parsed class.
+		# @raises [ArgumentError] if the constant is not a class.
 		def self.parse(input)
 			klass = Object.const_get(input)
 			
@@ -60,8 +75,17 @@ module Types
 			
 			return klass
 		end
+		
+		# Resolves to the actual Ruby Class class.
+		# @returns [Class] The Class class.
+		def self.resolve
+			::Class
+		end
 	end
 	
+	# Constructs a {Class} type with an optional base class constraint.
+	# @parameter base [Class] The base class constraint.
+	# @returns [Class] a new {Class} type.
 	def self.Class(base = Object)
 		Class.new(base)
 	end

data/lib/types/decimal.rb

@@ -1,40 +1,41 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
-
-require 'bigdecimal'
+require_relative "generic"
+require "bigdecimal"
 
 module Types
+	# Represents a decimal type using BigDecimal.
+	#
+	# ```ruby
+	# type = Types::Decimal
+	# type.parse("3.14") # => #<BigDecimal ...>
+	# ```
 	module Decimal
 		extend Generic
 		
+		# Parses the input as a BigDecimal.
+		# @parameter input [Object] The value to parse.
+		# @returns [BigDecimal] The parsed decimal value.
+		# @raises [ArgumentError] if the input cannot be converted to a BigDecimal.
 		def self.parse(input)
 			case input
 			when ::Float
-				BigDecimal(input, ::Float::DIG+1)
+				Kernel.BigDecimal(input, ::Float::DIG+1)
 			else
-				BigDecimal(input)
+				Kernel.BigDecimal(input)
 			end
 		end
+		
+		# Resolves to the actual Ruby BigDecimal class.
+		# @returns [Class] The BigDecimal class.
+		def self.resolve
+			::BigDecimal
+		end
 	end
+	
+	# Alias for the Decimal type.
+	BigDecimal = Decimal
 end

data/lib/types/float.rb

@@ -1,33 +1,37 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
+require_relative "generic"
 
 module Types
+	# Represents a floating point type.
+	#
+	# ```ruby
+	# type = Types::Float
+	# type.parse("3.14") # => 3.14
+	# ```
 	module Float
 		extend Generic
 		
+		# Parses the input as a float.
+		# @parameter input [Object] The value to parse.
+		# @returns [Float] The parsed float value.
+		# @raises [ArgumentError] if the input cannot be converted to a float.
 		def self.parse(input)
 			Float(input)
 		end
+		
+		# @returns [String] the RBS type string, e.g. `Float`.
+		def self.to_rbs
+			"Float"
+		end
+		
+		# Resolves to the actual Ruby Float class.
+		# @returns [Class] The Float class.
+		def self.resolve
+			::Float
+		end
 	end
 end

data/lib/types/generic.rb

@@ -1,43 +1,38 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'any'
+require_relative "any"
 
 module Types
 	# An extension module which allows constructing `Any` types using the `|` operator.
+	#
+	# ```ruby
+	# type = Types::String | Types::Integer
+	# ```
 	module Generic
 		# Create an instance of `Any` with the arguments as types.
 		# @parameter other [Type] the alternative type to match.
+		# @returns [Any] a new {Any} type representing the union.
 		def | other
 			Any.new([self, other])
 		end
 		
-		# Whether a type contains nested types or not.
+		# @returns [String] the RBS representation of this type as a string.
+		# By default, this is the same as to_s, but can be overridden by composite types.
+		def to_rbs
+			to_s
+		end
+		
+		# @returns [Boolean] whether a type contains nested types or not.
 		def composite?
 			false
 		end
 		
+		# @returns [String] the string representation of the type.
 		def to_s
-			self.name.rpartition('::').last
+			self.name.rpartition("::").last
 		end
 	end
 end

data/lib/types/hash.rb

@@ -1,40 +1,36 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
+require_relative "generic"
 
 module Types
+	# Represents a hash type with key and value types.
+	#
+	# ```ruby
+	# type = Types::Hash(Types::String, Types::Integer)
+	# type.parse({"foo" => "42"}) # => {"foo" => 42}
+	# ```
 	class Hash
 		include Generic
 		
+		# @parameter key_type [Type] The type of the hash keys.
+		# @parameter value_type [Type] The type of the hash values.
 		def initialize(key_type, value_type)
 			@key_type = key_type
 			@value_type = value_type
 		end
 		
+		# @returns [Boolean] true if this is a composite type.
 		def composite?
 			true
 		end
 		
+		# Parses the input as a hash with the specified key and value types.
+		# @parameter input [Object] The value to parse.
+		# @returns [Hash] The parsed hash.
+		# @raises [ArgumentError] if the input cannot be converted to a hash.
 		def parse(input)
 			case input
 			when ::String
@@ -46,10 +42,22 @@ module Types
 			end
 		end
 		
+		# @returns [String] the string representation of the hash type.
 		def to_s
 			"Hash(#{@key_type}, #{@value_type})"
 		end
 		
+		# @returns [String] the RBS type string, e.g. `{ String => Integer }`.
+		def to_rbs
+			"{ #{@key_type.to_rbs} => #{@value_type.to_rbs} }"
+		end
+		
+		# Resolves to the actual Ruby Hash class.
+		# @returns [Class] The Hash class.
+		def resolve
+			::Hash
+		end
+		
 		private
 		
 		def parse_string(input)
@@ -61,6 +69,10 @@ module Types
 		end
 	end
 	
+	# Constructs a {Hash} type from the given key and value types.
+	# @parameter key_type [Type] The type of the hash keys.
+	# @parameter value_type [Type] The type of the hash values.
+	# @returns [Hash] a new {Hash} type.
 	def self.Hash(key_type, value_type)
 		Hash.new(key_type, value_type)
 	end

data/lib/types/integer.rb

@@ -1,33 +1,37 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
+require_relative "generic"
 
 module Types
+	# Represents an integer type.
+	#
+	# ```ruby
+	# type = Types::Integer
+	# type.parse("42") # => 42
+	# ```
 	module Integer
 		extend Generic
 		
+		# Parses the input as an integer.
+		# @parameter input [Object] The value to parse.
+		# @returns [Integer] The parsed integer value.
+		# @raises [ArgumentError] if the input cannot be converted to an integer.
 		def self.parse(input)
 			Integer(input)
 		end
+		
+		# @returns [String] the RBS type string, e.g. `Integer`.
+		def self.to_rbs
+			"Integer"
+		end
+		
+		# Resolves to the actual Ruby Integer class.
+		# @returns [Class] The Integer class.
+		def self.resolve
+			::Integer
+		end
 	end
 end

data/lib/types/interface.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+require_relative "generic"
+require_relative "method"
+require_relative "any"
+
+module Types
+	# Represents an interface type, defined by required method names.
+	#
+	# ```ruby
+	# type = Types::Interface(
+	# 	foo: Method.new(Any, returns: Any),
+	# 	bar: Method.new(Any, returns: Any)
+	# )
+	# type.valid?(obj) # => true if obj responds to :foo and :bar
+	# ```
+	class Interface
+		extend Generic
+		
+		# @parameter methods [Array(Symbol)] The required method names.
+		def initialize(methods)
+			@methods = methods
+		end
+		
+		# @returns [Array(Symbol)] The required method names.
+		attr :methods
+		
+		# @returns [Boolean] true if this is a composite type.
+		def composite?
+			true
+		end
+		
+		# @returns [String] the string representation of the interface type.
+		def to_s
+			buffer = ::String.new
+			
+			buffer << "Interface("
+			
+			if @methods&.any?
+				first = true
+				@methods.each do |name, method|
+					if first
+						first = false
+					else
+						buffer << ", "
+					end
+					
+					buffer << "#{name}: #{method}"
+				end
+			end
+			
+			buffer << ")"
+			
+			return buffer
+		end
+		
+		# Checks if the given instance responds to all required methods.
+		# @parameter instance [Object] The object to check.
+		# @returns [Boolean] true if the instance responds to all methods.
+		def valid?(instance)
+			@methods.all? do |name, method|
+				instance.respond_to?(name)
+			end
+		end
+		
+		# Parses the input as an object and checks if it matches the interface.
+		# @parameter input [Object] The value to parse.
+		# @returns [Object] the input if it matches the interface.
+		# @raises [ArgumentError] if the input does not match the interface.
+		def parse(input)
+			case input
+			when ::String
+				instance = eval(input)
+			else
+				instance = input
+			end
+			
+			if valid?(instance)
+				return instance
+			else
+				raise ArgumentError, "Cannot coerce #{input.inspect} into #{self}!"
+			end
+		end
+	end
+	
+	# Constructs an {Interface} type from the given method names.
+	# @parameter methods [Array(Symbol)] The required method names.
+	# @returns [Interface] a new {Interface} type.
+	def self.Interface(*names, **methods)
+		# This is a deprecated way to create an interfaces with names only. Ideally, we actually need to know the methods.
+		names.each do |name|
+			methods[name.to_sym] = Method.new(Any(), [], Any())
+		end
+		
+		Interface.new(methods)
+	end
+end

data/lib/types/lambda.rb

@@ -1,44 +1,38 @@
 # frozen_string_literal: true
 
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
 
-require_relative 'generic'
+require_relative "generic"
 
 module Types
-	# A lambda that represents a function (or callable object).
+	# Represents a lambda (function) type with argument and return types.
+	#
+	# ```ruby
+	# type = Types::Lambda(Types::String, Types::Integer, returns: Types::String)
+	# type.to_s # => "Lambda(String, Integer, returns: String)"
+	# ```
 	class Lambda
 		include Generic
 		
+		# @parameter argument_types [Array(Type)] The types of the lambda arguments.
+		# @parameter return_type [Type | Nil] The return type of the lambda.
 		def initialize(argument_types, return_type)
 			@argument_types = argument_types
 			@return_type = return_type
 		end
 		
+		# @returns [Array(Type)] The types of the lambda arguments.
 		attr :argument_types
+		# @returns [Type | Nil] The return type of the lambda.
 		attr :return_type
 		
+		# @returns [Boolean] true if this is a composite type.
 		def composite?
 			true
 		end
 		
+		# @returns [String] the string representation of the lambda type.
 		def to_s
 			if @return_type
 				"Lambda(#{@argument_types.join(', ')}, returns: #{@return_type})"
@@ -47,6 +41,10 @@ module Types
 			end
 		end
 		
+		# Parses the input as a lambda/proc.
+		# @parameter input [Object] The value to parse.
+		# @returns [Proc] the parsed lambda/proc.
+		# @raises [ArgumentError] if the input cannot be converted to a lambda.
 		def parse(input)
 			case input
 			when ::String
@@ -59,6 +57,10 @@ module Types
 		end
 	end
 	
+	# Constructs a {Lambda} type from the given argument and return types.
+	# @parameter argument_types [Array(Type)] The types of the lambda arguments.
+	# @parameter returns [Type | Nil] The return type of the lambda.
+	# @returns [Lambda] a new {Lambda} type.
 	def self.Lambda(*argument_types, returns: nil)
 		Lambda.new(argument_types, returns)
 	end