containable 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 014d1582fc52d294c3c860f611866683ec3308dd0f95c23083defc93b8db0f8a
-  data.tar.gz: 321b1a573df10500ddbc4eede5503537caee0cb3380cfd296eb6baf68c478f4e
+  metadata.gz: 7c5be0b5f9d940c754f77ded0f06992cb9d1dc13e45ec055ccde1a877fbe1782
+  data.tar.gz: 156d209e8b763fe0f995fa19bb709282537c2122c1a54e05c167e082f052055d
 SHA512:
-  metadata.gz: 3dd07f1911ceb4df23b10dcdbf5364c0391a6341e5869a0f1dc94c619b493c1acaec058d315d1bc3b6c2c93dd6a2c5c5c9e23e80366098ee4e5bd99a7263a3dd
-  data.tar.gz: 7f3d378b0e9a2ecb0385e50ffcd07f9054e559104e5ebd3f2ca3ad17f1c4999107d5748aeb0a316e67742ac594901b649f8a0490cc2726dc913fc37e498a07f2
+  metadata.gz: 8c6fa5e47492849f7d67121a0725dae9466f0bb79fdc4e014f8ba80daa02d68507b6efb3dc56a3d75fc87b0130d2b001127a78c709eb8a54b345bd8f09d14d53
+  data.tar.gz: 9a43d1dfce8ea6768240a48c4292b10b26abd984fa51c969dd68b6bd4a5170edaabac3a7dc716b9995559b592b844bb3bea4ab0a01b7aa5535a298c67dd2f757

data/README.adoc

@@ -110,7 +110,7 @@ module Container
 end
 ----
 
-With the above, `1` (literal) will be associated with the `:demo` key. This is perfect for registering literals, constants, or any objects you immediately want evaluated or have a reference to. To lazily register a dependency, use a block with parameters:
+With the above, `1` (literal) will be associated with the `:demo` key. This is perfect for registering literals, constants, or any objects you immediately want evaluated or have a reference to. To lazy register a dependency, use a block with parameters:
 
 [source,ruby]
 ----
@@ -155,7 +155,7 @@ end
 Use `:cache` and `:fresh` to direct how your closures will be resolved. Here's what each does:
 
 * `+:cache+`: Ensures the same object is answered each time the key is resolved. In the above example, this means the `one` dependency will always answer the _same_ instance of an `Object` when resolved. This is default behavior so you don't need to define this key and is only shown for explicit illustration purposes.
-* `+:fresh+`: Ensures a new object is answered each time the key is resolved. In the above example, this means that the `two` dependency will always answer a _different_ instance of an `Object`. You want to use this when you want to lazily resolve a dependency while still wanting a new instance each time.
+* `+:fresh+`: Ensures a new object is answered each time the key is resolved. In the above example, this means that the `two` dependency will always answer a _different_ instance of an `Object`. You want to use this when you want to lazy resolve a dependency while still wanting a new instance each time.
 
 💡 The `as` key is only applied when using a closure with no parameters and is ignored otherwise. This means you don't need to supply this key when using literals.
 
@@ -188,8 +188,15 @@ module Container
   register :one, 1
 end
 
+# Single (preferred)
 Container.register :two, 2
+
+# Single (setter)
 Container[:three] = 3
+
+# Multiples.
+Container.register(:four, 4)
+         .register(:five, 5)
 ----
 
 With the above, a combination of `.register` and `.[]=` (setter) messages are used. While the latter is handy, the former is preferred for improved readability.
@@ -246,7 +253,7 @@ Container[:two]                # #<Proc:0x000000012e9f8718 /demo:23>
 Container[:three]              # #<Proc:0x000000012e9f8628 /demo:24 (lambda)>
 ----
 
-With the above, you can see `:one` was immediately resolved to the value of `1` even though it was wrapped in a closure to begin with. This happened because the closure had no parameters so was safe to resolve. Again, this allows you to lazily resolve a dependency until you need it.
+With the above, you can see `:one` was immediately resolved to the value of `1` even though it was wrapped in a closure to begin with. This happened because the closure had no parameters so was safe to resolve. Again, this allows you to lazy resolve a dependency until you need it.
 
 For keys `:two` and `:three`, we have a closure that has at least one parameter so remains a closure. This allows you to supply required arguments later. Here's a closer look of using the `:two` and `:three` dependencies:
 
@@ -277,7 +284,65 @@ Container[:two]    # #<Object:0x000000012d237728>
 Container[:two]    # #<Object:0x000000012d2de550>
 ----
 
-Notice `one` always answers the same instance of an `Object` while `two` always answers a new instance of `Object`. By using `:fresh`, this allows you to lazily evaluate your closure while disabling default caching support.
+Notice `one` always answers the same instance of an `Object` while `two` always answers a new instance of `Object`. By using `:fresh`, this allows you to lazy evaluate your closure while disabling default caching support.
+
+=== Merges
+
+You can merge dependencies from another container into your current container. Consider the following containers:
+
+[source,ruby]
+----
+module Primary
+  extend Containable
+
+  register :zero, 0
+end
+
+module Secondary
+  extend Containable
+
+  namespace :one do
+    register :two, 2
+  end
+
+  register :three, 3
+end
+
+module Other
+  extend Containable
+
+  register :four, 4
+end
+----
+
+With the above, this means you can do the following:
+
+[source,ruby]
+----
+# Merge a single dependency.
+Primary.merge Secondary, :three
+Primary[:three]  # 3
+
+# Merge multiple dependencies.
+Primary.merge Secondary, "one.two", :three
+Primary["one.two"]  # 2
+Primary[:three]     # 3
+
+# Merge with a namespace.
+Primary.merge Secondary, "one.two", :three, namespace: :top
+Primary["top.one.two"]  # 2
+Primary["top.three"]    # 3
+
+# Merge as fresh (normally, the default is cache).
+Primary.merge Secondary, "one.two", as: :fresh
+
+# Merge with repeated messages since it answers itself.
+Primary.merge(Secondary, :three)
+       .merge(Other, :four)
+
+Primary[:three]  # 3
+Primary[:four]   # 4
+----
 
 === Namespaces
 
@@ -316,6 +381,16 @@ Container["two.green"]     # "green"
 Container["three.silver"]  # "silver"
 ----
 
+You can also send multiple messages to create a namespace register a dependency:
+
+[source,]
+----
+Container.namespace(:one)
+         .register(:two, 2)
+----
+
+This is a convenience that should only be used in rare situations because defining your namespaces and associated dependencies using block syntax improves readability.
+
 === Enumeration
 
 Enumeration is possible but limited. Given the following:

data/containable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "containable"
-  spec.version = "2.2.1"
+  spec.version = "2.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/containable"

data/lib/containable/builder.rb

@@ -40,11 +40,22 @@ module Containable
         fail FrozenError, "Can't modify frozen container." if dependencies.frozen?
 
         target.call key, value, as:, &block
+        self
+      end
+    end
+
+    def define_merge target: register
+      define_method :merge do |other, *keys, namespace: nil, as: :cache|
+        target.merge(other, *keys, namespace:, as:)
+        self
       end
     end
 
     def define_namespace target = register
-      define_method(:namespace) { |name, &block| target.namespace name, &block }
+      define_method :namespace do |name, &block|
+        target.namespace name, &block
+        self
+      end
     end
 
     def define_resolve target = resolver

data/lib/containable/register.rb

@@ -25,14 +25,21 @@ module Containable
       check_duplicate key, namespaced_key
       check_directive as
       dependencies[namespaced_key] = [block || value, as]
+      self
     end
 
     alias register call
 
+    def merge other, *keys, namespace: nil, as: :cache
+      keys.each { call [namespace, it].compact.join("."), other[it], as: }
+      self
+    end
+
     def namespace(name, &)
       keys.clear if depth.zero?
       keys.append name
       visit(&)
+      self
     end
 
     protected

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: containable
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.12
 specification_version: 4
 summary: A thread-safe dependency injection container.
 test_files: []