factrey 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c99d12d76f3bb5c00381aa92c12fa7590256312a4bc44af811b6ebfcc379ac2a
-  data.tar.gz: 62cfdf298cfa82d3341d26e140e57d28660376ed810142b54486650deb37ecd4
+  metadata.gz: 16dba45f9a86cdb78925559b08fe048a8cb1b8004a5206e2a103aa8df2889fe3
+  data.tar.gz: e84a1b67bce17d637837ecc3e1882e1b7dce4b96267652cc0e23c8bc97c46441
 SHA512:
-  metadata.gz: 68317b56351965174b8ae361c2a68e9d125359f8d9f2ec3203b6892391cacb8c9a2db6e4056c2e13531c8ffbb4a47d141bed74662327b170da55de6852fcc806
-  data.tar.gz: 3705848394bf3870e84505241ecfbd7075813c558d9b377848c60b6bb939a8cda789edd3bc5d0cf24087bd7847daf4f1fb5fe62ba9f7e2da9dd240f470b9e9d9
+  metadata.gz: 001c21f917a7c52d76191005a127889f6ed067c0d440d4f42b6879e252224b0ffa0e585a7458ba999ec753feb7e03b4bc29c79d8f35fe0265450e56ffd48b285
+  data.tar.gz: 45e4982f36da43ff79aa9dcb316b82c8551f30034ba223aee39a321b19f01f0deddbb7ac901e842fd60ded4bd9ac26a04e2b58097b0f94f713a5a035e16a6103

data/lib/factrey/blueprint/instantiator.rb

@@ -23,11 +23,6 @@ module Factrey
         @objects
       end
 
-      def instantiate_result
-        instantiate_objects # To keep consistency in the order of instantiation
-        resolver.resolve(@blueprint.result)
-      end
-
       private
 
       # @param node [Node]

data/lib/factrey/blueprint/node.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require "set"
+require "securerandom"
 
 module Factrey
   class Blueprint
     # A node corresponds to an object to be created. A {Blueprint} consists of a set of nodes.
     class Node
+      # A name prefix given to anonymous nodes for convenience.
       ANONYMOUS_NAME_PREFIX = "_anon_"
+      # Name used for the node that hold the results of the blueprint.
+      RESULT_NAME = :_result_
 
       # @return [Symbol] name given to the object to be created
       attr_reader :name
@@ -35,14 +39,31 @@ module Factrey
         @kwargs = kwargs
       end
 
-      # @return [Ref]
-      def to_ref = Ref.new(name)
+      # @param name [Symbol, nil]
+      # @param value [Object]
+      # @param ancestors [Array<Node>]
+      def self.computed(name, value, ancestors: [])
+        new(name, Blueprint::Type::COMPUTED, ancestors:, args: [value])
+      end
 
       # @return [Boolean]
-      def root? = ancestors.empty?
+      def anonymous? = name.start_with?(ANONYMOUS_NAME_PREFIX)
 
       # @return [Boolean]
-      def anonymous? = name.start_with?(ANONYMOUS_NAME_PREFIX)
+      def result? = name == RESULT_NAME
+
+      # @return [Ref] the reference to this node
+      def to_ref = Ref.new(name)
+
+      # @return [Ref, nil] if this node works as an alias to another node, return the reference to the node
+      def alias_ref
+        case [@type, args]
+        in Blueprint::Type::COMPUTED, [Ref => ref]
+          ref
+        else
+          nil
+        end
+      end
 
       # Used for debugging and error reporting.
       # @return [String]

data/lib/factrey/blueprint/type.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Factrey
   class Blueprint
     # A type representation on Factrey blueprints.
@@ -40,6 +42,9 @@ module Factrey
         @auto_references = auto_references.freeze
         @factory = factory
       end
+
+      # A special type that represents values computed from other objects.
+      COMPUTED = Type.new(:_computed) { |_, _, arg| arg }
     end
   end
 end

data/lib/factrey/blueprint.rb

@@ -10,8 +10,6 @@ module Factrey
   class Blueprint
     # @return [Hash{Symbol => Node}] a set of nodes
     attr_reader :nodes
-    # @return [Object] the result of the DSL code is defined here
-    attr_reader :result
 
     # Creates an empty blueprint.
     def initialize
@@ -23,7 +21,7 @@ module Factrey
       result = self.class.new
 
       nodes.each_value do |node|
-        result.add_node(
+        new_node = Node.new(
           node.name,
           node.type,
           # This is OK since Hash insertion order in Ruby is retained
@@ -31,38 +29,39 @@ module Factrey
           args: node.args.dup,
           kwargs: node.kwargs.dup,
         )
+        result.add_node(new_node)
       end
 
       result
     end
 
     # Add a node. This method is used by {DSL} and usually does not need to be called directly.
+    # @param node [Node]
     # @return [Node]
-    def add_node(...)
-      node = Node.new(...)
+    def add_node(node)
       raise ArgumentError, "duplicate node: #{node.name}" if nodes.member?(node.name)
 
       nodes[node.name] = node
       node
     end
 
-    # Define the result. This method is used by {DSL} and usually does not need to be called directly.
-    # @param result [Object]
-    # @param overwrite [Boolean] whether to overwrite the existing result
-    def define_result(result, overwrite: false)
-      return if defined?(@result) && !overwrite
+    # Resolve a node.
+    # @param name [Symbol]
+    # @param follow_alias [Boolean] whether to follow an alias node. See {Node#alias_ref}
+    # @return [Node, nil]
+    def resolve_node(name, follow_alias: true)
+      node = nodes[name]
+      return node unless follow_alias
 
-      @result = result
+      ref = node&.alias_ref
+      ref ? resolve_node(ref.name) : node
     end
 
-    # Create a set of objects and compute the result based on this blueprint.
+    # Create a set of objects based on this blueprint.
     # @param context [Object] context object to be passed to the factories
-    # @return [(Object, {Symbol => Object})] the result and the created objects
+    # @return [Hash{Symbol => Object}] the created objects
     def instantiate(context = nil)
-      instantiator = Instantiator.new(context, self)
-      objects = instantiator.instantiate_objects
-      result = instantiator.instantiate_result
-      [result, objects]
+      Instantiator.new(context, self).instantiate_objects
     end
   end
 end

data/lib/factrey/dsl.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
 require "set"
-require "securerandom"
-
-require_relative "dsl/let"
-require_relative "dsl/on"
 
 module Factrey
   # {Blueprint} DSL implementation.
   class DSL
     # Methods reserved for DSL.
     RESERVED_METHODS = %i[
-      ref ext let let_default_name node on type args
-      __send__ __id__ nil? object_id class instance_exec initialize block_given? raise
+      ref ext object_node computed_node let on args
+      __send__ __method__ __id__ nil? is_a? to_s inspect object_id class instance_eval instance_variables
+      initialize block_given? enum_for raise
     ].to_set.freeze
 
     (instance_methods + private_instance_methods).each do |method|
@@ -32,100 +29,81 @@ module Factrey
     # @return [Object] the external object passed to {Factrey.blueprint}
     attr_reader :ext
 
-    # By preceding <code>let(name).</code> to the declaration, give a name to the node.
-    # @param name [Symbol, nil] defaults to {Blueprint::Type#name} if omitted
-    # @return [Let]
+    # Add an object node to the blueprint.
+    #
+    # This method is usually not called directly. Use the shorthand method defined by {.add_type} instead.
+    # @param name [Symbol, nil]
+    # @param type [Blueprint::Type]
+    # @yieldparam ref [Ref]
+    # @return [Ref]
+    def object_node(name, type, ...)
+      node = @blueprint.add_node(Blueprint::Node.new(name, type, ancestors: @ancestors))
+      on(node.name, ...)
+    end
+
+    # Add a computed node to the blueprint.
+    #
+    # This method is usually not called directly. Use {#let} instead.
+    # @param name [Symbol, nil]
+    # @param value [Object]
+    def computed_node(name, value)
+      node = @blueprint.add_node(Blueprint::Node.computed(name, value, ancestors: @ancestors))
+      node.to_ref
+    end
+
+    # Define a computed node with name.
+    # @param setter_name [Symbol, nil] the setter name for the computed node
+    # @return [Ref, Proxy] returns a {Proxy} for <code>let.node_name = ...</code> notation if no argument is given
     # @example
     #   bp =
     #     Factrey.blueprint do
-    #       article                 # no meaningful name is given (See Blueprint::Node#anonymous?)
-    #       let.article             # named as article
-    #       let(:article2).article  # named as article2
+    #       article(title: "Foo")                # object itself has no meaningful name (See Blueprint::Node#anonymous?)
+    #       let.article = article(title: "Bar")  # an alias `article` to the article object is defined
+    #       let.article(title: "Bar")            # We can omit `.node_name =` if the name is the same as the method name
+    #       let.article2 = article(title: "Baz") # an alias `article2` to the article object is defined
     #     end
     #   bp.instantiate              #=> { article: ..., article2: ..., ... }
-    def let(name = nil, &)
-      raise TypeError, "name must be a Symbol" if name && !name.is_a?(Symbol)
-      raise ArgumentError, "nested let" if @let_scope
-
-      let = Let.new(self, name)
-      return let unless block_given?
-
-      @let_scope = let
-      ret = yield
-      @let_scope = nil
-      ret
-    end
-
-    # Overrides the default name given by {#let}.
-    #
-    # This method does nothing if it is not preceded by {#let}.
-    # @param name [Symbol]
-    # @return [Let, Blueprint]
-    # @example
-    #   class Factrey::DSL do
-    #     # Define a shortcut method for user(:admin)
-    #     def admin_user(...) = let_default_name(:admin_user).user(:admin, ...)
-    #   end
-    #   Factrey.blueprint do
-    #     admin_user              # no meaningful name is given (See Blueprint::Node#anonymous?)
-    #     let.admin_user          # named as admin_user
-    #     let(:user2).admin_user  # named as user2
-    #   end
-    def let_default_name(name, &)
-      raise TypeError, "name must be a Symbol" unless name.is_a?(Symbol)
+    def let(setter_name = nil, *args, **kwargs, &block)
+      return Proxy.new(self, __method__) unless setter_name
 
-      if @let_scope && @let_scope.name.nil?
-        @let_scope = nil # consumed
+      if setter_name.end_with? "="
+        raise ArgumentError, "Wrong setter use" if args.size != 1 || !kwargs.empty? || block
 
-        let(name, &)
+        computed_node(setter_name[0..-2].to_sym, args[0])
       else
-        return self unless block_given?
-
-        yield
+        # `let.node_name(...)` is a shorthand for `let.node_name = node_name(...)`
+        let(:"#{setter_name}=", __send__(setter_name, *args, **kwargs, &block))
       end
     end
 
-    # Add a node to the blueprint.
-    #
-    # This method is usually not called directly. Use the shorthand method defined by {.add_type} instead.
-    # @param type [Blueprint::Type]
-    # @yieldparam ref [Ref]
-    # @return [Ref]
-    def node(type, ...)
-      name = @let_scope ? (@let_scope.name || type.name) : nil
-      @let_scope = nil # consumed
-
-      node = @blueprint.add_node(name, type, ancestors: @ancestors)
-      on(node.name, ...)
-    end
-
     # Enter the node to configure arguments and child nodes.
-    # @yieldparam ref [Ref]
-    # @return [Ref]
+    # @param node_name [Symbol, nil] the node name to enter
+    # @return [Ref, Proxy] returns a {Proxy} for <code>on.node_name(...)</code> notation if no argument is given
     # @example
     #   Factrey.blueprint do
     #     let.blog do
-    #       let(:article1).article
-    #       let(:article2).article
+    #       let.article1 = article
+    #       let.article2 = article
     #     end
     #
     #     # Add article to `blog`
-    #     on.blog { let(:article3).article }
+    #     on.blog { let.article3 = article }
     #     # Add title to `article2`
     #     on.article2(title: "This is an article 2")
     #   end
-    def on(name = nil, *args, **kwargs)
-      return On.new(self) if name.nil? && !block_given?
+    def on(node_name = nil, ...)
+      return Proxy.new(self, __method__) unless node_name
 
-      node = @blueprint.nodes[name]
-      raise ArgumentError, "unknown node: #{name}" unless node
+      node = @blueprint.resolve_node(node_name)
+      raise ArgumentError, "unknown node: #{node_name}" unless node
 
       stashed_ancestors = @ancestors
       @ancestors = node.ancestors + [node]
-      args(*args, **kwargs)
-      yield node.to_ref if block_given?
-      @ancestors = stashed_ancestors
-      node.to_ref
+      begin
+        args(...)
+      ensure
+        @ancestors = stashed_ancestors
+      end
     end
 
     # Add arguments to the current node.
@@ -138,10 +116,13 @@ module Factrey
     #     on.blog(:premium, title: "Who-ha")
     #   end
     def args(*args, **kwargs)
-      raise NameError, "Cannot use args at toplevel" if @ancestors.empty?
+      raise NameError, "cannot use args at toplevel" if @ancestors.empty?
+      raise NameError, "cannot use args to computed nodes" if @ancestors.last.type == Blueprint::Type::COMPUTED
 
       @ancestors.last.args.concat(args)
       @ancestors.last.kwargs.update(kwargs)
+      yield @ancestors.last.to_ref if block_given?
+      @ancestors.last.to_ref
     end
 
     class << self
@@ -151,8 +132,8 @@ module Factrey
       end
 
       # Add a new type that will be available in this DSL.
-      # A helper method with the same name as the type name is also defined in the DSL. For example,
-      # if you have added the <code>foo</code> type, you can declare node with <code>#foo</code>.
+      # This method defines a helper method with the same name as the type name. For example,
+      # if you have added the <code>foo</code> type, you can declare an object node with <code>#foo</code>.
       #
       # {.add_type} is called automatically when you use <code>factory_bot-blueprint</code> gem.
       # @param type [Blueprint::Type] blueprint type
@@ -179,7 +160,7 @@ module Factrey
         end
 
         types[type.name] = type
-        define_method(type.name) { |*args, **kwargs, &block| node(type, *args, **kwargs, &block) }
+        define_method(type.name) { |*args, **kwargs, &block| object_node(nil, type, *args, **kwargs, &block) }
       end
     end
   end

data/lib/factrey/proxy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Factrey
+  # An intermediate object to provide some notation combined with <code>method_missing</code>.
+  # @example
+  #   class Foo
+  #     def foo(name = nil)
+  #       return Factrey::Proxy.new(self, __method__) unless name
+  #
+  #       name
+  #     end
+  #   end
+  #
+  #   Foo.new.foo.bar #=> :bar
+  class Proxy < BasicObject
+    # @param receiver [Object]
+    # @param method [Symbol]
+    def initialize(receiver, method)
+      @receiver = receiver
+      @method = method
+    end
+
+    # @!visibility private
+    def respond_to_missing?(_method_name, _) = true
+
+    def method_missing(method_name, ...)
+      @receiver.__send__(@method, method_name, ...)
+    end
+  end
+end

data/lib/factrey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Factrey
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/factrey.rb

@@ -2,6 +2,7 @@
 
 require_relative "factrey/version"
 require_relative "factrey/ref"
+require_relative "factrey/proxy"
 require_relative "factrey/blueprint"
 require_relative "factrey/dsl"
 
@@ -36,8 +37,12 @@ module Factrey
       raise TypeError, "blueprint must be a Blueprint" if blueprint && !blueprint.is_a?(Blueprint)
       raise TypeError, "dsl must be a subclass of DSL" unless dsl <= DSL
 
+      is_extending = !blueprint.nil?
       blueprint ||= Blueprint.new
-      blueprint.define_result dsl.new(blueprint:, ext:).instance_exec(&) if block_given?
+
+      result = block_given? ? dsl.new(blueprint:, ext:).instance_eval(&) : nil
+      blueprint.add_node(Blueprint::Node.computed(Blueprint::Node::RESULT_NAME, result)) unless is_extending
+
       blueprint
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factrey
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - yubrot
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-29 00:00:00.000000000 Z
+date: 2024-08-13 00:00:00.000000000 Z
 dependencies: []
 description: |
   Factrey provides a declarative DSL to represent the creation plan of objects, for FactoryBot::Blueprint.
@@ -27,8 +27,7 @@ files:
 - lib/factrey/blueprint/node.rb
 - lib/factrey/blueprint/type.rb
 - lib/factrey/dsl.rb
-- lib/factrey/dsl/let.rb
-- lib/factrey/dsl/on.rb
+- lib/factrey/proxy.rb
 - lib/factrey/ref.rb
 - lib/factrey/ref/builder.rb
 - lib/factrey/ref/defer.rb

data/lib/factrey/dsl/let.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Factrey
-  class DSL
-    # An intermediate object for <code>let(:name).node(...)</code> notation. See {DSL#let}.
-    class Let < BasicObject
-      attr_reader :name
-
-      # @param dsl [DSL]
-      # @param name [Symbol, nil]
-      def initialize(dsl, name)
-        @dsl = dsl
-        @name = name
-      end
-
-      # @!visibility private
-      def respond_to_missing?(_method_name, _) = true
-
-      def method_missing(method_name, ...) = @dsl.let(@name) { @dsl.__send__(method_name, ...) }
-    end
-  end
-end

data/lib/factrey/dsl/on.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Factrey
-  class DSL
-    # An intermediate object for <code>on.name(...)</code> notation. See {DSL#on}.
-    class On < BasicObject
-      # @param dsl [DSL]
-      def initialize(dsl) = @dsl = dsl
-
-      # @!visibility private
-      def respond_to_missing?(_name, _) = true
-
-      def method_missing(name, ...) = @dsl.on(name, ...)
-    end
-  end
-end