cattri 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c63162e310f56cece90ee13f07b6edce76503e525ac899094a454248187a0b4
-  data.tar.gz: b2eca347c4603946fa1b1dc62bd5d36138c4fed87e4909e9650b62005dc89e02
+  metadata.gz: e8689b6e0fa1e741fc271fece58183191d290875fe203af5622f069aaf3c4cf7
+  data.tar.gz: 2435ba9915a003f39d2d0275c725064c0c5c885940e7de109bb852a7258dfdd6
 SHA512:
-  metadata.gz: 3c749774916b9921d089554b2e0a2c2c747205d328700f54ee41c6912a40d98656b4d861e7d86523ae3f709e612dde9115ce0357541571efe3361d1d5ef03c49
-  data.tar.gz: 3a2748150b821d01d8d36bbf44aefbc093751f3ac18f32819c6e731581173abc9423821ad259ad1089c952860e4fd4cc8b759f6312179a62c055423fcf7e4a96
+  metadata.gz: 847f1396957fa8567868273f61c1906e95001e0fd8c632de72ed3f520ec4a7edb1c91c7c1f6a02101913c392d119b24a32a4d835827dab864338ab0e6b668574
+  data.tar.gz: f7347d6cb14bb1b0501ff45799ba513388462ede2c95a47f84efb9d4a99ce7c9a6c6a8c726e605b4d475b26664c5f8861f8fc50922da4ebfbe4b139a257af131

data/.rubocop.yml

@@ -5,7 +5,11 @@ AllCops:
 
 Style/Documentation:
   Exclude:
-    - spec/castkit/**/*.rb
+    - spec/cattri/**/*.rb
+
+Style/DocumentationMethod:
+  Exclude:
+    - spec/cattri/**/*.rb
 
 Style/StringLiterals:
   Enabled: true

data/CHANGELOG.md

@@ -1,4 +1,34 @@
-## [Unreleased]
+## [0.1.1] - 2025-04-22
+
+### Added
+
+- `Cattri::Context`: new class encapsulating all class-level and instance-level attribute metadata.
+- `Cattri::Attribute`: formal representation of a defined attribute, with support for default values, coercion, and visibility.
+- `Cattri::AttributeDefiner`: internal abstraction for building attributes and assigning behavior based on visibility and type.
+- `Cattri::Visibility`: tracks current method visibility (`public`, `protected`, `private`) to ensure dynamically defined methods (e.g., via `cattr`, `iattr`) respect the active access scope during declaration.
+
+### Changed
+
+- Internal architecture now uses `Context` to manage attribute storage and duplication logic across inheritance chains.
+- Class and instance attribute definitions (`cattr`, `iattr`) now delegate to `AttributeDefiner`, improving consistency and reducing duplication.
+- Visibility handling is now centralized through `Cattri::Visibility`, which intercepts `public`, `protected`, and `private` to track and apply the current access level when defining methods.
+- Subclass inheritance now copies attribute metadata and current values using a consistent, visibility-aware strategy.
+
+### Removed
+
+- Legacy handling of attribute hashes and manual copying in `inherited` hooks.
+- Ad hoc attribute construction logic in `ClassAttributes` and `InstanceAttributes`.
+
+### Improved
+
+- Clear separation of concerns between metadata (`Attribute`), context (`Context`), and definition logic (`AttributeDefiner`).
+- More robust error messages and consistent failure behavior when defining attributes with invalid configuration.
+
+---
+
+No breaking changes – the public DSL (cattr, iattr) remains identical to v0.1.0.
+
+---
 
 ## [0.1.0] - 2025-04-17
 

data/README.md

@@ -1,153 +1,209 @@
 # Cattri
 
-Cattri is a lightweight Ruby DSL for defining class-level and instance-level attributes with optional defaults, coercion, and reset capabilities.
+A **minimal‑footprint** DSL for defining **class‑level** and **instance‑level** attributes in Ruby, with first‑class support for custom defaults, coercion, visibility tracking, and safety‑first error handling.
 
-It provides fine-grained control over attribute behavior, including:
+---
+
+## Why another attribute DSL?
 
-- 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
+| Capability | Cattri | `attr_*` / `cattr_*` (Ruby / ActiveSupport) | `dry-configurable` |
+|------------|:------:|:-------------------------------------------:|:------------------:|
+| **Single DSL for class *and* instance attributes** | ✅ | ❌ (separate APIs) | ⚠️ (config only) |
+| **Per‑subclass deep copy of attribute metadata & values** | ✅ | ❌ | ❌ |
+| **Built‑in visibility tracking (`public` / `protected` / `private`)** | ✅ | ❌ | ❌ |
+| **Lazy or static *default* values** | ✅ | ⚠️ (writer‑based) | ✅ |
+| **Optional *coercion* via custom setter block** | ✅ | ❌ | ✅ |
+| **Read‑only / write‑only flags** | ✅ | ⚠️ (reader / writer macros) | ❌ |
+| **Introspection helpers (`snapshot_*`)** | ✅ | ❌ | ⚠️ via internals |
+| **Clear, granular error hierarchy** | ✅ | ❌ | ✅ |
+| **Zero runtime dependencies** | ✅ | ⚠️ (ActiveSupport) | ✅ |
 
-## ✨ Features
+> **TL;DR** – If you need lightweight, _Rails‑agnostic_ attribute helpers that play nicely with inheritance and don’t leak state between subclasses, Cattri is for you.
 
-- ✅ 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
+## Installation
 
 ```bash
-bundle add cattri
+bundle add cattri     # Ruby ≥ 2.7
 ```
 
-Or add to your Gemfile:
+Or in your Gemfile:
 
 ```ruby
 gem "cattri"
 ```
 
-## 🚀 Usage
+---
 
-### Class & Instance Attributes
+## Quick start
 
 ```ruby
-class MyConfig
-  include Cattri
+class Config
+  include Cattri          # exposes `cattr` & `iattr`
+
+  # -- class‑level ----------------------------------
+  cattr :enabled,  default: true
+  cattr :timeout,  default: -> { 5.0 }, instance_reader: false
 
-  cattr :enabled, default: true
-  iattr :name, default: "anonymous"
+  # -- instance‑level -------------------------------
+  iattr :name,     default: "anonymous"
+  iattr :age,      default: 0 do |val|                 # coercion block
+    Integer(val)
+  end
 end
 
-MyConfig.enabled # => true
-MyConfig.new.name # => "anonymous"
+Config.enabled        # => true
+Config.enabled = false
+Config.new.age = "42" # => 42
 ```
 
-### 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
+## Defining attributes
 
-MyConfig.format           # => :json
-MyConfig.format :xml
-MyConfig.format           # => :xml
+### Class attributes (`cattr`)
 
-MyConfig.version          # => "1.0.0"
+```ruby
+cattr :log_level, default: :info,
+                  access:  :protected,     # respects current visibility by default
+                  readonly: false,
+                  instance_reader: true do |value|
+                    value.to_sym
+                  end
 ```
 
-#### Instance Access
+### Instance attributes (`iattr`)
 
 ```ruby
-MyConfig.new.format       # => :xml
+iattr :token, default: -> { SecureRandom.hex(8) },
+              reader:  true,
+              writer:  false                  # read‑only
 ```
 
-#### Locking Class Attribute Definitions
+Both forms accept:
 
-```ruby
-MyConfig.lock_cattrs!
-```
+| Option | Purpose |
+| ------ | ------- |
+| `default:` | Static value or callable (`Proc`) evaluated lazily. |
+| `access:` | Override inferred visibility (`:public`, `:protected`, `:private`). |
+| `reader:` / `writer:` | Disable reader or writer for instance attributes. |
+| `readonly:` | Shorthand for class attributes (`writer` is always present). |
+| `instance_reader:` | Expose class attribute as instance reader (default: **true**). |
+
+If you pass a block, it’s treated as a **coercion setter** and receives the incoming value.
 
-This prevents redefinition of existing class attributes in subclasses.
+---
+
+## Visibility tracking
 
-### Instance Attributes
+Cattri watches calls to `public`, `protected`, and `private` while you define methods:
 
 ```ruby
-class Request
-  include Cattri::InstanceAttributes
+class Secrets
+  include Cattri
 
-  iattr :headers, default: -> { {} }
-  iattr_writer :raw_body do |val|
-    val.to_s.strip
-  end
+  private
+  cattr :api_key
 end
 
-req = Request.new
-req.headers["Content-Type"] = "application/json"
-req.raw_body = "  data  "
+Secrets.private_methods.include?(:api_key)   # => true
 ```
 
-### Resetting Attributes
+No boilerplate—attributes inherit the visibility that was in effect at the call site.
+
+---
+
+## Safe inheritance
+
+Subclassing copies both **metadata** and **current values**, using defensive `#dup` where possible and falling back safely when objects are frozen or not duplicable:
 
 ```ruby
-MyConfig.reset_cattrs!        # Reset all class attributes
-MyConfig.reset_cattr!(:format)
+class Base
+  include Cattri
+  cattr :settings, default: {}
+end
+
+class Child < Base; end
 
-req.reset_iattr!(:headers)    # Reset a specific instance attribute
+Base.settings[:foo]  = 1
+Child.settings       # => {}  (isolated copy)
 ```
 
-## 🔍 Introspection
+---
+
+## Introspection helpers
 
-If you include the `Cattri::Introspection` module:
+Add `include Cattri::Introspection` (or `extend` for class‑only use) to snapshot live values:
 
 ```ruby
-class MyConfig
-  include Cattri
-  include Cattri::Introspection
+Config.snapshot_cattrs   # => { enabled: false, timeout: 5.0 }
+instance.snapshot_iattrs # => { name: "bob", age: 42 }
+```
 
-  cattr :items, default: []
-end
+Great for debugging or test assertions.
 
-MyConfig.items << :a
-MyConfig.snapshot_class_attributes # => { items: [:a] }
-```
+---
 
-## 📚 API Overview
+## Error handling
 
-| 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        |
+All errors inherit from `Cattri::Error`, allowing a single rescue for any gem‑specific issue.
 
-## 🧪 Testing
+| Error class | Raised when… |
+|-------------|--------------|
+| `Cattri::AttributeDefinedError` | an attribute is declared twice on the same level |
+| `Cattri::AttributeDefinitionError` | method generation (`define_method`) fails |
+| `Cattri::UnsupportedTypeError` | an internal API receives an unknown type |
+| `Cattri::AttributeError` | generic superclass for attribute‑related issues |
 
-```bash
-bundle exec rspec
+Example:
+
+```ruby
+begin
+  class Foo
+    include Cattri
+    cattr :foo
+    cattr :foo   # duplicate
+  end
+rescue Cattri::AttributeDefinedError => e
+  warn e.message   # => "Class attribute :foo has already been defined"
+rescue Cattri::AttributeError => e
+  warn e.message   # => Catch-all for any error raised within attributes
+end
 ```
 
-## 💡 Why Cattri?
+---
+
+## Comparison with standard patterns
+
+* **Core Ruby macros** (`attr_accessor`, `cattr_accessor`) are simple but global—attributes bleed into subclasses and lack defaults or coercion.
+* **ActiveSupport** extends the API but still relies on mutable class variables and offers no visibility control.
+* **Dry‑configurable** is robust yet heavyweight when you only need a handful of attributes outside a full config object.
+
+Cattri sits in the sweet spot: **micro‑sized (~200 LOC)**, dependency‑free, and purpose‑built for attribute declaration.
+
+---
+
+## Testing tips
+
+* Use `include Cattri::Introspection` in spec helper files to capture snapshots before/after mutations.
+* Rescue `Cattri::Error` in high‑level test helpers to assert failures without coupling to sub‑class names.
 
-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
+## Contributing
 
-MIT © [Nathan Lucas](https://github.com/bnlucas). See [LICENSE](LICENSE).
+1. Fork the repo
+2. `bundle install`
+3. Run the test suite with `bundle exec rake`
+4. Submit a pull request – ensure new code is covered and **rubocop** passes.
 
 ---
 
+## License
+
+This gem is released under the MIT License – see See [LICENSE](LICENSE) for details.
+
 ## 🙏 Credits
 
 Created with ❤️ by [Nathan Lucas](https://github.com/bnlucas)

data/lib/cattri/attribute.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Cattri
+  # Represents a single attribute definition in Cattri.
+  #
+  # This class encapsulates metadata and behavior for a declared attribute,
+  # including name, visibility, default value, and setter coercion logic.
+  #
+  # It is used internally by the DSL to configure how accessors are defined,
+  # memoized, and resolved at runtime.
+  class Attribute
+    # Supported attribute scopes within Cattri.
+    ATTRIBUTE_TYPES = %i[class instance].freeze
+
+    # Supported Ruby method visibility levels.
+    ACCESS_LEVELS = %i[public protected private].freeze
+
+    # Ruby value types considered safe to reuse as-is (no `#dup` needed).
+    SAFE_VALUE_TYPES = [Numeric, Symbol, TrueClass, FalseClass, NilClass].freeze
+
+    # Default options for class-level attributes.
+    DEFAULT_CLASS_ATTRIBUTE_OPTIONS = {
+      readonly: false,
+      instance_reader: true
+    }.freeze
+
+    # Default options for instance-level attributes.
+    DEFAULT_INSTANCE_ATTRIBUTE_OPTIONS = {
+      reader: true,
+      writer: true
+    }.freeze
+
+    # @return [Symbol] the attribute name
+    attr_reader :name
+
+    # @return [Symbol] the attribute type (:class or :instance)
+    attr_reader :type
+
+    # @return [Symbol] the associated instance variable (e.g., :@items)
+    attr_reader :ivar
+
+    # @return [Symbol] the access level (:public, :protected, :private)
+    attr_reader :access
+
+    # @return [Proc] the normalized default value block
+    attr_reader :default
+
+    # @return [Proc] the setter function used to assign values
+    attr_reader :setter
+
+    # Initializes a new attribute definition.
+    #
+    # @param name [String, Symbol] the name of the attribute
+    # @param type [Symbol] either :class or :instance
+    # @param options [Hash] additional attribute configuration
+    # @param block [Proc, nil] optional block for setter coercion
+    #
+    # @raise [Cattri::UnsupportedTypeError] if an invalid type is provided
+    def initialize(name, type, options, block)
+      @type = type.to_sym
+      raise Cattri::UnsupportedTypeError, type unless ATTRIBUTE_TYPES.include?(@type)
+
+      @name = name.to_sym
+      @ivar = normalize_ivar(options[:ivar])
+      @access = options[:access] || :public
+      @default = normalize_default(options[:default])
+      @setter = normalize_setter(block)
+      @options = typed_options(options)
+    end
+
+    # Hash-like access to option values or metadata.
+    #
+    # @param key [Symbol, String]
+    # @return [Object]
+    def [](key)
+      to_hash[key.to_sym]
+    end
+
+    # Serializes this attribute to a hash, including core properties and type-specific flags.
+    #
+    # @return [Hash]
+    def to_hash
+      @to_hash ||= {
+        name: @name,
+        ivar: @ivar,
+        type: @type,
+        access: @access,
+        default: @default,
+        setter: @setter
+      }.merge(@options)
+    end
+
+    alias to_h to_hash
+
+    # @return [Boolean] true if the attribute is class-scoped
+    def class_level?
+      type == :class
+    end
+
+    # @return [Boolean] true if the attribute is instance-scoped
+    def instance_level?
+      type == :instance
+    end
+
+    # @return [Boolean] whether the attribute is public
+    def public?
+      access == :public
+    end
+
+    # @return [Boolean] whether the attribute is protected
+    def protected?
+      access == :protected
+    end
+
+    # @return [Boolean] whether the attribute is private
+    def private?
+      access == :private
+    end
+
+    # Invokes the default value logic for the attribute.
+    #
+    # @return [Object] the default value for the attribute
+    # @raise [Cattri::AttributeError] if the default value logic raises an error
+    def invoke_default
+      default.call
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to evaluate the default value for :#{name}. Error: #{e.message}"
+    end
+
+    # Invokes the setter function with error handling
+    #
+    # @param args [Array] the positional arguments
+    # @param kwargs [Hash] the keyword arguments
+    # @raise [Cattri::AttributeError] if setter raises an error
+    # @return [Object] the value returned by the setter
+    def invoke_setter(*args, **kwargs)
+      setter.call(*args, **kwargs)
+    rescue StandardError => e
+      raise Cattri::AttributeError, "Failed to evaluate the setter for :#{name}. Error: #{e.message}"
+    end
+
+    private
+
+    # Applies class- or instance-level defaults and filters valid option keys.
+    #
+    # @param options [Hash]
+    # @return [Hash]
+    def typed_options(options)
+      defaults = type == :class ? DEFAULT_CLASS_ATTRIBUTE_OPTIONS : DEFAULT_INSTANCE_ATTRIBUTE_OPTIONS
+      defaults.merge(options.slice(*defaults.keys))
+    end
+
+    # Normalizes the instance variable name for the attribute.
+    #
+    # @param ivar [String, Symbol, nil]
+    # @return [Symbol]
+    def normalize_ivar(ivar)
+      ivar ||= name
+      :"@#{ivar.to_s.delete_prefix("@")}"
+    end
+
+    # Returns the setter proc. If no block is provided, uses default logic:
+    # - Returns kwargs if given
+    # - Returns the single positional argument if one
+    # - Returns all args as an array otherwise
+    #
+    # @param block [Proc, nil]
+    # @return [Proc]
+    def normalize_setter(block)
+      block || lambda { |*args, **kwargs|
+        return kwargs unless kwargs.empty?
+        return args.first if args.length == 1
+
+        args
+      }
+    end
+
+    # Wraps the default value in a memoized lambda.
+    #
+    # If value is already callable, returns it.
+    # If immutable, wraps it in a lambda.
+    # If mutable, wraps it in a lambda that calls `#dup`.
+    #
+    # @param default [Object, Proc, nil]
+    # @return [Proc]
+    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) }
+
+      lambda {
+        begin
+          default.dup
+        rescue StandardError => e
+          raise Cattri::AttributeError,
+                "Failed to duplicate default value for :#{name}. Error: #{e.message}"
+        end
+      }
+    end
+  end
+end

data/lib/cattri/attribute_definer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Defines attribute accessors on a given target class using Cattri's Context.
+  #
+  # This class provides a set of utility methods to generate reader and writer
+  # methods dynamically, with support for default values, coercion, and memoization.
+  #
+  # All accessors are defined through the Cattri::Context abstraction to ensure
+  # consistent scoping, visibility, and method tracking.
+  class AttributeDefiner
+    class << self
+      # Defines a callable accessor for class-level attributes.
+      #
+      # The generated method:
+      # - Returns the memoized default value when called with no args or if readonly
+      # - Otherwise, calls the attribute’s setter and memoizes the result
+      #
+      # If the attribute is not readonly, a writer (`foo=`) is also defined.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      # @raise [Cattri::AttributeError] if the setter raises an error
+      def define_callable_accessor(attribute, context)
+        return unless attribute.class_level?
+
+        context.define_method(attribute) do |*args, **kwargs|
+          readonly = (args.empty? && kwargs.empty?) || attribute[:readonly]
+          return AttributeDefiner.send(:memoize_default_value, self, attribute) if readonly
+
+          value = attribute.invoke_setter(*args, **kwargs)
+          instance_variable_set(attribute.ivar, value)
+        end
+
+        define_writer(attribute, context) unless attribute[:readonly]
+      end
+
+      # Defines an instance-level reader for class-level attributes.
+      #
+      # This method delegates the instance-level call to the class method.
+      # It is used when `instance_reader: true` is specified.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_instance_level_reader(attribute, context)
+        return unless attribute.class_level?
+
+        context.target.define_method(attribute.name) do
+          self.class.__send__(attribute.name)
+        end
+
+        context.send(:apply_access, attribute.name, attribute)
+      end
+
+      # Defines standard reader and writer methods for instance-level attributes.
+      #
+      # Skips definition if `reader: false` or `writer: false` is specified.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_accessor(attribute, context)
+        define_reader(attribute, context) if attribute[:reader]
+        define_writer(attribute, context) if attribute[:writer]
+      end
+
+      # Defines a memoizing reader for the given attribute.
+      #
+      # This is used for both class and instance attributes, and ensures that
+      # the default value is computed only once and stored in the ivar.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_reader(attribute, context)
+        context.define_method(attribute) do
+          AttributeDefiner.send(:memoize_default_value, self, attribute)
+        end
+      end
+
+      # Defines a writer method (`foo=`) that sets and coerces a value via the attribute setter.
+      #
+      # @param attribute [Cattri::Attribute]
+      # @param context [Cattri::Context]
+      # @return [void]
+      def define_writer(attribute, context)
+        context.define_method(attribute, name: :"#{attribute.name}=") do |value|
+          coerced_value = attribute.setter.call(value)
+          instance_variable_set(attribute.ivar, coerced_value)
+        end
+      end
+
+      private
+
+      # Returns the memoized value for an attribute or computes it from the default.
+      #
+      # This helper ensures lazy initialization while guarding against errors in the default proc.
+      #
+      # @param receiver [Object]
+      # @param attribute [Cattri::Attribute]
+      # @return [Object]
+      # @raise [Cattri::AttributeError] if the default block raises an error
+      def memoize_default_value(receiver, attribute)
+        return receiver.instance_variable_get(attribute.ivar) if receiver.instance_variable_defined?(attribute.ivar)
+
+        receiver.instance_variable_set(attribute.ivar, attribute.invoke_default)
+      end
+    end
+  end
+end