literal 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02ab6065a85602e1f60d915cb11cf8e0505881894ec9df310f08fc9194124a77
-  data.tar.gz: d86ff5c802deb2896486fa016da1f851af1296be511b79f5eab779a6e7bcb169
+  metadata.gz: 6ab1d4d21286c3cc2a094362e0f1f6a94856738c7ba9a93d285607bb57ce49b5
+  data.tar.gz: 27c2f4fe6ecbb00fcaeb5faf5b4d13849c3ef8dcc6eec817775f55648fac4847
 SHA512:
-  metadata.gz: de1ddb15cb9172712bc0534ac4c4c09aeb8d224496e8dcfe913cb03a1f3d4496b7ceee128e0eda7f94ada97dfa16160acafbae130165e7662a6714a6e25c2e67
-  data.tar.gz: 59a8bebc8c29ca4b62ba2c0adb6acc03037f92589465012fcbb8edafbe3d8acb36526439c6acad3346f2e4f9210c3b33902a03395b2e1ddf7221dc3cd5d46f57
+  metadata.gz: ef894ddc2c2ee8ca82175d3f833ca0a05f479adf164766c681c4bc165a21840f8431da8c4ee6d4d971b10bf4f37427af40914795f2bdd14855927f818633abb7
+  data.tar.gz: 806aa654d1670c8842dae039c4e0845dbd1ea304bfabb634aefc0ea79b380889d8e249b3348274d11cc7ac01b173e3c9b468d13d4c44f321ceaa8ac83d5b11ec

data/README.md

@@ -1,112 +1,158 @@
-# Literal
+# A Literal Ruby Gem [WIP]
 
-## Basic Usage
+## Types
 
-### Mixin
+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:
 
-```ruby
-class User
-  include Literal
+- 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.
 
-  attribute :name, String
-  attribute :age, Integer
-end
-```
+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)`.
 
-### Struct
+If we want to check that a given value is an `Array`, we could do this:
 
 ```ruby
-class Person < Literal::Struct
-  attribute :name, String
-  attribute :age, Integer
-end
+Array === [1, 2, 3]
 ```
 
-### Data
+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
-class Person < Literal::Data
-  attribute :name, String
-  attribute :age, Integer
-end
+_Array(Integer) === [1, 2, 3]
 ```
 
-## Special Types
-
-### Union
+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
-_Union(String, Symbol)
+extend Literal::Types
 ```
 
-### Boolean
+This is recommended for applications, but not for libraries, as we don’t want to pollute the global namespace from library code.
 
-```ruby
-_Boolean
-```
+`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.
 
-### Maybe
+## 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
-_Maybe(String)
+class Person
+  extend Literal::Properties
+
+  prop :name, String
+  prop :age, Integer
+end
 ```
 
-### Array
+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
-_Array(String)
+class Person
+  extend Literal::Properties
+
+  prop :name, String, reader: :public
+  prop :age, Integer, writer: :protected
+end
 ```
 
-### Set
+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
-_Set(String)
+class Person
+  extend Literal::Properties
+
+  prop :name, String
+  prop :age, _Nilable(Integer)
+end
 ```
 
-### Enumerable
+Alternatively, you can give the property a default value. This default value must match the type of the property.
 
 ```ruby
-_Enumerable(String)
+class Person
+  extend Literal::Properties
+
+  prop :name, String, default: "John Doe"
+  prop :age, _Nilable(Integer)
+end
 ```
 
-### Tuple
-An Enumerable containing exactly the specified types in order.
+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
-_Tuple(String, Integer)
+class Person
+  extend Literal::Properties
+
+  prop :name, String, default: -> { "John Doe" }
+  prop :age, _Nilable(Integer)
+end
 ```
 
-### Hash
+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
-_Hash(String, Integer)
+class Person
+  extend Literal::Properties
+
+  prop :name, String
+  prop :age, Integer do |value|
+    value.to_i
+  end
+end
 ```
 
-### Interface
+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
-_Interface(:to_s)
+class Person
+  extend Literal::Properties
+
+  prop :class, String, :positional
+  prop :end, Integer
+end
 ```
 
-### Class
+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(RuntimeError)
+class Person < Literal::Object
+  prop :name, String
+  prop :age, Integer
+end
 ```
 
-### Module
+## 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
-_Module(Enumerable)
+class Person < Literal::Struct
+  prop :name, String
+  prop :age, Integer
+end
 ```
 
-### Integer
-You can of course just use `Integer` to specify an integer type. The special type `_Integer` allows you to limit that type with a range, while verifying that it's an integer and not something else that matches the range such as a float.
+## Data
 
-```
-_Integer(18..)
-```
+`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.
 
-You can use these types together.
 ```ruby
-_Maybe(Union(String, Symbol, Interface(:to_s), Interface(:to_str), Tuple(String, Symbol)))
+class Person < Literal::Data
+  prop :name, String
+  prop :age, Integer
+end
 ```

data/lib/literal/data.rb

@@ -1,12 +1,25 @@
-class Literal::Data < Literal::Struct
-  def initialize(...)
-    super
-    @attributes.each(&:freeze)
-    @attributes.freeze
-    freeze
-  end
-
-  def dup(**attributes)
-    self.class.new(**@attributes.merge(attributes))
-  end
+# frozen_string_literal: true
+
+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:)
+		end
+
+		def literal_properties
+			return @literal_properties if defined?(@literal_properties)
+
+			if superclass.is_a?(Literal::Data)
+				@literal_properties = superclass.literal_properties.dup
+			else
+				@literal_properties = Literal::Properties::DataSchema.new
+			end
+		end
+
+		private
+
+		def __literal_property_class__
+			Literal::DataProperty
+		end
+	end
 end

data/lib/literal/data_property.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Literal::DataProperty < Literal::Property
+	def generate_initializer_assign_value(buffer = +"")
+		buffer <<
+			"@" <<
+			@name.name <<
+			" = " <<
+			escaped_name <<
+			".frozen? ? " <<
+			escaped_name <<
+			" : " <<
+			escaped_name <<
+			".dup.freeze\n"
+	end
+end

data/lib/literal/data_structure.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# @api private
+class Literal::DataStructure
+	extend Literal::Properties
+
+	def self.from_pack(payload)
+		object = allocate
+		object.marshal_load(payload)
+		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}")
+	end
+
+	def []=(key, value)
+		@literal_properties[key].check(value)
+		instance_variable_set("@#{key}", value)
+	end
+
+	def deconstruct
+		to_h.values
+	end
+
+	def deconstruct_keys(keys)
+		h = to_h
+		keys ? h.slice(*keys) : h
+	end
+
+	def as_pack
+		marshal_dump
+	end
+
+	def marshal_load(payload)
+		_version, attributes, was_frozen = payload
+
+		attributes.each do |key, value|
+			instance_variable_set("@#{key}", value)
+		end
+
+		freeze if was_frozen
+	end
+
+	def marshal_dump
+		[1, to_h, frozen?]
+	end
+end

data/lib/literal/enum.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+class Literal::Enum
+	extend Literal::Properties
+
+	class << self
+		include Enumerable
+
+		attr_reader :members
+
+		def values = @values.keys
+
+		def prop(name, type, kind = :keyword, reader: :public, default: nil)
+			super(name, type, kind, reader:, writer: false, default:)
+		end
+
+		def inherited(subclass)
+			subclass.instance_exec do
+				@values = {}
+				@members = Set[]
+				@indexes = {}
+				@index = {}
+			end
+		end
+
+		def index(name, type, unique: true, &block)
+			@indexes[name] = [type, unique, block || name.to_proc]
+		end
+
+		def where(**kwargs)
+			unless kwargs.length == 1
+				raise ArgumentError.new("You can only specify one index when using `where`.")
+			end
+
+			key, value = kwargs.first
+
+			unless (type = @indexes.fetch(key)[0]) === value
+				raise Literal::TypeError.expected(value, to_be_a: type)
+			end
+
+			@index.fetch(key)[value]
+		end
+
+		def find_by(**kwargs)
+			unless kwargs.length == 1
+				raise ArgumentError.new("You can only specify one index when using `where`.")
+			end
+
+			key, value = kwargs.first
+
+			unless @indexes.fetch(key)[1]
+				raise ArgumentError.new("You can only use `find_by` on unique indexes.")
+			end
+
+			unless (type = @indexes.fetch(key)[0]) === value
+				raise Literal::TypeError.expected(value, to_be_a: type)
+			end
+
+			@index.fetch(key)[value]&.first
+		end
+
+		def _load(data)
+			self[Marshal.load(data)]
+		end
+
+		def const_added(name)
+			raise ArgumentError if frozen?
+			object = const_get(name)
+
+			if self === object
+				object.instance_variable_set(:@name, name)
+				@values[object.value] = object
+				@members << object
+				define_method("#{name.to_s.gsub(/([^A-Z])([A-Z]+)/, '\1_\2').downcase}?") { self == object }
+				object.freeze
+			end
+		end
+
+		def new(*, **, &block)
+			raise ArgumentError if frozen?
+			new_object = super(*, **, &nil)
+
+			if block
+				new_object.instance_exec(&block)
+			end
+
+			new_object
+		end
+
+		def __after_defined__
+			raise ArgumentError if frozen?
+
+			@indexes.each do |name, (type, unique, block)|
+				index = @members.group_by(&block).freeze
+
+				index.each do |key, values|
+					unless type === key
+						raise Literal::TypeError.expected(key, to_be_a: type)
+					end
+
+					if unique && values.size > 1
+						raise ArgumentError.new("The index #{name} is not unique.")
+					end
+				end
+
+				@index[name] = index
+			end
+
+			@values.freeze
+			@members.freeze
+			freeze
+		end
+
+		def each(&)
+			@members.each(&)
+		end
+
+		def each_value(&)
+			@values.each_key(&)
+		end
+
+		def [](value)
+			@values[value]
+		end
+
+		alias_method :cast, :[]
+
+		def fetch(...)
+			@values.fetch(...)
+		end
+
+		def to_proc
+			method(:cast).to_proc
+		end
+
+		def to_h(*args)
+			@values.dup
+		end
+	end
+
+	def initialize(name, value, &block)
+		@name = name
+		@value = value
+		instance_exec(&block) if block
+		freeze
+	end
+
+	attr_reader :value
+
+	def name
+		"#{self.class.name}::#{@name}"
+	end
+
+	alias_method :inspect, :name
+
+	def deconstruct
+		[@value]
+	end
+
+	def deconstruct_keys(keys)
+		h = to_h
+		keys ? h.slice(*keys) : h
+	end
+
+	def _dump(level)
+		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/argument_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Literal::ArgumentError < ArgumentError
+	include Literal::Error
+end

data/lib/literal/errors/error.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module Literal::Error
+end

data/lib/literal/errors/type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class Literal::TypeError < TypeError
+	include Literal::Error
+
+	def self.expected(value, to_be_a:)
+		type = to_be_a
+		new("Expected `#{value.inspect}` to be of type: `#{type.inspect}`.")
+	end
+end

data/lib/literal/null.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Literal::Null
+	def self.inspect
+		"Literal::Null"
+	end
+
+	freeze
+end

data/lib/literal/object.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Literal::Object
+	extend Literal::Properties
+end

data/lib/literal/properties/data_schema.rb

@@ -0,0 +1,9 @@
+# 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"
+	end
+end

data/lib/literal/properties/schema.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# @api private
+class Literal::Properties::Schema
+	include Enumerable
+
+	def initialize(properties_index: {}, sorted_properties: [])
+		@properties_index = properties_index
+		@sorted_properties = sorted_properties
+		@mutex = Mutex.new
+	end
+
+	attr_reader :properties_index
+
+	def [](key)
+		@properties_index[key]
+	end
+
+	def <<(value)
+		@mutex.synchronize do
+			@properties_index[value.name] = value
+			@sorted_properties = @properties_index.values.sort!
+		end
+
+		self
+	end
+
+	def dup
+		self.class.new(
+			properties_index: @properties_index.dup,
+			sorted_properties: @sorted_properties.dup,
+		)
+	end
+
+	def each(&)
+		@sorted_properties.each(&)
+	end
+
+	def size
+		@sorted_properties.size
+	end
+
+	def generate_initializer(buffer = +"")
+		buffer << "def initialize(#{generate_initializer_params})\n"
+		generate_initializer_body(buffer)
+		buffer << "end\n"
+	end
+
+	def generate_to_h(buffer = +"")
+		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"
+			i += 1
+		end
+
+		buffer << "}\n" << "end\n"
+	end
+
+	private
+
+	def generate_initializer_params(buffer = +"")
+		sorted_properties = @sorted_properties
+		i, n = 0, sorted_properties.size
+		while i < n
+			property = sorted_properties[i]
+
+			case property.kind
+			when :*
+				buffer << "*" << property.escaped_name
+			when :**
+				buffer << "**" << property.escaped_name
+			when :&
+				buffer << "&" << property.escaped_name
+			when :positional
+				if property.default?
+					buffer << property.escaped_name << " = Literal::Null"
+				elsif property.type === nil # optional
+					buffer << property.escaped_name << " = nil"
+				else # required
+					buffer << property.escaped_name
+				end
+			else # keyword
+				if property.default?
+					buffer << property.name.name << ": Literal::Null"
+				elsif property.type === nil
+					buffer << property.name.name << ": nil" # optional
+				else # required
+					buffer << property.name.name << ":"
+				end
+			end
+
+			i += 1
+			buffer << ", " if i < n
+		end
+
+		buffer
+	end
+
+	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)\n"
+	end
+
+	def generate_initializer_handle_properties(properties, buffer = +"")
+		i, n = 0, properties.size
+		while i < n
+			properties[i].generate_initializer_handle_property(buffer)
+			i += 1
+		end
+
+		buffer
+	end
+end