cattri 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c63162e310f56cece90ee13f07b6edce76503e525ac899094a454248187a0b4
-  data.tar.gz: b2eca347c4603946fa1b1dc62bd5d36138c4fed87e4909e9650b62005dc89e02
+  metadata.gz: 4558aae18122f29cebf5ddb34fe452ee6b00898d994b4cd8f2b0a825c5a599aa
+  data.tar.gz: '092f86968324144a229510426858c9a4cee0245267503a160e27b6087384e88e'
 SHA512:
-  metadata.gz: 3c749774916b9921d089554b2e0a2c2c747205d328700f54ee41c6912a40d98656b4d861e7d86523ae3f709e612dde9115ce0357541571efe3361d1d5ef03c49
-  data.tar.gz: 3a2748150b821d01d8d36bbf44aefbc093751f3ac18f32819c6e731581173abc9423821ad259ad1089c952860e4fd4cc8b759f6312179a62c055423fcf7e4a96
+  metadata.gz: 61ac08cebe59853a0a4c163052bdabef6e70db7476bf0d93ff4a1184b706e326fab8583ad6b77533f7c297e5be15cd15cd3414ef8c751443d4f1ed8a06b768a6
+  data.tar.gz: dc18a8a83dc56d9a4c2b122c3f824808f8037f0d1cb08a2d71e82ef6aa933d73c75efa083df12cb4b5a7dfb30a0ce22c0558871fe07365d73b601b2e32b537fd

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,57 @@
-## [Unreleased]
+## [0.1.2] - 2025-04-22
+
+### Added
+
+- Support for defining multiple attributes in a single call to `cattr` or `iattr`.
+  - Example: `cattr :foo, :bar, default: 1`
+  - Shared options apply to all attributes.
+- Adds `cattr_setter` and `iattr_setter` for defining setters on attributes, useful when defining multiple attributes since ambiguous blocks are not allow.
+  ```ruby
+  class Config
+    include Cattri
+  
+    cattr :a, :b               # new functionality, does not allow setter blocks.
+                               # creates writers as def a=(val); @a = val; end
+    
+    cattr_setter :a do |val|   # redefines a= as def a=(val); val.to_s.downcase.to_sym; end
+      val.to_s.downcase.to_sym
+    end
+  end
+  ```
+- Validation to prevent use of a block when defining multiple attributes.
+  - Raises `Cattri::AmbiguousBlockError` if `&block` is passed with more than one attribute.
+
+## [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,253 @@
 # 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
-
-  cattr :enabled, default: true
-  iattr :name, default: "anonymous"
+class Config
+  include Cattri          # exposes `cattr` & `iattr`
+
+  # -- class‑level ----------------------------------
+  cattr :flag_a, :flag_b, default: true
+  cattr :enabled,         default: true
+  cattr :timeout,         default: -> { 5.0 }, instance_reader: false
+
+  # -- instance‑level -------------------------------
+  iattr :item_a, :item_b, default: true
+  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:
+
+| 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.
+
+---
+
+## Post-definition coercion with `*_setter`
+
+If you define multiple attributes at once, you can't provide a coercion block inline:
 
 ```ruby
-MyConfig.lock_cattrs!
+cattr :foo, :bar, default: nil      # ❌ cannot use block here
 ```
 
-This prevents redefinition of existing class attributes in subclasses.
+Instead, define them first, then apply a coercion later using:
 
-### Instance Attributes
+- `cattr_setter` for class attributes
+- `iattr_setter` for instance attributes
+
+These allow you to attach or override the setter logic after the fact:
 
 ```ruby
-class Request
-  include Cattri::InstanceAttributes
+class Config
+  include Cattri
 
-  iattr :headers, default: -> { {} }
-  iattr_writer :raw_body do |val|
-    val.to_s.strip
+  cattr :log_level
+  cattr_setter :log_level do |val|
+    val.to_s.downcase.to_sym
   end
-end
 
-req = Request.new
-req.headers["Content-Type"] = "application/json"
-req.raw_body = "  data  "
+  iattr_writer :token
+  iattr_setter :token do |val|
+    val.strip
+  end
+end
 ```
 
-### Resetting Attributes
+Coercion is only applied when the attribute is written (via `=` or callable form), not when read.
+
+Attempting to use `*_setter` on an undefined attribute or one without a writer will raise:
+
+- `Cattri::AttributeNotDefinedError` – the attribute doesn't exist or wasn't fully defined
+- `Cattri::AttributeDefinitionError` – the attribute is marked as readonly
+
+These APIs ensure your DSL stays consistent and extensible, even when bulk-declaring attributes up front.
+
+---
+
+## Visibility tracking
+
+Cattri watches calls to `public`, `protected`, and `private` while you define methods:
 
 ```ruby
-MyConfig.reset_cattrs!        # Reset all class attributes
-MyConfig.reset_cattr!(:format)
+class Secrets
+  include Cattri
 
-req.reset_iattr!(:headers)    # Reset a specific instance attribute
+  private
+  cattr :api_key
+end
+
+Secrets.private_methods.include?(:api_key)   # => true
 ```
 
-## 🔍 Introspection
+No boilerplate—attributes inherit the visibility that was in effect at the call site.
+
+---
+
+## Safe inheritance
 
-If you include the `Cattri::Introspection` module:
+Subclassing copies both **metadata** and **current values**, using defensive `#dup` where possible and falling back safely when objects are frozen or not duplicable:
 
 ```ruby
-class MyConfig
+class Base
   include Cattri
-  include Cattri::Introspection
-
-  cattr :items, default: []
+  cattr :settings, default: {}
 end
 
-MyConfig.items << :a
-MyConfig.snapshot_class_attributes # => { items: [:a] }
+class Child < Base; end
+
+Base.settings[:foo]  = 1
+Child.settings       # => {}  (isolated copy)
 ```
 
-## 📚 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        |
+## Introspection helpers
 
-## 🧪 Testing
+Add `include Cattri::Introspection` (or `extend` for class‑only use) to snapshot live values:
 
-```bash
-bundle exec rspec
+```ruby
+Config.snapshot_cattrs   # => { enabled: false, timeout: 5.0 }
+instance.snapshot_iattrs # => { name: "bob", age: 42 }
+```
+
+Great for debugging or test assertions.
+
+---
+
+## Error handling
+
+All errors inherit from `Cattri::Error`, allowing a single rescue for any gem‑specific issue.
+
+| 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 |
+
+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 provides a cleaner alternative to `class_attribute`, `attr_accessor`, and configuration gems like `Dry::Configurable` or `ActiveSupport::Configurable`, without monkey-patching or runtime surprises.
+Cattri sits in the sweet spot: **micro‑sized (~300 LOC)**, dependency‑free, and purpose‑built for attribute declaration.
 
-## 📝 License
+---
+
+## 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.
+
+---
+
+## 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