etcher 1.6.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e462682ab4cb1a7149595a36e1d2893f329db37813209655c53a6fd767e9751
-  data.tar.gz: 2f1a5bd597dfa8590d6ad48f9bd92de9688023b14a40c3856842d4539c9e3ca7
+  metadata.gz: 34e559c63ed6f3baa580995e227f09113e26cacc8920a919f5d10912b4d1cad0
+  data.tar.gz: e23d9de0fffff7d2ae6835a0c6e38dbab5cfdc555839051544a9f24432b73884
 SHA512:
-  metadata.gz: 37067ae8933e3512d3be4a0e10147cad3813a76c969c414801b915b31c164bd1154b11dff58bb1196857e7f30b5fc9455ade7f305824ddf2a0c61c7149eec610
-  data.tar.gz: d37ae593f29bc0a8c2402dc39bc4d6df37478baec964480b76bbd94a23b00ff17d4236d21deff7e57b92cd18ed1d0f5cc29f00f7b7c907c0c6158c7ecf8543a7
+  metadata.gz: 5855391dea3b6fa69e206867a8f4b5b3c304e06902044cd70d01eea97dfcc4126bc505d2ea0e9c5424e1089caca8bf7d4ad3d340350a6a53a0d34e55cd4280eb
+  data.tar.gz: e4c23192f2f12a3b086a4dcfc796fa9be9b52c743583e39bcd241071e8e7d4dc487b2b1a47f37a2d31076efd62247d56a043d45c8e135100f2636b40052d2013

data/README.adoc

@@ -15,6 +15,7 @@
 :pipeable_link: link:https://alchemists.io/projects/pipeable[Pipeable]
 :runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
 :sod_link: link:https://alchemists.io/projects/sod[Sod]
+:string_formats_link: link:https://docs.ruby-lang.org/en/3.3/format_specifications_rdoc.html[String Formats]
 :struct_link: link:https://alchemists.io/articles/ruby_structs[Struct]
 :versionaire_link: link:https://alchemists.io/projects/versionaire[Versionaire]
 :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
@@ -28,7 +29,7 @@ ____
 [Use] strong acid or mordant to cut into the unprotected parts of a metal surface to create a design in intaglio (incised) in the metal.
 ____
 
-By using Etcher, you have a reliable way to load default configurations (i.e. {environment_link}, {json_link}, {yaml_link}) which can be validated and etched into _frozen_ records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application which doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API and pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
+By using Etcher, you have a reliable way to load default configurations (i.e. {hash_link}, {environment_link}, {json_link}, {yaml_link}) which can be validated and etched into _frozen_ records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application which doesn't violate the {demeter_link}. This comes complete with loaders, transformations, and validations all via a simple Object API that pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
 
 toc::[]
 
@@ -36,7 +37,7 @@ toc::[]
 
 * Supports contracts which respond to `#call` to validate a {hash_link} before building the final record. Pairs well with the {dry_schema_link} and {dry_validation_link} gems.
 * Supports models which respond to `.[]` for consuming a splatted {hash_link} to instantiate new records. Pairs well with primitives such as: {hash_link}, {data_link}, and {struct_link}.
-* Supports loading of default configurations from the {environment_link}, a {json_link} configuration, a {yaml_link} configuration, or anything that can answer a hash.
+* Supports loading of default configurations from a {hash_link}, the {environment_link}, a {json_link} configuration, a {yaml_link} configuration, or anything that can answer a hash.
 * Supports multiple transformations which can process loaded configuration hashes and answer a transformed hash.
 * Supports {hash_link} overrides as a final customization which is handy for Command Line Interfaces (CLIs), as aided by {sod_link}, or anything that might require user input at runtime.
 
@@ -133,16 +134,16 @@ While this is a more advanced use case, you'll usually only need to register a c
 As hinted at above, the complete sequence of steps are performed in the order listed:
 
 . *Load*: Each loader, if any, is called and merged with the previous loader to build initial attributes.
-. *Override*: Any overrides are merged with the result of the last loader to produce updated attributes. ⚠️ _In Version 2.0.0, this step will happen after the Transform step._
 . *Transform*: Each transformer, if any, is called to transform and manipulate the attributes.
+. *Override*: Overrides, if any, are merged with the result of the last transformer so you can fine tune the data as desired.
 . *Validate*: The contract is called to validate the attributes as previously loaded, overwritten, and transformed.
 . *Model*: The model consumes the attributes of the validated contract and creates a new record for you to use as needed.
 
-You can use the above steps as a reference when using this gem. Each step is explained in greater detail below.
+Each step _mutates_ the attributes of the previous step in order to produce a record (success) or error (failure). You can use the above steps as a reference when using this gem. Each step is explained in greater below.
 
 === Registry
 
-The registry is provided as a way to register any/all complexity for before creating a new Etcher instance. Here's what you get by default:
+The registry provides a way to register any/all behavior for before creating a new Etcher instance. Here's what you get by default:
 
 [source,ruby]
 ----
@@ -179,7 +180,7 @@ Contracts are a critical piece of this workflow as they provide a way to validat
 
 * `#call`: Must be able to consume a {hash_link} and answer an object which can respond to `#to_monad`.
 
-The best gems which adhere to this interface are: {dry_schema_link} and {dry_validation_link}. You'll also want to make sure the {dry_monads_link} extensions are loaded, as briefly shown earlier, so the result will respond to `#to_monad`. Here's how to enable monad support if using both gems:
+Both {dry_schema_link} and {dry_validation_link} respond to the `#to_monad` message. Ensure the {dry_monads_link} extensions are loaded too, as briefly shown earlier, so the result will respond to the `#to_monad` message. Here's how to enable monad support if using both gems:
 
 [source,ruby]
 ----
@@ -209,7 +210,7 @@ etcher.call from: "Mork", to: "Mindy"
 # Success({:from=>"Mork", :to=>"Mindy"})
 ----
 
-Here you can see the power of using a contract to validate your data both as a failure and a success. Unfortunately, with the success, we only get a {hash_link} as a record and it would be nice to structured record which will be explained shortly.
+Here you can see the power of using a contract to validate your data both as a failure and a success. Unfortunately, with the success, we only get a {hash_link} as a record but it would be better to have a data structure which will be explained shortly.
 
 === Types
 
@@ -279,7 +280,7 @@ Notice we get an failure if all attributes are not provided but if we supply the
 
 === Loaders
 
-Loaders are a great way to load a _default_ configuration for your application which can be in multiple formats. Loaders can either be defined when creating a new registry instance or added after the fact. Here are a few examples:
+Loaders are a great way to load a _default_ configuration for your application which can be in multiple formats. Loaders can either be defined when creating a new registry instance or added after the fact. Here are a couple examples:
 
 [source,ruby]
 ----
@@ -290,10 +291,26 @@ 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:
 
-* They must respond to `#call` with no arguments.
-* All keys are symbolized which helps streamline merging and overriding values from the same keys across multiple configurations.
+[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.`)
+* All keys are symbolized after the loader is called which helps streamline merging and overriding values from the same keys across multiple configurations.
 * 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.
 
@@ -341,6 +358,25 @@ loader.call
 
 This loader is great for pulling from environment variables as a fallback configuration for your application.
 
+==== Hash
+
+Use `:hash` or `Etcher::Loaders::Hash` to load in-memory attributes. By default, this loader will answer an empty hash if not supplied with any attributes. Here's a few examples:
+
+[source,ruby]
+----
+# Default behavior.
+loader = Etcher::Loaders::Hash.new
+loader.call
+# Success({})
+
+# With custom attributes
+loader = Etcher::Loaders::Hash.new one: 1, two: 2
+loader.call
+# Success({:one=>1, :two=>2})
+----
+
+This loader is great for adding custom attributes, overriding/adjusting attributes from a previous loader, or customizing attributes for testing purposes within a test suite.
+
 ==== JSON
 
 Use `Etcher::Loaders::JSON` to load configuration information from a {json_link} file. Here's how to use this loader (using a file that doesn't exist):
@@ -362,9 +398,12 @@ loader = Etcher::Loaders::JSON.new "your/path/to/configuration.json",
 loader.call  # Success({})
 ----
 
-Otherwise, if the file exists with content, you'll get a `Hash` wrapped as a `Success`.
+If the file exists with _valid_ content, you'll get a `Hash` wrapped as a `Success`. In situations in which the file doesn't exist, you'll get a `Success` with an empty hash and debug information logged instead. Any failures will be provided with step, constant, and payload details. Example:
 
-ℹ️ The logger is only used to log debug information when issues are encountered when reading from the file. This is done to reduce noise in your console when a configuration might have issues and can safely revert to the fallback in order to load the rest of the configuration.
+[source,ruby]
+----
+Failure step: :load, constant: Etcher::Loaders::JSON, payload: "Danger!"
+----
 
 ==== YAML
 
@@ -387,9 +426,12 @@ loader = Etcher::Loaders::YAML.new "your/path/to/configuration.yml",
 loader.call  # Success({})
 ----
 
-Otherwise, if the file exists with content, you'll get a `Hash` wrapped as a `Success`.
+If the file exists with _valid_ content, you'll get a `Hash` wrapped as a `Success`. In situations in which the file doesn't exist, you'll get a `Success` with an empty hash and debug information logged instead. Any failures will be provided with step, constant, and payload details. Example:
 
-ℹ️ The logger is only used to log debug information when issues are encountered when reading from the file. This is done to reduce noise in your console when a configuration might have issues and can safely revert to the fallback in order to load the rest of the configuration.
+[source,ruby]
+----
+Failure step: :load, constant: Etcher::Loaders::YAML, payload: "Danger!"
+----
 
 ==== Custom
 
@@ -402,26 +444,31 @@ require "dry/monads"
 class Demo
   include Dry::Monads[:result]
 
-  def initialize fallback: {}
-    @fallback = fallback
+  def initialize processor: Processor.new
+    @processor = processor
   end
 
-  def call = Success fallback
+  def call
+    Success processor.call
+  rescue ProcessorError => error
+    Failure step: :load, constant: self.class, payload: error.message
+  end
 
   private
 
-  attr_reader :fallback
+  attr_reader :processor
 end
 
-etcher = Etcher::Registry[loaders: [Demo.new]].then { |registry| Etcher.new registry }
-etcher.call  # Success({})
+registry = Etcher::Registry[loaders: [Demo.new]]
+
+Etcher.new(registry).call
 ----
 
-While the above isn't super useful since it only answers whatever you provide as fallback information, you can see there is little effort required to implement and customize as desired.
+While the above assumes you have some kind of `Processor` for loading attributes, you can see there is little effort required to implement and customize as desired.
 
 === Transformers
 
-Transformers are great for modifying specific keys and values. They give you finer grained control over your configuration and are the last step before validating and creating an associated record of your configuration. Transformers can either be defined when creating a new registry instance or added after the fact. Here are a few examples:
+Transformers are great for _mutating_ specific keys and values. They give you fine grained customization over your configuration. Transformers can either be defined when creating a new registry instance or added after the fact. Here are a couple examples:
 
 [source,ruby]
 ----
@@ -432,12 +479,28 @@ 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.
 * 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.
-* 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.
+* They must answer either a success with attributes (i.e. `Success attributes`) or a failure with details about the failure (i.e. `Failure step: :transform, constant: MyTransformer, payload: "My error message.`)
+* When using a proc/lambda, the first, _required_, parameter should be the `attributes` parameter followed by a second positional `key` parameter.
+* When using a class, the `key` should be your first positional parameter. 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.
 
 For example, the following capitalizes all values (which may or may not be good depending on your data structure):
@@ -492,8 +555,8 @@ For convenience, all transformers -- only packaged with this gem -- can be regis
 ----
 registry = Etcher::Registry.new
 
-# String
-registry.add_transformer :string, :project_uri
+# Format
+registry.add_transformer :format, :project_uri
 
 # Time
 registry.add_transformer :time
@@ -501,9 +564,47 @@ 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
+==== Basename
+
+Use `Etcher::Transformers::Basename` to dynamically obtain the name of the current directory as a value for a key. This is handy for scripting or CLI purposes when needing to know the name of the current project you are working in. Example:
+
+[source,ruby]
+----
+transformer = Etcher::Transformers::Basename.new :demo
+transformer.call({})
+# Success({:demo=>"scratch"})
+
+transformer = Etcher::Transformers::Basename.new :demo, fallback: "undefined"
+transformer.call({})
+# Success({:demo=>"undefined"})
+
+transformer = Etcher::Transformers::Basename.new :demo
+transformer.call({demo: "defined"})
+# Success({:demo=>"defined"})
+----
+
+==== Root
+
+Use `Etcher::Transformers::Root` to dynamically obtain the current path as a value for a key. This is handy for obtaining the absolute path to a new or existing directory. Example:
+
+[source,ruby]
+----
+transformer = Etcher::Transformers::Root.new :demo
+transformer.call({})
+# Success({:demo=>#<Pathname:/Users/demo/Engineering/OSS/scratch>})
+
+transformer = Etcher::Transformers::Root.new :demo, fallback: "undefined"
+transformer.call({})
+# Success({:demo=>#<Pathname:/Users/demo/Engineering/undefined>})
+
+transformer = Etcher::Transformers::Root.new :demo
+transformer.call({demo: "defined"})
+# Success({:demo=>#<Pathname:/Users/demo/Engineering/defined>})
+----
+
+==== Format
 
-Use `Etcher::Transformers::String` to transform any key in your configuration by using the configuration's existing keys. 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]
 ----
@@ -512,10 +613,13 @@ attributes = {
   project_name: "test",
   project_uri: "%<organization_uri>s/projects/%<project_name>s"
 }
+----
 
-transformer = Etcher::Transformers::String.new :project_uri
+Using the above `attributes`, you'll get a `Success` when all required keys exist:
 
-transformer.call attributes
+[source,ruby]
+----
+Etcher::Transformers::Format.new(:project_uri).call attributes
 # Success(
   {
     organization_uri: "https://acme.io",
@@ -523,56 +627,109 @@ transformer.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
-# Failure("Unable to transform :project_uri, missing specifier: \"<project_name>\".")
+Etcher::Transformers::Format.new(:project_uri).call attributes
+
+# Failure(
+#   {
+#     step: :transform,
+#     constant: Etcher::Transformers::Format,
+#     payload: "Unable to transform :project_uri, missing specifier: \"<project_name>\"."
+#   }
+# )
 ----
 
-==== Time
+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
 
-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.
+# 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.
 
-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:
+You can also, safely, transform a value which _doesn't_ have string specifiers:
 
 [source,ruby]
 ----
-transformer = Etcher::Transformers::Time.new
-transformer.call({})
-# Success({:loaded_at=>2024-05-23 22:18:27.92767 UTC})
+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 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
+
+Use `Etcher::Transformers::Time` to transform the any 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.
+
+You must supply a key and `Time.now.utc` is the default fallback. You can customize as desired. Example:
+
+[source,ruby]
+----
 transformer = Etcher::Transformers::Time.new :now
 transformer.call({})
-# Success({:now=>2024-05-23 22:18:49.93189 UTC})
+# Success({:now=>2024-06-15 22:43:29.178488 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})
+transformer = Etcher::Transformers::Time.new :now
+transformer.call({now: Time.utc(2000, 1, 1)})
+# Success({:now=>2000-01-01 00:00:00 UTC})
 ----
 
 === Overrides
 
-Overrides are what you pass to the Etcher instance when called. Example:
+Overrides are what you pass to the Etcher instance when called. They allow you to override any values that were loaded and/or transformed. Example:
 
 [source,ruby]
 ----
 etcher = Etcher.new
+
+# With symbol keys.
 etcher.call name: "test", label: "Test"
+# Success({:name=>"test", :label=>"Test"})
 
+# With string keys.
+etcher.call "name" => "test", "label" => "Test"
 # Success({:name=>"test", :label=>"Test"})
 ----
 
-Overrides are applied _after_ any loaders are processed and _before_ any transformations. They are a nice way to deal with user input during runtime or provide any additional configuration not supplied by the loading of your default configuration while still allowing you to transform them if desired.
-
-⚠️ In Version 2.0.0, this step will be changed to occur _after_ the Transform step for maximum flexibility.
+Overrides are applied _after_ any transforms and _before_ validations. They are a nice way to deal with user input during runtime or provide additional attributes not supplied by the loading and/or transforming of your default configuration while ensuring they are validated properly. Any string keys will be transformed to symbol keys to ensure consistency and reduce issues when merged.
 
 === Resolver
 
-In situations where you'd like Etcher to handle the complete load, transform, validate, and build steps for you, then you can use the resolver. This is provided for use cases where you'd like Etcher to handle everything for you and abort if otherwise. Example:
+In situations where you'd like Etcher to handle the complete load, transform, override, validate, and model steps for you, then you can use the resolver. This is provided for use cases where you'd like Etcher to handle everything for you and abort if otherwise. Example:
 
 [source,ruby]
 ----
@@ -599,23 +756,22 @@ registry = Etcher::Registry.new(contract:, model:)
 
 Etcher.call registry
 
-# 🔥 Unable to load configuration due to the following issues:
+# 🛑 Etcher validate failure (Etcher::Builder). Unable to load configuration:
 #   - to is missing
 #   - from is missing
 
 Etcher.call registry, to: "Mindy"
 
-# 🔥 Unable to load configuration due to the following issues:
+# 🛑 Etcher validate failure (Etcher::Builder). Unable to load configuration:
 #   - from is missing
 
-
 registry = Etcher::Registry.new(model: Data.define(:name, :label))
 Etcher.call registry, to: "Mindy"
 
-# 🔥 Build failure: :record. Missing keywords: :name, :label.
+# 🛑 Etcher model failure (Etcher::Builder). Missing keywords: :name, :label.
 ----
 
-💡 When using a custom registry, make sure it's the first argument. All arguments afterwards can be any number of key/values overrides which is similar to how `Etcher.new` works.
+💡 When using a custom registry, make sure it's the first argument. Additional arguments can be supplied afterwards and they can be any number of key/value overrides which is similar to how `Etcher.new` works.
 
 == Development
 
@@ -639,7 +795,7 @@ bin/console
 
 The following illustrates the full sequences of events when _etching_ new records:
 
-image::https://alchemists.io/images/projects/etcher/doc/architecture.svg[Architecture Diagram]
+image::https://alchemists.io/images/projects/etcher/architecture.png[Architecture Diagram,1250,1071,role=focal_point]
 
 == Tests
 

data/etcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "etcher"
-  spec.version = "1.6.0"
+  spec.version = "2.1.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/etcher"
@@ -23,11 +23,11 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = "~> 3.3"
-  spec.add_dependency "cogger", "~> 0.15"
+  spec.add_dependency "cogger", "~> 0.21"
   spec.add_dependency "core", "~> 1.0"
   spec.add_dependency "dry-monads", "~> 1.6"
   spec.add_dependency "dry-types", "~> 1.7"
-  spec.add_dependency "refinements", "~> 12.1"
+  spec.add_dependency "refinements", "~> 12.5"
   spec.add_dependency "versionaire", "~> 13.0"
   spec.add_dependency "zeitwerk", "~> 2.6"
 

data/lib/etcher/builder.rb

@@ -16,27 +16,25 @@ module Etcher
     end
 
     def call(**overrides)
-      load(overrides.symbolize_keys!).then { |attributes| transform attributes }
-                                     .bind { |attributes| validate attributes }
-                                     .bind { |attributes| model attributes }
+      load.bind { |attributes| transform attributes }
+          .fmap { |attributes| attributes.merge! overrides.symbolize_keys! }
+          .bind { |attributes| validate attributes }
+          .bind { |attributes| model attributes }
     end
 
     private
 
     attr_reader :registry
 
-    def load overrides
+    def load
       registry.loaders
               .map { |loader| loader.call.fmap { |pairs| pairs.flatten_keys.symbolize_keys! } }
-              .each
-              .with_object({}) { |attributes, all| attributes.bind { |body| all.merge! body } }
-              .merge!(overrides.flatten_keys)
-              .then { |attributes| Success attributes }
+              .reduce(Success({})) { |all, result| merge all, result }
     end
 
     def transform attributes
-      registry.transformers.reduce attributes do |all, transformer|
-        all.bind { |body| transformer.call body }
+      registry.transformers.reduce Success(attributes) do |all, transformer|
+        merge all, transformer.call(attributes)
       end
     end
 
@@ -44,13 +42,22 @@ module Etcher
       registry.contract
               .call(attributes)
               .to_monad
-              .or { |result| Failure step: __method__, payload: result.errors.to_h }
+              .or do |result|
+                Failure step: __method__, constant: self.class, payload: result.errors.to_h
+              end
     end
 
     def model attributes
       Success registry.model[**attributes.to_h].freeze
     rescue ArgumentError => error
-      Failure step: __method__, payload: "#{error.message.capitalize}."
+      Failure step: __method__, constant: self.class, payload: "#{error.message.capitalize}."
+    end
+
+    def merge(*items)
+      case items
+        in Success(all), Success(subset) then Success(all.merge!(subset))
+        else items.last
+      end
     end
   end
 end

data/lib/etcher/loaders/environment.rb

@@ -9,16 +9,16 @@ module Etcher
     class Environment
       include Dry::Monads[:result]
 
-      def initialize includes = Core::EMPTY_ARRAY, source: ENV
-        @includes = Array includes
-        @source = source
+      def initialize attributes = ENV, only: Core::EMPTY_ARRAY
+        @attributes = attributes
+        @only = Array only
       end
 
-      def call = Success source.slice(*includes).transform_keys(&:downcase)
+      def call = Success attributes.slice(*only).transform_keys(&:downcase)
 
       private
 
-      attr_reader :includes, :source
+      attr_reader :attributes, :only
     end
   end
 end

data/lib/etcher/loaders/hash.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Etcher
+  module Loaders
+    # Loads (wraps) raw attributes.
+    class Hash
+      include Dry::Monads[:result]
+
+      def initialize(**attributes)
+        @attributes = attributes
+      end
+
+      def call = Success attributes
+
+      private
+
+      attr_reader :attributes
+    end
+  end
+end

data/lib/etcher/loaders/json.rb

@@ -18,22 +18,33 @@ module Etcher
 
       def call
         Success ::JSON.load_file(path)
-      rescue TypeError, Errno::ENOENT
-        debug_and_fallback "Invalid path: #{path_info}. Using fallback."
-      rescue ::JSON::ParserError => error
-        debug_and_fallback "#{error.message}. Path: #{path_info}. Using fallback."
+      rescue Errno::ENOENT, TypeError then debug_invalid_path
+      rescue ::JSON::ParserError => error then content_failure error
       end
 
       private
 
       attr_reader :path, :fallback, :logger
 
-      def path_info = path.to_s.inspect
-
-      def debug_and_fallback message
-        logger.debug { message }
+      def debug_invalid_path
+        logger.debug { "Invalid path: #{path_info}. Using fallback." }
         Success fallback
       end
+
+      def content_failure error
+        constant = self.class
+        token = error.message[/(?<token>'.+?')/, :token].to_s.tr "'", ""
+
+        if token.empty?
+          Failure step: :load, constant:, payload: "File is empty: #{path_info}."
+        else
+          Failure step: :load,
+                  constant:,
+                  payload: "Invalid content: #{token.inspect}. Path: #{path_info}."
+        end
+      end
+
+      def path_info = path.to_s.inspect
     end
   end
 end

data/lib/etcher/loaders/yaml.rb

@@ -2,6 +2,7 @@
 
 require "core"
 require "dry/monads"
+require "refinements/string"
 require "yaml"
 
 module Etcher
@@ -10,6 +11,8 @@ module Etcher
     class YAML
       include Dry::Monads[:result]
 
+      using Refinements::String
+
       def initialize path, fallback: Core::EMPTY_HASH, logger: LOGGER
         @path = path
         @fallback = fallback
@@ -18,10 +21,10 @@ module Etcher
 
       def call
         load
-      rescue TypeError, Errno::ENOENT
-        debug_and_fallback "Invalid path: #{path_info}. Using fallback."
-      rescue Psych::Exception => error
-        debug_and_fallback "#{error.message}. Path: #{path_info}. Using fallback."
+      rescue Errno::ENOENT, TypeError then debug_invalid_path
+      rescue Psych::AliasesNotEnabled then alias_failure
+      rescue Psych::DisallowedClass => error then disallowed_failure error
+      rescue Psych::SyntaxError => error then syntax_failure error
       end
 
       private
@@ -31,17 +34,48 @@ module Etcher
       def load
         content = ::YAML.safe_load_file path
 
-        return Success content if content.is_a? Hash
+        case content
+          in ::Hash then Success content
+          in nil then empty_failure
+          else invalid_failure content
+        end
+      end
 
-        debug_and_fallback "Invalid content: #{content.inspect}. Using fallback."
+      def debug_invalid_path
+        logger.debug { "Invalid path: #{path_info}. Using fallback." }
+        Success fallback
       end
 
-      def path_info = path.to_s.inspect
+      def empty_failure
+        Failure step: :load, constant: self.class, payload: "File is empty: #{path_info}."
+      end
 
-      def debug_and_fallback message
-        logger.debug { message }
-        Success fallback
+      def invalid_failure content
+        Failure step: :load,
+                constant: self.class,
+                payload: "Invalid content: #{content.inspect}. Path: #{path_info}."
+      end
+
+      def alias_failure
+        Failure step: :load,
+                constant: self.class,
+                payload: "Aliases are disabled, please remove. Path: #{path_info}."
+      end
+
+      def disallowed_failure error
+        Failure step: :load,
+                constant: self.class,
+                payload: "Invalid type, #{error.message.down}. Path: #{path_info}."
       end
+
+      def syntax_failure error
+        Failure step: :load,
+                constant: self.class,
+                payload: "Invalid syntax, #{error.message[/found.+/]}. " \
+                         "Path: #{path_info}."
+      end
+
+      def path_info = path.to_s.inspect
     end
   end
 end

data/lib/etcher/registry.rb

@@ -15,25 +15,30 @@ module Etcher
       super
     end
 
-    def add_loader(loader, *, **)
-      if loader.is_a? Symbol
-        self.class.find(:Loaders, loader).then { |constant| loaders.append constant.new(*, **) }
+    def add_loader(loader, ...) = add(loader, :Loaders, ...)
+
+    def remove_loader(index) = remove index, loaders
+
+    def add_transformer(transformer, ...) = add(transformer, :Transformers, ...)
+
+    def remove_transformer(index) = remove index, transformers
+
+    private
+
+    def add(item, namespace, ...)
+      collection = __send__ namespace.downcase
+
+      if item.is_a? Symbol
+        self.class.find(namespace, item).then { |kind| collection.append kind.new(...) }
       else
-        loaders.append loader
+        collection.append item
       end
 
       self
     end
 
-    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
-
+    def remove index, collection
+      collection.delete_at index
       self
     end
   end

data/lib/etcher/resolver.rb

@@ -10,35 +10,33 @@ module Etcher
 
     using Refinements::Array
 
-    def initialize registry = Registry.new, kernel: Kernel, logger: LOGGER
+    def initialize registry = Registry.new, logger: LOGGER
       @builder = Builder.new registry
-      @kernel = kernel
       @logger = logger
     end
 
     def call(**overrides)
       case builder.call(**overrides)
         in Success(attributes) then attributes
-        in Failure(step:, payload: String => payload)
-          logger.fatal { "Build failure: #{step.inspect}. #{payload}" }
-          kernel.abort
-        in Failure(step:, payload: Hash => payload) then log_and_abort payload
-        else fail StandardError, "Unable to parse configuration."
+        in Failure(step:, constant:, payload: String => payload)
+          logger.abort "#{step.capitalize} failure (#{constant}). #{payload}"
+        in Failure(step:, constant:, payload: Hash => payload)
+          log_and_abort step, constant, payload
+        in Failure(String => message) then logger.abort message
+        else logger.abort "Unable to parse failure."
       end
     end
 
     private
 
-    attr_reader :builder, :kernel, :logger
+    attr_reader :builder, :logger
 
-    def log_and_abort errors
-      logger.fatal do
-        details = errors.map { |key, message| "  - #{key} #{message.to_sentence}\n" }
-                        .join
-        "Unable to load configuration due to the following issues:\n#{details}"
-      end
+    def log_and_abort step, constant, errors
+      details = errors.map { |key, message| "  - #{key} #{message.to_sentence}\n" }
+                      .join
 
-      kernel.abort
+      logger.abort "#{step.capitalize} failure (#{constant}). " \
+                   "Unable to load configuration:\n#{details}"
     end
   end
 end

data/lib/etcher/transformers/basename.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "refinements/hash"
+
+module Etcher
+  module Transformers
+    # Conditionally updates value based on path.
+    class Basename
+      include Dry::Monads[:result]
+
+      using Refinements::Hash
+
+      def initialize key, fallback: Pathname.pwd.basename.to_s
+        @key = key
+        @fallback = fallback
+      end
+
+      def call attributes
+        attributes.fetch_value(key) { attributes.merge! key => fallback }
+        Success attributes
+      end
+
+      private
+
+      attr_reader :key, :fallback
+    end
+  end
+end

data/lib/etcher/transformers/format.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Etcher
+  module Transformers
+    # Formats given key using existing and/or placeholder attributes.
+    class Format
+      include Dry::Monads[:result]
+
+      def initialize key, *retainers, **mappings
+        @key = key
+        @retainers = retainers
+        @mappings = mappings
+        @pattern = /%<.+>s/o
+      end
+
+      def call attributes
+        value = attributes[key]
+
+        return Success attributes unless value && value.match?(pattern)
+
+        Success attributes.merge!(key => format(value, **attributes, **pass_throughs))
+      rescue KeyError => error
+        Failure step: :transform,
+                constant: self.class,
+                payload: "Unable to transform #{key.inspect}, missing specifier: " \
+                         "\"#{error.message[/<.+>/]}\"."
+      end
+
+      private
+
+      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

data/lib/etcher/transformers/root.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "refinements/hash"
+
+module Etcher
+  module Transformers
+    # Conditionally updates value based on path.
+    class Root
+      include Dry::Monads[:result]
+
+      using Refinements::Hash
+
+      def initialize key, fallback: Pathname.pwd
+        @key = key
+        @fallback = fallback
+      end
+
+      def call attributes
+        value = attributes.fetch_value(key) { fallback }
+        Success attributes.merge!(key => Pathname(value).expand_path)
+      end
+
+      private
+
+      attr_reader :key, :fallback
+    end
+  end
+end

data/lib/etcher/transformers/time.rb

@@ -8,14 +8,14 @@ module Etcher
     class Time
       include Dry::Monads[:result]
 
-      def initialize key = :loaded_at, fallback: ::Time.now.utc
+      def initialize key, fallback: ::Time.now.utc
         @key = key
         @fallback = fallback
       end
 
       def call attributes
-        attributes.fetch(key) { fallback }
-                  .then { |value| Success attributes.merge!(key => value) }
+        attributes.fetch(key) { attributes.merge! key => fallback }
+        Success attributes
       end
 
       private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 1.6.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-05-31 00:00:00.000000000 Z
+date: 2024-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.21'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.21'
 - !ruby/object:Gem::Dependency
   name: core
   requirement: !ruby/object:Gem::Requirement
@@ -99,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.1'
+        version: '12.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.1'
+        version: '12.5'
 - !ruby/object:Gem::Dependency
   name: versionaire
   requirement: !ruby/object:Gem::Requirement
@@ -152,11 +152,14 @@ files:
 - lib/etcher/contract.rb
 - lib/etcher/finder.rb
 - lib/etcher/loaders/environment.rb
+- lib/etcher/loaders/hash.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/basename.rb
+- lib/etcher/transformers/format.rb
+- lib/etcher/transformers/root.rb
 - lib/etcher/transformers/time.rb
 - lib/etcher/types.rb
 homepage: https://alchemists.io/projects/etcher
@@ -185,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.

data/lib/etcher/transformers/string.rb

@@ -1,32 +0,0 @@
-# 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