etcher 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 765e913767d6c9d357ce121dc81ed86269abebeac8575e664c4becbc0043b21e
-  data.tar.gz: b16b6a76d818bbc560d615edcafba252ba42471cfa5ba1d1fc83375f37e75086
+  metadata.gz: bdae8d6e407c3a6d7f9c43c79be0f97040996c4460f726976931a0a395c6f0c5
+  data.tar.gz: 0ff6f4e79245a0e14c4e7dc36672562b5ae7ea370dd9a9ce1dae0cc83ff950bc
 SHA512:
-  metadata.gz: 70aa7039b3fabaf0b2164cc9a8c7d06a6721377ac3ba3f6b4d82e586f5fd6fd24f32d48f44ebe05b5565a624e0b1d0c00411319045638c2dabc79999d937c7e5
-  data.tar.gz: bd628b9a423ce9df42ba5f388214989e6692c09b5273975f3231b3081df47de4d1d024e9e345d939777c4f903c2b39cd1f8ddf35cfab2e8cb85d43ef814de3d3
+  metadata.gz: e9cd8e067ab556f27a53804f18f389a41a3987f9e942dcfa471cfbc937fc4a2a353c3f6a0bf260daa91667906bdcd8e162d99133563a6386fa98c9e241f3174c
+  data.tar.gz: 5feeefaa7b6216791071572592d69e93fcbd5de940ff36713c68fec83e368fa53374ab42b780748c26b08c8acc283dbe03ef77c0d2a45cf0ca379a992754db38

data/README.adoc

@@ -14,8 +14,10 @@
 :hash_link: link:https://rubyapi.org/o/hash[Hash]
 :json_link: link:https://rubyapi.org/o/json[JSON]
 :runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
+:sod_link: link:https://alchemists.io/projects/sod[Sod]
 :struct_link: link:https://alchemists.io/articles/ruby_structs[Struct]
 :transactable_link: link:https://alchemists.io/projects/transactable[Transactable]
+:versionaire_link: link:https://alchemists.io/projects/versionaire[Versionaire]
 :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
 :yaml_link: link:https://rubyapi.org/o/yaml[YAML]
 
@@ -27,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 turned into records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application. In other words, the ability to take primitive hashes and _etch_ them into a _frozen_ record with a nice interface that doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API. Finally, this pairs well with the {xdg_link} and {runcom_link} gems, Command Line Interfaces (CLIs), Application Programming Interfaces (APIs), or any application that can be configured by the user.
+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 turned into records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application. In other words, the ability to take primitive hashes and _etch_ them into a _frozen_ record with a nice interface that doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API. Finally, this pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
 
 toc::[]
 
@@ -37,7 +39,7 @@ toc::[]
 * Supports models which respond to `.[]` for consuming a splatted {hash_link} to instantiate new records. This 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 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) or anything that might require user input at runtime.
+* 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.
 
 == Requirements
 
@@ -87,7 +89,9 @@ etcher.call({one: 1, two: 2})
 # Success({:one=>1, :two=>2})
 ----
 
-Notice you get a monad -- either a `Success` or `Failure` -- as provided by the {dry_monads_link} gem. This allows you to create more sophisticated pipelines as found with the {transactable_link} gem or any kind of failsafe workflow you might need. The only problem is -- by default -- any attributes you message the instance with will only pass through what you gave it and always answer a `Success`. This is nice for initial experimentation but true power comes with full customization of the instance. Here's an advanced configuration showing all features:
+Notice you get a monad -- either a `Success` or `Failure` -- as provided by the {dry_monads_link} gem. This allows you to create more sophisticated pipelines as found with the {transactable_link} gem or any kind of failsafe workflow you might need.
+
+By default, any attributes you message the instance with will only pass through what you gave it and always answer a `Success`. This is nice for initial experimentation but true power comes with full customization of the instance. Here's an advanced configuration showing all features:
 
 [source,ruby]
 ----
@@ -122,6 +126,18 @@ While this is a more advanced use case, you'll usually only need to register a c
 
 ℹ️ All keys are converted to symbols before being processed. This is done to ensure consistency and improve debugablity when dealing with raw input that might be a mix of strings and/or symbols.
 
+=== Steps
+
+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 content.
+. *Override*: Any overrides are merged with the result of the last loader to produce updated content.
+. *Transform*: Each transformer, if any, is called to transform and manipulate the content.
+. *Validate*: The contract is called to validate the content as previously loaded, overwritten, and transformed.
+. *Model*: The model consumes the content 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.
+
 === 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:
@@ -195,14 +211,16 @@ Here you can see the power of using a contract to validate your data both as a f
 
 === Types
 
-To support contracts further, especially when working with file paths, there is a custom type for pathnames:
+To support contracts further, there are a couple custom types which might be of interest. Each custom type, as described below, is made possible via {dry_types_link}.
+
+==== Pathnames
 
 [source,ruby]
 ----
 Etcher::Types::Pathname
 ----
 
-This means you can use this custom type in your contracts to validate and cast pathnames:
+The above allows you to use pathname types in your contracts to validate and cast as pathnames:
 
 [source,ruby]
 ----
@@ -214,7 +232,24 @@ contract.call(path: "a/path").to_monad
 # Success(#<Dry::Schema::Result{:path=>#<Pathname:a/path>} errors={} path=[]>)
 ----
 
-All of this is made possible via {dry_types_link} so make sure to check out documentation for details.
+==== Versions
+
+[source,ruby]
+----
+Etcher::Types::Version
+----
+
+The above allows you to validate and cast versions within your contracts -- via the {versionaire_link} gem -- as follows:
+
+[source,ruby]
+----
+contract = Dry::Schema.Params do
+  required(:version).filled Etcher::Types::Version
+end
+
+contract.call(version: "1.2.3").to_monad
+# Success(#<Dry::Schema::Result{:version=>"1.2.3"} errors={} path=[]>)
+----
 
 === Models
 
@@ -258,7 +293,7 @@ There are a few guidelines to using them:
 * 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.
 * 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 loaders defined first when overriding the same keys.
+* 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.
 

data/etcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "etcher"
-  spec.version = "0.2.0"
+  spec.version = "0.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/etcher"
@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dry-monads", "~> 1.6"
   spec.add_dependency "dry-types", "~> 1.7"
   spec.add_dependency "refinements", "~> 11.0"
+  spec.add_dependency "versionaire", "~> 12.1"
   spec.add_dependency "zeitwerk", "~> 2.6"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data/lib/etcher/types.rb

@@ -2,6 +2,7 @@
 
 require "dry/types"
 require "pathname"
+require "versionaire"
 
 module Etcher
   # Defines custom types.
@@ -9,5 +10,6 @@ module Etcher
     include Dry.Types(default: :strict)
 
     Pathname = Constructor ::Pathname
+    Version = Constructor Versionaire::Version, Versionaire.method(:Version)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-06-13 00:00:00.000000000 Z
+date: 2023-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: versionaire
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -168,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
+rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.