envied 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 591c914549fd162d08a2cb78db12f68b7eab29e8
-  data.tar.gz: 87b5af48a1422bb8f2ff6bb8c9c566fbd86f909e
+  metadata.gz: 5d3ba3eb81e06018962bb52faa7caf1fdf044aca
+  data.tar.gz: a92a83a6a9272771f39eca36b3f0126aac9fd439
 SHA512:
-  metadata.gz: 7ab15f9483472b1977f56fbbb224fe880ac40e126e36972ddf0908dcd0cc5baa28c3d9e3aa7f47f6784160796cf94f752ebbb328fa0fcb0ed7763dd66de98fbc
-  data.tar.gz: fa3a4be832c289a0bc4ca2b6ba423224d2b6590b9e0836345b1d915a72291a0bf7ed3e13d4b74b5fdbfa731348c521ef3bf1de1b1761c89360944e968043276b
+  metadata.gz: 7d4643b26e39b59b534285cc8f58f0228285468ec3860c3479b0a1cd3b5041a2d7fae2b40ce176c985105d4a793f705d226eef3ccf9591bc1c87a50f9d1b90a5
+  data.tar.gz: 2407bd5bf9a1700b76d81d77de7a4de9b2b7da1fba44257119444afb9e0e08ed2e4badf19d0f8d7cdecdf314c9a3affb4ef89119d42e0f3a9426bd0ac1d10bae

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# 0.4.0 / 2014-05-16
+
+* groups added
+
+  This allows for more fine-grained requiring.  
+  See the section in the [README](https://github.com/eval/envied/tree/v0.4.0#groups).
+
+* configuring is now simpler:
+
+  ```ruby
+  ENVied.configure { variable :RACK_ENV }
+  # vs
+  ENVied.configure {|env| env.variable :RACK_ENV }
+  ```
+
+* Deprecate `require!`. Use `require` instead.
+
+  Just like requiring groups with Bundler.
+
+* Deprecate lowercase methods for uppercase ENV-variables.
+
+  `ENV['RACK_ENV']` is no longer accessible as `ENVied.rack_env`, only as `ENVied.RACK_ENV`.  
+  This is not only what you would expect, but it also reduces the chance of clashing with existing class-methods.
+
+# 0.3.0 / 2014-03-14
+
+* defaults need to be enabled explicitly:
+
+  `ENVied.configure(enable_defaults: Rails.env.development?) { ... }`
+
+# 0.2.0 / 2014-03-14
+
+* add defaults
+
+# 0.1.0 / 2014-03-13
+
+* add defaults

data/README.md

@@ -1,4 +1,4 @@
-# ENVied
+# ENVied [![travis](https://secure.travis-ci.org/eval/envied.png?branch=master)](https://secure.travis-ci.org/#!/eval/envied)
 
 ### TL;DR ensure presence and type of your app's ENV-variables.
 
@@ -20,33 +20,61 @@ Let's configure the ENV-variables we need:
 
 ```ruby
 # e.g. config/application.rb
-ENVied.configure do |env|
-  env.variable :force_ssl, :Boolean
-  env.variable :port, :Integer
+ENVied.configure do
+  variable :FORCE_SSL, :Boolean
+  variable :PORT, :Integer
 end
 ```
 
 ### 2) Check for presence and type
 
 ```ruby
-ENVied.require!
+ENVied.require
 ```
-Excecution will halt unless ENV is something like
-`{'FORCE_SSL' => 'false', 'PORT' => '3001'}`.
 
-A meaningful error will in this case explain what key and type is needed.
+This will throw an error if not:
+* both `ENV['FORCE_SSL']` and `ENV['PORT']` are present
+* both the values of `ENV['FORCE_SSL']` and `ENV['PORT']` can be coerced (to resp. Boolean or Integer).
+
+(The error contains exactly what ENV-variables are missing/faulty.)
 
 ### 3) Use typed variables
 
 Variables accessed via ENVied have the configured type:
 
 ```ruby
-ENVied.port # => 3001
-ENVied.force_ssl # => false
+ENVied.PORT # => 3001
+ENVied.FORCE_SSL # => false
 ```
 
 ## Configuration
 
+### Groups
+
+Groups give you more flexibility to define when variables are needed.  
+It's just like you Gemfile:
+
+```ruby
+ENVied.configure do
+  variable :FORCE_SSL, :Boolean
+
+  group :production do
+    variable :NEW_RELIC_LICENSE_KEY
+  end
+end
+
+# For local development you would typically do:
+ENVied.require(:default) #=> Only ENV['FORCE_SSL'] is required
+# On the server:
+ENVied.require(:default, :production) #=> ...also ENV['NEW_RELIC_LICENSE_KEY'] is required
+
+# BTW the following are equivalent:
+ENVied.require
+ENVied.require(:default)
+ENVied.require('default')
+ENVied.require(nil)
+```
+
 ### Types
 
 The following types are supported:
@@ -63,20 +91,71 @@ The following types are supported:
 In order to let other developers easily bootstrap the application, you can assign defaults to variables.
 Defaults can be a value or a `Proc` (see example below).
 
-Note that 'easily bootstrap' is quite the opposite of 'fail-fast when not all ENV-variables are present'. Therefor it's disabled by default and you should explicitly state whén it is allowed:
+Note that 'easily bootstrap' is quite the opposite of 'fail-fast when not all ENV-variables are present'. Therefor you should explicitly state whén defaults are allowed:
 
 ```ruby
-ENVied.configure(enable_defaults: Rails.env.development?) do |env|
-  env.variable :port, :Integer, default: proc {|env, variable| env.force_ssl ? 443 : 80 }
-  env.variable :force_ssl, :Boolean, default: false
+ENVied.configure(enable_defaults: ENV['RACK_ENV'] == 'development') do
+  variable :FORCE_SSL, :Boolean, default: false
+  variable :PORT, :Integer, default: proc {|envied| envied.FORCE_SSL ? 443 : 80 }
 end
 ```
 
-Please remember that ENVied only **reads** from ENV; don't let setting a default for, say `rails_env`, give you or your team the impression that `ENV['RAILS_ENV']` is set.  
-As a rule of thumb: you should only use defaults:
-* in a development-environment
+Please remember that ENVied only **reads** from ENV; it doesn't set ENV-variables.
+Don't let setting a default for, say `RAILS_ENV`, give you the impression that `ENV['RAILS_ENV']` is set.  
+As a rule of thumb you should only use defaults:
+* for local development
 * for ENV-variables that your application introduces (i.e. for `ENV['DEFAULT_SENDER']` not for `ENV['REDIS_URL']`)
 
+### A more extensive example:
+
+```ruby
+# We allow defaults for local development (and local tests), but want our CI
+# to mimic our production as much as possible.
+# New developers that don't have RACK_ENV set, will in this way not be presented with a huge
+# list of missing variables, as defaults are still enabled.
+not_production_nor_ci = ->{ !(ENV['RACK_ENV'] == 'production' || ENV['CI']) }
+ENVied.configure(enable_defaults: &not_production_nor_ci) do
+  # Your code will likely not use ENVied.RACK_ENV (better use Rails.env),
+  # we want it to be present though; heck, we're using it in this file!
+  variable :RACK_ENV
+
+  variable :FORCE_SSL, :Boolean, default: false
+  variable :PORT, :Integer, default: 3000
+  # generate the default value using the value of PORT:
+  variable :PUBLIC_HOST_WITH_PORT, :String, default: proc {|envied| "localhost:#{envied.PORT}" }
+
+  group :production do
+    variable :MAIL_PAAS_USERNAME
+    variable :DATABASE_URL, :Symbol
+  end
+
+  group :ci do
+    # ci-only stuff
+  end
+
+  group :not_ci do
+    # CI needs no puma-threads, and sidekiq-stuff etc.
+    # Define that here:
+    variable :MIN_THREADS, :Integer, default: 1
+    # more...
+  end
+end
+
+# Depending on our situation, we can now require the groups needed:
+# At local machines:
+ENVied.require(:default, :development, :not_ci) or
+ENVied.require(:default, :test, :not_ci)
+
+# At the server:
+ENVied.require(:default, :production, :not_ci)
+
+# At CI:
+ENVied.require(:default, :test, :ci)
+
+# All in one line:
+ENVied.require(:default, ENV['RACK_ENV'], (ENV['CI'] ? :ci : :not_ci))
+```
+
 
 ## Installation
 

data/lib/envied/version.rb

@@ -0,0 +1,3 @@
+class ENVied
+  VERSION = '0.4.0'
+end

data/lib/envied.rb

@@ -1,137 +1,172 @@
+require 'virtus'
+
 class ENVied
-  module Configurable
-    require 'virtus'
+  class Configuration
+    include Virtus.model
 
-    class VariableError < StandardError
-      attr_reader :variable
-      def initialize(variable)
-        @variable = variable
-      end
+    def self.variable(name, type = :String, options = {})
+      options = { strict: true, group: self.current_group }.merge(options)
+      attribute(name, type, options)
+    end
 
-      def variable_type
-        variable.type.to_s.split("::").last
-      end
+    def self.group(name, &block)
+      self.current_group = name.to_sym
+      yield
+    ensure
+      self.current_group = :default
     end
 
-    class VariableMissingError < VariableError
-      def message
-        "Please provide ENV['#{variable.name.to_s.upcase}'] of type #{variable_type}"
-      end
+    def self.enable_defaults
+      @enable_defaults.respond_to?(:call) ?
+        @enable_defaults.call :
+        @enable_defaults
     end
 
-    class VariableTypeError < VariableError
-      def message
-        "ENV['#{variable.name.to_s.upcase}'] should be of type #{variable_type}"
-      end
+    class << self
+      attr_writer :enable_defaults
+      alias_method :defaults_enabled?, :enable_defaults
+      attr_accessor :current_group
     end
 
-    def self.included(base)
-      base.class_eval do
-        include Virtus.model
+    def self.current_group
+      @current_group ||= :default
+    end
+  end
 
-        class << self
-          attr_accessor :enable_defaults
-        end
+  def self.configuration(options = {}, &block)
+    if block_given?
+      @configuration = build_configuration(&block).tap do |c|
+        options.each{|k, v| c.public_send("#{k}=", v) }
       end
-      base.extend ClassMethods
     end
+    @configuration ||= build_configuration
+  end
 
-    module ClassMethods
-      # Creates a configuration instance from env.
-      #
-      # Will raise VariableMissingError for variables not present in ENV.
-      #
-      # Will raise VariableTypeError for variables whose ENV-value can't be coerced to the configured type.
-      #
-      # @param env [Hash] the env
-      def parse_env(env)
-        atts = attribute_set.map(&:name).each_with_object({}) do |name, result|
-          variable = attribute_set[name]
-          default = variable.options[:default]
-          value = env[name.to_s] || env[name.to_s.upcase]
-          if !(value || default)
-            raise VariableMissingError, variable
-          end
-
-          try_coercion(variable, value, default)
-          result[name] = value if value
-        end
-
-        new(atts)
-      end
+  class << self
+    alias_method :configure, :configuration
+    attr_accessor :required_groups
+  end
 
-      # Define a variable.
-      #
-      # @param name [Symbol] name of the variable
-      # @param type [Symbol] type (one of :String (default), :Symbol, :Integer, :Boolean,
-      #   :Date, :Time)
-      # @param options [Hash]
-      # @option options [String, Integer, Boolean, #call] :default (nil) what value will be
-      #   used when no ENV-variable is present.
-      # @note Defaults are ignored by default, see {configure}.
-      #
-      def variable(name, type = :String, options = {})
-        options.delete(:default) unless self.enable_defaults
-        attribute name, type, { strict: true }.merge(options)
-      end
+  def self.build_configuration(&block)
+    Class.new(Configuration).tap do |c|
+      c.instance_eval(&block) if block_given?
+    end
+  end
+
+  def self.require(*groups)
+    groups.compact!
+    @instance = nil
+    if groups.any?
+      self.required_groups = groups.map(&:to_sym)
+    else
+      self.required_groups = [:default]
+    end
+    error_on_missing_variables!
+    error_on_uncoercible_variables!
 
-      private
-      def try_coercion(variable, value, default)
-        value ||= begin
-          default unless default.respond_to?(:call)
-        end
-        return unless value
-        @variable = variable
-
-        variable.coerce(value)
-      rescue Virtus::CoercionError => e
-        raise VariableTypeError.new(@variable)
+    _required_variables = required_variables
+    group_configuration = build_configuration do
+      _required_variables.each do |v|
+        @attribute_set << v
       end
     end
+    @instance = group_configuration.new(ENV.to_hash)
   end
 
-  class << self
-    attr_accessor :configuration
+  def self.error_on_missing_variables!
+    if missing_variable_names.any?
+      raise "Please set the following ENV-variables: #{missing_variable_names.sort.join(',')}"
+    end
   end
 
-  # Configure ENVied.
-  #
-  # @param options [Hash]
-  # @option options [Boolean] :enable_defaults (false) whether or not defaults are used.
+  def self.error_on_uncoercible_variables!
+    if non_coercible_variables.any?
+      single_error = "ENV['%{name}'] ('%{value}' can't be coerced to %{type})"
+      errors = non_coercible_variables.map do |v|
+        var_type = v.type.to_s.split("::").last
+        single_error % { name: v.name, value: env_value_or_default(v), type: var_type }
+      end.join ", "
+
+      raise "Some ENV-variables are not coercible: #{errors}"
+    end
+  end
+
+  def self.env_value(variable)
+    ENV[variable.name.to_s]
+  end
+
+  def self.env_value_or_default(variable)
+    env_value(variable) || default_value(variable)
+  end
+
+  # Yields the assigned default for the variable.
+  # When defaults are disabled, nil is returned.
+  def self.default_value(variable)
+    defaults_enabled? ? variable.default_value.value : nil
+  end
+
+  # A list of all configured variable names.
   #
   # @example
-  #   ENVied.configure(enable_defaults: Rails.env.development?) do
-  #     variable :force_ssl, :Boolean, default: false
-  #   end
+  #   ENVied.configured_variable_names
+  #   # => [:DATABASE_URL]
   #
-  def self.configure(options = {}, &block)
-    options = { enable_defaults: false }.merge(options)
-    @configuration = Class.new { include Configurable }.tap do |k|
-      k.enable_defaults = options[:enable_defaults]
-      k.instance_eval(&block)
-    end
-    # or define this thing as ENVied::Configuration? prolly not threadsafe
-  ensure
-    @instance = nil
+  # @return [Array<Symbol>] the list of variable names
+  def self.required_variable_names
+    required_variables.map(&:name).map(&:to_sym)
   end
 
-  def self.instance
-    @instance ||= @configuration.parse_env(ENV.to_hash)
+  def self.required_variables
+    from_required_group = ->(var){ self.required_groups.include?(var.options[:group]) }
+    configured_variables.to_a.keep_if(&from_required_group)
   end
-  class << self
-    alias_method :require!, :instance
+
+  def self.configured_variables
+    configuration.attribute_set.dup#.to_a.keep_if(&var_from_required_group)
+  end
+
+  def self.provided_variable_names
+    ENV.keys.map(&:to_sym)
+  end
+
+  def self.non_coercible_variables
+    required_variables.reject(&method(:variable_coercible?))
+  end
+
+  def self.variable_coercible?(variable)
+    var_value = env_value_or_default(variable)
+    return true if var_value.respond_to?(:call)
+
+    variable.coerce var_value
+  rescue Virtus::CoercionError
+    return false
+  end
+
+  def self.missing_variable_names
+    unprovided = required_variable_names - provided_variable_names
+    unprovided -= names_of_required_variables_with_defaults if defaults_enabled?
+    unprovided
+  end
+
+  def self.names_of_required_variables_with_defaults
+    required_variables_with_defaults.map(&:name).map(&:to_sym)
+  end
+
+  def self.required_variables_with_defaults
+    required_variables.map do |v|
+      v unless v.default_value.value.nil?
+    end.compact
   end
 
-  def self.[](key)
-    instance.attributes[key]
-    #instance[key] # will raise and complain that <class <>> doesn't response; better?
+  def self.defaults_enabled?
+    configuration.enable_defaults
   end
 
   def self.method_missing(method, *args, &block)
-    respond_to_missing?(method) ? instance.public_send(method, *args, &block) : super
+    respond_to_missing?(method) ? @instance.public_send(method, *args, &block) : super
   end
 
   def self.respond_to_missing?(method, include_private = false)
-    instance.attributes.key?(method) || super
+    @instance.respond_to?(method) || super
   end
 end

data/spec/envied_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 describe ENVied do
   subject { described_class }
 
-  it { should respond_to :require! }
+  it { should respond_to :require }
   it { should respond_to :configure }
 
   context 'configured' do
@@ -14,14 +14,16 @@ describe ENVied do
     end
 
     def configure(options = {}, &block)
+      described_class.instance_eval { @configuration = nil }
       described_class.configure(options, &block)
       self
     end
 
     def configured_with(hash = {})
-      described_class.configure do |env|
+      described_class.instance_eval { @configuration = nil }
+      described_class.configure do
         hash.each do |name, type|
-          env.variable(name, *type)
+          variable(name, *type)
         end
       end
       self
@@ -37,62 +39,155 @@ describe ENVied do
     end
 
     it 'responds to configured variables' do
-      configured_with(a: :Integer).and_ENV({'A' => '1'})
+      configured_with(a: :Integer).and_ENV({'a' => '1'})
+      described_class.require
+
       is_expected.to respond_to :a
     end
 
     it 'responds not to unconfigured variables' do
       unconfigured.and_ENV({'A' => '1'})
-      is_expected.to_not respond_to :a
+      described_class.require
+
+      is_expected.to_not respond_to :B
     end
 
     context 'ENV contains not all configured variables' do
       before { configured_with(a: :Integer).and_no_ENV }
 
-      it 'raises EnvMissing on calling require!' do
-        expect {
-          ENVied.require!
-        }.to raise_error(ENVied::Configurable::VariableMissingError)
-      end
-
-      it 'raises EnvMissing when interacted with' do
+      specify do
         expect {
-          ENVied.any_missing_method
-        }.to raise_error(ENVied::Configurable::VariableMissingError)
+          ENVied.require
+        }.to raise_error /set the following ENV-variables: a/
       end
     end
 
-    context 'ENV containing variable of different type' do
-      before { configured_with(a: :Integer).and_ENV('A' => 'NaN') }
+    context 'ENV variables are not coercible' do
+      before { configured_with(A: :Integer).and_ENV('A' => 'NaN') }
 
       specify do
         expect {
-          ENVied.a
-        }.to raise_error(ENVied::Configurable::VariableTypeError)
+          ENVied.require
+        }.to raise_error /ENV\['A'\] \('NaN' can't be coerced to Integer/
       end
     end
 
-    describe 'variable with default' do
-      it "are disabled by default" do
-        configured_with(a: [:Integer, default: 1]).and_no_ENV
+    describe 'defaults' do
+      describe 'setting' do
+        subject { described_class.configuration }
+
+        it 'is disabled by default' do
+          expect(subject.enable_defaults).to_not be
+        end
 
-        expect { ENVied.a }.to raise_error
+        it 'can be enabled via #configure' do
+          configure(enable_defaults: true){ }
+
+          expect(subject.enable_defaults).to be
+        end
+
+        it 'can be enabled via a configure-block' do
+          configure { self.enable_defaults = true }
+
+          expect(subject.enable_defaults).to be
+        end
+
+        it 'can be assigned a Proc' do
+          configure { self.enable_defaults = -> { true } }
+
+          expect(subject.enable_defaults).to be
+        end
       end
 
-      it 'can be a value' do
-        configure(enable_defaults: true) do
-          variable :a, :Integer, default: 1
-        end.and_no_ENV
+      describe 'assigning' do
+        it 'can be a value' do
+          configure(enable_defaults: true) do
+            variable :A, :Integer, default: 1
+          end
+          described_class.require
+
+          expect(described_class.A).to eq 1
+        end
+
+        it 'can be a Proc' do
+          configure(enable_defaults: true) do
+            variable :A, :Integer, default: proc { 1 }
+          end
+          described_class.require
 
-        expect(ENVied.a).to eq 1
+          expect(described_class.A).to eq 1
+        end
+
+        it 'is ignored if defaults are disabled' do
+          configure(enable_defaults: false) do
+            variable :A, :Integer, default: 1
+          end.and_no_ENV
+
+          expect {
+            described_class.require
+          }.to raise_error
+        end
+
+        it 'is is ignored if ENV is provided' do
+          configure(enable_defaults: true) do
+            variable :A, :Integer, default: 1
+          end.and_ENV('A' => '2')
+          described_class.require
+
+          expect(described_class.A).to eq 2
+        end
+
+        it 'can be defined in terms of other variables' do
+          configure(enable_defaults: true) do
+            variable :A, :Integer
+            variable :B, :Integer, default: proc {|env| env.A * 2 }
+          end.and_ENV('A' => '1')
+          described_class.require
+
+          expect(described_class.B).to eq 2
+        end
       end
+    end
+    describe "groups" do
+      context 'a variable in a group' do
+        before do
+          configure do
+            variable :moar
+
+            group :foo do
+              variable :bar
+            end
+          end.and_no_ENV
+        end
 
-      it "can be anything callable" do
-        configure(enable_defaults: true) do
-          variable :a, :Integer, default: proc { 1 }
-        end.and_no_ENV
+        it 'is required when requiring the group' do
+          expect {
+            described_class.require(:foo)
+          }.to raise_error /bar/
+        end
+
+        it 'is not required when requiring another group' do
+          expect {
+            described_class.require(:bat)
+          }.to_not raise_error
+        end
 
-        expect(ENVied.a).to eq 1
+        it 'wont define non-required variables on ENVied' do
+          stub_const("ENV", {'moar' => 'yes'})
+          described_class.require(:default)
+
+          expect {
+            described_class.bar
+          }.to raise_error
+        end
+
+        it 'requires variables without a group when requiring the default group' do
+          [:default, 'default'].each do |groups|
+            expect {
+              described_class.require(*groups)
+            }.to raise_error /moar/
+          end
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: envied
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Gert Goet
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-10 00:00:00.000000000 Z
+date: 2014-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: virtus
@@ -74,12 +74,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - envied.gemspec
 - lib/envied.rb
+- lib/envied/version.rb
 - spec/envied_spec.rb
 - spec/spec_helper.rb
 - underconstruction.gif