etcher 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18c97ac57c0742fedf8872da7aa401ceae29552ccc9e78ce0d8df72fc8fff08c
-  data.tar.gz: feb2442ddc16419bc49dc97ba1e449e226713d57a2c1fd6714e8592479faf636
+  metadata.gz: 34e559c63ed6f3baa580995e227f09113e26cacc8920a919f5d10912b4d1cad0
+  data.tar.gz: e23d9de0fffff7d2ae6835a0c6e38dbab5cfdc555839051544a9f24432b73884
 SHA512:
-  metadata.gz: cd2eb81d5e6a950c8d2cc7205fa09d41608bf2a835e25aa13dc5bbbb9bf4f6a60eea36716d5a132047aba29290a3706c8b3b6b54c175df9f95d0e25943719d25
-  data.tar.gz: af20a0db0eaefd28a6a69c1bf0193084ec841a1042cc6f842667c3cc2da803d064e244670429c30a621905615b4a6aee963cab081028b6d10d7b563444fa6969
+  metadata.gz: 5855391dea3b6fa69e206867a8f4b5b3c304e06902044cd70d01eea97dfcc4126bc505d2ea0e9c5424e1089caca8bf7d4ad3d340350a6a53a0d34e55cd4280eb
+  data.tar.gz: e4c23192f2f12a3b086a4dcfc796fa9be9b52c743583e39bcd241071e8e7d4dc487b2b1a47f37a2d31076efd62247d56a043d45c8e135100f2636b40052d2013

data/README.adoc

@@ -291,7 +291,22 @@ registry = Etcher::Registry[loaders: [MyLoader.new]]
 registry = Etcher::Registry.new.add_loader MyLoader.new
 ----
 
-There are a few guidelines to using them:
+You can also remove a previously added loader by index:
+
+[source,ruby]
+----
+registry = Etcher::Registry.new
+
+# Application
+registry.add_loader MyLoader.new
+
+# RSpec
+registry.remove_loader 0
+----
+
+The ability to remove a loader is especially handy in a testing environment where you might need to temporarily remove a loader or don't need a specific loader for testing purposes.
+
+There are a few guidelines to using loaders:
 
 * All loaders must respond to `#call` with no arguments.
 * All loaders must answer either a success with attributes (i.e. `Success attributes`) or a failure with details about the failure (i.e. `Failure step: :load, constant: MyLoader, payload: "My error message.`)
@@ -464,6 +479,21 @@ registry = Etcher::Registry[transformers: [MyTransformer]]
 registry = Etcher::Registry.new.add_transformer MyTransformer
 ----
 
+You can also remove a previously added transformer by index:
+
+[source,ruby]
+----
+registry = Etcher::Registry.new
+
+# Application
+registry.add_transformer MyTransformer
+
+# RSpec
+registry.remove_transformer 0
+----
+
+The ability to remove a transformer is especially handy in a testing environment where you might need to temporarily remove a transformer or don't need a specific transformer for testing purposes.
+
 The guidelines for using transformers are:
 
 * They can be initialized with whatever requirements you need.
@@ -574,7 +604,7 @@ transformer.call({demo: "defined"})
 
 ==== Format
 
-Use `Etcher::Transformers::Format` to transform any key's value by using the configuration's existing attributes to format the value of a specific key using the {string_formats_link} Specification. Example:
+Use `Etcher::Transformers::Format` to transform any key's value by using the configuration's existing attributes to format the value of a specific key using the {string_formats_link} Specification. To start, we'll use the same attributes for all examples:
 
 [source,ruby]
 ----
@@ -583,7 +613,12 @@ attributes = {
   project_name: "test",
   project_uri: "%<organization_uri>s/projects/%<project_name>s"
 }
+----
+
+Using the above `attributes`, you'll get a `Success` when all required keys exist:
 
+[source,ruby]
+----
 Etcher::Transformers::Format.new(:project_uri).call attributes
 # Success(
   {
@@ -592,9 +627,14 @@ Etcher::Transformers::Format.new(:project_uri).call attributes
     project_uri: "https://acme.io/projects/test"
   }
 )
+----
 
+When some required keys are missing, you'll get a `Failure`:
+
+[source,ruby]
+----
 attributes.delete :project_name
-transformer.call attributes
+Etcher::Transformers::Format.new(:project_uri).call attributes
 
 # Failure(
 #   {
@@ -605,6 +645,38 @@ transformer.call attributes
 # )
 ----
 
+You can partially transform a value using _retainers_ and/or _mappings_ for situations where you need to format a value while preserving and/or remapping string specifiers for delayed formatting. Here's an example using a _retainer_ which preserves the `:project_name`.
+
+[source,ruby]
+----
+Etcher::Transformers::Format.new(:project_uri, :project_name).call attributes
+
+# Success(
+#  {
+#      organization_uri: "https://acme.io",
+#      project_name: "test",
+#      project_uri: "https://acme.io/projects/%<project_name>s"
+#   }
+# )
+----
+
+Notice the `organization_uri` was formatted in the `project_uri` while the `project_name` was preserved. This allows you to format the `project_name` when you can supply the value later. Similarly, you can remap a string specifier. Example:
+
+[source,ruby]
+----
+Etcher::Transformers::Format.new(:project_uri, project_name: "%<id>s").call attributes
+
+# Success(
+#  {
+#      organization_uri: "https://acme.io",
+#      project_name: "test",
+#      project_uri: "https://acme.io/projects/%<id>s"
+#   }
+# )
+----
+
+Notice the `organization_uri` was formatted in the `project_uri` (same as before) while the `project_name` was remapped as `%<id>s`. As shown mentioned earlier, this allows you to _delay_ supplying the `id` when you might not have a value for it yet.
+
 You can also, safely, transform a value which _doesn't_ have string specifiers:
 
 [source,ruby]
@@ -613,7 +685,7 @@ Etcher::Transformers::Format.new(:version).call(version: "1.2.3")
 # Success({:version=>"1.2.3"})
 ----
 
-Normally, you'd get a "too many arguments for format string" warning but this transformer detects and immediate skips formatting when no string specifiers are detected. This is handy for situations where your configuration supports values which may or may not need formatting.
+Normally, you'd get a "too many arguments for format string" warning but this transformer detects and immediately skips formatting when no string specifiers are detected. This is handy for situations where your configuration supports values which may or may not need formatting.
 
 ==== Time
 

data/etcher.gemspec

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

data/lib/etcher/transformers/format.rb

@@ -8,9 +8,10 @@ module Etcher
     class Format
       include Dry::Monads[:result]
 
-      def initialize key, **pass_throughs
+      def initialize key, *retainers, **mappings
         @key = key
-        @pass_throughs = pass_throughs
+        @retainers = retainers
+        @mappings = mappings
         @pattern = /%<.+>s/o
       end
 
@@ -29,7 +30,13 @@ module Etcher
 
       private
 
-      attr_reader :key, :pass_throughs, :pattern
+      attr_reader :key, :retainers, :mappings, :pattern
+
+      def pass_throughs
+        retainers.each
+                 .with_object({}) { |key, expansions| expansions[key] = "%<#{key}>s" }
+                 .merge! mappings
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-07-05 00:00:00.000000000 Z
+date: 2024-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -188,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.