etcher 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a7381f41e75ad83f44a491f33f396be3ffb5b401a1a72fdcef2086984424fff
-  data.tar.gz: '09b9c86d96af82fbc821e23c92e7966c97234e61625d3d23838471b930906629'
+  metadata.gz: 3e462682ab4cb1a7149595a36e1d2893f329db37813209655c53a6fd767e9751
+  data.tar.gz: 2f1a5bd597dfa8590d6ad48f9bd92de9688023b14a40c3856842d4539c9e3ca7
 SHA512:
-  metadata.gz: 3d3008b4581dfd66426ba9e9c2ed0158241d130c2e68372f124369dd42c5893fed86aff36fe9e1b14612fff2139f39cf7e4b07492b5faac13699a3f0d87f609c
-  data.tar.gz: 885d3f522cefba39eeb8765fe671ea822d52edefc700d1633997825fd7cb61c834db7d6111cbd92881c5c9d232519e70bb4aa120027cc6ad432e82286d15fb99
+  metadata.gz: 37067ae8933e3512d3be4a0e10147cad3813a76c969c414801b915b31c164bd1154b11dff58bb1196857e7f30b5fc9455ade7f305824ddf2a0c61c7149eec610
+  data.tar.gz: d37ae593f29bc0a8c2402dc39bc4d6df37478baec964480b76bbd94a23b00ff17d4236d21deff7e57b92cd18ed1d0f5cc29f00f7b7c907c0c6158c7ecf8543a7

data/README.adoc

@@ -111,7 +111,7 @@ transformer = lambda do |attributes, key = :user|
 end
 
 Etcher::Registry.new(contract:, model:, transformers: [transformer])
-                .add_loader(Etcher::Loaders::Environment.new(%w[USER HOME]))
+                .add_loader(:environment, %w[USER HOME])
                 .then { |registry| Etcher.new(registry).call }
 
 # Success(#<data user="DEMO", home="/Users/demo">)
@@ -297,11 +297,29 @@ There are a few guidelines to using them:
 * All nested keys will be flattened after being loaded. This means a key structure of `{demo: {one: "test"}}` will be flattened to `demo_one: "test"` which adheres to the {demeter_link} when a new recored is _etched_ for you.
 * The order in which you define your loaders matters. This means the first loader defined will be processed first, then the second, and so forth. Loaders defined last take precedence over previously defined loaders when overriding the same keys.
 
-The next couple of sections will help you learn about the supported loaders and how to build your own custom loader.
+For convenience, all loaders -- only packaged with this gem -- can be registered by symbol instead of constant/instance. Example:
+
+[source,ruby]
+----
+registry = Etcher::Registry.new
+
+# Environment
+registry.add_loader :environment
+
+# JSON
+registry.add_loader :json, "path/to/configuration.json"
+
+# YAML
+registry.add_loader :yaml, "path/to/configuration.yml"
+----
+
+Any positional or keyword arguments will be passed to the loader's constructor. _This only works when using `Registry#add_loader`, though._
+
+The next sections will help you learn about the supported loaders and how to build your own custom loader.
 
 ==== Environment
 
-Use `Etcher::Loaders::Environment` to load configuration information from your {environment_link}. By default, this object wraps `ENV`, uses an empty array for keys to include, and answers a filtered hash where all keys are downcased. _If you don't specify keys to include, then an empty hash is answered back_. Here's a few examples:
+Use `:environment` or `Etcher::Loaders::Environment` to load configuration information from your {environment_link}. By default, this object wraps `ENV`, uses an empty array for included keys, and answers a filtered hash where all keys are downcased. _If you don't specify keys to include, then an empty hash is answered back_. Here's a few examples:
 
 [source,ruby]
 ----
@@ -414,16 +432,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 +452,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 +481,79 @@ 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
 ----
 
+For convenience, all transformers -- only packaged with this gem -- can be registered by symbol instead of constant/instance. Example:
+
+[source,ruby]
+----
+registry = Etcher::Registry.new
+
+# String
+registry.add_transformer :string, :project_uri
+
+# Time
+registry.add_transformer :time
+----
+
+Any positional or keyword arguments will be passed to the transformers's constructor. _This only works when using `Registry#add_transformer`, though._ The following sections provide more details on each.
+
+==== String
+
+Use `Etcher::Transformers::String` to transform any key in your configuration by using the configuration's existing keys. Example:
+
+[source,ruby]
+----
+attributes = {
+  organization_uri: "https://acme.io",
+  project_name: "test",
+  project_uri: "%<organization_uri>s/projects/%<project_name>s"
+}
+
+transformer = Etcher::Transformers::String.new :project_uri
+
+transformer.call attributes
+# Success(
+  {
+    organization_uri: "https://acme.io",
+    project_name: "test",
+    project_uri: "https://acme.io/projects/test"
+  }
+)
+
+attributes.delete :project_name
+transformer.call attributes
+# Failure("Unable to transform :project_uri, missing specifier: \"<project_name>\".")
+----
+
+==== 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.6.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/etcher"

data/lib/etcher/finder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+# Finds internal constant if moniker matches, otherwise answers a failure.
+module Etcher
+  include Dry::Monads[:result]
+
+  Finder = lambda do |namespace, moniker|
+    Etcher.const_get(namespace)
+          .constants
+          .find { |constant| constant.downcase == moniker }
+          .then do |constant|
+            return Dry::Monads::Success Etcher.const_get("#{namespace}::#{constant}") if constant
+
+            Dry::Monads::Failure "Unable to select #{moniker.inspect} within #{namespace.downcase}."
+          end
+  rescue NameError
+    Dry::Monads::Failure "Invalid namespace: #{namespace.inspect}."
+  end
+end

data/lib/etcher/registry.rb

@@ -3,17 +3,37 @@
 module Etcher
   # Provides a registry of customization for loading and resolving a configuration.
   Registry = Data.define :contract, :model, :loaders, :transformers do
+    def self.find namespace, moniker, logger: LOGGER
+      case Finder.call namespace, moniker
+        in Success(constant) then constant
+        in Failure(message) then logger.abort message
+        else logger.abort "Unable to find constant in registry."
+      end
+    end
+
     def initialize contract: Contract, model: Hash, loaders: [], transformers: []
       super
     end
 
-    def add_loader loader
-      loaders.append loader
+    def add_loader(loader, *, **)
+      if loader.is_a? Symbol
+        self.class.find(:Loaders, loader).then { |constant| loaders.append constant.new(*, **) }
+      else
+        loaders.append loader
+      end
+
       self
     end
 
-    def add_transformer transformer
-      transformers.append transformer
+    def add_transformer(transformer, *, **)
+      if transformer.is_a? Symbol
+        self.class.find(:Transformers, transformer).then do |constant|
+          transformers.append constant.new(*, **)
+        end
+      else
+        transformers.append transformer
+      end
+
       self
     end
   end

data/lib/etcher/transformers/string.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Etcher
+  module Transformers
+    # Formats given key using existing and/or ancillary attributes.
+    class String
+      include Dry::Monads[:result]
+
+      def initialize key, **ancillary
+        @key = key
+        @ancillary = ancillary
+      end
+
+      def call attributes
+        value = attributes[key]
+
+        return Success attributes unless value
+
+        Success attributes.merge(key => format(value, **attributes, **ancillary))
+      rescue KeyError => error
+        Failure "Unable to transform #{key.inspect}, missing specifier: " \
+                "\"#{error.message[/<.+>/]}\"."
+      end
+
+      private
+
+      attr_reader :key, :ancillary
+    end
+  end
+end

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.6.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-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -150,11 +150,14 @@ files:
 - lib/etcher.rb
 - lib/etcher/builder.rb
 - lib/etcher/contract.rb
+- lib/etcher/finder.rb
 - lib/etcher/loaders/environment.rb
 - lib/etcher/loaders/json.rb
 - lib/etcher/loaders/yaml.rb
 - lib/etcher/registry.rb
 - lib/etcher/resolver.rb
+- lib/etcher/transformers/string.rb
+- lib/etcher/transformers/time.rb
 - lib/etcher/types.rb
 homepage: https://alchemists.io/projects/etcher
 licenses:
@@ -182,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.