cattri 0.1.0

data/README.md

@@ -0,0 +1,153 @@
+# Cattri
+
+Cattri is a lightweight Ruby DSL for defining class-level and instance-level attributes with optional defaults, coercion, and reset capabilities.
+
+It provides fine-grained control over attribute behavior, including:
+
+- Class-level attributes (`cattr`) with optional instance accessors
+- Instance-level attributes (`iattr`) with coercion and lazy defaults
+- Optional locking of class attribute definitions to prevent subclass redefinition
+- Simple, expressive DSL for reusable metaprogramming
+
+## ✨ Features
+
+- ✅ Define readable/writable class and instance attributes
+- 🧱 Static or callable default values
+- 🌀 Optional coercion logic via blocks
+- 🧼 Reset attributes to default
+- 🔒 Lock class attribute definitions in base class
+- 🔍 Introspect attribute definitions and values (optional)
+
+## 📦 Installation
+
+```bash
+bundle add cattri
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "cattri"
+```
+
+## 🚀 Usage
+
+### Class & Instance Attributes
+
+```ruby
+class MyConfig
+  include Cattri
+
+  cattr :enabled, default: true
+  iattr :name, default: "anonymous"
+end
+
+MyConfig.enabled # => true
+MyConfig.new.name # => "anonymous"
+```
+
+### Class Attributes
+
+```ruby
+class MyConfig
+  extend Cattri::ClassAttributes
+
+  cattr :format, default: :json
+  cattr_reader :version, default: "1.0.0"
+  cattr :enabled, default: true do |value|
+    !!value
+  end
+end
+
+MyConfig.format           # => :json
+MyConfig.format :xml
+MyConfig.format           # => :xml
+
+MyConfig.version          # => "1.0.0"
+```
+
+#### Instance Access
+
+```ruby
+MyConfig.new.format       # => :xml
+```
+
+#### Locking Class Attribute Definitions
+
+```ruby
+MyConfig.lock_cattrs!
+```
+
+This prevents redefinition of existing class attributes in subclasses.
+
+### Instance Attributes
+
+```ruby
+class Request
+  include Cattri::InstanceAttributes
+
+  iattr :headers, default: -> { {} }
+  iattr_writer :raw_body do |val|
+    val.to_s.strip
+  end
+end
+
+req = Request.new
+req.headers["Content-Type"] = "application/json"
+req.raw_body = "  data  "
+```
+
+### Resetting Attributes
+
+```ruby
+MyConfig.reset_cattrs!        # Reset all class attributes
+MyConfig.reset_cattr!(:format)
+
+req.reset_iattr!(:headers)    # Reset a specific instance attribute
+```
+
+## 🔍 Introspection
+
+If you include the `Cattri::Introspection` module:
+
+```ruby
+class MyConfig
+  include Cattri
+  include Cattri::Introspection
+
+  cattr :items, default: []
+end
+
+MyConfig.items << :a
+MyConfig.snapshot_class_attributes # => { items: [:a] }
+```
+
+## 📚 API Overview
+
+| Method                           | Description                                |
+|----------------------------------|--------------------------------------------|
+| `cattr`, `cattr_reader`          | Define class-level attributes              |
+| `iattr`, `iattr_reader`, `iattr_writer` | Define instance-level attributes       |
+| `reset_cattr!`, `reset_iattr!`   | Reset specific attributes                 |
+| `cattr_definition(:name)`        | Get attribute metadata                    |
+| `lock_cattrs!`                   | Prevent redefinition in subclasses        |
+
+## 🧪 Testing
+
+```bash
+bundle exec rspec
+```
+
+## 💡 Why Cattri?
+
+Cattri provides a cleaner alternative to `class_attribute`, `attr_accessor`, and configuration gems like `Dry::Configurable` or `ActiveSupport::Configurable`, without monkey-patching or runtime surprises.
+
+## 📝 License
+
+MIT © [Nathan Lucas](https://github.com/bnlucas). See [LICENSE](LICENSE).
+
+---
+
+## 🙏 Credits
+
+Created with ❤️ by [Nathan Lucas](https://github.com/bnlucas)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/cattri.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/cattri/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "cattri"
+  spec.version       = Cattri::VERSION
+  spec.authors       = ["Nathan Lucas"]
+  spec.email         = ["bnlucas@outlook.com"]
+
+  spec.summary       = "Simple class and instance attribute DSL for Ruby."
+  spec.description   = "Cattri provides a clean DSL for defining class-level and instance-level attributes " \
+                       "with optional defaults, coercion, accessors, and inheritance support."
+  spec.homepage      = "https://github.com/bnlucas/cattri"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"]     = spec.homepage
+  spec.metadata["source_code_uri"]  = "https://github.com/bnlucas/cattri"
+  spec.metadata["changelog_uri"]    = "https://github.com/bnlucas/cattri/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  # Runtime dependencies
+  # spec.add_dependency "gem"
+
+  # Development dependencies
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "simplecov-cobertura"
+  spec.add_development_dependency "simplecov-html"
+  spec.add_development_dependency "yard"
+end

data/lib/cattri/class_attributes.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "helpers"
+
+module Cattri
+  # Provides a DSL for defining class-level attributes with support for:
+  #
+  # - Static or dynamic default values
+  # - Optional coercion via setter blocks
+  # - Optional instance-level readers
+  # - Read-only attribute enforcement
+  # - Inheritance-safe duplication
+  # - Attribute locking to prevent mutation in subclasses
+  #
+  # This module is designed for advanced metaprogramming needs such as DSL builders,
+  # configuration objects, and plugin systems that require reusable and introspectable
+  # class-level state.
+  #
+  # @example
+  #   class MyClass
+  #     extend Cattri::ClassAttributes
+  #
+  #     cattr :format, default: :json
+  #     cattr_reader :version, default: "1.0.0"
+  #     cattr :enabled, default: true do |value|
+  #       !!value
+  #     end
+  #   end
+  #
+  #   MyClass.format        # => :json
+  #   MyClass.format :xml
+  #   MyClass.format        # => :xml
+  #   MyClass.version       # => "1.0.0"
+  #
+  #   instance = MyClass.new
+  #   instance.format       # => :xml
+  module ClassAttributes
+    include Cattri::Helpers
+
+    # Default options applied to all class-level attributes.
+    DEFAULT_OPTIONS = { default: nil, readonly: false }.freeze
+
+    # Defines a class-level attribute with optional default, coercion, and reader access.
+    #
+    # @param name [Symbol] the attribute name
+    # @param options [Hash] additional attribute options
+    # @option options [Object, Proc] :default the default value or callable
+    # @option options [Boolean] :readonly whether the attribute is read-only
+    # @option options [Boolean] :instance_reader whether to define an instance-level reader
+    # @yield [*args] Optional setter block for custom coercion
+    # @raise [Cattri::Error] if attribute is already defined
+    # @return [void]
+    def class_attribute(name, **options, &block)
+      define_inheritance unless respond_to?(:__cattri_class_attributes)
+
+      name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
+      raise Cattri::Error, "Class attribute `#{name}` already defined" if class_attribute_defined?(name)
+
+      __cattri_class_attributes[name] = definition
+      define_accessor(name, definition)
+      define_instance_reader(name) if options.fetch(:instance_reader, true)
+    end
+
+    # Defines a read-only class attribute (no writer).
+    #
+    # @param name [Symbol]
+    # @param options [Hash]
+    # @return [void]
+    def class_attribute_reader(name, **options)
+      class_attribute(name, readonly: true, **options)
+    end
+
+    # Returns all defined class-level attribute names.
+    #
+    # @return [Array<Symbol>]
+    def class_attributes
+      __cattri_class_attributes.keys
+    end
+
+    # Checks whether a class-level attribute is defined.
+    #
+    # @param name [Symbol]
+    # @return [Boolean]
+    def class_attribute_defined?(name)
+      __cattri_class_attributes.key?(name.to_sym)
+    end
+
+    # Returns metadata for a given class-level attribute.
+    #
+    # @param name [Symbol]
+    # @return [Hash, nil]
+    def class_attribute_definition(name)
+      __cattri_class_attributes[name.to_sym]
+    end
+
+    # Resets all defined class attributes to their default values.
+    #
+    # @return [void]
+    def reset_class_attributes!
+      reset_attributes!(self, __cattri_class_attributes.values)
+    end
+
+    # Resets a single class attribute to its default value.
+    #
+    # @param name [Symbol]
+    # @return [void]
+    def reset_class_attribute!(name)
+      definition = __cattri_class_attributes[name]
+      return unless definition
+
+      reset_attributes!(self, [definition])
+    end
+
+    # alias lock_cattrs! lock_class_attributes!
+    # alias cattrs_locked? class_attributes_locked?
+
+    # @!method cattr(name, **options, &block)
+    #   Alias for {.class_attribute}
+    #   @see .class_attribute
+    alias cattr class_attribute
+
+    # @!method cattr_accessor(name, **options, &block)
+    #   Alias for {.class_attribute}
+    #   @see .class_attribute
+    alias cattr_accessor class_attribute
+
+    # @!method cattr_reader(name, **options)
+    #   Alias for {.class_attribute_reader}
+    #   @see .class_attribute_reader
+    alias cattr_reader class_attribute_reader
+
+    # @!method cattrs
+    #   @return [Array<Symbol>] all defined class attribute names
+    #   @see .class_attributes
+    alias cattrs class_attributes
+
+    # @!method cattr_defined?(name)
+    #   @return [Boolean] whether the given attribute has been defined
+    #   @see .class_attribute_defined?
+    alias cattr_defined? class_attribute_defined?
+
+    # @!method cattr_for(name)
+    #   @return [Hash, nil] the internal metadata hash for a defined attribute
+    #   @see .class_attribute_for
+    alias cattr_definition class_attribute_definition
+
+    # @!method reset_cattrs!
+    #   Resets all class attributes to their default values.
+    #   @see .reset_class_attributes!
+    alias reset_cattrs! reset_class_attributes!
+
+    # @!method reset_cattr!(name)
+    #   Resets a specific class attribute to its default value.
+    #   @see .reset_class_attribute!
+    alias reset_cattr! reset_class_attribute!
+
+    private
+
+    # Defines class-level inheritance behavior for declared attributes.
+    #
+    # @return [void]
+    def define_inheritance
+      unless singleton_class.method_defined?(:__cattri_class_attributes)
+        define_singleton_method(:__cattri_class_attributes) { @__cattri_class_attributes ||= {} }
+      end
+
+      define_singleton_method(:inherited) do |subclass|
+        super(subclass)
+        subclass_attributes = {}
+
+        __cattri_class_attributes.each do |name, definition|
+          apply_attribute!(subclass, subclass_attributes, name, definition)
+        end
+
+        subclass.instance_variable_set(:@__cattri_class_attributes, subclass_attributes)
+      end
+    end
+
+    # Defines the primary accessor method on the class.
+    #
+    # @param name [Symbol]
+    # @param definition [Hash]
+    # @return [void]
+    def define_accessor(name, definition)
+      ivar = definition[:ivar]
+
+      define_singleton_method(name) do |*args, **kwargs|
+        readonly = readonly_call?(args, kwargs) || definition[:readonly]
+        return apply_readonly(ivar, definition[:default]) if readonly
+
+        instance_variable_set(ivar, definition[:setter].call(*args, **kwargs))
+      end
+
+      return if definition[:readonly]
+
+      define_singleton_method("#{name}=") do |value|
+        instance_variable_set(ivar, definition[:setter].call(value))
+      end
+    end
+
+    # Defines an instance-level reader that delegates to the class-level method.
+    #
+    # @param name [Symbol]
+    # @return [void]
+    def define_instance_reader(name)
+      define_method(name) { self.class.__send__(name) }
+    end
+
+    # Applies the default value for a read-only call.
+    #
+    # @param ivar [Symbol]
+    # @param default [Proc]
+    # @return [Object]
+    def apply_readonly(ivar, default)
+      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+      value = default.call
+      instance_variable_set(ivar, value)
+    end
+
+    # Applies inherited attribute definitions to a subclass.
+    #
+    # @param subclass [Class]
+    # @param attributes [Hash]
+    # @param name [Symbol]
+    # @param definition [Hash]
+    # @return [void]
+    def apply_attribute!(subclass, attributes, name, definition)
+      value = instance_variable_get(definition[:ivar])
+      value = value.dup rescue value # rubocop:disable Style/RescueModifier
+
+      subclass.instance_variable_set(definition[:ivar], value)
+      attributes[name] = definition
+    end
+
+    # Determines if the method call should be treated as read-only access.
+    #
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
+    def readonly_call?(args, kwargs)
+      args.empty? && kwargs.empty?
+    end
+  end
+end

data/lib/cattri/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cattri
+  class Error < StandardError; end
+end

data/lib/cattri/helpers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Internal support utilities for Cattri modules.
+  #
+  # Provides shared logic for safe default handling, attribute definition, and
+  # consistent reset behavior across class-level and instance-level attributes.
+  #
+  # This module is intended for internal use only and is included by both
+  # Cattri::ClassAttributes and Cattri::InstanceAttributes.
+  module Helpers
+    # A list of immutable Ruby types that are safe to reuse directly without duplication.
+    #
+    # These types are treated as-is when used as default values.
+    #
+    # @return [Array<Class>]
+    SAFE_VALUE_TYPES = [Numeric, Symbol, TrueClass, FalseClass, NilClass].freeze
+
+    protected
+
+    # Defines an attribute structure used internally for accessors.
+    #
+    # Combines the caller's options with normalized default and setter logic,
+    # and attaches a consistent `@ivar` key for storage.
+    #
+    # @param name [Symbol, String] The attribute name
+    # @param options [Hash] The caller-provided options (e.g., `:default`, `:readonly`)
+    # @param block [Proc, nil] Optional setter block
+    # @param defaults [Hash] A set of fallback/default values to merge in
+    # @return [Array] Normalized name and attribute definition hash
+    def define_attribute(name, options, block, defaults)
+      options[:default] = normalize_default(options[:default])
+      options[:setter] = block || lambda { |*args, **kwargs|
+        return kwargs unless kwargs.empty?
+        return args.first if args.length == 1
+
+        args
+      }
+
+      name = name.to_sym
+      [name, defaults.merge(ivar: :"@#{name}", **options)]
+    end
+
+    # Wraps static default values in lambdas to ensure safety.
+    #
+    # If the value is already callable, it is returned as-is.
+    # If the value is immutable, it is wrapped directly.
+    # Otherwise, it is wrapped with `.dup` for safe reuse.
+    #
+    # @param default [Object, Proc, nil] The user-provided default value
+    # @return [Proc] A proc that returns a safe default value
+    def normalize_default(default)
+      return default if default.respond_to?(:call)
+      return -> { default } if default.frozen? || SAFE_VALUE_TYPES.any? { |type| default.is_a?(type) }
+
+      -> { default.dup }
+    end
+
+    # Resets a set of attribute definitions on a target object.
+    #
+    # Used to restore class or instance attributes to their configured default values.
+    #
+    # @param target [Object] The object or class whose instance variables will be reset
+    # @param attribute_definitions [Enumerable<Hash>] A list of attribute definition hashes
+    # @return [void]
+    def reset_attributes!(target, attribute_definitions)
+      attribute_definitions.each do |definition|
+        target.instance_variable_set(
+          definition[:ivar],
+          definition[:default].call
+        )
+      end
+    end
+  end
+end