etcher 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a7381f41e75ad83f44a491f33f396be3ffb5b401a1a72fdcef2086984424fff
-  data.tar.gz: '09b9c86d96af82fbc821e23c92e7966c97234e61625d3d23838471b930906629'
+  metadata.gz: 75820bd97bf8b61960802c1bb85cb91d5ad583778ca5860d4a887eea59f516a5
+  data.tar.gz: b83d2f5ed78a7ef5ba8b622b63855226413fb4a574cf44577a9f825509a33d82
 SHA512:
-  metadata.gz: 3d3008b4581dfd66426ba9e9c2ed0158241d130c2e68372f124369dd42c5893fed86aff36fe9e1b14612fff2139f39cf7e4b07492b5faac13699a3f0d87f609c
-  data.tar.gz: 885d3f522cefba39eeb8765fe671ea822d52edefc700d1633997825fd7cb61c834db7d6111cbd92881c5c9d232519e70bb4aa120027cc6ad432e82286d15fb99
+  metadata.gz: 891f2042e506243598e6545846ea5a4aeae21658315f5c25e32121c45279a64721cea0c275cf8ce7d723724007e108d3e09b7d538b6d28c7a049c7599da09c73
+  data.tar.gz: 0cb1f523435a2244994e88a9a51852f2a67b83c10bb3b817b147c9c80dd615bf777ecec069b2121af497dc225c6f1a032f53e856d41961145255b792eb70c80c

data/README.adoc

@@ -414,16 +414,15 @@ registry = Etcher::Registry[transformers: [MyTransformer]]
 registry = Etcher::Registry.new.add_transformer MyTransformer
 ----
 
-Here are a few guidelines to using them:
+The guidelines for using transformers are:
 
-* They can be initialized with whatever requirements you might need.
+* They can be initialized with whatever requirements you need.
 * They must respond to `#call` which takes a required `attributes` positional argument and answers a modified version of these attributes (`Hash`) wrapped as a monad.
-* A second _optional_ positional `key` parameter should follow your `attributes` parameter when implementing your transformer. This allows you to quickly refactor the key later while also reducing key duplication throughout your implementation.
+* When using a proc/lambda, the first, _required_, parameter should be the `attributes` parameter followed by an _optional_ positional `key` parameter with a default value. This allows you to quickly refactor the key later while also reducing key duplication throughout your implementation.
+* When using a class, the `key` should be your first positional parameter with a default value. Additional parameters can be supplied after if desired.
 * The `attributes` passed to your transformer will have symbolized keys so you don't need to transform them further.
 
-Here are a few examples of where you could go with this:
-
-The following capitalizes all values (which may or may not be good depending on your data structure).
+For example, the following capitalizes all values (which may or may not be good depending on your data structure):
 
 [source,ruby]
 ----
@@ -435,28 +434,7 @@ Capitalize.call(name: "test")
 # Success({:name=>"Test"})
 ----
 
-The following updates current time relative to when configuration was transformed.
-
-[source,ruby]
-----
-require "dry/monads"
-
-CurrentTime = lambda do |attributes, key = :at, at: Time.now|
-  attributes.fetch(key) { at }
-            .then { |value| Dry::Monads::Success attributes.merge!(key => value) }
-end
-
-CurrentTime.call({})
-# Success({:at=>2023-04-23 15:22:23.746408 -0600})
-
-CurrentTime.call({at: Time.utc(2023, 10, 15)})
-# Success({:at=>2023-10-15 00:00:00 UTC})
-
-CurrentTime.call({}, at: Time.utc(2023, 1, 10))
-# Success({:at=>2023-01-10 00:00:00 UTC})
-----
-
-The following obtains the current Git user's email address from the global Git configuration using the {gitt_link} gem.
+The following obtains the current Git user's email address from the global Git configuration using the {gitt_link} gem:
 
 [source,ruby]
 ----
@@ -485,11 +463,38 @@ To use all of the above, you'd only need to register and use them:
 
 [source,ruby]
 ----
-registry = Etcher::Registry[transformers: [Capitalize, CurrentTime, GitEmail.new]]
+registry = Etcher::Registry[transformers: [Capitalize, GitEmail.new]]
 etcher = Etcher.new(registry)
 etcher.call
 ----
 
+If you'd like prebuilt transformers, the following details what is supplied by this gem.
+
+==== Time
+
+Use `Etcher::Transformers::Time` to transform the `loaded_at` key in your configuration when you want to know the current time at which the configuration was loaded. Handy for situations where you need to calculate relative time or format time based on when your configuration was loaded.
+
+Even though `loaded_at` is the default key and `Time.now.utc` is the default fallback, you're not limited to using different keys and fallbacks. Example:
+
+[source,ruby]
+----
+transformer = Etcher::Transformers::Time.new
+transformer.call({})
+# Success({:loaded_at=>2024-05-23 22:18:27.92767 UTC})
+
+transformer = Etcher::Transformers::Time.new :now
+transformer.call({})
+# Success({:now=>2024-05-23 22:18:49.93189 UTC})
+
+transformer = Etcher::Transformers::Time.new :now, fallback: Time.utc(2000, 1, 1)
+transformer.call({})
+# Success({:now=>2000-01-01 00:00:00 UTC})
+
+transformer = Etcher::Transformers::Time.new
+transformer.call({loaded_at: Time.utc(2000, 1, 1)})
+# Success({:loaded_at=>2000-01-01 00:00:00 UTC})
+----
+
 === Overrides
 
 Overrides are what you pass to the Etcher instance when called. Example:

data/etcher.gemspec

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

data/lib/etcher/transformers/time.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Etcher
+  module Transformers
+    # Conditionally transforms current time for key.
+    class Time
+      include Dry::Monads[:result]
+
+      def initialize key = :loaded_at, fallback: ::Time.now.utc
+        @key = key
+        @fallback = fallback
+      end
+
+      def call attributes
+        attributes.fetch(key) { fallback }
+                  .then { |value| Success attributes.merge!(key => value) }
+      end
+
+      private
+
+      attr_reader :key, :fallback
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-05-11 00:00:00.000000000 Z
+date: 2024-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -155,6 +155,7 @@ files:
 - lib/etcher/loaders/yaml.rb
 - lib/etcher/registry.rb
 - lib/etcher/resolver.rb
+- lib/etcher/transformers/time.rb
 - lib/etcher/types.rb
 homepage: https://alchemists.io/projects/etcher
 licenses: