literal 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d45b4ed514f637e98bd45cd2ecbf54b3eba3cc8ece8c513cea63258ef11cd842
-  data.tar.gz: 10486859e1ecb34e9f0af4da5c2a5e6f408e49d1ff8403f75643839df8b10ccb
+  metadata.gz: 0bb6bc1253e6b8116aaf174380fb8ea5a0edbaec66d80df5f514a2a3241325b8
+  data.tar.gz: f018a260e5c17f101813d1e665f314ecebb80b9f769e59eccc8b67bb196a64b6
 SHA512:
-  metadata.gz: 881e25855ffe6931e684eee59030f55fce875fd48092934ad83a76e7270410aba9eb10b774584c6e45b61fc7fecfa6ebea3b400275a326f6ad2464d67a390084
-  data.tar.gz: 2ef3da3eabc5c3c8db4c71135cae66fed8185007f7583864345dcd476dad528865dd4d7f81bc6045babddf19c9487965845758e2555359e95ae54bb9ed3abf20
+  metadata.gz: 79d7771c617d331b8bc6a6cb94cc7949059dbcf5e449162a21c0f502de8081075aeb32810313b77d10a9439ef88c65bf4db3c1815f78eb2771466acdb9a551db
+  data.tar.gz: 8b48552cf91a9b474501f906b6bdd1b04fdfc68b0102ec388063c3d8b7dc50b5520a49bb79e00a3ef84aa56899167d416b2911f672522b60c77bde38d5cb09cc

data/lib/literal/array.rb

@@ -20,10 +20,10 @@ class Literal::Array
 			Literal::Array === value && Literal.subtype?(value.__type__, @type)
 		end
 
-		def >=(other)
+		def >=(other, context: nil)
 			case other
 			when Literal::Array::Generic
-				Literal.subtype?(other.type, @type)
+				Literal.subtype?(other.type, @type, context:)
 			else
 				false
 			end

data/lib/literal/data.rb

@@ -2,8 +2,16 @@
 
 class Literal::Data < Literal::DataStructure
 	class << self
-		def prop(name, type, kind = :keyword, reader: :public, predicate: false, default: nil)
-			super(name, type, kind, reader:, writer: false, predicate:, default:)
+		def [](...) = new(...)
+
+		def define(**properties)
+			Class.new(self) do
+				properties.each { |name, type| prop(name, type) }
+			end
+		end
+
+		def prop(name, type, kind = :keyword, reader: :public, predicate: false, default: nil, description: nil)
+			super(name, type, kind, reader:, writer: false, predicate:, default:, description:)
 		end
 
 		def literal_properties

data/lib/literal/data_structure.rb

@@ -29,6 +29,7 @@ class Literal::DataStructure
 		marshal_dump
 	end
 
+	# required method for Marshal compatibility
 	def marshal_load(payload)
 		_version, attributes, was_frozen = payload
 
@@ -39,6 +40,7 @@ class Literal::DataStructure
 		freeze if was_frozen
 	end
 
+	# required method for Marshal compatibility
 	def marshal_dump
 		[1, to_h, frozen?].freeze
 	end

data/lib/literal/enum.rb

@@ -11,8 +11,8 @@ class Literal::Enum
 		def values = @values.keys
 		def names = @names
 
-		def prop(name, type, kind = :keyword, reader: :public, predicate: false, default: nil)
-			super(name, type, kind, reader:, writer: false, predicate:, default:)
+		def prop(name, type, kind = :keyword, reader: :public, predicate: false, default: nil, description: nil)
+			super(name, type, kind, reader:, writer: false, predicate:, default:, description:)
 		end
 
 		def inherited(subclass)
@@ -55,7 +55,7 @@ class Literal::Enum
 
 			types = @indexes_definitions.fetch(key)
 			type = types.first
-			Literal.check(value, type) { |c| raise NotImplementedError }
+			Literal.check(value, type)
 
 			@indexes.fetch(key)[value]
 		end
@@ -125,7 +125,12 @@ class Literal::Enum
 
 				index.each do |key, values|
 					unless type === key
-						raise Literal::TypeError.expected(key, to_be_a: type)
+						raise Literal::TypeError.new(
+							context: Literal::TypeError::Context.new(
+								expected: type,
+								actual: key,
+							)
+						)
 					end
 
 					if unique && values.size > 1
@@ -199,7 +204,14 @@ class Literal::Enum
 	end
 
 	alias_method :inspect, :name
-	alias_method :to_s, :name
+
+	def to_sym
+		self.class.names[self]
+	end
+
+	def to_s
+		to_sym.to_s
+	end
 
 	def deconstruct
 		[@value]

data/lib/literal/errors/type_error.rb

@@ -41,6 +41,19 @@ class Literal::TypeError < TypeError
 			expected.record_literal_type_errors(child) if expected.respond_to?(:record_literal_type_errors)
 			@children << child
 		end
+
+		def to_h
+			{
+				receiver: @receiver,
+				method: @method,
+				label: @label,
+				expected: @expected,
+				actual: @actual,
+				children: @children.map(&:to_h),
+			}
+		end
+
+		alias to_hash to_h
 	end
 
 	def initialize(context:)

data/lib/literal/failure.rb

@@ -1,7 +1,85 @@
 # frozen_string_literal: true
 
 class Literal::Failure < Literal::Result
-	def initialize(error)
+	class Generic
+		include Literal::Type
+
+		def initialize(type)
+			@type = type
+			freeze
+		end
+
+		attr_reader :type
+
+		def ===(object)
+			Literal::Failure === object && @type === object.error!
+		end
+
+		def inspect
+			"Literal::Failure(#{@type.inspect})"
+		end
+
+		freeze
+	end
+
+	def initialize(error, success_type:, failure_type:)
 		@error = error
+
+		@success_type = success_type
+		@failure_type = failure_type
+
+		Literal.check(error, failure_type)
+
+		freeze
+	end
+
+	attr_reader :success_type, :failure_type
+
+	def success?
+		false
+	end
+
+	def failure?
+		true
+	end
+
+	def value!
+		raise Literal::ArgumentError.new("Failure has no value")
+	end
+
+	def deconstruct
+		[@error]
+	end
+
+	def deconstruct_keys(keys)
+		if @error.respond_to?(:deconstruct_keys)
+			@error.deconstruct_keys(keys)
+		else
+			{}
+		end
+	end
+
+	def error!
+		@error
+	end
+
+	def map(type)
+		raise ArgumentError unless block_given?
+
+		Literal::Failure.new(
+			@error,
+			success_type: type,
+			failure_type: @failure_type
+		)
+	end
+
+	def then
+		raise ArgumentError unless block_given?
+		self
+	end
+
+	def value_or
+		raise ArgumentError unless block_given?
+		yield(@error)
 	end
 end

data/lib/literal/properties/introspection.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Literal::Properties::Introspection
+	def positional_properties
+		literal_properties.filter(&:positional?)
+	end
+
+	def keyword_properties
+		literal_properties.filter(&:keyword?)
+	end
+
+	def required_properties
+		literal_properties.filter(&:required?)
+	end
+
+	def required_positional_properties
+		required_properties.filter(&:positional?)
+	end
+
+	def required_keyword_properties
+		required_properties.filter(&:keyword?)
+	end
+
+	def optional_positional_properties
+		positional_properties - required_positional_properties
+	end
+
+	def optional_keyword_properties
+		keyword_properties - required_keyword_properties
+	end
+
+	def positional_property_names
+		positional_properties.map(&:name)
+	end
+
+	def keyword_property_names
+		keyword_properties.map(&:name)
+	end
+
+	def required_property_names
+		required_properties.map(&:name)
+	end
+
+	def required_positional_property_names
+		required_positional_properties.map(&:name)
+	end
+
+	def required_keyword_property_names
+		required_keyword_properties.map(&:name)
+	end
+
+	def optional_positional_property_names
+		optional_positional_properties.map(&:name)
+	end
+
+	def optional_keyword_property_names
+		optional_keyword_properties.map(&:name)
+	end
+end

data/lib/literal/properties/schema.rb

@@ -127,7 +127,7 @@ class Literal::Properties::Schema
 				buffer << "&" << property.escaped_name
 			when :positional
 				if property.default?
-					buffer << property.escaped_name << " = Literal::Null"
+					buffer << property.escaped_name << " = Literal::Undefined"
 				elsif property.type === nil # optional
 					buffer << property.escaped_name << " = nil"
 				else # required
@@ -135,7 +135,7 @@ class Literal::Properties::Schema
 				end
 			when :keyword
 				if property.default?
-					buffer << property.name.name << ": Literal::Null"
+					buffer << property.name.name << ": Literal::Undefined"
 				elsif property.type === nil
 					buffer << property.name.name << ": nil" # optional
 				else # required

data/lib/literal/properties.rb

@@ -13,7 +13,11 @@ module Literal::Properties
 		base.include(base.__send__(:__literal_extension__))
 	end
 
-	def prop(name, type, kind = :keyword, reader: false, writer: false, predicate: false, default: nil, &coercion)
+	def prop?(name, type, kind = :keyword, reader: false, writer: false, predicate: false, &coercion)
+		prop(name, _Union(type, Literal::Undefined), kind, reader:, writer:, predicate:, default: Literal::Undefined, description: nil, &coercion)
+	end
+
+	def prop(name, type, kind = :keyword, reader: false, writer: false, predicate: false, default: nil, description: nil, &coercion)
 		if default && !(Proc === default || default.frozen?)
 			raise Literal::ArgumentError.new("The default must be a frozen object or a Proc.")
 		end
@@ -40,6 +44,10 @@ module Literal::Properties
 			raise Literal::ArgumentError.new("The kind must be one of #{Literal::Property::KIND_OPTIONS.map(&:inspect).join(', ')}.")
 		end
 
+		unless description.nil? || String === description
+			raise Literal::ArgumentError.new("The description must be a String or nil.")
+		end
+
 		property = __literal_property_class__.new(
 			name:,
 			type:,
@@ -48,6 +56,7 @@ module Literal::Properties
 			writer:,
 			predicate:,
 			default:,
+			description:,
 			coercion:,
 		)
 

data/lib/literal/property.rb

@@ -9,7 +9,7 @@ class Literal::Property
 
 	include Comparable
 
-	def initialize(name:, type:, kind:, reader:, writer:, predicate:, default:, coercion:)
+	def initialize(name:, type:, kind:, reader:, writer:, predicate:, default:, description:, coercion:)
 		@name = name
 		@type = type
 		@kind = kind
@@ -17,10 +17,11 @@ class Literal::Property
 		@writer = writer
 		@predicate = predicate
 		@default = default
+		@description = description
 		@coercion = coercion
 	end
 
-	attr_reader :name, :type, :kind, :reader, :writer, :predicate, :default, :coercion
+	attr_reader :name, :type, :kind, :reader, :writer, :predicate, :default, :description, :coercion
 
 	def optional?
 		default? || @type === nil
@@ -51,9 +52,14 @@ class Literal::Property
 	end
 
 	def default?
+		return true if splat? || double_splat?
 		nil != @default
 	end
 
+	def description?
+		!!@description
+	end
+
 	def param
 		case @kind
 		when :*
@@ -183,7 +189,7 @@ class Literal::Property
 	private def generate_initializer_assign_default(buffer = +"")
 		buffer <<
 			"  if " <<
-			((@kind == :&) ? "nil" : "Literal::Null") <<
+			((@kind == :&) ? "nil" : "Literal::Undefined") <<
 			" == " <<
 			escaped_name <<
 			"\n    " <<

data/lib/literal/rails/relation_type.rb

@@ -3,14 +3,6 @@
 module Literal::Rails
 	class RelationType
 		def initialize(model_class)
-			unless Class === model_class && model_class < ActiveRecord::Base
-				raise Literal::TypeError.new(
-						context: Literal::TypeError::Context.new(
-							expected: ActiveRecord::Base, actual: model_class
-						)
-					)
-			end
-
 			@model_class = model_class
 		end
 
@@ -18,10 +10,10 @@ module Literal::Rails
 
 		def ===(value)
 			case value
-				when ActiveRecord::Relation, ActiveRecord::Associations::CollectionProxy, ActiveRecord::AssociationRelation
-					@model_class == value.model || value.model < @model_class
-				else
-					false
+			when ActiveRecord::Relation, ActiveRecord::Associations::CollectionProxy, ActiveRecord::AssociationRelation
+				@model_class == value.model || value.model < @model_class
+			else
+				false
 			end
 		end
 	end

data/lib/literal/result.rb

@@ -1,4 +1,72 @@
 # frozen_string_literal: true
 
 class Literal::Result
+	class Thrown
+		def initialize(result)
+			@result = result
+			freeze
+		end
+
+		attr_reader :result
+	end
+
+	class Emitter
+		def initialize(type:, ball:)
+			@type = type
+			@ball = ball
+			freeze
+		end
+
+		def success(value)
+			throw(@ball, Thrown.new(@type.success(value)))
+		end
+
+		def failure(error)
+			throw(@ball, Thrown.new(@type.failure(error)))
+		end
+	end
+
+	class Generic
+		include Literal::Type
+
+		def initialize(success_type, failure_type)
+			@success_type = success_type
+			@failure_type = failure_type
+
+			freeze
+		end
+
+		attr_reader :success_type, :failure_type
+
+		def ===(object)
+			case object
+			when Literal::Success
+				@success_type === object.value!
+			when Literal::Failure
+				@failure_type === object.error!
+			end
+		end
+
+		def success(value)
+			Literal::Success.new(
+				value,
+				success_type: @success_type,
+				failure_type: @failure_type
+			)
+		end
+
+		def failure(error)
+			Literal::Failure.new(
+				error,
+				success_type: @success_type,
+				failure_type: @failure_type
+			)
+		end
+
+		freeze
+	end
+
+	def handle(&)
+		Literal::ResultHandler.new(self).handle(&)
+	end
 end

data/lib/literal/result_handler.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Literal::ResultHandler
+	def initialize(result)
+		@result = result
+		@success_cases = []
+		@failure_cases = []
+	end
+
+	def handle
+		return @result unless block_given?
+
+		yield(self)
+
+		unless Literal.subtype?(@result.success_type, covered_type(@success_cases))
+			raise Literal::ArgumentError.new("No success handler covers #{@result.success_type.inspect}")
+		end
+
+		unless Literal.subtype?(@result.failure_type, covered_type(@failure_cases))
+			raise Literal::ArgumentError.new("No failure handler covers #{@result.failure_type.inspect}")
+		end
+
+		case @result
+		when Literal::Success
+			@success_cases.each do |type, block|
+				if type === @result.value!
+					return block&.call(@result.value!)
+				end
+			end
+		when Literal::Failure
+			@failure_cases.each do |type, block|
+				if type === @result.error!
+					return block&.call(@result.error!)
+				end
+			end
+		end
+
+		raise Literal::ArgumentError.new("Unhandled result type: #{@result.class}")
+	end
+
+	def success(type = Literal::Types::_Any?, &block)
+		@success_cases << [type, block]
+	end
+
+	def failure(type = Literal::Types::_Any?, &block)
+		@failure_cases << [type, block]
+	end
+
+	private def covered_type(cases)
+		return Literal::Types::NeverType::Instance if cases.empty?
+
+		Literal::Types::_Union(*cases.map(&:first))
+	end
+end

data/lib/literal/struct.rb

@@ -2,7 +2,7 @@
 
 class Literal::Struct < Literal::DataStructure
 	class << self
-		def prop(name, type, kind = :keyword, reader: :public, writer: :public, default: nil)
+		def prop(name, type, kind = :keyword, reader: :public, writer: :public, default: nil, description: nil)
 			super
 		end
 	end

data/lib/literal/subtype_context.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Literal::SubtypeContext
+	def initialize
+		@memo = {}
+		@in_progress = {}
+	end
+
+	attr_reader :memo, :in_progress
+
+	def memoized?(key)
+		@memo.key?(key)
+	end
+
+	def fetch(key)
+		@memo[key]
+	end
+
+	def store(key, result)
+		@memo[key] = result
+	end
+
+	def acquire(key)
+		return false if @in_progress.key?(key)
+
+		@in_progress[key] = true
+		true
+	end
+
+	def release(key)
+		@in_progress.delete(key)
+	end
+end

data/lib/literal/success.rb

@@ -1,7 +1,103 @@
 # frozen_string_literal: true
 
 class Literal::Success < Literal::Result
-	def initialize(value)
+	class Generic
+		include Literal::Type
+
+		def initialize(type)
+			@type = type
+			freeze
+		end
+
+		attr_reader :type
+
+		def ===(object)
+			Literal::Success === object && @type === object.value!
+		end
+
+		def inspect
+			"Literal::Success(#{@type.inspect})"
+		end
+
+		freeze
+	end
+
+	def initialize(value, success_type:, failure_type:)
 		@value = value
+
+		@success_type = success_type
+		@failure_type = failure_type
+
+		Literal.check(@value, success_type)
+
+		freeze
+	end
+
+	attr_reader :success_type, :failure_type
+
+	def success?
+		true
+	end
+
+	def failure?
+		false
+	end
+
+	def value!
+		@value
+	end
+
+	def deconstruct
+		[@value]
+	end
+
+	def deconstruct_keys(keys)
+		if @value.respond_to?(:deconstruct_keys)
+			@value.deconstruct_keys(keys)
+		else
+			{}
+		end
+	end
+
+	def error!
+		raise Literal::ArgumentError.new("Success has no error")
+	end
+
+	def map(type)
+		raise ArgumentError unless block_given?
+		result = yield(@value)
+
+		Literal::Success.new(
+			result,
+			success_type: type,
+			failure_type: @failure_type
+		)
+	end
+
+	def then
+		raise ArgumentError unless block_given?
+		result = yield(@value)
+
+		case result
+		when Literal::Failure
+			Literal::Failure.new(
+				result.error!,
+				success_type: result.success_type,
+				failure_type: Literal::Types::_Union(@failure_type, result.failure_type)
+			)
+		when Literal::Success
+			Literal::Success.new(
+				result.value!,
+				success_type: result.success_type,
+				failure_type: Literal::Types::_Union(@failure_type, result.failure_type)
+			)
+		else
+			raise Literal::ArgumentError.new("Expected block to return a Literal::Result, got #{result.class.inspect}")
+		end
+	end
+
+	def value_or
+		raise ArgumentError unless block_given?
+		@value
 	end
 end

data/lib/literal/tuple.rb

@@ -26,7 +26,7 @@ class Literal::Tuple
 			true
 		end
 
-		def >=(other)
+		def >=(other, context: nil)
 			case other
 			when Literal::Tuple::Generic
 				types = @types
@@ -36,7 +36,7 @@ class Literal::Tuple
 
 				i, len = 0, types.size
 				while i < len
-					return false unless Literal.subtype?(other_types[i], types[i])
+					return false unless Literal.subtype?(other_types[i], types[i], context:)
 					i += 1
 				end