cattri 0.1.0

data/lib/cattri/instance_attributes.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Provides a DSL for defining instance-level attributes with support for:
+  #
+  # - Default values (static or callable)
+  # - Optional reader/writer method generation
+  # - Custom coercion logic for writers
+  # - Full attribute metadata access and reset capabilities
+  #
+  # This module is designed for mixin into classes or modules that want to offer
+  # configurable instance attributes (e.g., plugin systems, DTOs, DSLs).
+  #
+  # Example:
+  #
+  #   class MyObject
+  #     extend Cattri::InstanceAttributes
+  #
+  #     iattr :name, default: "anonymous"
+  #     iattr_writer :age, default: 0 do |v|
+  #       Integer(v)
+  #     end
+  #   end
+  #
+  #   obj = MyObject.new
+  #   obj.name # => "anonymous"
+  #   obj.age = "42"
+  #   obj.instance_variable_get(:@age) # => 42
+  module InstanceAttributes
+    include Cattri::Helpers
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods for defining instance attributes
+    module ClassMethods
+      include Cattri::Helpers
+
+      # Default options for all instance attributes
+      DEFAULT_OPTIONS = { default: nil, reader: true, writer: true }.freeze
+
+      # Defines a new instance-level attribute with optional default and coercion.
+      #
+      # @param name [Symbol, String] the name of the attribute
+      # @param options [Hash] additional options like `:default`, `:reader`, `:writer`
+      # @option options [Object, Proc] :default the default value or proc returning the value
+      # @option options [Boolean] :reader whether to define a reader method (default: true)
+      # @option options [Boolean] :writer whether to define a writer method (default: true)
+      # @yield [value] optional coercion logic for the writer
+      # @return [void]
+      def instance_attribute(name, **options, &block)
+        name, definition = define_attribute(name, options, block, DEFAULT_OPTIONS)
+        __cattri_instance_attributes[name] = definition
+
+        define_reader(name, definition) if options.fetch(:reader, true)
+        define_writer(name, definition) if options.fetch(:writer, true)
+      end
+
+      # Defines a read-only instance-level attribute.
+      #
+      # @param name [Symbol, String]
+      # @param options [Hash]
+      # @return [void]
+      def instance_attribute_reader(name, **options)
+        instance_attribute(name, writer: false, **options)
+      end
+
+      # Defines a write-only instance-level attribute.
+      #
+      # @param name [Symbol, String]
+      # @param options [Hash]
+      # @yield [value] coercion logic
+      # @return [void]
+      def instance_attribute_writer(name, **options, &block)
+        instance_attribute(name, reader: false, **options, &block)
+      end
+
+      def __cattri_instance_attributes
+        @__cattri_instance_attributes ||= {}
+      end
+
+      # Returns all defined instance-level attribute names.
+      #
+      # @return [Array<Symbol>]
+      def instance_attributes
+        __cattri_instance_attributes.keys
+      end
+
+      # Checks whether an instance attribute is defined.
+      #
+      # @param name [Symbol, String]
+      # @return [Boolean]
+      def instance_attribute_defined?(name)
+        __cattri_instance_attributes.key?(name.to_sym)
+      end
+
+      # Fetches the full definition hash for a specific attribute.
+      #
+      # @param name [Symbol, String]
+      # @return [Hash, nil]
+      def instance_attribute_definition(name)
+        __cattri_instance_attributes[name.to_sym]
+      end
+
+      # @!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 iattrs
+      #   @return [Hash<Symbol, Hash>] all defined attributes
+      #   @see .instance_attributes
+      alias iattrs instance_attributes
+
+      # @!method iattr_defined?(name)
+      #   @return [Boolean]
+      #   @see .instance_attribute_defined?
+      alias iattr_defined? instance_attribute_defined?
+
+      # @!method iattr_for(name)
+      #   @return [Hash, nil]
+      #   @see .instance_attribute_definition
+      alias iattr_definition instance_attribute_definition
+
+      private
+
+      # Defines the reader method for an instance attribute.
+      #
+      # @param name [Symbol] attribute name
+      # @param definition [Hash] full attribute definition
+      def define_reader(name, definition)
+        ivar = definition[:ivar]
+
+        define_method(name) do
+          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+          value = definition[:default].call
+          instance_variable_set(ivar, value)
+        end
+      end
+
+      # Defines the writer method for an instance attribute.
+      #
+      # @param name [Symbol] attribute name
+      # @param definition [Hash] full attribute definition
+      def define_writer(name, definition)
+        define_method("#{name}=") do |value|
+          coerced_value = definition[:setter].call(value)
+          instance_variable_set(definition[:ivar], coerced_value)
+        end
+      end
+    end
+
+    # Resets all defined attributes to their default values.
+    #
+    # @return [void]
+    def reset_instance_attributes!
+      reset_attributes!(self, self.class.__cattri_instance_attributes.values)
+    end
+
+    # Resets a specific attribute to its default value.
+    #
+    # @param name [Symbol, String]
+    # @return [void]
+    def reset_instance_attribute!(name)
+      definition = self.class.__cattri_instance_attributes[name]
+      return unless definition
+
+      reset_attributes!(self, [definition])
+    end
+
+    # @!method reset_iattrs!
+    #   @return [void]
+    #   @see .reset_instance_attributes!
+    alias reset_iattrs! reset_instance_attributes!
+
+    # @!method reset_iattr!(name)
+    #   @return [void]
+    #   @see .reset_instance_attribute!
+    alias reset_iattr! reset_instance_attribute!
+  end
+end

data/lib/cattri/introspection.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cattri
+  # Adds debugging and inspection helpers for reading the current values of
+  # class- and instance-level attributes defined via Cattri.
+  #
+  # This module is intended for use in development and test environments to
+  # help capture attribute state at a given moment.
+  #
+  # It can be included in any class or module that uses {Cattri::ClassAttributes}
+  # or {Cattri::InstanceAttributes}.
+  #
+  # @example
+  #   class MyConfig
+  #     extend Cattri::ClassAttributes
+  #     include Cattri::Introspection
+  #
+  #     cattr :items, default: []
+  #   end
+  #
+  #   MyConfig.items << :a
+  #   MyConfig.snapshot_class_attributes #=> { items: [:a] }
+  module Introspection
+    # Hook called when the module is included. Extends the base with class methods.
+    #
+    # @param base [Class, Module]
+    # @return [void]
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods for introspection.
+    module ClassMethods
+      # Returns a hash of current class attribute values.
+      #
+      # @return [Hash<Symbol, Object>] a snapshot of each defined class attribute
+      def snapshot_class_attributes
+        return {} unless respond_to?(:class_attributes)
+
+        class_attributes.each_with_object({}) do |attribute, hash|
+          hash[attribute] = send(attribute)
+        end
+      end
+
+      # @!method snapshot_cattrs
+      #   Alias for {.snapshot_class_attributes}
+      #   @see .snapshot_class_attributes
+      alias snapshot_cattrs snapshot_class_attributes
+    end
+
+    # Returns a hash of current instance attribute values for this object.
+    #
+    # @return [Hash<Symbol, Object>] a snapshot of each defined instance attribute
+    def snapshot_instance_attributes
+      return {} unless self.class.respond_to?(:instance_attributes)
+
+      self.class.instance_attributes.each_with_object({}) do |attribute, hash|
+        hash[attribute] = send(attribute)
+      rescue NoMethodError
+        # Catch for write-only methods
+        hash[attribute] = instance_variable_get(:"@#{attribute}")
+      end
+    end
+
+    # @!method snapshot_iattrs
+    #   Alias for {#snapshot_instance_attributes}
+    #   @see #snapshot_instance_attributes
+    alias snapshot_iattrs snapshot_instance_attributes
+  end
+end

data/lib/cattri/version.rb

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

data/lib/cattri.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "cattri/version"
+require_relative "cattri/class_attributes"
+require_relative "cattri/instance_attributes"
+require_relative "cattri/introspection"
+
+# The primary entry point for the Cattri gem.
+#
+# When included, it adds support for both class-level and instance-level
+# attribute declarations using `cattr` and `iattr` style methods.
+#
+# This module does **not** include introspection helpers by default —
+# use `include Cattri::Introspection` explicitly if needed.
+#
+# @example Using both class and instance attributes
+#   class MyConfig
+#     include Cattri
+#
+#     cattr :enabled, default: true
+#     iattr :name, default: "anonymous"
+#   end
+#
+#   MyConfig.enabled # => true
+#   MyConfig.new.name # => "anonymous"
+module Cattri
+  # Hook triggered when `include Cattri` is called.
+  # Adds class and instance attribute support to the target.
+  #
+  # @param base [Class, Module] the receiving class or module
+  # @return [void]
+  def self.included(base)
+    base.extend(Cattri::ClassAttributes)
+    base.include(Cattri::InstanceAttributes)
+  end
+end

data/sig/cattri.rbs

@@ -0,0 +1,4 @@
+module Cattri
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: cattri
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nathan Lucas
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-html
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Cattri provides a clean DSL for defining class-level and instance-level
+  attributes with optional defaults, coercion, accessors, and inheritance support.
+email:
+- bnlucas@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".idea/workspace.xml"
+- ".rspec"
+- ".rspec_status"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- cattri.gemspec
+- lib/cattri.rb
+- lib/cattri/class_attributes.rb
+- lib/cattri/error.rb
+- lib/cattri/helpers.rb
+- lib/cattri/instance_attributes.rb
+- lib/cattri/introspection.rb
+- lib/cattri/version.rb
+- sig/cattri.rbs
+homepage: https://github.com/bnlucas/cattri
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bnlucas/cattri
+  source_code_uri: https://github.com/bnlucas/cattri
+  changelog_uri: https://github.com/bnlucas/cattri/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.4
+signing_key:
+specification_version: 4
+summary: Simple class and instance attribute DSL for Ruby.
+test_files: []