literal 0.2.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ab1d4d21286c3cc2a094362e0f1f6a94856738c7ba9a93d285607bb57ce49b5
-  data.tar.gz: 27c2f4fe6ecbb00fcaeb5faf5b4d13849c3ef8dcc6eec817775f55648fac4847
+  metadata.gz: 75c7cc8853143bd8f4ac74b7fc4a5b5d2812bd39c0b4f696a87c2ffc0fb31046
+  data.tar.gz: 7781d6362e9ae8f75d0156809f95b0c1f8a37df855356173c9b6f09428419bc0
 SHA512:
-  metadata.gz: ef894ddc2c2ee8ca82175d3f833ca0a05f479adf164766c681c4bc165a21840f8431da8c4ee6d4d971b10bf4f37427af40914795f2bdd14855927f818633abb7
-  data.tar.gz: 806aa654d1670c8842dae039c4e0845dbd1ea304bfabb634aefc0ea79b380889d8e249b3348274d11cc7ac01b173e3c9b468d13d4c44f321ceaa8ac83d5b11ec
+  metadata.gz: 6acc2552c11ff3c5f12877b5597f9a6a138bf4901f5fce3801004e286b522c6263fa2454621ac4f5511f553af073d5113d96cd1af1045bc9e44c014c15ab7420
+  data.tar.gz: 6f9b205b3343426385185ebd0ea0e04164f6a06f9d42d6cb34c542c8d12a98ab327e274b336fb13d389e7380f5bd79831eb2b508f2d019cd6143658db40f3195

data/README.md

@@ -1,158 +1,3 @@
 # A Literal Ruby Gem [WIP]
 
-## Types
-
-Literal uses Ruby-native types. Any method that responds to `===(value)` is considered a type. Note, this is how Ruby’s case statements and pattern matching work. It’s also how `Array#any?` and `Array#all?` work. Essentially all Ruby objects are types and just work the way you’d expect them to. A few examples:
-
-- On a `Range`, `===(value)` checks if the value is within the range.
-- On a `Regexp`, `===(value)` checks if the value matches the pattern.
-- On a `Class`, `===(value)` checks if the value is an instance of the class.
-- On a `Proc`, `===(value)` calls the proc with the value.
-- On a `String`, `===(value)` checks if the value is equal to the string.
-- On the class `String`, `===(value)` checks if the value is a string.
-
-Literal extends this idea with the concept of generics or _parameterised_ types. A generic is a method that returns an object that respond to `===(value)`.
-
-If we want to check that a given value is an `Array`, we could do this:
-
-```ruby
-Array === [1, 2, 3]
-```
-
-But what if we want to check that it’s an Array of Integers? Literal provides a library of special types that can be composed for this purpose. In this case, we can use the type `_Array(Integer)`.
-
-```ruby
-_Array(Integer) === [1, 2, 3]
-```
-
-These special types are defined on the `Literal::Types` module. To access them in a class, you can `extend` this module. To access them on an instance, you can `include` the module. If you want to use them globally, you can `extend` the module at the root.
-
-```ruby
-extend Literal::Types
-```
-
-This is recommended for applications, but not for libraries, as we don’t want to pollute the global namespace from library code.
-
-`Literal::Properties`, `Literal::Object`, `Literal::Struct` and `Literal::Data` already extend `Literal::Types`, so you don’t need to extend `Literal::Types` yourself if you’re only using literal types for literal properties.
-
-## Properties
-
-`Literal::Properties` is a mixin that allows you to define the structure of an object. Properties are defined using the `prop` method.
-
-The first argument is the name of the property as a `Symbol`. The second argument is the _type_ of the property. Remember, the type can be any object that responds to `===(value)`.
-
-The third argument is optional. You can set this to `:*`, `:**`, `:&`, or `:positional` to change the kind of initializer parameter.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String
-  prop :age, Integer
-end
-```
-
-You can also use keyword arguments to define _readers_ and _writers_. These can be set to `false`, `:public`, `:protected`, or `:private` and default to `false`.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String, reader: :public
-  prop :age, Integer, writer: :protected
-end
-```
-
-Properties are required by deafult. To make them optional, set the type to a that responds to `===(nil)` with `true`. `Literal::Types` provides a special types for this purpose. Let’s make the age optional by setting its type to a `_Nilable(Integer)`:
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String
-  prop :age, _Nilable(Integer)
-end
-```
-
-Alternatively, you can give the property a default value. This default value must match the type of the property.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String, default: "John Doe"
-  prop :age, _Nilable(Integer)
-end
-```
-
-Note, the above example will fail unless you have frozen string literals enabled. (Which, honestly, you should.) Default values must be frozen. If you can’t use a frozen value, you can pass a proc instead.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String, default: -> { "John Doe" }
-  prop :age, _Nilable(Integer)
-end
-```
-
-The proc will be called to generate the default value.
-
-You can also pass a block to the `prop` method. This block will be called with the value of the property when it’s set, which is useful for coercion.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :name, String
-  prop :age, Integer do |value|
-    value.to_i
-  end
-end
-```
-
-Coercion takes place prior to type-checking, so you can safely coerce a value to a different type in the block.
-
-You can use properties that conflict with ruby keywords. Literal will handle everything for you automatically.
-
-```ruby
-class Person
-  extend Literal::Properties
-
-  prop :class, String, :positional
-  prop :end, Integer
-end
-```
-
-If you’d prefer to subclass than extend a module, you can use the `Literal::Object` class instead. `Literal::Object` literally extends `Literal::Properties`.
-
-```ruby
-class Person < Literal::Object
-  prop :name, String
-  prop :age, Integer
-end
-```
-
-## Structs
-
-`Literal::Struct` is like `Literal::Object`, but it also provides a few extras.
-
-Structs implement `==` so you can compare one struct to another. They also implement `hash`. Structs also have public _readers_ and _writers_ by default.
-
-```ruby
-class Person < Literal::Struct
-  prop :name, String
-  prop :age, Integer
-end
-```
-
-## Data
-
-`Literal::Data` is like `Literal::Struct`, but you can’t define _writers_. Additionally, objects are _frozen_ after initialization. Additionally any non-frozen properties are duplicated and frozen.
-
-```ruby
-class Person < Literal::Data
-  prop :name, String
-  prop :age, Integer
-end
-```
+See the website for [documentation](https://literal.fun/docs).

data/lib/literal/data_structure.rb

@@ -10,25 +10,18 @@ class Literal::DataStructure
 		object
 	end
 
-	def ==(other)
-		if Literal::DataStructure === other
-			to_h == other.to_h
-		else
-			false
-		end
-	end
-
-	def hash
-		[self.class, to_h].hash
-	end
-
 	def [](key)
-		instance_variable_get("@#{key}")
+		instance_variable_get(:"@#{key}")
 	end
 
 	def []=(key, value)
-		@literal_properties[key].check(value)
-		instance_variable_set("@#{key}", value)
+		# TODO: Sync error array w/ generated setter
+		@literal_properties[key].check(value) { |c| raise NotImplementedError }
+		instance_variable_set(:"@#{key}", value)
+	end
+
+	def to_h
+		{}
 	end
 
 	def deconstruct
@@ -57,4 +50,20 @@ class Literal::DataStructure
 	def marshal_dump
 		[1, to_h, frozen?]
 	end
+
+	def hash
+		self.class.hash
+	end
+
+	def ==(other)
+		other.is_a?(self.class) && other.class.literal_properties.empty?
+	end
+	alias eql? ==
+
+	def self.__generate_literal_methods__(new_property, buffer = +"")
+		super
+		literal_properties.generate_hash(buffer)
+		literal_properties.generate_eq(buffer)
+		buffer
+	end
 end

data/lib/literal/enum.rb

@@ -21,6 +21,15 @@ class Literal::Enum
 				@indexes = {}
 				@index = {}
 			end
+
+			if RUBY_ENGINE != "truffleruby"
+				TracePoint.trace(:end) do |tp|
+					if tp.self == subclass
+						tp.self.__after_defined__
+						tp.disable
+					end
+				end
+			end
 		end
 
 		def index(name, type, unique: true, &block)
@@ -34,9 +43,9 @@ class Literal::Enum
 
 			key, value = kwargs.first
 
-			unless (type = @indexes.fetch(key)[0]) === value
-				raise Literal::TypeError.expected(value, to_be_a: type)
-			end
+			types = @indexes.fetch(key)
+			type = types.first
+			Literal.check(actual: value, expected: type) { |c| raise NotImplementedError }
 
 			@index.fetch(key)[value]
 		end
@@ -76,9 +85,9 @@ class Literal::Enum
 			end
 		end
 
-		def new(*, **, &block)
+		def new(*args, **kwargs, &block)
 			raise ArgumentError if frozen?
-			new_object = super(*, **, &nil)
+			new_object = super(*args, **kwargs, &nil)
 
 			if block
 				new_object.instance_exec(&block)
@@ -90,6 +99,10 @@ class Literal::Enum
 		def __after_defined__
 			raise ArgumentError if frozen?
 
+			if RUBY_VERSION < "3.2"
+				constants(false).each { |name| const_added(name) }
+			end
+
 			@indexes.each do |name, (type, unique, block)|
 				index = @members.group_by(&block).freeze
 
@@ -111,8 +124,8 @@ class Literal::Enum
 			freeze
 		end
 
-		def each(&)
-			@members.each(&)
+		def each
+			@members.each { |member| yield(member) }
 		end
 
 		def each_value(&)
@@ -166,11 +179,3 @@ class Literal::Enum
 		Marshal.dump(@value)
 	end
 end
-
-TracePoint.trace(:end) do |tp|
-	it = tp.self
-
-	if Class === it && it < Literal::Enum
-		it.__after_defined__
-	end
-end

data/lib/literal/errors/type_error.rb

@@ -1,10 +1,83 @@
 # frozen_string_literal: true
 
 class Literal::TypeError < TypeError
+	INDENT = "  "
+
 	include Literal::Error
 
-	def self.expected(value, to_be_a:)
-		type = to_be_a
-		new("Expected `#{value.inspect}` to be of type: `#{type.inspect}`.")
+	class Context
+		attr_reader :receiver, :method, :label, :expected, :actual, :children
+
+		def initialize(
+			receiver: nil, # _Nilable(Object)
+			method: nil, # _Nilable(String)
+			label: nil, # _Nilable(String)
+			expected: nil, # _Nilable(_Any)
+			actual: nil, # _Nilable(_Any)
+			parent: nil # _Nilable(Context)
+		)
+			@receiver = receiver
+			@method = method
+			@label = label
+			@expected = expected
+			@actual = actual
+			@children = []
+		end
+
+		def descend(level = 0, &blk)
+			yield self, level
+			@children.each { |child| child.descend(level + 1, &blk) }
+			nil
+		end
+
+		def fill_receiver(receiver:, method:, label: nil)
+			@receiver = receiver
+			@method = method
+			@label = label
+		end
+
+		def add_child(expected: nil, **kwargs)
+			child = self.class.new(expected:, **kwargs)
+			expected.record_literal_type_errors(child) if expected.respond_to?(:record_literal_type_errors)
+			@children << child
+		end
+	end
+
+	def initialize(context:)
+		@context = context
+
+		super()
+	end
+
+	def message
+		message = +"Type mismatch\n\n"
+
+		@context.descend do |c, level|
+			idt = INDENT * level
+			if c.receiver || c.method
+				message << idt
+				message << c.receiver.class.inspect if c.receiver
+				message << c.method if c.method
+				message << " (from #{backtrace[1]})" if level.zero?
+				message << "\n"
+			end
+			if c.label
+				idt << INDENT
+				message << idt << c.label << "\n"
+			end
+			if c.expected && c.children.empty?
+				message << idt << "  Expected: #{c.expected.inspect}\n"
+				message << idt << "  Actual (#{c.actual.class}): #{c.actual.inspect}\n"
+			end
+		end
+		message
+	end
+
+	def deconstruct_keys(keys)
+		to_h.slice(*keys)
+	end
+
+	def to_h
+		@context.to_h
 	end
 end

data/lib/literal/properties/data_schema.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 class Literal::Properties::DataSchema < Literal::Properties::Schema
-	def generate_initializer_body(buffer = +"")
-		buffer << "properties = self.class.literal_properties.properties_index\n"
-		generate_initializer_handle_properties(@sorted_properties, buffer)
-		buffer << "after_initialize if respond_to?(:after_initialize)\nfreeze\n"
+	def generate_after_initializer(buffer = +"")
+		super
+		buffer << "  freeze\n"
 	end
 end

data/lib/literal/properties/schema.rb

@@ -19,7 +19,9 @@ class Literal::Properties::Schema
 	def <<(value)
 		@mutex.synchronize do
 			@properties_index[value.name] = value
-			@sorted_properties = @properties_index.values.sort!
+			# ruby's sort is unstable, this trick makes it stable
+			n = 0
+			@sorted_properties = @properties_index.values.sort_by! { |it| n += 1; [it, n] }
 		end
 
 		self
@@ -40,24 +42,71 @@ class Literal::Properties::Schema
 		@sorted_properties.size
 	end
 
+	def empty?
+		@sorted_properties.empty?
+	end
+
 	def generate_initializer(buffer = +"")
+		buffer << "alias initialize initialize\n"
 		buffer << "def initialize(#{generate_initializer_params})\n"
 		generate_initializer_body(buffer)
+		buffer << "" \
+			"rescue Literal::TypeError => error\n" \
+			"  error.set_backtrace(caller(2))\n" \
+			"  raise\n" \
+			"else\n"
+		generate_after_initializer(buffer)
 		buffer << "end\n"
 	end
 
+	def generate_after_initializer(buffer = +"")
+		buffer << "  after_initialize if respond_to?(:after_initialize)\n"
+	end
+
 	def generate_to_h(buffer = +"")
-		buffer << "def to_h\n" << "{\n"
+		buffer << "alias to_h to_h\n"
+		buffer << "def to_h\n" << "  {\n"
 
 		sorted_properties = @sorted_properties
 		i, n = 0, sorted_properties.size
 		while i < n
 			property = sorted_properties[i]
-			buffer << property.name.name << ": @" << property.name.name << ",\n"
+			buffer << "    " << property.name.name << ": @" << property.name.name << ",\n"
 			i += 1
 		end
 
-		buffer << "}\n" << "end\n"
+		buffer << "  }\n" << "end\n"
+	end
+
+	def generate_hash(buffer = +"")
+		buffer << "def hash\n  [self.class,\n"
+
+		sorted_properties = @sorted_properties
+		i, n = 0, sorted_properties.size
+		while i < n
+			property = sorted_properties[i]
+			buffer << "  @" << property.name.name << ",\n"
+			i += 1
+		end
+
+		buffer << "  ].hash\n" << "end\n"
+	end
+
+	def generate_eq(buffer = +"")
+		buffer << "def ==(other)\n"
+		buffer << "  return false unless other.is_a?(self.class) && other.class.literal_properties.size == self.class.literal_properties.size\n"
+
+		sorted_properties = @sorted_properties
+		i, n = 0, sorted_properties.size
+		while i < n
+			property = sorted_properties[i]
+			buffer << "  @" << property.name.name << " == other.#{property.escaped_name}"
+			buffer << " &&\n  " if i < n - 1
+			i += 1
+		end
+		buffer << "  true" if n.zero?
+		buffer << "\nend\n"
+		buffer << "alias eql? ==\n"
 	end
 
 	private
@@ -83,7 +132,7 @@ class Literal::Properties::Schema
 				else # required
 					buffer << property.escaped_name
 				end
-			else # keyword
+			when :keyword
 				if property.default?
 					buffer << property.name.name << ": Literal::Null"
 				elsif property.type === nil
@@ -91,6 +140,8 @@ class Literal::Properties::Schema
 				else # required
 					buffer << property.name.name << ":"
 				end
+			else
+				raise "You should never see this error."
 			end
 
 			i += 1
@@ -101,9 +152,8 @@ class Literal::Properties::Schema
 	end
 
 	def generate_initializer_body(buffer = +"")
-		buffer << "properties = self.class.literal_properties.properties_index\n"
+		buffer << "  properties = self.class.literal_properties.properties_index\n"
 		generate_initializer_handle_properties(@sorted_properties, buffer)
-		buffer << "after_initialize if respond_to?(:after_initialize)\n"
 	end
 
 	def generate_initializer_handle_properties(properties, buffer = +"")

data/lib/literal/properties.rb

@@ -6,6 +6,11 @@ module Literal::Properties
 
 	include Literal::Types
 
+	def self.extended(base)
+		super
+		base.include(base.__send__(:__literal_extension__))
+	end
+
 	def prop(name, type, kind = :keyword, reader: false, writer: false, predicate: false, default: nil, &coercion)
 		if default && !(Proc === default || default.frozen?)
 			raise Literal::ArgumentError.new("The default must be a frozen object or a Proc.")
@@ -66,16 +71,25 @@ module Literal::Properties
 	end
 
 	def __define_literal_methods__(new_property)
-		__literal_extension__.module_eval(
-			__generate_literal_methods__(new_property),
-		)
+		code =	__generate_literal_methods__(new_property)
+		__literal_extension__.module_eval(code)
 	end
 
 	def __literal_extension__
 		if defined?(@__literal_extension__)
 			@__literal_extension__
 		else
-			@__literal_extension__ = Module.new
+			@__literal_extension__ = Module.new do
+				def initialize
+					after_initialize if respond_to?(:after_initialize)
+				end
+
+				def to_h
+						{}
+				end
+
+				set_temporary_name "Literal::Properties(Extension)" if respond_to?(:set_temporary_name)
+			end
 		end
 	end
 

data/lib/literal/property.rb

@@ -51,7 +51,24 @@ class Literal::Property
 	end
 
 	def default?
-			nil != @default
+		nil != @default
+	end
+
+	def param
+		case @kind
+		when :*
+			"*#{escaped_name}"
+		when :**
+			"**#{escaped_name}"
+		when :&
+			"&#{escaped_name}"
+		when :positional
+			escaped_name
+		when :keyword
+			"#{@name.name}:"
+		else
+			raise "You should never see this error."
+		end
 	end
 
 	def <=>(other)
@@ -77,18 +94,28 @@ class Literal::Property
 		end
 	end
 
-	def check(value)
-		Literal.check(value, @type)
+	def check(value, &)
+		raise ArgumentError.new("Cannot check type without a block") unless block_given?
+
+		Literal.check(actual: value, expected: @type, &)
+	end
+
+	def check_writer(receiver, value)
+		Literal.check(actual: value, expected: @type) { |c| c.fill_receiver(receiver:, method: "##{@name.name}=(value)") }
+	end
+
+	def check_initializer(receiver, value)
+		Literal.check(actual: value, expected: @type) { |c| c.fill_receiver(receiver:, method: "#initialize", label: param) }
 	end
 
 	def generate_reader_method(buffer = +"")
 		buffer <<
 			(@reader ? @reader.name : "public") <<
-			" def " <<
+			"\ndef " <<
 			@name.name <<
-			"\nvalue = @" <<
+			"\n  value = @" <<
 			@name.name <<
-			"\nvalue\nend\n"
+			"\n  value\nend\n"
 	end
 
 	if Literal::TYPE_CHECKS_DISABLED
@@ -98,7 +125,7 @@ class Literal::Property
 				" def " <<
 				@name.name <<
 				"=(value)\n" <<
-				"@#{@name.name} = value\nend\n"
+				"  @#{@name.name} = value\nend\n"
 		end
 	else # type checks are enabled
 		def generate_writer_method(buffer = +"")
@@ -107,10 +134,12 @@ class Literal::Property
 				" def " <<
 				@name.name <<
 				"=(value)\n" <<
-				"self.class.literal_properties[:" <<
+				"  self.class.literal_properties[:" <<
 				@name.name <<
-				"].check(value)\n" <<
-				"@#{@name.name} = value\nend\n"
+				"].check_writer(self, value)\n" <<
+				"  @" << @name.name << " = value\n" <<
+				"rescue Literal::TypeError => error\n  error.set_backtrace(caller(1))\n  raise\n" <<
+				"end\n"
 		end
 	end
 
@@ -120,15 +149,15 @@ class Literal::Property
 			" def " <<
 			@name.name <<
 			"?\n" <<
-			"!!@" <<
+			"  !!@" <<
 			@name.name <<
 			"\n" <<
 			"end\n"
 	end
 
 	def generate_initializer_handle_property(buffer = +"")
-		buffer << "# " << @name.name << "\n" <<
-			"property = properties[:" << @name.name << "]\n"
+		buffer << "  # " << @name.name << "\n" <<
+			"  property = properties[:" << @name.name << "]\n"
 
 		if @kind == :keyword && ruby_keyword?
 			generate_initializer_escape_keyword(buffer)
@@ -169,25 +198,23 @@ class Literal::Property
 
 	def generate_initializer_assign_default(buffer = +"")
 		buffer <<
-			"if " <<
+			"  if " <<
 			((@kind == :&) ? "nil" : "Literal::Null") <<
 			" == " <<
 			escaped_name <<
-			"\n" <<
+			"\n    " <<
 			escaped_name <<
-			" = property.default_value\nend\n"
+			" = property.default_value\n  end\n"
 	end
 
 	def generate_initializer_check_type(buffer = +"")
 		buffer <<
-			"unless property.type === " << escaped_name << "\n" <<
-			"raise Literal::TypeError.expected(" << escaped_name << ", to_be_a: property.type)\n" <<
-			"end\n"
+			"  property.check_initializer(self, " << escaped_name << ")\n"
 	end
 
 	def generate_initializer_assign_value(buffer = +"")
 		buffer <<
-			"@" <<
+			"  @" <<
 			@name.name <<
 			" = " <<
 			escaped_name <<