etcher 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75820bd97bf8b61960802c1bb85cb91d5ad583778ca5860d4a887eea59f516a5
-  data.tar.gz: b83d2f5ed78a7ef5ba8b622b63855226413fb4a574cf44577a9f825509a33d82
+  metadata.gz: 3e462682ab4cb1a7149595a36e1d2893f329db37813209655c53a6fd767e9751
+  data.tar.gz: 2f1a5bd597dfa8590d6ad48f9bd92de9688023b14a40c3856842d4539c9e3ca7
 SHA512:
-  metadata.gz: 891f2042e506243598e6545846ea5a4aeae21658315f5c25e32121c45279a64721cea0c275cf8ce7d723724007e108d3e09b7d538b6d28c7a049c7599da09c73
-  data.tar.gz: 0cb1f523435a2244994e88a9a51852f2a67b83c10bb3b817b147c9c80dd615bf777ecec069b2121af497dc225c6f1a032f53e856d41961145255b792eb70c80c
+  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]
 ----
@@ -468,7 +486,48 @@ etcher = Etcher.new(registry)
 etcher.call
 ----
 
-If you'd like prebuilt transformers, the following details what is supplied by this gem.
+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
 

data/etcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "etcher"
-  spec.version = "1.5.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 1.5.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-23 00:00:00.000000000 Z
+date: 2024-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -150,11 +150,13 @@ 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
@@ -183,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.