shale-builder 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da77acaa0e4c63b3155b114625c4da322066c92447ce1297915eac5e4facef71
-  data.tar.gz: 043214cb3659bc261089c29306082051e1cf14dc222e8852336b9cf9f4dd102e
+  metadata.gz: febc908c436d767296b5869c0f83de5192ebd2dea56649a68840f951ca61210e
+  data.tar.gz: 921efc21393a6a01516dc0954efe6f87fe74326d51d1969c00e985f3f8ad9824
 SHA512:
-  metadata.gz: 2e00a2bbeb8ba5c240543520d7a881e2b10fc3e79cf941250230c5906e7ba85742b31611a04154f45e953ba8ec16a1c6dbbd5dc7c6a72e895d25f646e01a19b7
-  data.tar.gz: 1f5462ad104ca4ffdb7f68d895a517d70dd67b7fe666da7baed61bddd2c68de101061d992abad6895045cb6dc8c958ec59a57cc39cbc51a8fb56056e1bafd5ed
+  metadata.gz: 315da1873bcba3a08cbf4a6d405b975a8c9be51442726faab0e886138be48b50fa6bec7c5367064d1d0cc731af17ec0c10bbe9cfb04716a5b1d0712de46244a5
+  data.tar.gz: 54df3a9708bc1e327ecb7f85338a1420cca5b98d82b754acbecd03417541951472b9f2d005035abe5fe1217bfd5db10d3730a1966043c65956b3cdb83d080299

data/CHANGELOG.md

@@ -5,9 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-10-15
+
+[Diff](https://github.com/Verseth/ruby-shale-builder/compare/v0.4.1...v0.5.0)
+
+### Changes
+- Add `Shale::Builder::AssignedAttributes` module which grants a shale mapper class with the ability to record which attributes have been assigned
+- Add `Shale::Builder::Value` which represents a value of a shale attribute.
+- Add `Shale::Builder#attribute_values`, a method that returns an array of `Shale::Builder::Value` objects for each attribute.
+
+## [0.4.1] - 2025-10-14
+
+[Diff](https://github.com/Verseth/ruby-shale-builder/compare/v0.4.0...v0.4.1)
+
+### Changes
+- Fix `Shale::Builder::alias_attribute`, improve changelog
+
 ## [0.4.0] - 2025-10-14
 
-[Diff](https://github.com/Verseth/ruby-shale-builder/compare/v0.3.0...v0.2.1)
+[Diff](https://github.com/Verseth/ruby-shale-builder/compare/v0.3.0...v0.4.0)
 
 ### Changes
 - Add `Shale::Builder::NestedValidations`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shale-builder (0.4.0)
+    shale-builder (0.5.0)
       booleans (>= 0.1)
       shale (< 2.0)
       sorbet-runtime (> 0.5)

data/README.md

@@ -263,50 +263,67 @@ obj.errors.messages #=> {cvv_code: ["can't be blank"], "amount.value": ["can't b
 
 You MUST include `ActiveModel::Validations` before `Shale::Builder::NestedValidations`.
 
-### Attribute aliases
+### Recording Assigned Attributes
 
-You can easily create aliases for attributes using `alias_attribute`
+There is an additional module `Shale::Builder::AssignedAttributes` that provides
+support for recording which attributes have been assigned in a shale mapper object.
+
+In order to load it do:
+
+```rb
+require 'shale/builder/assigned_attributes'
+```
 
 Then you can use it like so
 
 ```rb
 class AmountType < ::Shale::Mapper
     include ::Shale::Builder
-    include ::ActiveModel::Validations
-    include ::Shale::Builder::NestedValidations
+    include ::Shale::Builder::AssignedAttributes
 
     attribute :value, ::Shale::Type::Float
     attribute :currency, ::Shale::Type::String
-
-    validates :value, presence: true
 end
 
-class TransactionType < ::Shale::Mapper
-    include ::Shale::Builder
-    include ::ActiveModel::Validations
-    include ::Shale::Builder::NestedValidations
+obj = AmountType.new
+obj.assigned_attribute_names #=> #<Set: {}>
 
-    attribute :cvv_code, ::Shale::Type::String
-    attribute :amount, AmountType
+obj.value = 3
+obj.assigned_attribute_names #=> #<Set: {:value}>
+obj.assigned_attributes #=> [#<Shale::Attribute:0x000000011e959b50 @collection=false, @default=nil, @doc=nil, @name=:value, @setter="value=", @type=Shale::Type::Float>]
+obj.assigned_values #=> [#<Shale::Builder::Value:0x000000011d693318 @attribute=#<Shale::Attribute:0x000000011e959b50 @collection=false, @default=nil, @doc=nil, @name=:value, @setter="value=", @type=Shale::Type::Float>, @value=3.0>]
+```
 
-    validates :cvv_code, presence: true
-    validates :amount, presence: true
+- `assigned_attribute_names` returns a set of attribute names
+- `assigned_attributes` returns an array of attribute definitions
+- `assigned_values` returns an array of `Shale::Builder::Value`, which contains the current value of an attribute and a reference to its definition
+
+### Attribute aliases
+
+You can easily create aliases for attributes using `alias_attribute`
+
+Then you can use it like so
+
+```rb
+require 'shale/builder'
+
+class Amount < Shale::Mapper
+    include Shale::Builder
+
+    attribute :value, Shale::Type::Float
+    attribute :currency, Shale::Type::String
+
+    alias_attribute :val, :value
 end
 
-obj = TransactionType.build do |t|
-    t.amount do |a|
-        a.currency = 'USD'
-    end
+a = Amount.build do |a|
+    a.val = 3.2
 end
 
-obj.valid? #=> false
-obj.errors #=> #<ActiveModel::Errors [#<ActiveModel::Error attribute=cvv_code, type=blank, options={}>, #<ActiveModel::NestedError attribute=amount.value, type=blank, options={}>]>
-obj.errors.messages #=> {cvv_code: ["can't be blank"], "amount.value": ["can't be blank"]}
+a.val #=> 3.2
+a.value #=> 3.2
 ```
 
-You MUST include `ActiveModel::Validations` before `Shale::Builder::NestedValidations`.
-
-
 ### Sorbet support
 
 Shale-builder adds support for sorbet and tapioca.

data/lib/shale/attribute.rb

@@ -9,15 +9,15 @@ module Shale
 
     # Contains the documentation comment for the shale attribute
     # in a Ruby String.
-    sig { returns(T.nilable(String)) }
+    #: String?
     attr_accessor :doc
 
     # Contains the documentation comment for the shale attribute
     # in a Ruby String.
-    sig { returns(T.nilable(T::Array[Symbol])) }
+    #: Array[Symbol]?
     attr_accessor :aliases
 
-    sig { returns(T::Array[Symbol]) }
+    #: -> Array[Symbol]
     def all_names
       names = [name]
       aliases = self.aliases
@@ -25,5 +25,12 @@ module Shale
 
       names + aliases
     end
+
+    # Returns `true` if the attribute is handled by a shale mapper.
+    #
+    #: -> bool
+    def mapper?
+      type.is_a?(Class) && type < Shale::Mapper
+    end
   end
 end

data/lib/shale/builder/assigned_attributes.rb

@@ -0,0 +1,94 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'shale'
+require 'booleans'
+
+module Shale
+  module Builder
+    # Include in a class that already includes `Shale::Builder` to add support
+    # for getting a list of attributes that have been assigned.
+    #
+    # @requires_ancestor: Object
+    module AssignedAttributes
+      extend T::Sig
+      extend T::Helpers
+
+      class << self
+        extend T::Sig
+
+        # Gets called after including this module in a module or class.
+        #: (Module mod) -> void
+        def included(mod)
+          mod.extend ClassMethods
+          AssignedAttributes.prepare_mod(mod)
+        end
+
+        # Prepares the received module or class
+        # for dynamic method definition.
+        #: (Module mod) -> void
+        def prepare_mod(mod)
+          assigned_attributes_methods_module = ::Module.new
+          mod.instance_variable_set :@assigned_attributes_methods_module, assigned_attributes_methods_module
+          mod.include assigned_attributes_methods_module
+        end
+      end
+
+      # @requires_ancestor: singleton(Shale::Mapper)
+      module ClassMethods
+        extend T::Sig
+
+        # Contains overridden getter methods for attributes
+        # with complex types (so that they accept a block for building)
+        #: Module
+        attr_reader :assigned_attributes_methods_module
+
+        #: (String | Symbol name, Class type, ?collection: bool, ?default: Proc?, ?doc: String?, **untyped kwargs) ?{ -> void } -> void
+        def attribute(name, type, collection: false, default: nil, doc: nil, **kwargs, &block)
+          super
+
+          @assigned_attributes_methods_module.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}=(val)
+              super
+              return unless @__initialized
+
+              self.assigned_attribute_names << #{name.to_sym.inspect}
+            end
+          RUBY
+        end
+      end
+      mixes_in_class_methods ClassMethods
+
+      # Returns a set of names of assigned shale attributes.
+      #
+      #: -> Set[Symbol]
+      def assigned_attribute_names
+        @assigned_attribute_names ||= Set.new
+      end
+
+      # Returns an array of shale attributes
+      # that have been assigned.
+      #
+      #: -> Array[Shale::Attribute]
+      def assigned_attributes
+        klass = self.class #: as untyped
+        assigned_attribute_names.map do |name|
+          klass.attributes.fetch(name)
+        end
+      end
+
+      # Returns an array of shale values
+      # that have been assigned.
+      #
+      #: -> Array[Shale::Builder::Value]
+      def assigned_values
+        klass = self.class #: as untyped
+        assigned_attribute_names.map do |name|
+          attr = klass.attributes.fetch(name)
+          Shale::Builder::Value.new(attr, public_send(attr.name))
+        end
+      end
+
+    end
+  end
+end

data/lib/shale/builder/nested_validations.rb

@@ -6,7 +6,7 @@ require 'booleans'
 
 module Shale
   module Builder
-    # Include in a class tha already includes `Shale::Builder` to add support
+    # Include in a class that already includes `Shale::Builder` to add support
     # for nested ActiveModel validations.
     #
     # @requires_ancestor: Object

data/lib/shale/builder/value.rb

@@ -0,0 +1,30 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'shale'
+
+module Shale
+  module Builder
+    # Represents a value of a particular shale attribute.
+    # Hold the value and a reference to the attribute definition.
+    class Value
+      extend T::Sig
+
+      # Shale attribute definition
+      #
+      #: Shale::Attribute
+      attr_reader :attribute
+
+      # Value of the attribute.
+      #
+      #: untyped
+      attr_reader :value
+
+      #: (Shale::Attribute, untyped) -> void
+      def initialize(attribute, value)
+        @attribute = attribute
+        @value = value
+      end
+    end
+  end
+end

data/lib/shale/builder/version.rb

@@ -2,6 +2,6 @@
 
 module Shale
   module Builder
-    VERSION = '0.4.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/shale/builder.rb

@@ -39,6 +39,7 @@ module Shale
   #           end
   #       end
   #
+  # @requires_ancestor: Object
   module Builder
     extend T::Sig
     extend T::Helpers
@@ -47,7 +48,7 @@ module Shale
       extend T::Sig
 
       # Gets called after including this module in a module or class.
-      sig { params(mod: Module).void }
+      #: (Module mod) -> void
       def included(mod)
         mod.extend ClassMethods
         Builder.prepare_mod(mod)
@@ -55,7 +56,7 @@ module Shale
 
       # Prepares the received module or class
       # for dynamic method definition.
-      sig { params(mod: Module).void }
+      #: (Module mod) -> void
       def prepare_mod(mod)
         builder_methods_module = ::Module.new
         mod.instance_variable_set :@builder_methods_module, builder_methods_module
@@ -71,7 +72,7 @@ module Shale
       abstract!
       has_attached_class!
 
-      sig { params(subclass: Class).void }
+      #: (Class subclass) -> void
       def inherited(subclass)
         super
         Builder.prepare_mod(subclass)
@@ -79,10 +80,10 @@ module Shale
 
       # Contains overridden getter methods for attributes
       # with complex types (so that they accept a block for building)
-      sig { returns(Module) }
+      #: Module
       attr_reader :builder_methods_module
 
-      sig { params(_block: T.proc.params(arg0: T.attached_class).void).returns(T.attached_class) }
+      #: { (instance arg0) -> void } -> instance
       def build(&_block)
         body = new
         yield(body)
@@ -96,17 +97,7 @@ module Shale
       sig { abstract.returns(T::Hash[Symbol, Shale::Attribute]) }
       def attributes; end
 
-      sig do
-        params(
-          name:       T.any(String, Symbol),
-          type:       Class,
-          collection: T::Boolean,
-          default:    T.nilable(Proc),
-          doc:        T.nilable(String),
-          kwargs:     Object,
-          block:      T.nilable(T.proc.void),
-        ).void
-      end
+      #: ((String | Symbol) name, Class type, ?collection: bool, ?default: Proc?, ?doc: String?, **Object kwargs) ?{ -> void } -> void
       def attribute(name, type, collection: false, default: nil, doc: nil, **kwargs, &block)
         super(name, type, collection:, default:, **kwargs, &block)
         if (attr_def = attributes[name.to_sym])
@@ -140,27 +131,46 @@ module Shale
         RUBY
       end
 
-    end
-    mixes_in_class_methods(ClassMethods)
+      # Create an alias for the getter and setter of an attribute.
+      #: (Symbol new_name, Symbol old_name) -> void
+      def alias_attribute(new_name, old_name)
+        attr = attributes.fetch(old_name)
+        (attr.aliases ||= []) << new_name
 
-    # Create an alias for the getter and setter of an attribute.
-    sig { params(new_name: Symbol, old_name: Symbol).void }
-    def alias_attribute(new_name, old_name)
-      klass = T.unsafe(self).class
+        builder_methods_module.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{new_name}
+            #{old_name}
+          end
 
-      attr = klass.attributes[old_name]
-      (attr.aliases ||= []) << new_name
+          def #{new_name}=(val)
+            self.#{old_name} = val
+          end
+        RUBY
+      end
 
-      klass.builder_methods_module.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-        def #{new_name}
-          #{old_name}
-        end
+    end
+    mixes_in_class_methods(ClassMethods)
 
-        def #{new_name}=(val)
-          self.#{old_name} = val
-        end
-      RUBY
+    def initialize(*args, **kwargs, &block)
+      super
+      @__initialized = true
+    end
+
+    #: bool?
+    attr_reader :__initialized
+
+    # Returns an array of shale values
+    # that have been assigned.
+    #
+    #: -> Array[Shale::Builder::Value]
+    def attribute_values
+      klass = self.class #: as untyped
+      klass.attributes.map do |name, attr|
+        Shale::Builder::Value.new(attr, public_send(name))
+      end
     end
 
   end
 end
+
+require_relative 'builder/value'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shale-builder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mateusz Drewniak
@@ -69,7 +69,9 @@ files:
 - Rakefile
 - lib/shale/attribute.rb
 - lib/shale/builder.rb
+- lib/shale/builder/assigned_attributes.rb
 - lib/shale/builder/nested_validations.rb
+- lib/shale/builder/value.rb
 - lib/shale/builder/version.rb
 - lib/shale/mapper.rbi
 - lib/tapioca/dsl/compilers/shale.rb