unifig 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbc1ebd81be5210930760f06ea0c36849862425a9f0831512efed9d4cc0a81a9
-  data.tar.gz: 06c545484d1094f7a8d8609b48d077f602c689d0e505e01157e80d3adbedecb1
+  metadata.gz: 2daa78635ee2bccb9232401f2d8c26ad3845069ec0445ffbadf2657ac0ea85bd
+  data.tar.gz: 196d2431dc1025377ca12c5108dc6398c7c473b11d3daaf204dd3621a13cf4f7
 SHA512:
-  metadata.gz: b6c024e5b3aefe1a2bba0da9908352a489263afa1d8deb047b9a0a54b29dfe621f23a71266bf12ae1a332c7a6d62a3871b596540e12f0a52a5ed62065b3be219
-  data.tar.gz: 0ab9b4da14ee56d343dfbb95c6e73cdb81e924a8027686276c6c007bed49a017e0933a9023e644a4c8cd948d13c73b4963ef6d6b1bb9c6ec6ae2038120fa69f2
+  metadata.gz: 81359820cd6783317b0697ca4bac3161cd59650e76449d60a17e3b69eab1e5f46f7910643af53229859ebaa32886c9724728fbd490ddb7d76142593f1bae483a
+  data.tar.gz: d2f52f43b879df6941bcc790e22de92bc4ee75d5a0115b59b3b38454882481e525ff01847f09e009d6f3b0407fe66814426764981112a89d87b27996474b3cd5

data/CHANGELOG.md

@@ -1,5 +1,10 @@
+# [0.2.0][] (TBD)
+
+- An environment is no longer required.
+
 # [0.1.0][] (2022-07-18)
 
 Initial release.
 
+[0.2.0]: https://github.com/AaronLasseigne/unifig/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/AaronLasseigne/unifig/compare/v0.0.0...v0.1.0

data/CONTRIBUTING.md

@@ -8,7 +8,7 @@ For features please open a [discussion][] and we can make sure the feature fits
 2. Add a breaking test for your change.
 3. Make the tests pass.
 4. Push your fork.
-5. Submit a pull request.
+5. Submit a pull request against the `next` branch.
 
 ## Code Style
 

data/README.md

@@ -1,6 +1,6 @@
 # [Unifig][]
 
-Unifig lets you load external variables from one or more providers (e.g. local file, `ENV`).
+Unifig is a pluggable system for loading external variables from one or more providers (e.g. `ENV`).
 
 [![Version](https://img.shields.io/gem/v/unifig.svg?style=flat-square)](https://rubygems.org/gems/unifig)
 [![Test](https://img.shields.io/github/workflow/status/AaronLasseigne/unifig/Test?label=Test&style=flat-square)](https://github.com/AaronLasseigne/unifig/actions?query=workflow%3ATest)
@@ -10,13 +10,13 @@ Unifig lets you load external variables from one or more providers (e.g. local f
 Add it to your Gemfile:
 
 ``` rb
-gem 'unifig', '~> 0.1.0'
+gem 'unifig', '~> 0.2.0'
 ```
 
 Or install it manually:
 
 ``` sh
-$ gem install unifig --version '~> 0.1.0'
+$ gem install unifig --version '~> 0.2.0'
 ```
 
 This project uses [Semantic Versioning][].
@@ -24,27 +24,56 @@ Check out [GitHub releases][] for a detailed list of changes.
 
 ## Usage
 
+### Basics
+
+Unifig loads a [YAML configuration][] that instructs it on how to retrieve various external variables.
+These variable values come from providers.
+Unifig comes with a `local` provider which reads values straight from the configuration file.
+Additional providers may be installed.
+
+The most minimal configuration would be:
+
+```yml
+config:
+  providers: local
+
+HELLO:
+  value: "world"
+```
+
+Given that configuration, Unifig will attach two new methods to the `Unifig` class.
+From in your code you can call `Unifig.hello` to get the value of the variable and `Unifig.hello?` to see if the value was retrieved (for optional values).
+
+Unifig also allows you to override the overall configuration or the individual configuration by using environments.
+Here is an example where the `production` environment only pull from the `env` provider and in the `test` environment `Unifig.hello` will return `dlrow`:
+
+```yml
+config:
+  providers: [local, env]
+    envs:
+      production:
+        providers: env
+
+HELLO:
+  value: "world"
+  envs:
+    test:
+      value: "dlrow"
+```
+
 ### Loading
 
-Unifig loads a [YAML configuration][] which it uses to create methods allowing access to the variable values for a given environment.
-Loading is handled through the `Unifig::Init` class and methods are made available on the `Unifig` class.
+Loading a configuration is handled through the `Unifig::Init` class.
 From `Unifig::Init` you can load the YAML as a string with `.load` or a file with `.load_file`.
 
-All variables are converted into two methods on the `Unifig` class.
-A predicate method shows whether the variable was provided and a regular method provides access to the value.
-
 All variables are assumed to be required (not `nil` or a blank string).
-They can be made optional using the `:optional` setting.
+Variables can be made optional by using the `:optional` setting.
 If there is a required variable without a value, Unifig will throw an error when loading.
 
 ``` rb
-Unifig::Init.load(<<~YAML, :production)
+Unifig::Init.load(<<~YAML, env: :production)
   config:
-    envs:
-      development:
-        providers: local
-      production:
-        providers: local
+    providers: local
 
   HOST:
     value: github.com
@@ -81,17 +110,24 @@ If we replaced `:development` with `:production` inside the `load` call we'd get
 # => nil
 ```
 
+You can load from a configuration file by using `load_file`.
+
+``` rb
+Unifig::Init.load_file('unifig.yml', env: :production)
+```
+
 [API Documentation][]
 
 ### YAML Configuration
 
 The configuration YAML must contain a `config` key.
-Inside that all environments to be used must be listed under the `envs` key using the environment name.
-Each environment must list a provider or providers that are checked in order to find the value for each variable.
+A list of one or more providers must be given.
+They are are checked in order to find the value for each variable.
 Variables are then listed by name.
 
-The first level of settings apply to all environments.
+The first level of configurations apply to all environments.
 These can be overridden by setting the `envs` key and a key with the name of then environment and then redefining any settings.
+This is the case for the overall configuration as well as any variable configurations.
 
 ### Providers
 

data/lib/unifig/config.rb

@@ -3,15 +3,15 @@
 module Unifig
   # @private
   class Config
-    def initialize(config, env)
-      @config = config
-      @env = @config.dig(:envs, env)
-    end
+    def initialize(config, env: nil)
+      @env_config = config.slice(:providers)
+      @env = env
 
-    attr_reader :env
+      @env_config.merge!(config.dig(:envs, env) || {}) if @env
+    end
 
     def providers
-      @providers ||= Array(env[:providers]).map(&:to_sym).freeze
+      @providers ||= Array(@env_config[:providers]).map(&:to_sym).freeze
     end
   end
 end

data/lib/unifig/init.rb

@@ -8,7 +8,7 @@ module Unifig
     # Loads a string of YAML to configure Unifig.
     #
     # @example
-    #   Unifig::Init.load(<<~YML, :development)
+    #   Unifig::Init.load(<<~YML, env: :development)
     #     config:
     #       envs:
     #         development:
@@ -24,9 +24,9 @@ module Unifig
     # @raise [YAMLSyntaxError] - Invalid YAML
     # @raise (see #initialize)
     # @raise (see Unifig::Providers.list)
-    def self.load(str, env)
+    def self.load(str, env: nil)
       yml = Psych.load(str, symbolize_names: true)
-      new(yml, env).exec!
+      new(yml, env: env).exec!
     rescue Psych::SyntaxError, Psych::BadAlias => e
       raise YAMLSyntaxError, e.message
     end
@@ -34,29 +34,29 @@ module Unifig
     # Loads a YAML file to configure Unifig.
     #
     # @example
-    #   Unifig::Init.load_file('config.yml', :development)
+    #   Unifig::Init.load_file('config.yml', env: :development)
     #
     # @param file_path [String] The path to a YAML config file.
     # @param env [Symbol] An environment name to load.
     #
     # @raise (see Unifig::Init.load)
-    def self.load_file(file_path, env)
+    def self.load_file(file_path, env: nil)
       # Ruby 2.7 Psych.load_file doesn't support the :symbolize_names flag.
       # After Ruby 2.7 this can be changed to Psych.load_file if that's faster.
-      load(File.read(file_path), env)
+      load(File.read(file_path), env: env)
     end
 
     # @private
     #
     # @raise [MissingConfig] - No config section was provided in the YAML.
-    def initialize(yml, env)
+    def initialize(yml, env: nil)
       @yml = yml
       @env = env
 
       config = @yml.delete(:config)
       raise MissingConfig unless config
 
-      @config = Config.new(config, @env)
+      @config = Config.new(config, env: @env)
     end
 
     # @private

data/lib/unifig/providers/local.rb

@@ -2,11 +2,8 @@
 
 module Unifig
   module Providers
-    # A provider to retrieve values from the unifig.yml file.
+    # @private
     module Local
-      # Returns the name of the provider.
-      #
-      # @return [Symbol]
       def self.name
         :local
       end

data/lib/unifig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Unifig
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/spec/unifig/config_spec.rb

@@ -1,29 +1,29 @@
 RSpec.describe Unifig::Config do
-  subject(:config) { described_class.new(config_hash, env) }
+  subject(:config) { described_class.new(config_hash, env: env) }
 
-  let(:env) { :development }
-  let(:env_config) do
-    {
-      providers: 'local'
-    }
-  end
+  let(:env) { nil }
   let(:config_hash) do
     {
+      providers: 'local',
       envs: {
-        "#{env}": env_config
+        development: {
+          providers: %w[local forty_two]
+        }
       }
     }
   end
 
-  describe '#env' do
-    it 'returns the env config' do
-      expect(config.env).to eql env_config
-    end
-  end
-
   describe '#providers' do
     it 'returns a list of providers for the selected env' do
       expect(config.providers).to eql %i[local]
     end
+
+    context 'with an :env' do
+      let(:env) { :development }
+
+      it 'returns the list of providers for that env' do
+        expect(config.providers).to eql %i[local forty_two]
+      end
+    end
   end
 end

data/spec/unifig/init_spec.rb

@@ -20,8 +20,8 @@ RSpec.shared_examples 'basic load tests' do
   context 'without a config' do
     let(:str) do
       <<~YML
-        FOO_BAR:
-          value: "baz"
+        ONE:
+          value: 1
       YML
     end
 
@@ -34,20 +34,18 @@ RSpec.shared_examples 'basic load tests' do
     let(:str) do
       <<~YML
         config:
-          envs:
-            development:
-              providers: local
+          providers: local
 
-        FOO_BAR:
-          value: baz
+        ONE:
+          value: 1
       YML
     end
 
     it 'loads up a string of yaml' do
       subject
 
-      expect(Unifig).to respond_to(:foo_bar)
-      expect(Unifig.foo_bar).to eql 'baz'
+      expect(Unifig).to respond_to(:one)
+      expect(Unifig.one).to be 1
     end
   end
 end
@@ -56,7 +54,7 @@ RSpec.describe Unifig::Init do
   let(:env) { :development }
 
   describe '.load' do
-    subject(:load) { described_class.load(str, env) }
+    subject(:load) { described_class.load(str, env: env) }
 
     include_examples 'basic load tests'
 
@@ -64,21 +62,19 @@ RSpec.describe Unifig::Init do
       let(:str) do
         <<~YML
           config:
-            envs:
-              development:
-                providers: [local, forty_two]
+            providers: [local, forty_two]
 
-          FOO:
-          BAR:
-            value: bar
+          ONE:
+          TWO:
+            value: 2
         YML
       end
 
       it 'returns the values from the providers in order' do
         load
 
-        expect(Unifig.foo).to be 42
-        expect(Unifig.bar).to eql 'bar'
+        expect(Unifig.one).to be 42
+        expect(Unifig.two).to be 2
       end
     end
 
@@ -89,22 +85,20 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
+            ONE:
               optional: true
-              value: baz
+              value: 1
           YML
         end
 
         it 'loads the var' do
-          expect(Unifig.foo_bar).to eql 'baz'
+          expect(Unifig.one).to be 1
         end
 
         it 'sets the predicate to true' do
-          expect(Unifig).to be_foo_bar
+          expect(Unifig).to be_one
         end
       end
 
@@ -112,21 +106,19 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
+            ONE:
               optional: true
           YML
         end
 
         it 'makes the var nil' do
-          expect(Unifig.foo_bar).to be_nil
+          expect(Unifig.one).to be_nil
         end
 
         it 'sets the predicate to false' do
-          expect(Unifig).to_not be_foo_bar
+          expect(Unifig).to_not be_one
         end
       end
 
@@ -134,22 +126,20 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
+            ONE:
               optional: true
               value: ' '
           YML
         end
 
         it 'makes the var nil' do
-          expect(Unifig.foo_bar).to be_nil
+          expect(Unifig.one).to be_nil
         end
 
         it 'sets the predicate to false' do
-          expect(Unifig).to_not be_foo_bar
+          expect(Unifig).to_not be_one
         end
       end
     end
@@ -161,21 +151,19 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
-              value: baz
+            ONE:
+              value: 1
           YML
         end
 
         it 'loads the var' do
-          expect(Unifig.foo_bar).to eql 'baz'
+          expect(Unifig.one).to be 1
         end
 
         it 'sets the predicate to true' do
-          expect(Unifig).to be_foo_bar
+          expect(Unifig).to be_one
         end
       end
 
@@ -183,11 +171,9 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
+            ONE:
               value:
           YML
         end
@@ -201,11 +187,9 @@ RSpec.describe Unifig::Init do
         let(:str) do
           <<~YML
             config:
-              envs:
-                development:
-                  providers: local
+              providers: local
 
-            FOO_BAR:
+            ONE:
               value: ' '
           YML
         end
@@ -218,7 +202,7 @@ RSpec.describe Unifig::Init do
   end
 
   describe '.load_file' do
-    subject(:load_file) { described_class.load_file(file_path, env) }
+    subject(:load_file) { described_class.load_file(file_path, env: env) }
 
     let(:file) do
       Tempfile.new(%w[test .yml]).tap do |file|

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: unifig
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron Lasseigne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-18 00:00:00.000000000 Z
+date: 2022-07-24 00:00:00.000000000 Z
 dependencies: []
-description: A way to load external variables from one or more sources (e.g. ENV).
+description: A pluggable system for loading external variables from one or more providers
+  (e.g. ENV).
 email:
 - aaron.lasseigne@gmail.com
 executables: []
@@ -60,7 +61,8 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: A way to load external variables from one or more sources (e.g. ENV).
+summary: A pluggable system for loading external variables from one or more providers
+  (e.g. ENV).
 test_files:
 - spec/spec_helper.rb
 - spec/unifig/config_spec.rb