cattri 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8689b6e0fa1e741fc271fece58183191d290875fe203af5622f069aaf3c4cf7
-  data.tar.gz: 2435ba9915a003f39d2d0275c725064c0c5c885940e7de109bb852a7258dfdd6
+  metadata.gz: 4558aae18122f29cebf5ddb34fe452ee6b00898d994b4cd8f2b0a825c5a599aa
+  data.tar.gz: '092f86968324144a229510426858c9a4cee0245267503a160e27b6087384e88e'
 SHA512:
-  metadata.gz: 847f1396957fa8567868273f61c1906e95001e0fd8c632de72ed3f520ec4a7edb1c91c7c1f6a02101913c392d119b24a32a4d835827dab864338ab0e6b668574
-  data.tar.gz: f7347d6cb14bb1b0501ff45799ba513388462ede2c95a47f84efb9d4a99ce7c9a6c6a8c726e605b4d475b26664c5f8861f8fc50922da4ebfbe4b139a257af131
+  metadata.gz: 61ac08cebe59853a0a4c163052bdabef6e70db7476bf0d93ff4a1184b706e326fab8583ad6b77533f7c297e5be15cd15cd3414ef8c751443d4f1ed8a06b768a6
+  data.tar.gz: dc18a8a83dc56d9a4c2b122c3f824808f8037f0d1cb08a2d71e82ef6aa933d73c75efa083df12cb4b5a7dfb30a0ce22c0558871fe07365d73b601b2e32b537fd

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [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

data/README.md

@@ -43,12 +43,14 @@ class Config
   include Cattri          # exposes `cattr` & `iattr`
 
   # -- class‑level ----------------------------------
-  cattr :enabled,  default: true
-  cattr :timeout,  default: -> { 5.0 }, instance_reader: false
+  cattr :flag_a, :flag_b, default: true
+  cattr :enabled,         default: true
+  cattr :timeout,         default: -> { 5.0 }, instance_reader: false
 
   # -- instance‑level -------------------------------
-  iattr :name,     default: "anonymous"
-  iattr :age,      default: 0 do |val|                 # coercion block
+  iattr :item_a, :item_b, default: true
+  iattr :name,            default: "anonymous"
+  iattr :age,             default: 0 do |val|                 # coercion block
     Integer(val)
   end
 end
@@ -95,6 +97,48 @@ If you pass a block, it’s treated as a **coercion setter** and receives the in
 
 ---
 
+## Post-definition coercion with `*_setter`
+
+If you define multiple attributes at once, you can't provide a coercion block inline:
+
+```ruby
+cattr :foo, :bar, default: nil      # ❌ cannot use block here
+```
+
+Instead, define them first, then apply a coercion later using:
+
+- `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 Config
+  include Cattri
+
+  cattr :log_level
+  cattr_setter :log_level do |val|
+    val.to_s.downcase.to_sym
+  end
+
+  iattr_writer :token
+  iattr_setter :token do |val|
+    val.strip
+  end
+end
+```
+
+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:
@@ -180,7 +224,7 @@ end
 * **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.
+Cattri sits in the sweet spot: **micro‑sized (~300 LOC)**, dependency‑free, and purpose‑built for attribute declaration.
 
 ---
 

data/lib/cattri/attribute_definer.rb

@@ -92,6 +92,18 @@ module Cattri
         end
       end
 
+      # Defines, or redefines, 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.

data/lib/cattri/class_attributes.rb

@@ -20,9 +20,20 @@ module Cattri
   # Class attributes are stored internally as `Cattri::Attribute` instances and
   # values are memoized using class-level instance variables.
   module ClassAttributes
-    # Defines a class-level attribute with optional default, coercion, and reader access.
+    # Defines one or more class-level attributes with optional default, coercion, and reader access.
     #
-    # @param name [Symbol] the attribute name
+    # This method supports defining multiple attributes at once, provided they share the same options.
+    # If a block is given, only one attribute may be defined to avoid ambiguity.
+    #
+    # @example Define multiple attributes with shared options
+    #   class_attribute :foo, :bar, default: 42
+    #
+    # @example Define a single attribute with a coercion block
+    #   class_attribute :path do |val|
+    #     Pathname(val)
+    #   end
+    #
+    # @param names [Array<Symbol | String>] the names of the attributes to define
     # @param options [Hash] additional attribute options
     # @option options [Object, Proc] :default the default value or lambda
     # @option options [Boolean] :readonly whether the attribute is read-only
@@ -32,31 +43,59 @@ module Cattri
     # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
     #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
     #    already defined or an error occurs while defining methods)
-    def class_attribute(name, **options, &block)
-      options[:access] ||= __cattri_visibility
-      attribute = Cattri::Attribute.new(name, :class, options, block)
-
-      raise Cattri::AttributeDefinedError, attribute if class_attribute_defined?(attribute.name)
-
-      begin
-        __cattri_class_attributes[name] = attribute
+    # @return [void]
+    def class_attribute(*names, **options, &block)
+      raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-        Cattri::AttributeDefiner.define_callable_accessor(attribute, context)
-        Cattri::AttributeDefiner.define_instance_level_reader(attribute, context) if attribute[:instance_reader]
-      rescue StandardError => e
-        raise Cattri::AttributeDefinitionError.new(self, attribute, e)
-      end
+      names.each { |name| define_class_attribute(name, options, block) }
     end
 
     # Defines a read-only class attribute.
     #
     # Equivalent to calling `class_attribute(name, readonly: true, ...)`
     #
-    # @param name [Symbol]
-    # @param options [Hash]
+    # @param names [Array<Symbol | String>] the names of the attributes to define
+    # @param options [Hash] additional attribute options
+    # @option options [Object, Proc] :default the default value or lambda
+    # @option options [Boolean] :readonly whether the attribute is read-only
+    # @option options [Boolean] :instance_reader whether to define an instance-level reader (default: true)
+    # @option options [Symbol] :access visibility level (:public, :protected, :private)
+    # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
+    #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
+    #    already defined or an error occurs while defining methods)
+    # @return [void]
+    def class_attribute_reader(*names, **options)
+      class_attribute(*names, **options, readonly: true)
+    end
+
+    # Updates the setter behavior of an existing class-level attribute.
+    #
+    # This allows coercion logic to be defined or overridden after the attribute
+    # has been declared using `cattr`, as long as the writer method exists.
+    #
+    # @example Add coercion to an existing attribute
+    #   cattr :format
+    #   cattr_setter :format do |val|
+    #     val.to_s.downcase.to_sym
+    #   end
+    #
+    # @param name [Symbol, String] the name of the attribute
+    # @yieldparam value [Object] the value passed to the setter
+    # @yieldreturn [Object] the coerced value to be assigned
+    # @raise [Cattri::AttributeNotDefinedError] if the attribute is not defined or the writer method does not exist
+    # @raise [Cattri::AttributeDefinitionError] if method redefinition fails
     # @return [void]
-    def class_attribute_reader(name, **options)
-      class_attribute(name, readonly: true, **options)
+    def class_attribute_setter(name, &block)
+      name = name.to_sym
+      attribute = __cattri_class_attributes[name]
+      puts "<<< #{attribute} = #{name}>"
+
+      if attribute.nil? || !context.method_defined?(:"#{name}=")
+        raise Cattri::AttributeNotDefinedError.new(:class, name)
+      end
+
+      attribute.instance_variable_set(:@setter, attribute.send(:normalize_setter, block))
+      Cattri::AttributeDefiner.define_writer!(attribute, context)
     end
 
     # Returns a list of defined class attribute names.
@@ -116,6 +155,36 @@ module Cattri
 
     private
 
+    # Defines a single class-level attribute.
+    #
+    # This is the internal implementation used by {.class_attribute} and its aliases.
+    # It constructs a `Cattri::Attribute`, registers it, and defines the necessary
+    # class and instance methods.
+    #
+    # @param name [Symbol] the name of the attribute to define
+    # @param options [Hash] additional attribute options (e.g., :default, :readonly)
+    # @param block [Proc, nil] an optional setter block for coercion
+    #
+    # @raise [Cattri::AttributeDefinedError] if the attribute has already been defined
+    # @raise [Cattri::AttributeDefinitionError] if method definition fails
+    #
+    # @return [void]
+    def define_class_attribute(name, options, block) # rubocop:disable Metrics/AbcSize
+      options[:access] ||= __cattri_visibility
+      attribute = Cattri::Attribute.new(name, :class, options, block)
+
+      raise Cattri::AttributeDefinedError.new(:class, name) if class_attribute_defined?(attribute.name)
+
+      begin
+        __cattri_class_attributes[name] = attribute
+
+        Cattri::AttributeDefiner.define_callable_accessor(attribute, context)
+        Cattri::AttributeDefiner.define_instance_level_reader(attribute, context) if attribute[:instance_reader]
+      rescue StandardError => e
+        raise Cattri::AttributeDefinitionError.new(self, attribute, e)
+      end
+    end
+
     # Internal registry of defined class-level attributes.
     #
     # @return [Hash{Symbol => Cattri::Attribute}]

data/lib/cattri/context.rb

@@ -63,11 +63,27 @@ module Cattri
       name = (name || attribute.name).to_sym
       return if method_defined?(name)
 
+      define_method!(attribute, name: name, &block)
+    end
+
+    # Defines a method on the target class or singleton class, regardless of whether it already exists.
+    #
+    # This bypasses any checks for prior definition and forcibly installs the method using `define_method`.
+    # The method will be assigned visibility based on the attribute's `:access` setting.
+    #
+    # Used internally by attribute definers to (re)define writers, readers, or callables.
+    #
+    # @param attribute [Cattri::Attribute] the attribute whose context and access rules apply
+    # @param name [Symbol, nil] the method name to define (defaults to attribute name)
+    # @yield the method body to define
+    # @raise [Cattri::AttributeDefinitionError] if method definition fails
+    # @return [void]
+    def define_method!(attribute, name: nil, &block)
       target = target_for(attribute)
 
       begin
         target.define_method(name, &block)
-        @defined_methods << name
+        @defined_methods << name unless method_defined?(name)
         apply_access(name, attribute)
       rescue StandardError => e
         raise Cattri::AttributeDefinitionError.new(target, attribute, e)

data/lib/cattri/error.rb

@@ -30,9 +30,31 @@ module Cattri
   #   rescue Cattri::AttributeDefinedError => e
   #     puts e.message
   class AttributeDefinedError < Cattri::AttributeError
-    # @param attribute [Cattri::Attribute] the conflicting attribute
-    def initialize(attribute)
-      super("#{attribute.type.capitalize} attribute :#{attribute.name} has already been defined")
+    # @param type [Symbol, String] either :class or :instance
+    # @param name [Symbol, String] the name of the missing attribute
+    def initialize(type, name)
+      super("#{type.capitalize} attribute :#{name} has already been defined")
+    end
+  end
+
+  # Raised when attempting to access or modify an attribute that has not been defined.
+  #
+  # This applies to both class-level and instance-level attributes.
+  # It is typically raised when calling `.class_attribute_setter` or `.instance_attribute_setter`
+  # on a name that does not exist or lacks the expected method (e.g., writer).
+  #
+  # @example
+  #   raise Cattri::AttributeNotDefinedError.new(:class, :foo)
+  #   # => Class attribute :foo has not been defined
+  #
+  # @example
+  #   rescue Cattri::AttributeNotDefinedError => e
+  #     puts e.message
+  class AttributeNotDefinedError < Cattri::AttributeError
+    # @param type [Symbol, String] either :class or :instance
+    # @param name [Symbol, String] the name of the missing attribute
+    def initialize(type, name)
+      super("#{type.capitalize} attribute :#{name} has not been defined")
     end
   end
 
@@ -63,10 +85,21 @@ module Cattri
   # @example
   #   raise Cattri::UnsupportedTypeError.new(:foo)
   #   # => Attribute type :foo is not supported
-  class UnsupportedTypeError < Error
+  class UnsupportedTypeError < Cattri::AttributeError
     # @param type [Symbol] the invalid type that triggered the error
     def initialize(type)
       super("Attribute type :#{type} is not supported")
     end
   end
+
+  # Raised when a block is provided when defining a group of attributes `cattr :attr_a, :attr_b do ... end`
+  #
+  # @example
+  #   raise Cattri::AmbiguousBlockError
+  #   # => Cannot define multiple attributes with a block
+  class AmbiguousBlockError < Cattri::AttributeError
+    def initialize
+      super("Cannot define multiple attributes with a block")
+    end
+  end
 end

data/lib/cattri/instance_attributes.rb

@@ -26,9 +26,20 @@ module Cattri
 
     # Defines instance-level attribute DSL methods.
     module ClassMethods
-      # Defines an instance-level attribute with optional default and coercion.
+      # Defines one or more instance-level attributes with optional default and coercion.
       #
-      # @param name [Symbol, String] the name of the attribute
+      # This method supports defining multiple attributes at once, provided they share the same options.
+      # If a block is given, only one attribute may be defined to avoid ambiguity.
+      #
+      # @example Define multiple attributes with shared defaults
+      #   iattr :foo, :bar, default: []
+      #
+      # @example Define a single attribute with coercion
+      #   iattr :level do |val|
+      #     Integer(val)
+      #   end
+      #
+      # @param names [Array<Symbol | String>] the names of the attributes to define
       # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
       # @option options [Object, Proc] :default the default value or lambda
       # @option options [Boolean] :reader whether to define a reader method (default: true)
@@ -38,41 +49,74 @@ module Cattri
       # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
       #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
       #    already defined or an error occurs while defining methods)
-      def instance_attribute(name, **options, &block)
-        options[:access] ||= __cattri_visibility
-        attribute = Cattri::Attribute.new(name, :instance, options, block)
-
-        raise Cattri::AttributeDefinedError, attribute if instance_attribute_defined?(attribute.name)
+      # @return [void]
+      def instance_attribute(*names, **options, &block)
+        raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-        begin
-          __cattri_instance_attributes[name.to_sym] = attribute
-          Cattri::AttributeDefiner.define_accessor(attribute, context)
-        rescue StandardError => e
-          raise Cattri::AttributeDefinitionError.new(self, attribute, e)
-        end
+        names.each { |name| define_instance_attribute(name, options, block) }
       end
 
       # Defines a read-only instance-level attribute.
       #
       # Equivalent to `instance_attribute(..., writer: false)`
       #
-      # @param name [Symbol, String]
-      # @param options [Hash]
+      # @param names [Array<Symbol | String>] the names of the attributes to define
+      # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
+      # @option options [Object, Proc] :default the default value or lambda
+      # @option options [Boolean] :reader whether to define a reader method (default: true)
+      # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @yieldparam value [Object] optional custom coercion logic for the setter
+      # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
+      #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
+      #    already defined or an error occurs while defining methods)
       # @return [void]
-      def instance_attribute_reader(name, **options)
-        instance_attribute(name, writer: false, **options)
+      def instance_attribute_reader(*names, **options)
+        instance_attribute(*names, **options, writer: false)
       end
 
       # Defines a write-only instance-level attribute.
       #
       # Equivalent to `instance_attribute(..., reader: false)`
       #
-      # @param name [Symbol, String]
-      # @param options [Hash]
-      # @yieldparam value [Object] optional coercion logic
+      # @param names [Array<Symbol | String>] the names of the attributes to define
+      # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
+      # @option options [Object, Proc] :default the default value or lambda
+      # @option options [Boolean] :writer whether to define a writer method (default: true)
+      # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @yieldparam value [Object] optional custom coercion logic for the setter
+      # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
+      #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
+      #    already defined or an error occurs while defining methods)
       # @return [void]
-      def instance_attribute_writer(name, **options, &block)
-        instance_attribute(name, reader: false, **options, &block)
+      def instance_attribute_writer(*names, **options, &block)
+        instance_attribute(*names, **options.merge(reader: false), &block)
+      end
+
+      # Updates the setter behavior of an existing instance-level attribute.
+      #
+      # This allows coercion logic to be defined or overridden after the attribute
+      # has been declared using `iattr`, as long as the writer method exists.
+      #
+      # @example Add coercion to an existing attribute
+      #   iattr :format
+      #   iattr_setter :format do |val|
+      #     val.to_s.downcase.to_sym
+      #   end
+      #
+      # @param name [Symbol, String] the name of the attribute
+      # @yieldparam value [Object] the value passed to the setter
+      # @yieldreturn [Object] the coerced value to be assigned
+      # @raise [Cattri::AttributeNotDefinedError] if the attribute is not defined or the writer method does not exist
+      # @raise [Cattri::AttributeDefinitionError] if method redefinition fails
+      # @return [void]
+      def instance_attribute_setter(name, &block)
+        attribute = __cattri_instance_attributes[name.to_sym]
+
+        raise Cattri::AttributeNotDefinedError.new(:instance, name) if attribute.nil?
+        raise Cattri::AttributeError, "Cannot define setter for readonly attribute :#{name}" unless attribute[:writer]
+
+        attribute.instance_variable_set(:@setter, attribute.send(:normalize_setter, block))
+        Cattri::AttributeDefiner.define_writer!(attribute, context)
       end
 
       # Returns a list of defined instance-level attribute names.
@@ -114,6 +158,10 @@ module Cattri
       #   Alias for {#instance_attribute_writer}
       alias iattr_writer instance_attribute_writer
 
+      # @!method iattr_setter(name, &block)
+      #   Alias for {#instance_attribute_setter}
+      alias iattr_setter instance_attribute_setter
+
       # @!method iattrs
       #   Alias for {#instance_attributes}
       alias iattrs instance_attributes
@@ -128,6 +176,34 @@ module Cattri
 
       private
 
+      # Defines a single instance-level attribute.
+      #
+      # This is the internal implementation used by {.instance_attribute} and its aliases.
+      # It creates a `Cattri::Attribute`, registers it, and defines the appropriate
+      # reader and/or writer methods on the class.
+      #
+      # @param name [Symbol, String] the attribute name
+      # @param options [Hash] additional options for the attribute
+      # @param block [Proc, nil] optional setter coercion logic
+      #
+      # @raise [Cattri::AttributeDefinedError] if the attribute has already been defined
+      # @raise [Cattri::AttributeDefinitionError] if method definition fails
+      #
+      # @return [void]
+      def define_instance_attribute(name, options, block)
+        options[:access] ||= __cattri_visibility
+        attribute = Cattri::Attribute.new(name, :instance, options, block)
+
+        raise Cattri::AttributeDefinedError.new(:instance, name) if instance_attribute_defined?(attribute.name)
+
+        begin
+          __cattri_instance_attributes[name.to_sym] = attribute
+          Cattri::AttributeDefiner.define_accessor(attribute, context)
+        rescue StandardError => e
+          raise Cattri::AttributeDefinitionError.new(self, attribute, e)
+        end
+      end
+
       # Internal registry of instance attributes defined on the class.
       #
       # @return [Hash{Symbol => Cattri::Attribute}]

data/lib/cattri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cattri
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cattri
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-22 00:00:00.000000000 Z
+date: 2025-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec