object_forge 0.3.0 → 0.4.0

data/lib/object_forge/forge.rb

@@ -5,7 +5,12 @@ require_relative "forge_dsl"
 require_relative "molds"
 
 module ObjectForge
-  # Object instantitation forge.
+  # Object building forge.
+  #
+  # Usually created through {.define} or {Forgeyard#define} using {ForgeDSL}.
+  # Alternatively, can be directly initalized with {Parameters} if you prefer not using the DSL.
+  #
+  # Then, {#forge} can be called to build instances of {#forge_target}.
   #
   # @since 0.1.0
   class Forge
@@ -14,62 +19,72 @@ module ObjectForge
     # through means other than {ForgeDSL}.
     #
     # @!attribute [r] attributes
-    #   Non-trait values of the attributes.
-    #   @return [Hash{Symbol => Any}]
+    #   Default values of the attributes.
+    #   @return [Hash{Symbol => Proc, Any}]
     #
     # @!attribute [r] traits
     #   Attributes belonging to traits.
-    #   @return [Hash{Symbol => Hash{Symbol => Any}}]
-    #
-    # @!attribute [r] settings
-    #   A forge's settings.
-    #   Must include a +:mold+ key, containing an object that knows how to build the instance
-    #   with a +call+ method that takes a class and a hash of attributes.
+    #   @return [Hash{Symbol => Hash{Symbol => Proc, Any}}]
+    #
+    # @!attribute [r] options
+    #   A forge's options.
+    #   Known options:
+    #   - +:mold+ — a +call+able object that knows how to build the instance,
+    #     taking a class and a hash of attributes.
+    #   - +:crucible+ — a +call+able object that knows how to resolve attributes,
+    #     taking a hash of initial attributes.
+    #   - +:after_forge+/+:after_build+ — a +call+able object that is passed
+    #     the forged instance and can do anything with it.
     #   @since 0.3.0
     #   @return [Hash{Symbol => Any}]
-    Parameters = Struct.new(:attributes, :traits, :settings, keyword_init: true)
+    Parameters = Struct.new(:attributes, :traits, :options, keyword_init: true)
 
-    # Define (and create) a forge using DSL.
+    # Define (and initialize) a forge using DSL.
     #
     # @see ForgeDSL
     # @thread_safety Thread-safe if DSL definition is thread-safe.
     #
-    # @param forged [Class, Any] class or object to forge
+    # @param forge_target [Class, Any] class or object to forge
     # @param name [Symbol, nil] forge name
-    # @yieldparam f [ForgeDSL]
+    # @yieldparam dsl [ForgeDSL]
     # @yieldreturn [void]
     # @return [Forge] forge
-    def self.define(forged, name: nil, &)
-      new(forged, ForgeDSL.new(&), name:)
+    def self.define(forge_target, name: nil, &)
+      new(forge_target, ForgeDSL.new(&), name:)
     end
 
-    # @return [Symbol, nil] forge name
+    # @return [Symbol, nil] forge name, only used for identification purposes
     attr_reader :name
 
     # @return [Class, Any] class or object to forge
-    attr_reader :forged
+    # @since 0.4.0
+    attr_reader :forge_target
+    alias target forge_target
 
     # @return [Parameters, ForgeDSL] forge parameters
     attr_reader :parameters
 
-    # @param forged [Class, Any] class or object to forge
+    # @param forge_target [Class, Any] class or object to forge,
+    #   will be passed to mold as +forge_target+ argument
     # @param parameters [Parameters, ForgeDSL] forge parameters
-    # @param name [Symbol, nil] forge name;
-    #   only used for identification purposes
-    def initialize(forged, parameters, name: nil)
+    # @param name [Symbol, nil] forge name
+    #
+    # @raise [ObjectInterfaceError] if forge options do not have expected interface;
+    #   see {Parameters#options} for details
+    def initialize(forge_target, parameters, name: nil)
       @name = name
-      @forged = forged
+      @forge_target = forge_target
       @parameters = parameters
-      @mold = determine_mold(forged, parameters.settings[:mold])
+
+      options = @parameters.options
+      @crucible = determine_crucible(options)
+      @mold = determine_mold(forge_target, options)
+      @after_forge_hook = determine_after_forge_hook(options)
     end
 
-    # Forge a new instance.
+    # Forge a new instance, applying attributes to forge target.
     #
-    # @overload forge(*traits, **overrides, &)
-    # @overload forge(traits, overrides, &)
-    #
-    # Positional arguments are taken as trait names, keyword arguments as attribute overrides,
-    # unless there are exactly two positional arguments: an array and a hash.
+    # Positional arguments are taken as trait names, keyword arguments as attribute overrides.
     #
     # All traits and overrides are applied in argument order,
     # with overrides always applied after traits.
@@ -80,13 +95,16 @@ module ObjectForge
     #   +traits+ and +overrides+ are thread-safe.
     #
     # @param traits [Array<Symbol>] traits to apply
-    # @param overrides [Hash{Symbol => Any}] attribute overrides
+    # @param overrides [Hash{Symbol => Proc, Any}] attribute overrides
     # @yieldparam object [Any] forged instance
     # @yieldreturn [void]
-    # @return [Any] built instance
+    # @return [Any] forged instance
+    #
+    # @raise [ArgumentError] if a trait name is unknown
     def forge(*traits, **overrides)
       resolved_attributes = resolve_attributes(traits, overrides)
-      instance = @mold.call(forged: @forged, attributes: resolved_attributes)
+      instance = @mold.call(forge_target: @forge_target, attributes: resolved_attributes)
+      @after_forge_hook&.call(instance)
       yield instance if block_given?
       instance
     end
@@ -96,31 +114,83 @@ module ObjectForge
 
     private
 
+    # Get a crucible object based on parameters.
+    #
+    # It's either the object provided in options, or {Crucible}.
+    #
+    # @param options [Hash]
+    # @option options [#call, nil] :crucible
+    # @return [#call]
+    #
+    # @raise [ObjectInterfaceError]
+    #
+    # @since 0.4.0
+    def determine_crucible(options)
+      crucible = options[:crucible] || Crucible
+
+      unless crucible.respond_to?(:call)
+        raise ObjectInterfaceError, "crucible must respond to #call"
+      end
+
+      crucible
+    end
+
     # Get appropriate mold based on parameters.
     #
     # If +mold+ is already set, it will be used directly, or,
     # if it is Class, it will be wrapped in {Molds::WrappedMold} if posssible.
-    # If +nil+, a mold will be selected based on +forged+ class.
+    # If +nil+, a mold will be selected based on +forge_target+ class.
     #
-    # @param forged [Class, Any]
-    # @param mold [#call, Class, nil]
+    # @param forge_target [Class, Any]
+    # @param options [Hash]
+    # @option options [#call, Class, nil] :mold
     # @return [#call]
     #
-    # @raise [MoldError]
+    # @raise [ObjectInterfaceError]
     #
     # @since 0.3.0
-    def determine_mold(forged, mold)
-      Molds.wrap_mold(mold) || Molds.mold_for(forged)
+    def determine_mold(forge_target, options)
+      Molds.wrap_mold(options[:mold]) || Molds.mold_for(forge_target)
+    end
+
+    # Get after-forge hook if specified.
+    #
+    # Both +:after_forge+ and +:after_build+ are accepted, but +:after_forge+
+    # wins if both are present.
+    #
+    # @param options [Hash]
+    # @option options [#call, nil] :after_forge
+    # @option options [#call, nil] :after_build
+    # @return [#call, nil]
+    #
+    # @raise [ObjectInterfaceError]
+    #
+    # @since 0.4.0
+    def determine_after_forge_hook(options)
+      hook = options[:after_forge] || options[:after_build] || nil
+
+      unless hook.nil? || hook.respond_to?(:call)
+        raise ObjectInterfaceError, "after-forge hook must respond to #call"
+      end
+
+      hook
     end
 
     # Resolve attributes using default attributes, specified traits and overrides.
     #
     # @param traits [Array<Symbol>]
-    # @param overrides [Hash{Symbol => Any}]
+    # @param overrides [Hash{Symbol => Proc, Any}]
     # @return [Hash{Symbol => Any}]
+    #
+    # @raise [ArgumentError]
     def resolve_attributes(traits, overrides)
+      unless (unknown_traits = traits.difference(@parameters.traits.keys)).empty?
+        raise ArgumentError,
+              "unknown traits for forge#{" #{name}" if name}: #{unknown_traits.join(", ")}"
+      end
+
       attributes = @parameters.attributes.merge(*@parameters.traits.values_at(*traits), overrides)
-      Crucible.new(attributes).resolve!
+      @crucible.call(attributes)
     end
   end
 end

data/lib/object_forge/forge_dsl.rb

@@ -27,8 +27,8 @@ module ObjectForge
     # @return [Hash{Symbol => Hash{Symbol => Proc}}] trait definitions
     attr_reader :traits
 
-    # @return [Hash{Symbol => Any}] settings for forge, such as mold
-    attr_reader :settings
+    # @return [Hash{Symbol => Any}] options for forge, such as mold
+    attr_reader :options
 
     # Define forge's parameters through DSL.
     #
@@ -39,7 +39,7 @@ module ObjectForge
     #
     # @example with block parameter
     #   ForgeDSL.new do |f|
-    #     f.mold = ObjectForge::Molds::KeywordsMolds.new
+    #     f.mold = ObjectForge::Molds::KeywordsMold.new
     #     f.attribute(:name) { "Name" }
     #     f[:description] { name.upcase }
     #     f.duration { rand(1000) }
@@ -47,27 +47,27 @@ module ObjectForge
     #
     # @example without block parameter
     #   ForgeDSL.new do
-    #     self.mold = ::ObjectForge::Molds::KeywordsMolds.new
+    #     self.mold = ::ObjectForge::Molds::KeywordsMold.new
     #     attribute(:name) { "Name" }
     #     self[:description] { name.upcase }
     #     duration { rand(1000) }
     #   end
     #
-    # @yieldparam f [ForgeDSL] self
+    # @yieldparam dsl [ForgeDSL] self
     # @yieldreturn [void]
     def initialize(&dsl)
       super
       @attributes = {}
       @sequences = {}
       @traits = {}
-      @settings = {}
+      @options = {}
 
       dsl.arity.zero? ? instance_exec(&dsl) : yield(self)
 
       freeze
     end
 
-    # Freezes the instance, including +settings+, +attributes+, +sequences+ and +traits+.
+    # Freezes the instance, including +options+, +attributes+, +sequences+ and +traits+.
     # Prevents further responses through +#method_missing+.
     #
     # @note Called automatically in {#initialize}.
@@ -78,40 +78,42 @@ module ObjectForge
       @attributes.freeze
       @sequences.freeze
       @traits.freeze
-      @settings.freeze
+      @options.freeze
       self
     end
 
-    # Set a value for a forge's setting.
+    # Set a value for a forge's option.
     #
-    # Possible settings depend on used forge, but for default {Forge} a +mold+ is expected.
+    # Possible options depend on used forge, but for default {Forge} a +:mold+ is expected.
+    # Check its documentation for full list of available options.
     #
-    # It is also possible to set settings through +method_missing+, using name with a +=+ suffix.
+    # It is also possible to set options through +method_missing+, using name with a +=+ suffix.
     #
     # @see Molds
+    # @see Forge::Parameters#options
     #
     # @example
-    #   f.setting(:mold, ->(forged:, attributes:, **) { forge.new(**attributes) })
+    #   f.option(:mold, ->(forge_target:, attributes:, **) { forge.new(**attributes) })
     #   f.mold = ObjectForge::Molds::SingleArgumentMold.new
     #
-    # @param name [Sumbol] setting name
-    # @param value [Any] value for the setting
-    # @return [Symbol] setting name
+    # @param name [Symbol] option name
+    # @param value [Any] value for the option
+    # @return [Symbol] option name
     #
-    # @raise [ArgumentError] if +name+ is not a Symbol
-    def setting(name, value)
+    # @raise [TypeError] if +name+ is not a Symbol
+    def option(name, value)
       unless ::Symbol === name
-        raise ::ArgumentError, "setting name must be a Symbol, #{name.class} given"
+        raise ::TypeError, "option name must be a Symbol, #{name.class} given"
       end
 
-      @settings[name] = value
+      @options[name] = value
 
       name
     end
 
     # Define an attribute, possibly transient.
     #
-    # DSL does not know or care what attributes the forged class has,
+    # DSL does not know or care what attributes the target class has,
     # so the only difference between "real" and "transient" attributes
     # is how the class itself treats them.
     #
@@ -125,6 +127,7 @@ module ObjectForge
     #   f.attribute(:name) { "Name" }
     #   f[:description] { name.downcase }
     #   f.duration { rand(1000) }
+    #
     # @example using conflicting and reserved names
     #   f.attribute(:[]) { "Brackets" }
     #   f.attribute(:[]=) { "#{self[:[]]} are brackets" }
@@ -134,11 +137,11 @@ module ObjectForge
     # @yieldreturn [Any] attribute value
     # @return [Symbol] attribute name
     #
-    # @raise [ArgumentError] if +name+ is not a Symbol
+    # @raise [TypeError] if +name+ is not a Symbol
     # @raise [DSLError] if no block is given
     def attribute(name, &definition)
       unless ::Symbol === name
-        raise ::ArgumentError,
+        raise ::TypeError,
               "attribute name must be a Symbol, #{name.class} given (in #{name.inspect})"
       end
       unless block_given?
@@ -166,9 +169,11 @@ module ObjectForge
     #   f.sequence(:date, Date.today)
     #   f.sequence(:id) { _1.to_s }
     #   f.sequence(:dated_id, 10) { |n| "#{Date.today}/#{n}-#{id}" }
+    #
     # @example using external sequence
     #   seq = Sequence.new(1)
     #   f.sequence(:global_id, seq)
+    #
     # @example sequence reuse
     #   f.sequence(:id, "a") # => "a", "b", ...
     #   f.trait :new_id do
@@ -181,11 +186,11 @@ module ObjectForge
     # @yieldreturn [Any] attribute value
     # @return [Symbol] attribute name
     #
-    # @raise [ArgumentError] if +name+ is not a Symbol
-    # @raise [DSLError] if +initial+ does not respond to #succ and is not a {Sequence}
+    # @raise [TypeError] if +name+ is not a Symbol
+    # @raise [ObjectInterfaceError] if +initial+ does not respond to #succ and is not a {Sequence}
     def sequence(name, initial = 1, **nil, &)
       unless ::Symbol === name
-        raise ::ArgumentError,
+        raise ::TypeError,
               "sequence name must be a Symbol, #{name.class} given (in #{name.inspect})"
       end
 
@@ -210,6 +215,7 @@ module ObjectForge
     #     f.name { "***xXxSPECIALxXx***" }
     #     f.sequence(:special_id) { "~~~ SpEcIaL #{_1} ~~~" }
     #   end
+    #
     # @example externally defined trait
     #   # Variable defined outside of DSL:
     #   success_trait = ->(ft) do
@@ -227,13 +233,12 @@ module ObjectForge
     # @yieldreturn [void]
     # @return [Symbol] trait name
     #
-    # @raise [ArgumentError] if +name+ is not a Symbol
+    # @raise [TypeError] if +name+ is not a Symbol
     # @raise [DSLError] if no block is given
     # @raise [DSLError] if called inside of another trait definition
     def trait(name, **nil)
       unless ::Symbol === name
-        raise ::ArgumentError,
-              "trait name must be a Symbol, #{name.class} given (in #{name.inspect})"
+        raise ::TypeError, "trait name must be a Symbol, #{name.class} given (in #{name.inspect})"
       end
       if @current_trait
         raise DSLError, "can not define trait inside of another trait (in #{name.inspect})"
@@ -261,12 +266,12 @@ module ObjectForge
 
     private
 
-    # Define an attribute (like +name+) or set a setting (like +name=+) using a shorthand.
+    # Define an attribute (like +name+) or set a option (like +name=+) using a shorthand.
     #
     # Can not be used with reserved names.
     # Trying to use a conflicting name will lead to usual issues
     # with calling random methods.
-    # When in doubt, use {#attribute} or {#setting} instead.
+    # When in doubt, use {#attribute} or {#option} instead.
     #
     # Reserved names are:
     # - all names ending in +?+, +!+
@@ -274,16 +279,16 @@ module ObjectForge
     #   (operators, +`+, +[]+, +[]=+)
     # - +rand+
     #
-    # @param name [Symbol] attribute or setting name
-    # @param value [Any] value for setting
+    # @param name [Symbol] attribute or option name
+    # @param value [Any] value for option
     # @yieldreturn [Any] attribute value
-    # @return [Symbol] attribute or setting name
+    # @return [Symbol] attribute or option name
     #
     # @raise [DSLError] if a reserved +name+ is used
     def method_missing(name, value = nil, **nil, &)
       return super(name) if frozen?
-      if valid_setting_method?(name)
-        return setting(name[...-1].to_sym, value) # steep:ignore NoMethod
+      if valid_option_method?(name)
+        return option(name[...-1].to_sym, value) # steep:ignore NoMethod
       end
       return attribute(name, &) if respond_to_missing?(name, false)
 
@@ -291,12 +296,12 @@ module ObjectForge
     end
 
     def respond_to_missing?(name, _include_all)
-      return false if frozen?
+      return super if frozen?
 
       !name.end_with?("?", "!") && !name.match?(/\A(?=\p{ASCII})\P{Word}/) && name != :rand
     end
 
-    def valid_setting_method?(name)
+    def valid_option_method?(name)
       name.match?(/\A\p{Word}.*=\z/)
     end
   end

data/lib/object_forge/forgeyard.rb

@@ -22,12 +22,12 @@ module ObjectForge
     # @see Forge.define
     #
     # @param name [Symbol] name to register forge under
-    # @param forged [Class, Any] class or object to forge
-    # @yieldparam f [ForgeDSL]
+    # @param forge_target [Class, Any] class or object to forge
+    # @yieldparam dsl [ForgeDSL]
     # @yieldreturn [void]
     # @return [Forge] forge
-    def define(name, forged, &)
-      register(name, Forge.define(forged, name: name, &))
+    def define(name, forge_target, &)
+      register(name, Forge.define(forge_target, name: name, &))
     end
 
     # Add a forge under a specified name.
@@ -59,14 +59,15 @@ module ObjectForge
     #
     # @see Forge#forge
     #
-    # @param name [Symbol] name of the forge
-    # @param traits [Array<Symbol>] traits to apply
-    # @param overrides [Hash{Symbol => Any}] attribute overrides
-    # @yieldparam object [Any] forged instance
-    # @yieldreturn [void]
-    # @return [Any] built instance
-    #
-    # @raise [KeyError] if forge with the specified name is not registered
+    # @overload forge(name, *traits, **overrides)
+    #   @param name [Symbol] name of the forge
+    #   @param traits [Array<Symbol>] traits to apply
+    #   @param overrides [Hash{Symbol => Any}] attribute overrides
+    #   @yieldparam object [Any] forged instance
+    #   @yieldreturn [void]
+    #   @return [Any] forged instance
+    #   @raise [ArgumentError] if a trait name is unknown
+    #   @raise [KeyError] if forge with the specified name is not registered
     def forge(name, ...)
       @forges.fetch(name).call(...)
     end

data/lib/object_forge/molds/hash_mold.rb

@@ -36,15 +36,15 @@ module ObjectForge
         @default_proc = default_proc
       end
 
-      # Build a new hash using +forged.[]+.
+      # Build a new hash using +forge_target.[]+.
       #
       # @see Hash.[]
       #
-      # @param forged [Class] Hash or a subclass of Hash
+      # @param forge_target [Class] Hash or a subclass of Hash
       # @param attributes [Hash{Symbol => Any}]
       # @return [Hash]
-      def call(forged:, attributes:, **_)
-        hash = forged[attributes]
+      def call(forge_target:, attributes:, **_)
+        hash = forge_target[attributes]
         hash.default = @default if @default
         hash.default_proc = @default_proc if @default_proc
         hash

data/lib/object_forge/molds/keywords_mold.rb

@@ -2,7 +2,7 @@
 
 module ObjectForge
   module Molds
-    # Basic mold which calls +forged.new(**attributes)+.
+    # Basic mold which calls +forge_target.new(**attributes)+.
     #
     # Can be used instead of {SingleArgumentMold}
     # due to how keyword arguments are treated in Ruby,
@@ -11,13 +11,13 @@ module ObjectForge
     # @thread_safety Thread-safe.
     # @since 0.2.0
     class KeywordsMold
-      # Instantiate +forged+ with a hash of attributes.
+      # Instantiate forge target with a hash of attributes.
       #
-      # @param forged [Class, #new]
+      # @param forge_target [Class, #new]
       # @param attributes [Hash{Symbol => Any}]
       # @return [Any]
-      def call(forged:, attributes:, **_)
-        forged.new(**attributes)
+      def call(forge_target:, attributes:, **_)
+        forge_target.new(**attributes)
       end
     end
   end

data/lib/object_forge/molds/single_argument_mold.rb

@@ -2,18 +2,18 @@
 
 module ObjectForge
   module Molds
-    # Basic mold which calls +forged.new(attributes)+.
+    # Basic mold which calls +forge_target.new(attributes)+.
     #
     # @thread_safety Thread-safe.
     # @since 0.2.0
     class SingleArgumentMold
-      # Instantiate +forged+ with a hash of attributes.
+      # Instantiate forge target with a hash of attributes.
       #
-      # @param forged [Class, #new]
+      # @param forge_target [Class, #new]
       # @param attributes [Hash{Symbol => Any}]
       # @return [Any]
-      def call(forged:, attributes:, **_)
-        forged.new(attributes)
+      def call(forge_target:, attributes:, **_)
+        forge_target.new(attributes)
       end
     end
   end

data/lib/object_forge/molds/struct_mold.rb

@@ -32,18 +32,22 @@ module ObjectForge
         @lax = lax
       end
 
-      # Instantiate +forged+ struct with a hash of attributes.
+      # Instantiate target struct with a hash of attributes.
       #
-      # @param forged [Class] a subclass of Struct
+      # @param forge_target [Class] a subclass of Struct
       # @param attributes [Hash{Symbol => Any}]
       # @return [Struct]
-      def call(forged:, attributes:, **_)
-        if forged.keyword_init?
-          lax ? forged.new(attributes.slice(*forged.members)) : forged.new(attributes)
-        elsif forged.keyword_init? == false
-          forged.new(*attributes.values_at(*forged.members))
+      def call(forge_target:, attributes:, **_)
+        if forge_target.keyword_init?
+          if lax
+            forge_target.new(attributes.slice(*forge_target.members))
+          else
+            forge_target.new(attributes)
+          end
+        elsif forge_target.keyword_init? == false
+          forge_target.new(*attributes.values_at(*forge_target.members))
         else
-          build_struct_with_unspecified_keyword_init(forged, attributes)
+          build_struct_with_unspecified_keyword_init(forge_target, attributes)
         end
       end
 
@@ -51,18 +55,18 @@ module ObjectForge
 
       if RUBY_FEATURE_AUTO_KEYWORDS
         # Build struct by using keywords to specify member values.
-        def build_struct_with_unspecified_keyword_init(forged, attributes)
+        def build_struct_with_unspecified_keyword_init(forge_target, attributes)
           if lax
-            forged.new(**attributes.slice(*forged.members))
+            forge_target.new(**attributes.slice(*forge_target.members))
           else
-            forged.new(**attributes)
+            forge_target.new(**attributes)
           end
         end
       else
         # :nocov:
         # Build struct by using positional arguments to specify member values.
-        def build_struct_with_unspecified_keyword_init(forged, attributes)
-          forged.new(*attributes.values_at(*forged.members))
+        def build_struct_with_unspecified_keyword_init(forge_target, attributes)
+          forge_target.new(*attributes.values_at(*forge_target.members))
         end
         # :nocov:
       end

data/lib/object_forge/molds/wrapped_mold.rb

@@ -20,10 +20,10 @@ module ObjectForge
         @wrapped_mold = wrapped_mold
       end
 
-      # @overload call(...)
       # Instantiate {wrapped_mold} and call it.
       #
-      # @return [Any] result of +wrapped_mold.new.call(...)+
+      # @overload call(...)
+      #   @return [Any] result of +wrapped_mold.new.call(...)+
       def call(...)
         wrapped_mold.new.call(...)
       end