structure 3.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f0f08ca763d757b47a9ff12c51168361a37acdfec5db9d7c45a82c15f9059fb
-  data.tar.gz: 7ea79c6470d4fabe005474f572bf3f9564217dca45f18b118babf94c6e8ef36f
+  metadata.gz: 91e04b84b8e6a19728bf6212bdfd08895187bbe59ebf56b47288697962ed31b2
+  data.tar.gz: '028e8df792d344faa2850f82504d223a6691c195203c51acd53581ee9e97064c'
 SHA512:
-  metadata.gz: c37505be3556ec54d0277008506868f4fade809f8baa800336f54b32ceca265c61ee232ceca7326b2104793d6af8a6022fb193c61fbb28aaeb9d0493223b6677
-  data.tar.gz: 725e923fddcb8cca372340d12c9cf67c38d20782dac2a1fc2b1273e06e12d6cc712668c6a634d32af4661d8b70c8369e25fda5109e6e80e97ad65ddc0babf8d7
+  metadata.gz: 4e6fbbd3104fc0ed9001d66395606ab436a907cf3b1ab09f692c458b99e999e648e7b558dd0b2e8e4fb298d2c1c25decf51bef0ad5889bc9ff14f6d821c62ede
+  data.tar.gz: 74752c31b2898fea6c7d5c94e568f7fa9ca2724e116aa62e9d9c30f0da77d3f6f7de7b73540a8837834536bc2aa9b87f9d5b596ddd0bfd2089222e3fbec07334

data/lib/structure/builder.rb

@@ -5,7 +5,7 @@ require "structure/types"
 module Structure
   # Builder class for accumulating attribute definitions
   class Builder
-    attr_reader :mappings, :types, :defaults
+    attr_reader :mappings, :types, :defaults, :after_parse_callback
 
     def initialize
       @mappings = {}
@@ -13,6 +13,25 @@ module Structure
       @defaults = {}
     end
 
+    # DSL method for defining attributes with optional type coercion
+    #
+    # @param name [Symbol] The attribute name
+    # @param type [Class, Symbol, Array, nil] Type for coercion (e.g., String, :boolean, [String])
+    # @param from [String, nil] Source key in the data hash (defaults to name.to_s)
+    # @param default [Object, nil] Default value if attribute is missing
+    # @yield [value] Block for custom transformation
+    # @raise [ArgumentError] If both type and block are provided
+    #
+    # @example With type coercion
+    #   attribute :age, Integer
+    #
+    # @example With custom source key
+    #   attribute :created_at, Time, from: "CreatedAt"
+    #
+    # @example With transformation block
+    #   attribute :price do |value|
+    #     Money.new(value["amount"], value["currency"])
+    #   end
     def attribute(name, type = nil, from: nil, default: nil, &block)
       # Always store in mappings - use attribute name as default source
       @mappings[name] = from || name.to_s
@@ -27,15 +46,26 @@ module Structure
       end
     end
 
-    # Deduced from mappings - maintains order of definition
+    # Defines a callback to run after parsing
+    #
+    # @yield [instance] Block that receives the parsed instance
+    # @return [void]
+    #
+    # @example Validation
+    #   after_parse do |order|
+    #     raise "Invalid order" if order.total < 0
+    #   end
+    def after_parse(&block)
+      @after_parse_callback = block
+    end
+
     def attributes
       @mappings.keys
     end
 
-    # Deduced from types that are boolean
     def predicate_methods
       @types.filter_map do |name, type_lambda|
-        if type_lambda == Types.boolean
+        if type_lambda == Types.boolean && !name.to_s.end_with?("?")
           predicate_name = "#{name}?"
           [predicate_name.to_sym, name]
         end

data/lib/structure/types.rb

@@ -10,37 +10,35 @@ module Structure
     BOOLEAN_TRUTHY = [true, 1, "1", "t", "T", "true", "TRUE", "on", "ON"].freeze
     private_constant :BOOLEAN_TRUTHY
 
-    # Boolean conversion
     def boolean
       @boolean ||= ->(val) { BOOLEAN_TRUTHY.include?(val) }
     end
 
-    # Generic handler for classes with kernel methods (String, Integer, Float, etc.)
-    def kernel(type)
-      ->(val) { Kernel.send(type.name, val) }
-    end
-
-    # Handler for nested Structure classes
-    def structure(type)
-      ->(val) { type.parse(val) }
-    end
-
-    # Create coercer for array elements
-    def array(element_type)
-      element_coercer = coerce(element_type)
-      ->(array) { array.map { |element| element_coercer.call(element) } }
-    end
-
     # Main factory method for creating type coercers
+    #
+    # @param type [Class, Symbol, Array] Type specification
+    # @return [Proc, Object] Coercion proc or the type itself if no coercion available
+    #
+    # @example Boolean type
+    #   coerce(:boolean) # => boolean proc
+    #
+    # @example Kernel types
+    #   coerce(Integer) # => proc that calls Kernel.Integer
+    #
+    # @example Parseable types
+    #   coerce(Date) # => proc that calls Date.parse
+    #
+    # @example Array types
+    #   coerce([String]) # => proc that coerces array elements to String
     def coerce(type)
       case type
       when :boolean
         boolean
-      when Class
+      when Class, Module
         if type.name && Kernel.respond_to?(type.name)
           kernel(type)
         elsif type.respond_to?(:parse)
-          structure(type)
+          parseable(type)
         else
           type
         end
@@ -54,5 +52,20 @@ module Structure
         type
       end
     end
+
+    private
+
+    def kernel(type)
+      ->(val) { Kernel.send(type.name, val) }
+    end
+
+    def parseable(type)
+      ->(val) { type.parse(val) }
+    end
+
+    def array(element_type)
+      element_coercer = coerce(element_type)
+      ->(array) { array.map { |element| element_coercer.call(element) } }
+    end
   end
 end

data/lib/structure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Structure
-  VERSION = "3.0.0"
+  VERSION = "3.1.1"
 end

data/lib/structure.rb

@@ -5,6 +5,20 @@ require "structure/builder"
 # A library for parsing data into immutable Ruby Data objects with type coercion
 module Structure
   class << self
+    # Creates a new Data class with attribute definitions and type coercion
+    #
+    # @yield [Builder] Block for defining attributes using the DSL
+    # @return [Class] A Data class with a parse method
+    #
+    # @example Basic usage
+    #   Person = Structure.new do
+    #     attribute :name, String
+    #     attribute :age, Integer
+    #   end
+    #
+    #   person = Person.parse(name: "Alice", age: "30")
+    #   person.name # => "Alice"
+    #   person.age  # => 30
     def new(&block)
       builder = Builder.new
       builder.instance_eval(&block) if block
@@ -23,6 +37,7 @@ module Structure
       types = builder.types
       defaults = builder.defaults
       attributes = builder.attributes
+      after_parse_callback = builder.after_parse_callback
 
       data_class.define_singleton_method(:parse) do |data = {}, **kwargs|
         # Merge kwargs into data - kwargs take priority as overrides
@@ -48,7 +63,10 @@ module Structure
 
           final_kwargs[attr] = value
         end
-        new(**final_kwargs)
+
+        instance = new(**final_kwargs)
+        after_parse_callback&.call(instance)
+        instance
       end
 
       data_class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structure
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Hakan Ensari
@@ -9,7 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Parse data into immutable Ruby Data objects with type coercion
+description: Provides a DSL for generating immutable Ruby Data objects with type coercion
+  and data transformation capabilities.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -38,5 +39,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Structure your data!
+summary: Structure your data
 test_files: []