invariable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c53305cea17a18d1408e1a877638284b336815349579758e185c01a9a5cc344
+  data.tar.gz: aeb9efc0033747f03a137d39c118e5d961e6cca2c805b4736043edf37b7ae5ad
+SHA512:
+  metadata.gz: 437de015755448224c646e7e4a7cd07063658e75181442a437018869d40ee845eabd9f89823b7d6cefdcb3f0483193f0437ff19d1760184a76385e5089826fc2
+  data.tar.gz: a4a18c103fcfa25451c7be911640f870e236f782385283099829580fc3373b667c9a1c2e21fbcfcbd03d4ce3319c7c3b81520fa14abc0a3c38a96d5c05bc0cde

data/.gitignore

@@ -0,0 +1,6 @@
+tmp/
+pkg/
+local/
+doc/
+.yardoc/
+gems.locked

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--title 'tcp-client Documentation'
+--charset utf-8
+--markup markdown
+lib/**/*.rb - LICENSE
+

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2017-2021, Mike Blumtritt. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,65 @@
+# Invariable
+
+An Invariable bundles a number of read-only attributes.
+It can be used like a Hash as well as an Array. It supports subclassing and pattern matching.
+
+An Invariable can be created explicitly as a Class like a Struct. Or existing classes can easily be extended to an Invariable.
+
+- Gem: [rubygems.org](https://rubygems.org/gems/invariable)
+- Source: [github.com](https://github.com/mblumtritt/invariable)
+- Help: [rubydoc.info](https://rubydoc.info/github/mblumtritt/invariable/main/index)
+
+## Sample
+
+```ruby
+require 'invariable'
+
+class Person
+  include Invariable
+  attributes :name, :last_name
+  attribute address: Invariable.new(:city, :zip, :street)
+
+  def full_name
+    "#{name} #{last_name}"
+  end
+end
+...
+john = Person.new(name: 'John', last_name: 'Doe')
+john.full_name #=> "John Doe"
+john.address.city #=> nil
+john = john.update(
+  address: { street: '123 Main St', city: 'Anytown', zip: '45678' }
+)
+john.dig(:address, :city) #=> "Anytown"
+
+```
+
+For more samples see [the samples dir](https://github.com/mblumtritt/invariable/tree/main/samples)
+
+## Installation
+
+Use [Bundler](http://gembundler.com/) to use TCPClient in your own project:
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'invariable'
+```
+
+and install it by running Bundler:
+
+```bash
+bundle
+```
+
+To install the gem globally use:
+
+```bash
+gem install invariable
+```
+
+After that you need only a single line of code in your project to have all tools on board:
+
+```ruby
+require 'invariable'
+```

data/gems.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec

data/invariable.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative './lib/invariable/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'invariable'
+  spec.version = Invariable::VERSION
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.author = 'Mike Blumtritt'
+  spec.summary = 'The Invariable data class for Ruby.'
+  spec.description = <<~description
+    An Invariable bundles a number of read-only attributes.
+    It can be used like a Hash as well as an Array.
+    It supports subclassing and pattern matching.
+  description
+
+  spec.homepage = 'https://github.com/mblumtritt/invariable'
+  spec.license = 'BSD-3-Clause'
+  spec.metadata.merge!(
+    'source_code_uri' => 'https://github.com/mblumtritt/invariable',
+    'bug_tracker_uri' => 'https://github.com/mblumtritt/invariable/issues',
+    'documentation_uri' => 'https://rubydoc.info/github/mblumtritt/invariable'
+  )
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'yard'
+
+  all_files = Dir.chdir(__dir__) { `git ls-files -z`.split(0.chr) }
+  spec.test_files = all_files.grep(%r{^spec/})
+  spec.files = all_files - spec.test_files
+  spec.extra_rdoc_files = %w[README.md LICENSE]
+end

data/lib/invariable/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Invariable
+  # current version number
+  VERSION = '0.1.0'
+end

data/lib/invariable.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+#
+# An Invariable bundles a number of read-only attributes.
+# It can be used like a Hash as well as an Array. It supports subclassing
+# and pattern matching.
+#
+# An Invariable can be created explicitly as a Class like a Struct. Or existing
+# classes can easily be extended to an Invariable.
+#
+# @example
+#   class Person
+#     include Invariable
+#     attributes :name, :last_name
+#     attribute address: Invariable.new(:city, :zip, :street)
+#
+#     def full_name
+#       "#{name} #{last_name}"
+#     end
+#   end
+#   ...
+#   john = Person.new(name: 'John', last_name: 'Doe')
+#   john.full_name #=> "John Doe"
+#   john.address.city #=> nil
+#   john = john.update(
+#     address: { street: '123 Main St', city: 'Anytown', zip: '45678' }
+#   )
+#   john.dig(:address, :city) #=> "Anytown"
+#
+module Invariable
+  class << self
+    #
+    # @!attribute [r] members
+    #   @return [Array<Symbol>] all attribute names of this class
+    #
+    # @!method attributes(*names, **defaults)
+    #   Defines new attributes
+    #   @param names [Array<Symbol>] attribute names
+    #   @param defaults [Hash<Symbol,Object|Class>] attribute names with default
+    #     values
+    #   @return [Array<Symbols>] names of defined attributes
+    #
+    # @!method member?(name)
+    #   @return [Boolean] wheter the given name is a valid attribute name for
+    #     this class
+    #
+
+    #
+    # Creates a new class with the given attribute names. It also allows to
+    # specify default values which are used when an instance is created.
+    #
+    # With an optional block the class can be extended.
+    #
+    # @overload new(*names, **defaults, &block)
+    #   @example create a simple User class
+    #     User = Invariable.new(:name, :last_name)
+    #     User.members #=> [:name, :last_name]
+    #
+    #   @example create a User class with a default value
+    #     User = Invariable.new(:name, :last_name, processed: false)
+    #     User.new(name: 'John', last_name: 'Doe').to_h
+    #     #=> {:name=>"John", :last_name=>"Doe", :processed=>false}
+    #
+    #   @example create a User class with an additional method
+    #     User = Invariable.new(:name, :last_name) do
+    #       def full_name
+    #         "#{name} #{last_name}"
+    #       end
+    #     end
+    #     User.new(name: 'John', last_name: 'Doe').full_name
+    #     #=> "John Doe"
+    #
+    # @overload new(base_class, *names, **defaults, &block)
+    #   @example create a Person class derived from a User class
+    #     User = Invariable.new(:name, :last_name)
+    #     Person = Invariable.new(User, :city, :zip, :street)
+    #     Person.members #=> [:name, :last_name, :city, :zip, :street]
+    #
+    # @param names [Array<Symbol>] attribute names
+    # @param defaults [Hash<Symbol,Object|Class>] attribute names with default
+    #   values
+    # @yieldparam new_class [Class] the created class
+    #
+    # @return [Class] the created class
+    #
+    def new(*names, **defaults, &block)
+      Class.new(names.first.is_a?(Class) ? names.shift : Object) do
+        include(Invariable)
+        attributes(*names, **defaults)
+        class_eval(&block) if block
+      end
+    end
+
+    private
+
+    def included(base)
+      base.extend(InvariableClassMethods)
+    end
+  end
+
+  #
+  # Initializes a new instance with the given `attributes` Hash.
+  #
+  # @return [Invariable] itself
+  #
+  def initialize(attributes = nil)
+    super()
+    attributes ||= {}.compare_by_identity
+    @__attr__ = {}
+    self
+      .class
+      .instance_variable_get(:@__attr__)
+      .each_pair do |key, default|
+        @__attr__[key] =
+          if default.is_a?(Class)
+            default.new(attributes[key]).freeze
+          elsif attributes.key?(key)
+            attributes[key]
+          else
+            default
+          end
+      end
+  end
+
+  #
+  # Compares attributes of itself with the attributes of a given other Object.
+  #
+  # This means that the given object needs to implement the same attributes and
+  # all it's attribute values have to be equal.
+  #
+  # @return [Boolean] wheter the attribute values are equal
+  #
+  def ==(other)
+    @__attr__.each_pair do |k, v|
+      return false if !other.respond_to?(k) || (v != other.__send__(k))
+    end
+    true
+  end
+
+  #
+  # Returns the value of the given attribute or the attribute at the given
+  # index.
+  #
+  # @overload [](name)
+  #   @param name [Symbol] the name of the attribute
+  #
+  # @overload [](index)
+  #   @param index [Integer] the index of the attribute
+  #
+  # @return [Object] the attribute value
+  #
+  # @raise [NameError] if the named attribute does not exist
+  # @raise [IndexError] if the index is out of bounds
+  #
+  def [](arg)
+    return @__attr__[arg] if @__attr__.key?(arg)
+    raise(NameError, "not member - #{arg}", caller) unless Integer === arg
+    if arg >= @__attr__.size || arg < -@__attr__.size
+      raise(IndexError, "invalid offset - #{arg}")
+    end
+    @__attr__.values[arg]
+  end
+
+  # @!visibility private
+  def deconstruct_keys(...)
+    @__attr__.deconstruct_keys(...)
+  end
+
+  #
+  # Finds and returns the object in nested objects that is specified by the
+  # identifiers. The nested objects may be instances of various classes.
+  #
+  # @param identifiers [Array<Symbol,Integer>] one or more identifiers or
+  #   indices
+  #
+  # @return [Object] object found
+  # @return [nil] if nothing was found
+  #
+  def dig(*identifiers)
+    (Integer === identifiers.first ? @__attr__.values : @__attr__).dig(
+      *identifiers
+    )
+  end
+
+  #
+  # @overload each(&block)
+  #   Yields the value of each attribute in order.
+  #
+  #   @yieldparam value [Object] attribute value
+  #   @return [Invariable] itself
+  #
+  # @overload each
+  #   Creates an Enumerator about its attribute values.
+  #
+  #   @return [Enumerator]
+  #
+  def each(&block)
+    return to_enum(__method__) unless block
+    @__attr__.each_value(&block)
+    self
+  end
+
+  #
+  # @overload each_pair(&block)
+  #   Yields the name and value of each attribute in order.
+  #
+  #   @yieldparam name [Symbol] attribute name
+  #   @yieldparam value [Object] attribute value
+  #   @return [Invariable] itself
+  #
+  # @overload each
+  #   Creates an Enumerator about its attribute name/values pairs.
+  #
+  #   @return [Enumerator]
+  #
+  def each_pair(&block)
+    return to_enum(__method__) unless block
+    @__attr__.each_pair(&block)
+    self
+  end
+
+  #
+  # Compares its class and all attributes of itself with the class and
+  # attributes of a given other Object.
+  #
+  # @return [Boolean] wheter the classes and each attribute value are equal
+  #
+  # @see ==
+  #
+  def eql?(other)
+    self.class == other.class && self == other
+  end
+
+  # @!visibility private
+  def hash
+    (to_a << self.class).hash
+  end
+
+  #
+  # @return [String] description of itself as a string
+  #
+  def inspect
+    attributes = @__attr__.map { |k, v| "#{k}: #{v.inspect}" }
+    "<#{self.class}::#{__id__} #{attributes.join(', ')}>"
+  end
+  alias to_s inspect
+
+  #
+  # @return [Boolean] wheter the given name is a valid attribute name
+  #
+  def member?(name)
+    @__attr__.key?(name)
+  end
+  alias key? member?
+
+  #
+  # @attribute [r] members
+  # @return [Array<Symbol>] all attribute names
+  #
+  def members
+    @__attr__.keys
+  end
+
+  #
+  # @attribute [r] size
+  # @return [Integer] number of attributes
+  #
+  def size
+    @__attr__.size
+  end
+
+  #
+  # @return [Array<Object>] the values of all attributes
+  #
+  def to_a
+    @__attr__.values
+  end
+  alias values to_a
+
+  # @!visibility private
+  def deconstruct
+    @__attr__.values
+  end
+
+  #
+  # @overload to_h
+  #   @return [Hash<Symbol,Object>] names and values of all attributes
+  #
+  # @overload to_h(compact: true)
+  #   @return [Hash<Symbol,Object>] names and values of all attributes which
+  #     are not `nil` and which are not empty Invariable results
+  #
+  # @overload to_h(&block)
+  #   Returns a Hash containing the results of the block on each pair of the
+  #   receiver as pairs.
+  #   @yieldparam [Symbol] name the attribute name
+  #   @yieldparam [Object] value the attribute value
+  #   @yieldreturn [Array<Symbol,Object>] the pair to be stored in the result
+  #
+  #   @return [Hash<Object,Object>] pairs returned by the `block`
+  #
+  def to_h(compact: false, &block)
+    return to_compact_h if compact
+    return Hash[@__attr__.map(&block)] if block
+    @__attr__.transform_values { |v| v.is_a?(Invariable) ? v.to_h : v }
+  end
+
+  #
+  # Updates all given attributes.
+  #
+  # @return [Invariable] a new updated instance of itself
+  def update(attributes)
+    opts = {}
+    @__attr__.each_pair do |k, v|
+      opts[k] = attributes.key?(k) ? attributes[k] : v
+    end
+    self.class.new(opts)
+  end
+
+  #
+  # @return [Array<Object>] Array whose elements are the atttributes of self at
+  #   the given Integer indexes
+  def values_at(...)
+    @__attr__.values.values_at(...)
+  end
+
+  private
+
+  def to_compact_h
+    result = {}
+    @__attr__.each_pair do |key, value|
+      next if value.nil?
+      next result[key] = value unless value.is_a?(Invariable)
+      value = value.to_h(compact: true)
+      result[key] = value unless value.empty?
+    end
+    result
+  end
+
+  module InvariableClassMethods
+    # @!visibility private
+    def attributes(*names, **defaults)
+      @__attr__ = __attr__init unless defined?(@__attr__)
+      (names + defaults.keys).map do |name|
+        __attr__define(name, defaults[name])
+      end
+    end
+    alias attribute attributes
+
+    # @!visibility private
+    def members
+      @__attr__.keys
+    end
+
+    # @!visibility private
+    def member?(name)
+      @__attr__.key?(name)
+    end
+
+    private
+
+    def __attr__define(name, default)
+      unless name.respond_to?(:to_sym)
+        raise(TypeError, "invalid attribute name type - #{name}", caller(4))
+      end
+      name = name.to_sym
+      if method_defined?(name)
+        raise(NameError, "attribute already defined - #{name}", caller(4))
+      end
+      define_method(name) { @__attr__[name] }
+      @__attr__[name] = default.is_a?(Class) ? default : default.dup.freeze
+      name
+    end
+
+    def __attr__init
+      if superclass.instance_variable_defined?(:@__attr__)
+        Hash[superclass.instance_variable_get(:@__attr__)]
+      else
+        {}.compare_by_identity
+      end
+    end
+  end
+  private_constant(:InvariableClassMethods)
+end

data/rakefile.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rake/clean'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+$stdout.sync = $stderr.sync = true
+CLOBBER << 'prj' << '.yardoc' << 'doc'
+task(:default) { exec('rake --tasks') }
+RSpec::Core::RakeTask.new { |task| task.ruby_opts = %w[-w] }
+YARD::Rake::YardocTask.new { |task| task.stats_options = %w[--list-undoc] }

data/samples/http_options.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+#
+# Sample to use Invariables as complex options.
+# See the options used for Net::HTTP.start to refer the sample.
+#
+
+require_relative '../lib/invariable'
+
+#
+# HTTP Options
+# HTTPOptions#to_h is used to generate the options Hash provided to
+# Net::HTTP.start (see there).
+#
+class HTTPOptions
+  include Invariable
+
+  attributes :open_timeout,
+             :read_timeout,
+             :write_timeout,
+             :continue_timeout,
+             :keep_alive_timeout,
+             :close_on_empty_response
+
+  attribute proxy: Invariable.new(:from_env, :address, :port, :user, :pass)
+
+  attribute ssl:
+              Invariable.new(
+                :ca_file,
+                :ca_path,
+                :cert,
+                :cert_store,
+                :ciphers,
+                :extra_chain_cert,
+                :key,
+                :timeout,
+                :version,
+                :min_version,
+                :max_version,
+                :verify_callback,
+                :verify_depth,
+                :verify_mode,
+                :verify_hostname
+              )
+
+  #
+  # Superseded to add some magic and to flatten the Hash provided to eg.
+  # Net::HTTP.start.
+  #
+  def to_h
+    # the compact option allows to skip all values of nil and all empty
+    # Invariable values
+    result = super(compact: true)
+
+    # flatten the SSL options:
+    ssl = result.delete(:ssl)
+    if ssl
+      # prefix two options:
+      ssl[:ssl_timeout] = ssl.delete(:timeout) if ssl.key?(:timeout)
+      ssl[:ssl_version] = ssl.delete(:version) if ssl.key?(:version)
+      result.merge!(ssl)
+
+      # automagic :)
+      result[:use_ssl] = true
+    end
+
+    # flatten the proxy options and prefix the keys
+    proxy = result.delete(:proxy)
+    if proxy
+      result.merge!(proxy.transform_keys! { |key| "proxy_#{key}".to_sym })
+    end
+
+    result
+  end
+end
+
+puts '- create a sample'
+sample =
+  HTTPOptions.new(
+    open_timeout: 2,
+    read_timeout: 2,
+    write_timeout: 2,
+    ssl: {
+      timeout: 2,
+      min_version: :TLS1_2
+    },
+    proxy: {
+      from_env: true
+    }
+  )
+p sample.to_h

data/samples/person.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+#
+# This sample shows the different aspects of Invariable.
+#
+
+require_relative '../lib/invariable'
+
+#
+# Person is a sample class which is combined from primitives as well as an
+# anonymous Invariable class used for the address attribute.
+#
+class Person
+  include Invariable
+  attributes :name, :last_name, address: Invariable.new(:city, :zip, :street)
+
+  def full_name
+    "#{name} #{last_name}"
+  end
+
+  def to_s
+    address.to_a.unshift(full_name).compact.join(', ')
+  end
+end
+
+puts '- we can check the members of the class'
+p Person.members #=> [:name, :last_name, :address]
+p Person.member?(:last_name) #=> true
+
+puts '- create a person record'
+john = Person.new(name: 'John', last_name: 'Doe')
+puts john #=> "John Doe"
+
+puts '- we can check the members of the instance'
+p john.members #=> [:name, :last_name, :address]
+p john.member?(:last_name) #=> true
+
+puts '- the address members are nil'
+p john.address.city #=> nil
+
+puts '- converted to an compact Hash the address is skipped'
+p john.to_h(compact: true) #=> {:name=>"John", :last_name=>"Doe"}
+
+puts '- update the record with an address'
+john =
+  john.update(address: { street: '123 Main St', city: 'Anytown', zip: '45678' })
+
+puts '- the city is assigned now'
+p john.dig(:address, :city) #=> "Anytown"
+puts john #=> John Doe, Anytown, 45678, 123 Main St

data/spec/helper.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+require_relative '../lib/invariable'
+
+$stdout.sync = $stderr.sync = true
+
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+  config.warnings = true
+  config.order = :random
+end

data/spec/invariable_include_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+require_relative 'helper'
+
+RSpec.describe 'include Invariable' do
+  let(:invariable) do
+    Class.new do
+      include Invariable
+      attribute :name
+      attribute :last_name
+    end
+  end
+
+  it 'defines all attributes' do
+    expect(invariable.members).to eq %i[name last_name]
+  end
+
+  it 'initializes the attributes' do
+    instance = invariable.new(name: 'John', last_name: 'Doe')
+    expect(instance.name).to eq 'John'
+    expect(instance.last_name).to eq 'Doe'
+  end
+
+  it 'initializes only given attributes' do
+    instance = invariable.new(last_name: 'Doe')
+    expect(instance.name).to be_nil
+    expect(instance.last_name).to eq 'Doe'
+  end
+
+  it 'ignores unknown attributes' do
+    expect {
+      invariable.new(foo: 42, last_name: 'Doe', ignored: true)
+    }.not_to raise_error
+  end
+
+  context 'when defining an already defined attribute' do
+    it 'raises an exception' do
+      expect do
+        Class.new do
+          include Invariable
+          attribute :name
+          attribute :name
+        end
+      end.to raise_error(NameError, 'attribute already defined - name')
+    end
+  end
+
+  context 'when used in sub-classing' do
+    let(:invariable) { Class.new(base_class) { attributes :street, :city } }
+    let(:base_class) do
+      Class.new do
+        include Invariable
+        attributes :name, :last_name
+      end
+    end
+
+    it 'defines all attributes' do
+      expect(invariable.members).to eq %i[name last_name street city]
+    end
+
+    it 'initializes the attributes' do
+      instance =
+        invariable.new(
+          name: 'John',
+          last_name: 'Doe',
+          street: '123 Main St',
+          city: 'Anytown'
+        )
+
+      expect(instance.name).to eq 'John'
+      expect(instance.last_name).to eq 'Doe'
+      expect(instance.street).to eq '123 Main St'
+      expect(instance.city).to eq 'Anytown'
+    end
+
+    it 'initializes only given attributes' do
+      instance = invariable.new(last_name: 'Doe', city: 'Anytown')
+      expect(instance.name).to be_nil
+      expect(instance.last_name).to eq 'Doe'
+      expect(instance.street).to be_nil
+      expect(instance.city).to eq 'Anytown'
+    end
+
+    it 'ignores unknown attributes' do
+      expect {
+        invariable.new(foo: 42, city: 'Anytown', ignored: true)
+      }.not_to raise_error
+    end
+
+    context 'when defining an already defined attribute of the superclass' do
+      it 'raises an exception' do
+        expect do
+          Class.new(base_class){ attribute :name }
+        end.to raise_error(NameError, 'attribute already defined - name')
+      end
+    end
+  end
+end

data/spec/invariable_new_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+require_relative 'helper'
+
+RSpec.describe 'Invariable.new' do
+  context 'when only attribute names are given' do
+    subject(:invariable) { Invariable.new(:name, :last_name) }
+
+    it 'creates a new Class' do
+      expect(invariable).to be_a Class
+    end
+
+    it 'is inherited from Object' do
+      expect(invariable).to be < Object
+    end
+
+    it 'defines the attributes as instance methods' do
+      expect(invariable).to be_public_method_defined :name
+      expect(invariable).to be_public_method_defined :last_name
+    end
+  end
+
+  context 'when a base class and attribute names are given' do
+    subject(:invariable) { Invariable.new(foo_class, :name, :last_name) }
+    let(:foo_class) { Class.new }
+
+    it 'creates a new Class' do
+      expect(invariable).to be_a Class
+    end
+
+    it 'is inherited from the given class' do
+      expect(invariable).to be < foo_class
+    end
+
+    it 'defines the attributes as instance methods' do
+      expect(invariable).to be_public_method_defined :name
+      expect(invariable).to be_public_method_defined :last_name
+    end
+  end
+
+  context 'when a block is given' do
+    subject(:invariable) do
+      Invariable.new(:name, :last_name) do
+        def full_name
+          "#{name} #{last_name}"
+        end
+      end
+    end
+
+    it 'allows to extend the new class' do
+      expect(invariable).to be_public_method_defined :full_name
+    end
+  end
+end

data/spec/invariable_spec.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+require_relative 'helper'
+
+RSpec.describe Invariable do
+  subject(:instance) do
+    sample_class.new(
+      name: 'John',
+      last_name: 'Doe',
+      address: {
+        zip: '45678',
+        city: 'Anytown',
+        street: '123 Main St'
+      }
+    )
+  end
+
+  let(:sample_class) do
+    Class.new do
+      include Invariable
+      attributes :name, :last_name
+      attribute address: Invariable.new(:city, :zip, :street)
+
+      def full_name
+        "#{name} #{last_name}"
+      end
+    end
+  end
+
+  context 'attributes' do
+    it 'allows to read the attributes by name' do
+      expect(instance.name).to eq 'John'
+      expect(instance.last_name).to eq 'Doe'
+      expect(instance.address).to be_a Invariable
+    end
+
+    it 'provides information about its attributes' do
+      expect(instance.members).to eq %i[name last_name address]
+    end
+
+    it 'can be checked whether an attribute is defined' do
+      expect(instance.member?(:last_name)).to be true
+      expect(instance.member?(:city)).to be false
+    end
+  end
+
+  context 'Hash-like behavior' do
+    it 'provides Hash-like attribute access' do
+      expect(instance[:name]).to eq 'John'
+      expect(instance[:last_name]).to eq 'Doe'
+      expect(instance[:address][:city]).to eq 'Anytown'
+    end
+
+    context 'when the attribute name is unknown' do
+      it 'raises a NameError' do
+        expect { instance[:size_of_shoe] }.to raise_error(
+          NameError,
+          'not member - size_of_shoe'
+        )
+      end
+    end
+
+    it 'can be converted into a Hash' do
+      expect(instance.to_h).to eq(
+        name: 'John',
+        last_name: 'Doe',
+        address: {
+          zip: '45678',
+          city: 'Anytown',
+          street: '123 Main St'
+        }
+      )
+    end
+
+    it 'can be converted into a customized Hash' do
+      converted = instance.to_h { |key, value| ["my_#{key}", value] }
+      expect(converted.keys).to eq %w[my_name my_last_name my_address]
+    end
+
+    it 'allows to iterate all attribute name/value pairs' do
+      expect { |b| instance.each_pair(&b) }.to yield_successive_args(
+        [:name, 'John'],
+        [:last_name, 'Doe'],
+        [:address, instance.address]
+      )
+    end
+
+    it 'provides an Enumerable for its attributes name/value pairs' do
+      expect(instance.each_pair).to be_a(Enumerable)
+    end
+
+    it 'can be converted to a compact Hash' do
+      john = sample_class.new(name: 'John')
+      expect(john.to_h(compact: true)).to eq(name: 'John')
+    end
+  end
+
+  context 'Array-like behavior' do
+    it 'provides its attribute count' do
+      expect(instance.size).to be 3
+    end
+
+    it 'provides Array-like attribute access' do
+      expect(instance[0]).to eq 'John'
+      expect(instance[1]).to eq 'Doe'
+      expect(instance[2]).to be instance.address
+      expect(instance[-1]).to be instance.address
+    end
+
+    context 'when the access index is out of bounds' do
+      it 'raises a NameError' do
+        expect { instance[3] }.to raise_error(IndexError, 'invalid offset - 3')
+      end
+    end
+
+    it 'can be converted into an Array' do
+      expect(instance.to_a).to eq ['John', 'Doe', instance.address]
+    end
+
+    it 'allows to iterate all attribute values' do
+      expect { |b| instance.each(&b) }.to yield_successive_args(
+        'John',
+        'Doe',
+        instance.address
+      )
+    end
+
+    it 'provides an Enumerable for its attribute values' do
+      expect(instance.each).to be_a(Enumerable)
+    end
+  end
+
+  context 'comparing' do
+    it 'can be compared to other objects' do
+      other =
+        sample_class.new(
+          name: 'John',
+          last_name: 'Doe',
+          address: {
+            zip: '45678',
+            city: 'Anytown',
+            street: '123 Main St'
+          }
+        )
+      expect(instance == other).to be true
+
+      other =
+        sample_class.new(
+          name: 'John',
+          last_name: 'Doe',
+          address: {
+            zip: '45678',
+            city: 'Anytown',
+            street: '124 Main St' # difffers
+          }
+        )
+      expect(instance == other).to be false
+
+      other =
+        double(
+          :other,
+          name: 'John',
+          last_name: 'Doe',
+          address:
+            double(
+              :other_addr,
+              zip: '45678',
+              city: 'Anytown',
+              street: '123 Main St'
+            )
+        )
+      expect(instance == other).to be true
+    end
+
+    it 'can be tested for equality' do
+      other =
+        sample_class.new(
+          name: 'John',
+          last_name: 'Doe',
+          address: {
+            zip: '45678',
+            city: 'Anytown',
+            street: '123 Main St'
+          }
+        )
+      expect(instance.eql?(other)).to be true
+
+      other =
+        sample_class.new(
+          name: 'John',
+          last_name: 'Doe',
+          address: {
+            zip: '45679', # differs
+            city: 'Anytown',
+            street: '123 Main St'
+          }
+        )
+      expect(instance.eql?(other)).to be false
+
+      other = # class differs
+        double(
+          :other,
+          name: 'John',
+          last_name: 'Doe',
+          address: {
+            zip: '45678',
+            city: 'Anytown',
+            street: '123 Main St'
+          }
+        )
+      expect(instance.eql?(other)).to be false
+    end
+  end
+
+  context '#dig pattern' do
+    let(:data) { { person: instance } }
+
+    it 'can be used with attribute names' do
+      expect(data.dig(:person, :last_name)).to eq 'Doe'
+      expect(data.dig(:person, :zip)).to be_nil
+      expect(data.dig(:person, :address, :city)).to eq 'Anytown'
+    end
+
+    it 'can be used with indices' do
+      expect(data.dig(:person, 1)).to eq 'Doe'
+      expect(data.dig(:person, -1, :zip)).to eq '45678'
+    end
+  end
+
+  context 'pattern matching' do
+    it 'can be used for named pattern matching' do
+      result =
+        case instance
+        in name: 'Fred', last_name: 'Doe'
+          :fred
+        in name: 'John', last_name: 'New'
+          :not_john
+        in name: 'John', last_name: 'Doe', address: { city: 'NY' }
+          :john_from_ny
+        in name: 'John', last_name: 'Doe', address: { city: 'Anytown' }
+          :john
+        else
+          nil
+        end
+
+      expect(result).to be :john
+    end
+
+    it 'can be used for indexed pattern matching' do
+      result =
+        case instance
+        in 'Fred', 'Doe', *_
+          :fred
+        in 'John', 'New', *_
+          :not_john
+        in 'John', 'Doe', *_
+          :john
+        else
+          nil
+        end
+
+      expect(result).to be :john
+    end
+  end
+
+  it 'allows to create an updated version of itself' do
+    result =
+      instance.update(
+        name: 'Fred',
+        address: {
+          zip: '45678',
+          city: 'Anytown',
+          street: '124 Main St'
+        }
+      )
+    expect(result).to be_a sample_class
+    expect(result.name).to eq 'Fred'
+    expect(result.last_name).to eq 'Doe'
+    expect(result.address.to_h).to eq(
+      zip: '45678',
+      city: 'Anytown',
+      street: '124 Main St'
+    )
+  end
+
+  it 'can be inspected' do
+    expect(instance.inspect).to include(' name: "John", last_name: "Doe"')
+    expect(instance.inspect).to include(
+      'city: "Anytown", zip: "45678", street: "123 Main St"'
+    )
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: invariable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike Blumtritt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-12-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  An Invariable bundles a number of read-only attributes.
+  It can be used like a Hash as well as an Array.
+  It supports subclassing and pattern matching.
+email:
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- ".gitignore"
+- ".yardopts"
+- LICENSE
+- README.md
+- gems.rb
+- invariable.gemspec
+- lib/invariable.rb
+- lib/invariable/version.rb
+- rakefile.rb
+- samples/http_options.rb
+- samples/person.rb
+- spec/helper.rb
+- spec/invariable_include_spec.rb
+- spec/invariable_new_spec.rb
+- spec/invariable_spec.rb
+homepage: https://github.com/mblumtritt/invariable
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/mblumtritt/invariable
+  bug_tracker_uri: https://github.com/mblumtritt/invariable/issues
+  documentation_uri: https://rubydoc.info/github/mblumtritt/invariable
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: The Invariable data class for Ruby.
+test_files:
+- spec/helper.rb
+- spec/invariable_include_spec.rb
+- spec/invariable_new_spec.rb
+- spec/invariable_spec.rb