cattri 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4558aae18122f29cebf5ddb34fe452ee6b00898d994b4cd8f2b0a825c5a599aa
-  data.tar.gz: '092f86968324144a229510426858c9a4cee0245267503a160e27b6087384e88e'
+  metadata.gz: 2495a8756d30c301267ad2db2dfbd4c9669e817119fa316b608408665988b747
+  data.tar.gz: 47d682eaf5465e4ab6cc4bdb7dcc74d053c93c6b8d1ee3a8cfda0925cf68662a
 SHA512:
-  metadata.gz: 61ac08cebe59853a0a4c163052bdabef6e70db7476bf0d93ff4a1184b706e326fab8583ad6b77533f7c297e5be15cd15cd3414ef8c751443d4f1ed8a06b768a6
-  data.tar.gz: dc18a8a83dc56d9a4c2b122c3f824808f8037f0d1cb08a2d71e82ef6aa933d73c75efa083df12cb4b5a7dfb30a0ce22c0558871fe07365d73b601b2e32b537fd
+  metadata.gz: aae777877b7576a76b0be11a529aafaaac9c59066efd873fc9020689ba3ccefb78688411907b2246cb603dafa5e6868e1841e4724f296f634eac821a1bc27bc9
+  data.tar.gz: 8e919b6782d0cce71ed1a78bb46ebb92df995471238080a4e20604914d0fe958c041aec201eb598f9764598384fd776aaff03f5b131908082428c2d546c97cd9

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.1.3] - 2025-04-22
+
+### Added
+
+- ✅ Support for `predicate: true` on both `iattr` and `cattr` — defines a `:name?` method returning `!!send(:name)`
+- ✅ `iattr_alias` and `cattr_alias` — define alias methods that delegate to existing attributes (e.g., `:foo?` for `:foo`)
+- Predicate methods inherit visibility from the original attribute and are excluded from introspection (`iattrs`, `cattrs`)
+- Raised error when attempting to define an attribute ending in `?`, with guidance to use `predicate: true` or `*_alias`
+
 ## [0.1.2] - 2025-04-22
 
 ### Added

data/README.md

@@ -44,12 +44,13 @@ class Config
 
   # -- class‑level ----------------------------------
   cattr :flag_a, :flag_b, default: true
-  cattr :enabled,         default: true
+  cattr :enabled,         default: true, predicate: true
   cattr :timeout,         default: -> { 5.0 }, instance_reader: false
 
   # -- instance‑level -------------------------------
   iattr :item_a, :item_b, default: true
   iattr :name,            default: "anonymous"
+  iattr_alias :username, :name
   iattr :age,             default: 0 do |val|                 # coercion block
     Integer(val)
   end
@@ -57,7 +58,9 @@ end
 
 Config.enabled        # => true
 Config.enabled = false
+Config.enabled?       # => false (created with predicate: true flag)
 Config.new.age = "42" # => 42
+Config.new.username   # proxy to Config.new.name
 ```
 
 ---
@@ -67,12 +70,14 @@ Config.new.age = "42" # => 42
 ### Class attributes (`cattr`)
 
 ```ruby
-cattr :log_level, default: :info,
-                  access:  :protected,     # respects current visibility by default
-                  readonly: false,
-                  instance_reader: true do |value|
-                    value.to_sym
-                  end
+cattr :log_level,
+      default: :info,
+      access:  :protected,     # respects current visibility by default
+      readonly: false,
+      predicate: true,         # defines #{name}? predicate method that respects visibility
+      instance_reader: true do |value|
+  value.to_sym
+end
 ```
 
 ### Instance attributes (`iattr`)
@@ -80,7 +85,8 @@ cattr :log_level, default: :info,
 ```ruby
 iattr :token, default: -> { SecureRandom.hex(8) },
               reader:  true,
-              writer:  false                  # read‑only
+              writer:  false,                  # read‑only
+              predicate: true
 ```
 
 Both forms accept:
@@ -92,6 +98,7 @@ Both forms accept:
 | `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**). |
+| `predicate` | Define a `:name?` method that calls `!!send(name)`
 
 If you pass a block, it’s treated as a **coercion setter** and receives the incoming value.
 

data/lib/cattri/attribute.rb

@@ -23,13 +23,15 @@ module Cattri
     # Default options for class-level attributes.
     DEFAULT_CLASS_ATTRIBUTE_OPTIONS = {
       readonly: false,
-      instance_reader: true
+      instance_reader: true,
+      predicate: false
     }.freeze
 
     # Default options for instance-level attributes.
     DEFAULT_INSTANCE_ATTRIBUTE_OPTIONS = {
       reader: true,
-      writer: true
+      writer: true,
+      predicate: false
     }.freeze
 
     # @return [Symbol] the attribute name

data/lib/cattri/attribute_definer.rb

@@ -47,13 +47,32 @@ module Cattri
       def define_instance_level_reader(attribute, context)
         return unless attribute.class_level?
 
-        context.target.define_method(attribute.name) do
+        define_instance_level_method(attribute, context) do
           self.class.__send__(attribute.name)
         end
 
         context.send(:apply_access, attribute.name, attribute)
       end
 
+      # Defines an instance-level method for a class-level attribute.
+      #
+      # This is a shared utility for defining instance methods that delegate to class attributes,
+      # including both regular readers and predicate-style readers (`predicate: true`).
+      #
+      # Visibility is inherited from the attribute and applied to the defined method.
+      #
+      # @param attribute [Cattri::Attribute] the associated attribute metadata
+      # @param context [Cattri::Context] the context in which to define the method
+      # @param name [Symbol, nil] optional override for the method name (defaults to `attribute.name`)
+      # @yield the method body to define
+      # @return [void]
+      def define_instance_level_method(attribute, context, name: nil, &block)
+        name = (name || attribute.name).to_sym
+        context.target.define_method(name, &block)
+
+        context.send(:apply_access, name, attribute)
+      end
+
       # Defines standard reader and writer methods for instance-level attributes.
       #
       # Skips definition if `reader: false` or `writer: false` is specified.

data/lib/cattri/class_attributes.rb

@@ -39,6 +39,8 @@ module Cattri
     # @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)
+    # @option options [Boolean] :predicate whether to define a predicate-style alias method
+    #   (e.g., `foo?`) for the attribute
     # @yieldparam value [Object] an optional custom setter block
     # @raise [Cattri::AttributeError] or its subclasses, including `Cattri::AttributeDefinedError` or
     #   `Cattri::AttributeDefinitionError` if defining the attribute fails (e.g., if the attribute is
@@ -47,7 +49,15 @@ module Cattri
     def class_attribute(*names, **options, &block)
       raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-      names.each { |name| define_class_attribute(name, options, block) }
+      names.each do |name|
+        if name.end_with?("?")
+          raise Cattri::AttributeError,
+                "Attribute names ending in '?' are not allowed. Use `predicate: true` or `cattr_alias` instead."
+
+        end
+
+        define_class_attribute(name, options, block)
+      end
     end
 
     # Defines a read-only class attribute.
@@ -60,6 +70,8 @@ module Cattri
     # @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)
+    # @option options [Boolean] :predicate whether to define a predicate-style alias method
+    #   (e.g., `foo?`) for the attribute
     # @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)
@@ -98,11 +110,33 @@ module Cattri
       Cattri::AttributeDefiner.define_writer!(attribute, context)
     end
 
+    # Defines an alias method for an existing class-level attribute.
+    #
+    # This does **not** register a new attribute; it simply defines a method
+    # (e.g., a predicate-style alias like `foo?`) that delegates to an existing one.
+    #
+    # The alias method inherits the visibility of the original attribute.
+    #
+    # @param alias_name [Symbol, String] the new method name (e.g., `:foo?`)
+    # @param original [Symbol, String] the name of the existing attribute to delegate to (e.g., `:foo`)
+    # @raise [Cattri::AttributeNotDefinedError] if the original attribute is not defined
+    # @return [void]
+    def class_attribute_alias(alias_name, original)
+      attribute = __cattri_class_attributes[original.to_sym]
+      raise Cattri::AttributeNotDefinedError.new(:class, original) if attribute.nil?
+
+      context.define_method(attribute, name: alias_name) { public_send(original) }
+    end
+
     # Returns a list of defined class attribute names.
     #
     # @return [Array<Symbol>]
     def class_attributes
-      __cattri_class_attributes.keys
+      ([self] + ancestors + singleton_class.included_modules)
+        .uniq
+        .select { |mod| mod.respond_to?(:__cattri_class_attributes, true) }
+        .flat_map { |mod| mod.send(:__cattri_class_attributes).keys }
+        .uniq
     end
 
     # Checks whether a class attribute has been defined.
@@ -136,6 +170,16 @@ module Cattri
     #   @see #class_attribute_reader
     alias cattr_reader class_attribute_reader
 
+    # @!method cattr_setter(name, **options)
+    #   Alias for {.class_attribute_setter}
+    #   @see #class_attribute_setter
+    alias cattr_setter class_attribute_setter
+
+    # @!method cattr_alias(name, **options)
+    #   Alias for {.class_attribute_alias}
+    #   @see #class_attribute_alias
+    alias cattr_alias class_attribute_alias
+
     # @!method cattrs
     #   Alias for {.class_attributes}
     #   @return [Array<Symbol>]
@@ -183,6 +227,35 @@ module Cattri
       rescue StandardError => e
         raise Cattri::AttributeDefinitionError.new(self, attribute, e)
       end
+
+      define_predicate_methods(attribute) if attribute[:predicate]
+    end
+
+    # Defines predicate-style (`:name?`) methods for a class-level attribute.
+    #
+    # If `attribute[:predicate]` is true, this defines a method named `:name?` that returns
+    # a boolean based on the truthiness of the attribute's value (`!!value`).
+    #
+    # If `attribute[:instance_reader]` is also true, an instance-level predicate method
+    # is defined that delegates to the class-level value.
+    #
+    # Visibility is inherited from the original attribute.
+    #
+    # @param attribute [Cattri::Attribute] the attribute for which to define predicate methods
+    # @return [void]
+    def define_predicate_methods(attribute)
+      return unless attribute[:predicate]
+
+      predicate_name = :"#{attribute.name}?"
+
+      # rubocop:disable Style/DoubleNegation
+      context.define_method(attribute, name: predicate_name) { !!send(attribute.name) }
+      return unless attribute[:instance_reader]
+
+      Cattri::AttributeDefiner.define_instance_level_method(attribute, context, name: predicate_name) do
+        !!self.class.__send__(attribute.name)
+      end
+      # rubocop:enable Style/DoubleNegation
     end
 
     # Internal registry of defined class-level attributes.

data/lib/cattri/instance_attributes.rb

@@ -45,6 +45,8 @@ module Cattri
       # @option options [Boolean] :reader whether to define a reader method (default: true)
       # @option options [Boolean] :writer whether to define a writer method (default: true)
       # @option options [Symbol] :access method visibility (:public, :protected, :private)
+      # @option options [Boolean] :predicate whether to define a predicate-style alias method
+      #   (e.g., `foo?`) for the attribute
       # @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
@@ -53,7 +55,15 @@ module Cattri
       def instance_attribute(*names, **options, &block)
         raise Cattri::AmbiguousBlockError if names.size > 1 && block_given?
 
-        names.each { |name| define_instance_attribute(name, options, block) }
+        names.each do |name|
+          if name.end_with?("?")
+            raise Cattri::AttributeError,
+                  "Attribute names ending in '?' are not allowed. Use `predicate: true` or `iattr_alias` instead."
+
+          end
+
+          define_instance_attribute(name, options, block)
+        end
       end
 
       # Defines a read-only instance-level attribute.
@@ -65,6 +75,8 @@ module Cattri
       # @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)
+      # @option options [Boolean] :predicate whether to define a predicate-style alias method
+      #   (e.g., `foo?`) for the attribute
       # @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
@@ -76,7 +88,8 @@ module Cattri
 
       # Defines a write-only instance-level attribute.
       #
-      # Equivalent to `instance_attribute(..., reader: false)`
+      # Equivalent to `instance_attribute(..., reader: false)`. The predicate: option is not allowed
+      # when defining writer methods.
       #
       # @param names [Array<Symbol | String>] the names of the attributes to define
       # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
@@ -89,7 +102,7 @@ module Cattri
       #    already defined or an error occurs while defining methods)
       # @return [void]
       def instance_attribute_writer(*names, **options, &block)
-        instance_attribute(*names, **options.merge(reader: false), &block)
+        instance_attribute(*names, **options.merge(reader: false, predicate: false), &block)
       end
 
       # Updates the setter behavior of an existing instance-level attribute.
@@ -119,11 +132,33 @@ module Cattri
         Cattri::AttributeDefiner.define_writer!(attribute, context)
       end
 
+      # Defines an alias method for an existing instance-level attribute.
+      #
+      # This does **not** register a new attribute; it simply defines a method
+      # (e.g., a predicate-style alias like `foo?`) that delegates to an existing one.
+      #
+      # The alias method inherits the visibility of the original attribute.
+      #
+      # @param alias_name [Symbol, String] the new method name (e.g., `:foo?`)
+      # @param original [Symbol, String] the name of the existing attribute to delegate to (e.g., `:foo`)
+      # @raise [Cattri::AttributeNotDefinedError] if the original attribute is not defined
+      # @return [void]
+      def instance_attribute_alias(alias_name, original)
+        attribute = __cattri_instance_attributes[original.to_sym]
+        raise Cattri::AttributeNotDefinedError.new(:instance, original) if attribute.nil?
+
+        context.define_method(attribute, name: alias_name) { public_send(original) }
+      end
+
       # Returns a list of defined instance-level attribute names.
       #
       # @return [Array<Symbol>]
       def instance_attributes
-        __cattri_instance_attributes.keys
+        ([self] + ancestors + singleton_class.included_modules)
+          .uniq
+          .select { |mod| mod.respond_to?(:__cattri_instance_attributes, true) }
+          .flat_map { |mod| mod.send(:__cattri_instance_attributes).keys }
+          .uniq
       end
 
       # Checks if an instance-level attribute has been defined.
@@ -144,34 +179,47 @@ module Cattri
 
       # @!method iattr(name, **options, &block)
       #   Alias for {#instance_attribute}
+      #   @see #instance_attribute
       alias iattr instance_attribute
 
       # @!method iattr_accessor(name, **options, &block)
       #   Alias for {#instance_attribute}
+      #   @see #instance_attribute
       alias iattr_accessor instance_attribute
 
       # @!method iattr_reader(name, **options)
       #   Alias for {#instance_attribute_reader}
+      #   @see #instance_attribute_reader
       alias iattr_reader instance_attribute_reader
 
       # @!method iattr_writer(name, **options, &block)
       #   Alias for {#instance_attribute_writer}
+      #   @see #instance_attribute_writer
       alias iattr_writer instance_attribute_writer
 
       # @!method iattr_setter(name, &block)
       #   Alias for {#instance_attribute_setter}
+      #   @see #instance_attribute_setter
       alias iattr_setter instance_attribute_setter
 
+      # @!method iattr_alias(name, &block)
+      #   Alias for {#instance_attribute_alias}
+      #   @see #instance_attribute_alias
+      alias iattr_alias instance_attribute_alias
+
       # @!method iattrs
       #   Alias for {#instance_attributes}
+      #   @see #instance_attributes
       alias iattrs instance_attributes
 
       # @!method iattr_defined?(name)
       #   Alias for {#instance_attribute_defined?}
+      #   @see #instance_attribute_defined?
       alias iattr_defined? instance_attribute_defined?
 
       # @!method iattr_definition(name)
       #   Alias for {#instance_attribute_definition}
+      #   @see #instance_attribute_definition
       alias iattr_definition instance_attribute_definition
 
       private
@@ -190,7 +238,7 @@ module Cattri
       # @raise [Cattri::AttributeDefinitionError] if method definition fails
       #
       # @return [void]
-      def define_instance_attribute(name, options, block)
+      def define_instance_attribute(name, options, block) # rubocop:disable Metrics/AbcSize
         options[:access] ||= __cattri_visibility
         attribute = Cattri::Attribute.new(name, :instance, options, block)
 
@@ -202,6 +250,8 @@ module Cattri
         rescue StandardError => e
           raise Cattri::AttributeDefinitionError.new(self, attribute, e)
         end
+
+        context.define_method(attribute, name: :"#{name}?") { !!send(attribute.name) } if options[:predicate]
       end
 
       # Internal registry of instance attributes defined on the class.

data/lib/cattri/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cattri
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Nathan Lucas