types 0.1.3 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9009b2973c8d9b30fbc68da3eb4088ef28672339e593e63ed92f7f1685daf35
+  data.tar.gz: 45cbaae7e30b4603f59e7b95e8d85768edd8c8ded3df216c2c7087fdae839216
+SHA512:
+  metadata.gz: 1cbda8d764a40a9adb42358620e21a5091dd98dee66904d14e170a96f58fdfc744ad4c613beccb5ec0f52ec17ca2b61261f4a58c664e7eb5bbe41b7788f95f88
+  data.tar.gz: 34341cc300faea4cfb3053388d928d84b32432e128c17ba3c7641ea757d65fbaab706683352731e6b13c67620e0e7f9d32bc84a9957f390346e69b70fc9defc9

data/agent.md

@@ -0,0 +1,47 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Usage Guide](.context/agent-context/usage.md)
+
+`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` ...
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.

data/context/usage.md

@@ -0,0 +1,195 @@
+# Usage
+
+The Types gem provides abstract types for the Ruby programming language that can be used for documentation and evaluation purposes. It offers a simple and Ruby-compatible approach to type signatures, designed to work seamlessly with documentation tools and argument parsing.
+
+## Overview
+
+This gem provides a simple and Ruby-compatible approach to type information. It offers:
+
+- Simple type signature parsing.
+- String-to-value coercion.
+- Documentation integration.
+- RBS compatibility.
+
+The types are designed to be a subset of Ruby's type system, making them easy to understand and use while remaining powerful enough for most use cases.
+
+## How to Use Types
+
+Types can be used directly as modules or classes:
+
+```ruby
+# Simple types
+Types::String.parse("hello")     # => "hello"
+Types::Integer.parse("42")       # => 42
+Types::Float.parse("3.14")       # => 3.14
+Types::Boolean.parse("true")     # => true
+Types::Symbol.parse("hello")     # => :hello
+```
+
+### Composite Types
+
+For more complex types, you can create composite types:
+
+```ruby
+# Array with specific item type
+array_type = Types::Array(Types::Integer)
+array_type.parse(["1", "2", "3"])  # => [1, 2, 3]
+
+# Hash with key and value types
+hash_type = Types::Hash(Types::String, Types::Integer)
+hash_type.parse("a:1,b:2")        # => {"a" => 1, "b" => 2}
+
+# Tuple types
+tuple_type = Types::Tuple(Types::String, Types::Integer)
+tuple_type.parse("hello,42")      # => ["hello", 42]
+```
+
+### Union Types
+
+You can create union types using the `|` operator:
+
+```ruby
+# String or Integer
+string_or_int = Types::String | Types::Integer
+string_or_int.parse("hello")      # => "hello"
+string_or_int.parse("42")         # => 42
+```
+
+## How to Parse Types
+
+The main way to parse type signatures is using `Types.parse`:
+
+```ruby
+# Simple types
+Types.parse("String")                    # => Types::String
+Types.parse("Integer")                   # => Types::Integer
+Types.parse("Float")                     # => Types::Float
+
+# Composite types
+Types.parse("Array(String)")             # => Types::Array(Types::String)
+Types.parse("Hash(String, Integer)")     # => Types::Hash(Types::String, Types::Integer)
+Types.parse("Tuple(String, Integer)")    # => Types::Tuple(Types::String, Types::Integer)
+
+# Union types
+Types.parse("String|Integer")            # => Types::Any([Types::String, Types::Integer])
+```
+
+### Type Signature Format
+
+The gem supports a subset of Ruby expressions for type signatures:
+
+- Simple types: `String`, `Integer`, `Float`, `Boolean`, `Symbol`, `Nil`
+- Composite types: `Array(Type)`, `Hash(KeyType, ValueType)`, `Tuple(Type1, Type2)`
+- Union types: `Type1|Type2`
+- Lambda types: `Lambda(ArgType, returns: ReturnType)`
+
+### Validation
+
+Type signatures are validated against a regex pattern:
+
+```ruby
+Types::VALID_SIGNATURE = /\A[a-zA-Z\(\):,_|\s]+\z/
+```
+
+Invalid signatures will raise an `ArgumentError`:
+
+```ruby
+Types.parse("Invalid@Type")  # => ArgumentError: Invalid type signature: "Invalid@Type"!
+```
+
+## How to Use Types to Parse Strings into Values
+
+Each type provides a `parse` method that can convert strings to typed values:
+
+```ruby
+# Integer parsing
+Types::Integer.parse("42")        # => 42
+Types::Integer.parse("0")         # => 0
+Types::Integer.parse("-123")      # => -123
+
+# String parsing (converts any input to string)
+Types::String.parse(42)           # => "42"
+Types::String.parse("hello")      # => "hello"
+
+# Float parsing
+Types::Float.parse("3.14")        # => 3.14
+Types::Float.parse("0.0")         # => 0.0
+
+# Boolean parsing
+Types::Boolean.parse("true")      # => true
+Types::Boolean.parse("false")     # => false
+Types::Boolean.parse("1")         # => true
+Types::Boolean.parse("0")         # => false
+```
+
+### Array Parsing
+
+Arrays can parse both string representations and actual arrays:
+
+```ruby
+array_type = Types::Array(Types::Integer)
+
+# Parse string representation
+array_type.parse("1,2,3")         # => [1, 2, 3]
+array_type.parse("'a','b','c'")   # => ["a", "b", "c"]
+
+# Parse actual array
+array_type.parse(["1", "2", "3"]) # => [1, 2, 3]
+```
+
+### Hash Parsing
+
+Hashes can parse string representations:
+
+```ruby
+hash_type = Types::Hash(Types::String, Types::Integer)
+
+# Parse string representation
+hash_type.parse("a:1,b:2,c:3")    # => {"a" => 1, "b" => 2, "c" => 3}
+```
+
+### Error Handling
+
+Parsing methods will raise `ArgumentError` for invalid inputs:
+
+```ruby
+Types::Integer.parse("not_a_number")  # => ArgumentError
+Types::Array(Types::Integer).parse("invalid")  # => ArgumentError
+```
+
+### Practical Example: Command Line Arguments
+
+This is particularly useful for parsing command line arguments:
+
+```ruby
+def parse_arguments(arguments)
+  config = {
+    port: Types::Integer.parse(arguments[:port] || "8080"),
+    host: Types::String.parse(arguments[:host] || "localhost"),
+    debug: Types::Boolean.parse(arguments[:debug] || "false"),
+    tags: Types::Array(Types::String).parse(arguments[:tags] || "")
+  }
+  
+  config
+end
+
+# Usage
+parse_arguments(port: "3000", tags: "api,web,admin")
+# => {port: 3000, host: "localhost", debug: false, tags: ["api", "web", "admin"]}
+```
+
+### Integration with Documentation
+
+The types work seamlessly with documentation tools that use `@parameter` and `@returns` comments:
+
+```ruby
+# @parameter port [Integer] The port number to bind to
+# @parameter host [String] The host address to bind to
+# @parameter tags [Array(String)] List of tags to apply
+# @returns [Hash] Configuration hash
+def create_server(port, host, tags)
+  # Implementation here
+end
+```
+
+This provides a clean, consistent way to handle type information throughout your Ruby applications.

data/lib/types/any.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+module Types
+	# Represents a union of multiple types. The first type to match the input is used.
+	#
+	# ```ruby
+	# type = Types::Any(Types::String, Types::Integer)
+	# ```
+	class Any
+		# Initialize the instance with an array of types.
+		# @parameter types [Array] The array of types.
+		def initialize(types)
+			@types = types
+		end
+
+		# @returns [Any] a new {Any} with the other type appended.
+		# @parameter other [Type] The type instance to append.
+		def | other
+			self.class.new([*@types, other])
+		end
+
+		# @returns [Boolean] true if any of the listed types is composite.
+		def composite?
+			@types.any? {|type| type.composite?}
+		end
+
+		# Parses the input using the listed types in order, returning the first one that succeeds.
+		# @parameter input [String] the input to parse.
+		# @returns [Object] the parsed value.
+		# @raises [ArgumentError] if no type can parse the input.
+		def parse(input)
+			@types.each do |type|
+				return type.parse(input)
+			rescue => error
+				last_error = error
+			end
+			
+			if last_error
+				raise last_error
+			else
+				raise ArgumentError, "Unable to parse input #{input.inspect}!"
+			end
+		end
+		
+		# Accepts any value as a class type.
+		def self.parse(value)
+			value
+		end
+		
+		# @returns [String] a readable string representation of the listed types.
+		def to_s
+			if @types.empty?
+				"Any()"
+			else
+				"#{@types.join(' | ')}"
+			end
+		end
+		
+		# @returns [String] the RBS type string, e.g. `String | Integer`.
+		def to_rbs
+			@types.map(&:to_rbs).join(" | ")
+		end
+	end
+	
+	# Constructs an {Any} type from the given types.
+	# @parameter types [Array(Type)] The types to include in the union.
+	# @returns [Any] a new {Any} type.
+	def self.Any(*types)
+		Any.new(types)
+	end
+end

data/lib/types/array.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+require_relative "generic"
+
+module Types
+	# Represents an array type with a specific item type.
+	#
+	# ```ruby
+	# type = Types::Array(Types::Integer)
+	# type.parse(["1", "2"]) # => [1, 2]
+	# ```
+	class Array
+		include Generic
+		
+		# @parameter item_type [Type] The type of the array elements.
+		def initialize(item_type)
+			@item_type = item_type
+		end
+		
+		# @returns [Boolean] true if this is a composite type.
+		def composite?
+			true
+		end
+		
+		# Maps the given values using the item type's parse method.
+		# @parameter values [Array] The values to map.
+		# @returns [Array] The mapped array.
+		def map(values)
+			values.map{|value| @item_type.parse(value)}
+		end
+		
+		# Parses the input as an array with the specified item type.
+		# @parameter input [Object] The value to parse.
+		# @returns [Array] The parsed array.
+		# @raises [ArgumentError] if the input cannot be converted to an array.
+		def parse(input)
+			case input
+			when ::String
+				return parse_values(parse_string(input))
+			when ::Array
+				return parse_values(input)
+			else
+				raise ArgumentError, "Cannot coerce #{input.inspect} into Array!"
+			end
+		end
+		
+		# @returns [String] the string representation of the array type.
+		def to_s
+			"Array(#{@item_type})"
+		end
+		
+		# @returns [String] the RBS type string, e.g. `Array[String]`.
+		def to_rbs
+			"Array[#{@item_type.to_rbs}]"
+		end
+		
+		private
+		
+		def parse_string(input)
+			::JSON.parse("[#{input}]")
+		end
+		
+		def parse_values(input)
+			input.map{|value, index| @item_type.parse(value)}
+		end
+	end
+	
+	# Constructs an {Array} type from the given item type.
+	# @parameter item_type [Type] The type of the array elements.
+	# @returns [Array] a new {Array} type.
+	def self.Array(item_type = Any)
+		Array.new(item_type)
+	end
+end

data/lib/types/block.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+require_relative "method"
+
+module Types
+	# Represents a block (Proc) type with argument and return types.
+	#
+	# ```ruby
+	# type = Types::Block(Types::String, Types::Integer, returns: Types::String)
+	# type.to_s # => "Block(String, Integer, returns: String)"
+	# ```
+	class Block
+		include Generic
+		
+		# @parameter argument_types [Array(Type)] The types of the block arguments.
+		# @parameter return_type [Type | Nil] The return type of the block.
+		def initialize(argument_types, return_type)
+			@argument_types = argument_types
+			@return_type = return_type
+		end
+		
+		# @returns [Array(Type)] The types of the block arguments.
+		attr :argument_types
+		
+		# @returns [Type | Nil] The return type of the block.
+		attr :return_type
+		
+		# @returns [Boolean] true if this is a composite type.
+		def composite?
+			true
+		end
+		
+		# @returns [String] the string representation of the block type.
+		def to_s
+			if @return_type
+				"Block(#{@argument_types.join(', ')}, returns: #{@return_type})"
+			else
+				"Block(#{@argument_types.join(', ')})"
+			end
+		end
+		
+		# @returns [String] the RBS type string, e.g. `Proc[(String, Integer) -> String]`.
+		def to_rbs
+			argument_types = @argument_types.map(&:to_rbs).join(", ")
+			return_type = @return_type ? @return_type.to_rbs : "void"
+			
+			return "Proc[(#{argument_types}) -> #{return_type}]"
+		end
+	end
+	
+	# Constructs a {Block} type from the given argument and return types.
+	# @parameter argument_types [Array(Type)] The types of the block arguments.
+	# @parameter returns [Type | Nil] The return type of the block.
+	# @returns [Block] a new {Block} type.
+	def self.Block(*argument_types, returns: nil)
+		Block.new(argument_types, returns)
+	end
+end

data/lib/types/boolean.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+require_relative "generic"
+
+module Types
+	# Represents a boolean type.
+	#
+	# ```ruby
+	# type = Types::Boolean
+	# type.parse("true") # => true
+	# type.parse("no")   # => false
+	# ```
+	module Boolean
+		extend Generic
+		
+		# Parses the input as a boolean.
+		# @parameter input [Object] The value to parse.
+		# @returns [Boolean] The parsed boolean value.
+		# @raises [ArgumentError] if the input cannot be converted to a boolean.
+		def self.parse(input)
+			if input =~ /t(rue)?|y(es)?/i
+				return true
+			elsif input =~ /f(alse)?|n(o)?/i
+				return false
+			else
+				raise ArgumentError, "Cannot coerce #{input.inspect} into Boolean!"
+			end
+		end
+
+		# @returns [String] the RBS type string, e.g. `bool`.
+		def self.to_rbs
+			"bool"
+		end
+	end
+end

data/lib/types/class.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+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
+		
+		# 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)
+			
+			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)
+			
+			if !klass.is_a?(::Class)
+				raise ArgumentError, "Class #{klass} is not a Class!"
+			end
+			
+			return klass
+		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
+end

data/lib/types/decimal.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+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)
+			else
+				BigDecimal(input)
+			end
+		end
+	end
+end

data/lib/types/float.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+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
+	end
+end

data/lib/types/generic.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+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
+		
+		# @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
+		end
+	end
+end