u-struct 1.0.0 → 2.0.0

data/README.md

@@ -1,28 +1,34 @@
 <p align="center">
   <h1 align="center">🧱 μ-struct</h1>
   <p align="center"><i>Create powered Ruby structs.</i></p>
-  <br>
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/ruby%20%3E=%202.2,%20%3C%203.2-ruby.svg?colorA=99004d&colorB=cc0066" alt="Ruby">
   <a href="https://rubygems.org/gems/u-struct">
     <img alt="Gem" src="https://img.shields.io/gem/v/u-struct.svg?style=flat-square">
   </a>
-  <a href="https://github.com/serradura/u-struct/actions/workflows/ci.yml">
-    <img alt="Build Status" src="https://github.com/serradura/u-struct/actions/workflows/ci.yml/badge.svg">
-  </a>
-  <a href="https://codeclimate.com/github/serradura/u-struct/maintainability">
-    <img alt="Maintainability" src="https://api.codeclimate.com/v1/badges/2cc0204411cc2b392b7a/maintainability">
-  </a>
-  <a href="https://codeclimate.com/github/serradura/u-struct/test_coverage">
-    <img alt="Test Coverage" src="https://api.codeclimate.com/v1/badges/2cc0204411cc2b392b7a/test_coverage">
+  <a href="https://github.com/u-gems/u-struct/actions/workflows/ci.yml">
+    <img alt="Build Status" src="https://github.com/u-gems/u-struct/actions/workflows/ci.yml/badge.svg">
   </a>
+  <br/>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-struct"><img src="https://qlty.sh/gh/u-gems/projects/u-struct/maintainability.svg" alt="Maintainability" /></a>
+  <a href="https://qlty.sh/gh/u-gems/projects/u-struct"><img src="https://qlty.sh/gh/u-gems/projects/u-struct/coverage.svg" alt="Code Coverage" /></a>
+  <br/>
+  <img src="https://img.shields.io/badge/Ruby%20%3E%3D%202.7%2C%20%3C%3D%20Head-ruby.svg?colorA=444&colorB=333" alt="Ruby">
+  <img src="https://img.shields.io/badge/Rails%20%3E%3D%206.0%2C%20%3C%3D%20Edge-rails.svg?colorA=444&colorB=333" alt="Rails">
 </p>
 
+> [!IMPORTANT]
+> **No breaking API changes — ever.** `u-struct`'s public API is frozen: every release stays backward-compatible, so code that builds on it keeps working.
+>
+> Major version bumps signal only that a Ruby or Rails version was dropped from the supported matrix — per SemVer, a dependency-floor change. Your code keeps working.
+>
+> **Maintenance mode.** Ruby 3.2+ ships a native [`Data`](https://docs.ruby-lang.org/en/3.2/Data.html) type that covers this gem's use case; `u-struct` is kept only to support existing apps and gets no new features. New code should prefer `Data`.
+
 # Table of contents: <!-- omit in toc -->
+
 - [Introduction](#introduction)
-  - [Project Motivation](#project-motivation)
+  - [Motivation](#motivation)
 - [Installation](#installation)
 - [Usage](#usage)
   - [`Micro::Struct.new`](#microstructnew)
@@ -30,25 +36,30 @@
     - [`required:` option](#required-option)
     - [Defining custom methods/behavior](#defining-custom-methodsbehavior)
   - [`Micro::Struct.with`](#microstructwith)
+  - [`Micro::Struct[]`](#microstruct)
     - [`:to_ary`](#to_ary)
     - [`:to_hash`](#to_hash)
     - [`:to_proc`](#to_proc)
     - [`:readonly`](#readonly)
     - [`:instance_copy`](#instance_copy)
     - [`:exposed_features`](#exposed_features)
-  - [`Micro::Struct.instance()` or `Micro::Struct.with(...).instance()`](#microstructinstance-or-microstructwithinstance)
+  - [`Micro::Struct.instance` or `Micro::Struct.with(...).instance`](#microstructinstance-or-microstructwithinstance)
+  - [`Micro::Struct.immutable`](#microstructimmutable)
+  - [`Micro::Struct.readonly`](#microstructreadonly)
   - [TL;DR](#tldr)
 - [FAQ](#faq)
-  - [How to overwrite the Struct `.new` method?](#how-to-overwrite-the-struct-new-method)
-  - [Can I overwrite the Struct initializer?](#can-i-overwrite-the-struct-initializer)
+  - [How to override the Struct `.new` method?](#how-to-override-the-struct-new-method)
+  - [Can I override the Struct initializer?](#can-i-override-the-struct-initializer)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
+- [Contact](#contact)
+- [Acknowledgments](#acknowledgments)
 
 ## Introduction
 
-Ruby Struct is a versatile data structure because it can behave like an Array, Hash, and ordinary object. e.g.
+Ruby `Struct` is a versatile data structure because it can behave like an `Array`, `Hash`, and ordinary object:
 
 ```ruby
 Person = Struct.new(:first_name, :last_name)
@@ -99,7 +110,7 @@ person.to_a
 # ["John", "Doe"]
 ```
 
-Because of these characteristics, structs could be excellent candidates to create different kinds of POROs (Plain Old Ruby Objects). But, it is very common to see developers avoiding its usage because of some of its behaviors, like setters or the constructor's positional arguments. The addition of keywords arguments on its constructor ([available on Ruby >= 2.5](https://www.bigbinary.com/blog/ruby-2-5-allows-creating-structs-with-keyword-arguments)) improved the experience to instantiate Struct objects. But, as it doesn't require all the arguments, some developers can still avoid its usage.
+Because of these characteristics, structs could be excellent candidates to create different kinds of POROs (Plain Old Ruby Objects). However, it is very common to see developers avoiding its usage because of some of its behaviors, like setters or the constructor's positional arguments. The addition of keywords arguments on its constructor ([available on Ruby >= 2.5](https://www.bigbinary.com/blog/ruby-2-5-allows-creating-structs-with-keyword-arguments)) improved the experience to instantiate `Struct` objects but it doesn't require all the arguments. Some developers can still feel uncomfortable with that and they might avoid its usage.
 
 Look at the example showing the Struct's `keyword_init:` option creating a constructor with optional keyword arguments:
 
@@ -118,9 +129,9 @@ Person.new(foo: 1, bar: 2)
 # ArgumentError (unknown keywords: foo, bar)
 ```
 
-### Project Motivation
+### Motivation
 
-So, given this introduction, the idea of this project is to provide a way of creating Ruby Structs with some [powerful features](#microstructwith).  And to start, let's see how the `Micro::Struct.new()` works.
+So, given this introduction, the idea of this project is to provide a way of creating Ruby Structs with some [powerful features](#microstructwith). Let's see how the `Micro::Struct.new()` works.
 
 ```ruby
 require 'u-struct'
@@ -136,7 +147,7 @@ Person.new
 
 As you can see, the struct instantiation raised an error because all of the keywords arguments are required.
 
-But, if you need one or many optional arguments, you can use the `optional:` option to define them. e.g.
+If you need one or many optional arguments, you can use the `optional:` option to define them:
 
 ```ruby
 Person = Micro::Struct.new(:first_name, optional: :last_name)
@@ -148,9 +159,7 @@ Person.new(first_name: 'Rodrigo')
 # #<struct Person first_name="Rodrigo", last_name=nil>
 ```
 
-If you want a Struct only with optional members (or attributes), as the `keyword_init:` option does.
-
-You can declare all attributes within the `optional:` option.
+If you want a `Struct` only with optional members (or attributes), as the `keyword_init:` option does, you can declare all attributes within the optional: option:
 
 ```ruby
 Person = Micro::Struct.new(optional: [:first_name, :last_name])
@@ -186,15 +195,15 @@ Or install it yourself as:
 
     $ gem install u-struct
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## Usage
 
 ### `Micro::Struct.new`
 
-Like `Struct.new`, you will use `Micro::Struct.new` to create your Struct classes.
+Like `Struct.new`, you will use `Micro::Struct.new` to create your `Struct` classes.
 
-The key difference is: Structs created from `Micro::Struct` will use keyword arguments in their constructors.
+The key difference is: the `Struct` created from `Micro::Struct` will use keyword arguments in their constructors.
 
 ```ruby
 Person = Struct.new(:name)          # Person
@@ -211,11 +220,11 @@ Person.new  # #<struct Person name=nil>
 Persona.new # ArgumentError (missing keyword: :name)
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `optional:` option
 
-But if you need optional attributes, you can use this to define them.
+If you need optional attributes, you can use this to define them.
 
 ```ruby
 Person = Micro::Struct.new(:name, optional: :age)
@@ -239,7 +248,7 @@ Person.new(name: 'John')
 # #<struct Person name="John", age=nil, nickname=nil>
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `required:` option
 
@@ -258,11 +267,11 @@ Person.new first_name: 'John', last_name: 'Doe'
 # #<struct Person first_name="John", last_name="Doe", age=nil>
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### Defining custom methods/behavior
 
-The `Micro::Struct.new` accepts a block as a regular Struct, and you can use it to define some custom behavior/methods.
+The `Micro::Struct.new` accepts a block as a regular `Struct`, and you can use it to define some custom behavior/methods.
 
 ```ruby
 Person = Micro::Struct.new(:first_name, :last_name, optional: :age) do
@@ -279,13 +288,14 @@ person.last_name  # "Serradura"
 person.name       # "Rodrigo Serradura"
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ### `Micro::Struct.with`
 
-This method can do two things: first, it can create Struct factories; second, it sets some special behavior to their structs.
+This method can do two things: first, it can create `Struct` factories; second, it sets some special behavior to their structs.
 
 These are all of the available features which you can use (pick one, many, or all of them):
+
 - [`:to_ary`](#to_ary)
 - [`:to_hash`](#to_hash)
 - [`:to_proc`](#to_proc)
@@ -293,31 +303,54 @@ These are all of the available features which you can use (pick one, many, or al
 - [`:instance_copy`](#instance_copy)
 - [`:exposed_features`](#exposed_features)
 
+Look at an example of defining a `Struct` factory that can create "immutable" structs by picking the `:readonly`, `:instance_copy` features.
+
 ```ruby
 ReadonlyStruct = Micro::Struct.with(:readonly, :instance_copy)
 
-Person = ReadonlyStruct.new(:first_name, :last_name)
+# Use the factory to create structs with the same characteristics:
 
-Person.new # ArgumentError (missing keywords: :first_name, :last_name)
+Person = ReadonlyStruct.new(:first_name, :last_name)
 
 person = Person.new(first_name: 'Rodrigo', last_name: 'Rodrigues')
 # #<struct Person first_name="Rodrigo", last_name="Rodrigues">
 
+# The `:readonly` sets all the Struct writers as private.
+
 person.last_name = ''
 # NoMethodError (private method `last_name=' called for #<struct Person ...>)
 
 person[:last_name] = ''
 # NoMethodError (private method `[]=' called for #<struct Person ...>)
 
-person.with(last_name: 'Serradura')
+# The `:instance_copy` defines a `#with` instance method,
+# which allows you to create a new instance from the current struct state.
+
+new_person = person.with(last_name: 'Serradura')
 # #<struct Person first_name="Rodrigo", last_name="Serradura">
+
+new_person == person
+# false
+
+new_person.class == person.class
+# true
+```
+
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
+
+### `Micro::Struct[]`
+
+The `[]` brackets method is as an alias of `Micro::Struct.with`. e.g.
+
+```ruby
+Micro::Struct[:readonly, :to_hash] # is the same as Micro::Struct.with(:readonly, :to_hash)
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:to_ary`
 
-Defines a `#to_ary` method which will invoke the struct `#to_a` method, so if you overwrite the `#to_a` method you will also affect it.
+Defines a `#to_ary` method which will invoke the struct `#to_a` method. If you override the `#to_a` method you will also affect it.
 
 The `#to_ary` makes Ruby know how to deconstruct an object like an array.
 
@@ -336,11 +369,11 @@ p last_name  # "Serradura"
 p first_and_last_name # ["Rodrigo", "Serradura"]
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:to_hash`
 
-Defines a `#to_hash` method which will invoke the struct `#to_h` method, so if you overwrite the `#to_a` method you will also affect it.
+Defines a `#to_hash` method which will invoke the struct `#to_h` method. If you override the `#to_h` method you will also affect it.
 
 The `#to_hash` makes Ruby know how to deconstruct an object like a hash.
 
@@ -357,7 +390,7 @@ greet(**person)
 # Hi Rodrigo Serradura!
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:to_proc`
 
@@ -378,7 +411,7 @@ Person = Micro::Struct.with(:to_proc).new(:first_name, :last_name)
 # ]
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:readonly`
 
@@ -397,7 +430,7 @@ person[:last_name] = ''
 # NoMethodError (private method `[]=' called for #<struct Person ...>)
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:instance_copy`
 
@@ -425,7 +458,7 @@ person.last_name     # => "Serradura"
 new_person.last_name # => "Doe"
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 #### `:exposed_features`
 
@@ -454,9 +487,9 @@ Person.features.options?(:to_proc, :readonly) # => true
 Person.features.options?(:to_ary, :readonly)  # => false
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
-### `Micro::Struct.instance()` or `Micro::Struct.with(...).instance()`
+### `Micro::Struct.instance` or `Micro::Struct.with(...).instance`
 
 Creates a struct instance from a given hash. This could be useful to create constants or a singleton value.
 
@@ -498,18 +531,80 @@ person3.name # => "Rodrigo Serradura"
 person4.name # => "Rodrigo Serradura"
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
+
+### `Micro::Struct.immutable`
+
+This method is as a shortcut to `Micro::Struct.with(:readonly, :instance_copy)`.
+As it is quite common to see the usage of these two features, I decided to create this method to improve the DX.
+
+Additional info:
+
+1. It accepts the `with:` option, which can be used to define additional features.
+2. The `.instance` method can be called after its usage.
+
+Usage examples:
+
+```ruby
+Micro::Struct.immutable.new(:name)
+
+Micro::Struct.immutable.new(:name) do
+  def hi(other_name)
+    "Hi, #{other_name}! My name is #{name}"
+  end
+end
+
+Micro::Struct.immutable(with: :to_hash).new(:name)
+
+Micro::Struct.immutable(with: [:to_hash, :to_proc]).new(:name)
+
+Micro::Struct.immutable.instance(name: 'Rodrigo')
+
+Micro::Struct.immutable(with: [:to_hash]).instance(name: 'Serradura')
+```
+
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
+
+### `Micro::Struct.readonly`
+
+This method is as a shortcut to `Micro::Struct.with(:readonly)`.
+
+Additional info:
+
+1. It accepts the `with:` option, which can be used to define additional features.
+2. The `.instance` method can be called after its usage.
+
+Usage examples:
+
+```ruby
+Micro::Struct.readonly.new(:name)
+
+Micro::Struct.readonly.new(:name) do
+  def hi(other_name)
+    "Hi, #{other_name}! My name is #{name}"
+  end
+end
+
+Micro::Struct.readonly(with: :to_hash).new(:name)
+
+Micro::Struct.readonly(with: [:to_hash, :to_proc]).new(:name)
+
+Micro::Struct.readonly.instance(name: 'Rodrigo')
+
+Micro::Struct.readonly(with: [:to_hash]).instance(name: 'Serradura')
+```
+
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ### TL;DR
 
-Like in a regular Struct, you can define one or many attributes.
-But all of them will be required by default.
+Like in a regular `Struct`, you can define one or many attributes but all of them will be required by default.
 
 ```ruby
 Micro::Struct.new(:first_name, :last_name, ...)
 ```
 
-Use the `optional:` arg if you want some optional attributes.
+Use the `optional:` argument if you want some optional attributes.
 
 ```ruby
 Micro::Struct.new(:first_name, :last_name, optional: :gender)
@@ -519,7 +614,7 @@ Micro::Struct.new(:first_name, :last_name, optional: :gender)
 Micro::Struct.new(optional: [:first_name, :last_name])
 ```
 
-Use the `required:` arg to define required attributes.
+Use the `required:` argument to define required attributes.
 
 ```ruby
 Micro::Struct.new(
@@ -572,45 +667,50 @@ Micro::Struct.with(*features).new(...) {}
 
 Use `Micro::Struct.instance()` or `Micro::Struct.with(...).instance()` to create a struct instance from a given hash.
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## FAQ
 
-### How to overwrite the Struct `.new` method?
+### How to override the Struct `.new` method?
 
-The `.new` is an alias for the `.__new__` method, so you can use `.__new__` when overwriting it.
+The `.new` is an alias for the `.__new__` method, so you can use `.__new__` when overriding it.
 
 ```ruby
 module RGB
-  Number = ::Struct.new(:value) { def to_s; '%02x' % value; end }
+  Number = ->(value) do
+    return value if value.is_a?(::Integer) && value >= 0 && value <= 255
 
-  Color = Micro::Struct.new(:red, :green, :blue) do
-    def to_hex
-      "##{red}#{green}#{blue}"
-    end
+    raise TypeError, "#{value} must be an Integer(>= 0 and <= 255)"
   end
 
-  module Color
+  Color = Micro::Struct.new(:red, :green, :blue) do
     def self.new(r, g, b)
       __new__(
-        red: Number.new(r),
-        green: Number.new(g),
-        blue: Number.new(b),
+        red: Number[r],
+        green: Number[g],
+        blue: Number[b],
       )
     end
+
+    def to_hex
+      "##{red}#{green}#{blue}"
+    end
   end
 end
 
-rgb_color = RGB::Color.new(1,5,255)
+rgb_color = RGB::Color.new(1, 5, 255)
 # => #<struct RGB::Color::Struct red=#<struct RGB::Number value=1>, green=#<struct RGB::Number value=5>, blue=#<struct RGB::Number value=255>>
 
 rgb_color.to_hex
 # => "#0105ff"
+
+RGB::Color.new(-1, 5, 255)
+# => TypeError: -1 must be an Integer(>= 0 and <= 255)
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
-### Can I overwrite the Struct initializer?
+### Can I override the Struct initializer?
 
 Yes, you can, but the initializer must handle the arguments as positional ones.
 
@@ -646,30 +746,45 @@ RGBColor.new(red: 1, green: -1, blue: 255)
 # TypeError (-1 must be an Integer(>= 0 and <= 255))
 ```
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+Additional tools:
+
+- Sorbet (type checker): `bundle exec srb tc` (requires `Ruby >= 2.7`).
+- Rubocop (linter and code formatter): `bundle rubocop` (requires `Ruby >= 2.5`).
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/serradura/u-struct. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/serradura/u-struct/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/u-gems/u-struct. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/u-gems/u-struct/blob/main/CODE_OF_CONDUCT.md).
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
 
 ## Code of Conduct
 
-Everyone interacting in the Micro::Struct project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/serradura/u-struct/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `Micro::Struct` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/u-gems/u-struct/blob/main/CODE_OF_CONDUCT.md).
+
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
+
+## Contact
+
+Rodrigo Serradura - [Twitter](https://twitter.com/serradura) | [LinkedIn](https://www.linkedin.com/in/rodrigo-serradura/).
+
+<p align="right">(<a href="#table-of-contents-">⬆️ &nbsp;back to top</a>)</p>
+
+## Acknowledgments
 
-[⬆️ &nbsp;Back to Top](#table-of-contents-)
+- [`@vitoravelino`](https://github.com/vitoravelino) thanks for talking about some gem's ideas and reviewing the documentation.

data/Rakefile

@@ -1,12 +1,42 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+require 'appraisal/task'
+
+Appraisal::Task.new
+
+desc 'Run the full test suite against every supported Rails version'
+task :matrix do
+  appraisals =
+    if RUBY_VERSION < '3.1'
+      %w[rails-6-0 rails-6-1 rails-7-0 rails-7-1]
+    elsif RUBY_VERSION < '3.2'
+      %w[rails-7-0 rails-7-1 rails-7-2]
+    elsif RUBY_VERSION < '3.3'
+      %w[rails-7-0 rails-7-1 rails-7-2 rails-8-0]
+    elsif RUBY_VERSION < '3.4'
+      %w[rails-7-0 rails-7-1 rails-7-2 rails-8-0 rails-8-1 rails-edge]
+    elsif RUBY_VERSION < '4.0'
+      %w[rails-7-2 rails-8-0 rails-8-1 rails-edge]
+    else
+      %w[rails-8-1 rails-edge]
+    end
+
+  # Baseline (no activemodel)
+  sh 'bundle exec rake test'
+
+  # Each activemodel appraisal
+  appraisals.each do |appraisal|
+    sh "bundle exec appraisal #{appraisal} rake test"
+  end
 end
 
 task default: :test

data/bin/console

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
-require "micro/struct"
+require 'bundler/setup'
+require 'micro/struct'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,5 +11,5 @@ require "micro/struct"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/bin/matrix

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+ruby -v
+
+rm -f Gemfile.lock
+
+bundle install
+
+bundle exec appraisal update
+
+bundle exec rake matrix
+
+ruby -v

data/bin/setup

@@ -3,6 +3,10 @@ set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
+rm -f Gemfile.lock
+
 bundle install
 
+bundle exec appraisal install
+
 # Do any other automated setup that you need to do here

data/bin/tapioca

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('tapioca', 'tapioca')

data/examples/rgb/number.rb

@@ -11,7 +11,7 @@ module RGB
     end
 
     def to_s
-      @to_s ||= '%02x' % value
+      @to_s ||= format('%02x', value)
     end
 
     def inspect