envi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4a5095eefa6698a31f090267fd358bd1a7cf7967
+  data.tar.gz: 6cfb3cbce23466ac9fd4be27e51a8de4ac1ffcd6
+SHA512:
+  metadata.gz: 89d8e312da69554691dd9664650e06330e9d2b58b898790f79624f30fcbfca654562a08344bd4e5adcbc9e91211af3700af14ce001b5674001e5e91926e8aa03
+  data.tar.gz: da3ffbf021043da892281b952ce2516efd27f76892f461cd416e03890f7b335f36bbf2c7ae6fd064296b62b5a1b54e306cfa7995e02b99e5a0558d093af00dab

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,5 @@
+--format progress
+--color
+--order rand
+-I lib
+-r envi

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+  - rbx-19mode

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--title "Envy, for configuring required environment variables"
+--readme README.md
+--markup markdown
+--markup-provider kramdown
+--output-dir doc/api
+-
+HISTORY.md
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in envy.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Arjan van der Gaag
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,87 @@
+# Envy [![Build Status](https://secure.travis-ci.org/avdgaag/envy.png?branch=master)](http://travis-ci.org/avdgaag/envy)
+
+Envy is a simple module to define environment variable requirements, and to load
+those environment variables into Ruby constants. This is ideal for managing
+configuration settings using environment variables, as one would on [Heroku].
+
+Read the [full API documentation][docs] for detailed API and usage instructions.
+
+[docs]: http://rubydoc.info/github/avdgaag/envy
+[Heroku]: http://heroku.com
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'envy'
+
+And then execute:
+
+    % bundle
+
+Or install it yourself as:
+
+    % gem install envy
+
+## Usage
+
+### The `envars.yml` file
+
+First, define your requirements in a YAML file. By default, Envy will look for
+`./config/envars.yml`. For example:
+
+    ---
+    &defaults:
+      - name: AWS_ACCESS_KEY
+        message: Please provide your Amazon AWS credentials as environment variables.
+      - name: AWS_ACCESS_SECRET
+        message: Please provide your Amazon AWS credentials as environment variables.
+      - name: HASHING_SALT
+    production:
+      <<: *defaults
+    development:
+      <<: *defaults
+
+You can define your required environment variables by name, and also provide
+an optional custom exception message to be used when that variable is not
+set.
+
+### Initializing Envy
+
+To read the requirements and inspect the current environment variables,
+simply call `Envy.init`. This will raise an exception if requirements are not
+met. When working with Rails apps, you might want to use this is an
+initializer.
+
+### Providing environment variables in a file
+
+A common pattern is to define custom environment variables in a `.env` file
+in your application's root directory. Other gems, such as [Foreman][] will
+use such a file to augment the environment before running processes. When in
+development mode, Envy can also do this for you. Simply tell it which file to
+use:
+
+    Envy.init parse: '.env'
+
+It is a good idea to not include such a file (which commonly contains
+application secrets) in source control.
+
+### Extending your Rails application configuration
+
+Envy will expose all the loaded environment variables as constants in the Envy
+module, so you can access them as:
+
+    Envy::MY_VARIABLE
+
+You could also opt to extend your Rails configuration object:
+
+    Envy.init use: MyApp::Application.config
+    MyApp::Application.config.my_variable # => ...
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/envi.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'envi'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'envi'
+  spec.version       = Envi::VERSION
+  spec.authors       = ['Arjan van der Gaag']
+  spec.email         = ['arjan@arjanvandergaag.nl']
+  spec.description   = %q{Configure required environment variables in your Rails apps}
+  spec.summary       = <<-EOS
+  Envi is a simple tool to make managing required environment variables for
+  your Rails application a little easier. It allows you to define the required
+  variables in a YAML file and provide sensible failure instructions.
+  EOS
+  spec.homepage      = 'https://github.com/avdgaag/envi'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'rspec', '>= 2.13'
+end

data/lib/envi.rb

@@ -0,0 +1,179 @@
+require 'yaml'
+
+# Envi is a simple module to define environment variable requirements, and to load
+# those environment variables into Ruby constants. This is ideal for managing configuration
+# settings using environment variables, as one would on [Heroku].
+#
+# ## Setup
+#
+# ### The `envars.yml` file
+#
+# First, define your requirements in a YAML file. By default, Envi will look for
+# `./config/envars.yml`. For example:
+#
+#     ---
+#     &defaults:
+#       - name: AWS_ACCESS_KEY
+#         message: Please provide your Amazon AWS credentials as environment variables.
+#       - name: AWS_ACCESS_SECRET
+#         message: Please provide your Amazon AWS credentials as environment variables.
+#       - name: HASHING_SALT
+#     production:
+#       <<: *defaults
+#     development:
+#       <<: *defaults
+# {: lang="yaml" }
+#
+# You can define your required environment variables by name, and also provide
+# an optional custom exception message to be used when that variable is not
+# set.
+#
+# ### Initializing Envi
+#
+# To read the requirements and inspect the current environment variables,
+# simply call `Envi.init`. This will raise an exception if requirements are not
+# met. When working with Rails apps, you might want to use this is an
+# initializer.
+#
+# ### Providing environment variables in a file
+#
+# A common pattern is to define custom environment variables in a `.env` file
+# in your application's root directory. Other gems, such as [Foreman][] will
+# use such a file to augment the environment before running processes. When in
+# development mode, Envi can also do this for you. Simply tell it which file to
+# use:
+#
+#     Envi.init parse: '.env'
+# {: lang="ruby" }
+#
+# It is a good idea to not include such a file (which commonly contains
+# application secrets) in source control.
+#
+# ### Extending your Rails application configuration
+#
+# Envi will expose all the loaded environment variables as constants in the Envi
+# module, so you can access them as `Envi::MY_VARIABLE`. You could also opt to extend
+# your Rails configuration object:
+#
+#     Envi.init use: MyApp::Application.config
+#     MyApp::Application.config.my_variable # => ...
+#
+#@author Arjan van der Gaag <arjan@arjanvandergaag.nl>
+#
+# [Heroku]: http://heroku.com
+module Envi
+  # Special exception raised when required files could not be found. This is a
+  # library-specific wrapper around Errno::ENOENT.
+  FileNotFound = Class.new(StandardError)
+
+  # Special exception raised when the currently configured environment name is
+  # not present in the configuration file.
+  UnknownEnvironment = Class.new(StandardError)
+
+  # @return [String] standard location to look for a configuration YAML file
+  ENVI_DEFAULT_CONFIG_FILE = 'config/envars.yml'.freeze
+
+  # @return [String] the default environment to load from the configuration file
+  ENVI_DEFAULT_ENVIRONMENT = 'production'.freeze
+
+  # @return [String] Envi gem version in format major.minor.patch
+  VERSION = '0.0.1'.freeze
+
+  module_function
+
+  # Define the required environment variables defined in the configuration YAML
+  # file (or the `:config` option) as constants on the {Envi} module. Any
+  # previously defined constants will be removed.
+  #
+  # @param [Hash] options
+  # @option options [String] :parse path to a file to read extra environment
+  #   variables from.
+  # @option options [Object] :use an object to set downcased properties on
+  # @option options [String] :config path to the configuration file. Defaults
+  #   to value of {ENVI_DEFAULT_CONFIG_FILE}
+  # @option options [String] :enviroment name of the application environment.
+  #   Defaults to {environment}.
+  # @raise {NameError} when a required environment variable is not set.
+  # @raise {FileNotFound} when files in the `:config` or `:parse` options could
+  #   not be found.
+  # @raise {UnknownEnvironment} when the current environment is not defined in
+  #   the configuration file.
+  # @return [Hash] the parsed YAML configuration file
+  def init(options = {})
+    reset_consts
+    parse_envars_from(options[:parse]) if options[:parse]
+    config(options).each do |envar|
+      name = envar.fetch('name')
+      value = ENV.fetch(name) do
+        raise NameError, envar.fetch('message', "Required environment variable #{name} is undefined")
+      end
+      set name, value, options
+    end
+  end
+
+  # Read and parse a given `filename` and extract environment variables from it.
+  #
+  # @example
+  #   # in .env
+  #   FOO=bar
+  #
+  #   parse_envars_from('.env')
+  #   ENV['FOO'] # => 'bar'
+  # @raise {FileNotFound} when `filename` is not readable
+  def parse_envars_from(filename)
+    contents = File.readlines(filename).each do |line|
+      name, value = line.chomp.split('=', 2)
+      ENV[name] = value
+    end
+  rescue Errno::ENOENT => e
+    raise FileNotFound, e
+  end
+
+  # Store a constant by its `name` and `value` by defining it as a constant in
+  # the Envi module. Optionally, this will call a setter method on the object
+  # in `options[:use]`.
+  #
+  # @param [String] name of the constant to define
+  # @param [String] value of the constant to define
+  # @param [Hash] options
+  # @option options [Object] :use an object to set downcased properties on
+  def set(name, value, options)
+    if object = options[:use]
+      object.send("#{name.downcase}=", value)
+    end
+    const_set name, value
+    (@_envi_constants ||= []) << name
+  end
+
+  # Loads the YAML configuration file and returns the keys under the {environment}.
+  #
+  # @param [Hash] options
+  # @option options [String] :config path to the configuration file. Defaults
+  #   to value of {ENVI_DEFAULT_CONFIG_FILE}
+  # @option options [String] :enviroment name of the application environment.
+  #   Defaults to {environment}.
+  # @raise {UnknownEnvironment} when the current environment is not defined in
+  #   the configuration file.
+  # @see environment
+  def config(options)
+    location = options.fetch(:config, ENVI_DEFAULT_CONFIG_FILE)
+    env      = options.fetch(:environment, environment)
+    YAML.load_file(location).fetch(env) do
+      raise UnknownEnvironment, 'No configuration found for environment ' + environment
+    end
+  rescue Errno::ENOENT => e
+    raise FileNotFound, e
+  end
+
+  # @return [String] the value of RACK_ENV, RAILS_ENV or {ENVI_DEFAULT_ENVIRONMENT}
+  def environment
+    ENV['RACK_ENV'] || ENV['RAILS_ENV'] || ENVI_DEFAULT_ENVIRONMENT
+  end
+
+  # Remove any constants previously defined with {set}.
+  def reset_consts
+    (@_envi_constants || []).each do |name|
+      remove_const name if const_defined? name
+    end
+  end
+end

data/spec/envi_spec.rb

@@ -0,0 +1,107 @@
+require 'ostruct'
+
+describe Envi do
+  it 'has a version number' do
+    expect(Envi::VERSION).to_not be_nil
+  end
+
+  context 'when the configuration file exists' do
+    before do
+      YAML.should_receive(:load_file).with('config/envars.yml').and_return({
+        'production' => [
+          { 'name' => 'FOO' },
+          { 'name' => 'BAR', 'message' => 'Bar must be set' }
+        ],
+        'development' => [
+          { 'name' => 'BAZ' },
+        ]
+      })
+    end
+
+    context "and all keys are set" do
+      before do
+        stub_const('ENV', 'FOO' => 'bla', 'BAR' => 'bla')
+      end
+
+      it 'reads configuration from YAML file and values from ENV' do
+        Envi.init
+        expect(Envi::FOO).to eql('bla')
+      end
+
+      it 'raises error for unrequired keys' do
+        Envi.init
+        expect { Envi::BAZ }.to raise_error(NameError)
+      end
+    end
+
+    context "when keys are missing" do
+      it 'raises when required keys are missing' do
+        stub_const('ENV', {})
+        expect { Envi.init }.to raise_error(NameError, 'Required environment variable FOO is undefined')
+      end
+
+      it 'uses description from config file as error message' do
+        stub_const('ENV', 'FOO' => 'qux')
+        expect { Envi.init }.to raise_error(NameError, 'Bar must be set')
+      end
+    end
+
+    it 'defaults to RAILS_ENV for environment' do
+      stub_const('ENV', 'BAZ' => 'bla', 'RAILS_ENV' => 'development')
+      Envi.init
+      expect(Envi::BAZ).to eql('bla')
+      expect { Envi::FOO }.to raise_error(NameError)
+    end
+
+    it 'defaults to RACK_ENV for environment' do
+      stub_const('ENV', 'BAZ' => 'bla', 'RACK_ENV' => 'development')
+      Envi.init
+      expect(Envi::BAZ).to eql('bla')
+      expect { Envi::FOO }.to raise_error(NameError)
+    end
+
+    it 'raises when configured environment does not exist' do
+      stub_const('ENV', 'RACK_ENV' => 'hoeaap')
+      expect { Envi.init }.to raise_error(Envi::UnknownEnvironment)
+    end
+
+    it 'allows defining a custom environment' do
+      stub_const('ENV', 'BAZ' => 'bla')
+      Envi.init(environment: 'development')
+      expect(Envi::BAZ).to eql('bla')
+      expect { Envi::FOO }.to raise_error(NameError)
+    end
+
+    it 'can preload environment variables from a file' do
+      stub_const('ENV', 'BAR' => 'bla')
+      File.should_receive(:readlines).with('.env').and_return(["FOO=qux\n"])
+      Envi.init parse: '.env'
+      expect(ENV['FOO']).to eql('qux')
+    end
+  end
+
+  context "when using an existing object to call setters on" do
+    subject { OpenStruct.new }
+
+    before do
+      YAML.should_receive(:load_file).with('config/envars.yml').and_return({
+        'production' => [{ 'name' => 'FOO' }]
+      })
+      stub_const('ENV', 'FOO' => 'bar')
+      Envi.init(use: subject)
+    end
+
+    its(:foo) { should eql('bar') }
+  end
+
+  it 'allows loading a custom configuration file' do
+    YAML.should_receive(:load_file).with('foobar.yml').and_return({})
+    expect { Envi.init(config: 'foobar.yml') }.to raise_error(Envi::UnknownEnvironment)
+  end
+
+  context 'when the configuration file cannot be found' do
+    it 'raises an error' do
+      expect { Envi.init }.to raise_error(Envi::FileNotFound)
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: envi
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Arjan van der Gaag
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '2.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '2.13'
+description: Configure required environment variables in your Rails apps
+email:
+- arjan@arjanvandergaag.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- .yardopts
+- Gemfile
+- HISTORY.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- envi.gemspec
+- lib/envi.rb
+- spec/envi_spec.rb
+homepage: https://github.com/avdgaag/envi
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Envi is a simple tool to make managing required environment variables for
+  your Rails application a little easier. It allows you to define the required variables
+  in a YAML file and provide sensible failure instructions.
+test_files:
+- spec/envi_spec.rb
+has_rdoc: