prius 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b4efd54f9144bd36ec263a5cb4207ee0adc8b80c
-  data.tar.gz: 4a1cfedd0b63a10146b9164ca3cbc78f276afbfd
+  metadata.gz: 2f204cfe4500248f7ae5ec942f91aa3e367b5507
+  data.tar.gz: 375c5ede8265db74665bdfa8d5a512e6c2be84d0
 SHA512:
-  metadata.gz: f5f916b7b56ae454bed8bdcc82f37e7bad980a6003af01aa669776d725131e0fe74e479d8ad06be9be34e760d1cc4047debb538e94e4c8e471c64d37144687e5
-  data.tar.gz: 6d6788a1500a1efc21c7620fc09e902c3f4606feba3ce6211feb493eec44211248a5ba8da7f94dec700572e16a1e306d524b1370fde375f34114c5f43351bdff
+  metadata.gz: 1c8edc7fcae0e3b43d8bb2385228a8c4667511407724d8348b52e93e5a35bbee2f60e9626291b705a21f39fb21f802be17e750d9ce6e9e998817e9fc24e8eb2d
+  data.tar.gz: 8514bdb66909f5b16f7dd9173e0478503453fecd6bb0fcf41bab11b37bdc62de96b92107e08d6309a988481d7fa0521f3b4e3402c0957c4f023f8b1fa6e8b804

data/.gitignore

@@ -1 +1,3 @@
 Gemfile.lock
+.bundle
+*.gem

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  Exclude:
+    - prius.gemspec
+
+# Limit lines to 80 characters.
+LineLength:
+  Max: 80
+
+ClassLength:
+  Max: 300
+
+StringLiterals:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/SignalException:
+  EnforcedStyle: 'only_raise'
+
+Style/DotPosition:
+  EnforcedStyle: 'trailing'

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+
+matrix:
+  allow_failures:
+    - rvm: jruby
+    - rvm: rbx-2
+
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1
+  - 2.2
+  - jruby
+  - rbx-2
+
+script:
+  - bundle exec rubocop
+  - bundle exec rspec spec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 GoCardless
+
+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

@@ -1,4 +1,80 @@
 # Prius
-
 Environmentally-friendly application config for Ruby.
 
+[![Gem Version](https://badge.fury.io/rb/prius.svg)](http://badge.fury.io/rb/prius)
+[![Build Status](https://travis-ci.org/gocardless/prius.svg?branch=master)](https://travis-ci.org/gocardless/prius)
+
+Prius helps you guarantee that your environment variables are:
+
+- **Present** - an exception is raised if an environment variable is missing,
+  so you can hear about it as soon as your app boots.
+- **Valid** - an environment variable can be coerced to a desired type
+  (integer, boolean or string), and an exception will be raised if the value
+  doesn't match the type.
+
+## Usage
+
+#### Installing
+
+```
+$ gem install prius
+```
+
+#### Quick Start
+
+```ruby
+# Load a required environment variable into the Prius registry:
+Prius.load(:github_token)
+
+# Use the environment variable:
+Prius.get(:github_token)
+
+# Load an optional environment variable:
+Prius.load(:might_be_here_or_not, required: false)
+
+# Load and alias an environment variable:
+Prius.load(:alias_name, env_var: "HORRENDOUS_SYSTEM_VAR_NAME")
+
+# Load and coerce an environment variable (or raise):
+Prius.load(:my_flag, type: :bool)
+```
+
+You probably want to `load` all your environment variables as your app starts,
+so you catch config issues at boot time.
+
+#### Loading Environment Variables
+
+Environment variables need to be loaded into the Prius registry before being
+used. Typically this is done in an initialiser.
+
+```ruby
+Prius.load(name, options = {})
+```
+
+If an environment variable can't be loaded, Prius will raise one of:
+- `MissingValueError` if the environment variable was expected to be set but couldn't be found.
+- `TypeMismatchError` if the environment variable wasn't of the expected type (see below).
+
+`Prius.load` accepts the following options:
+
+| Param             | Default       | Description                                                                               |
+|-------------------|---------------|-------------------------------------------------------------------------------------------|
+| `required`        | `true`        | Flag to require the environment variable to have been set.                                |
+| `type`            | `:string`     | Type to coerce the environment variable to. Allowed values are `:string`, `:int` and `:bool`. |
+| `env_var`         | `name.upcase` | Name of the environment variable name (if different from the upcased `name`).             |
+
+#### Reading Environment Variables
+
+Once a variable has been loaded into the registry it can be read using:
+
+```ruby
+Prius.get(name)
+```
+
+If the environment variable hasn't been loaded, Prius will raise an `UndeclaredNameError`.
+
+#### Test and development environments
+
+To make running your app in test and development environments easier we
+recommend using [Dotenv](https://github.com/bkeepers/dotenv) to automatically
+load a file of dummy config values.

data/lib/prius.rb

@@ -2,15 +2,45 @@ require "prius/registry"
 require "prius/railtie" if defined?(Rails)
 
 module Prius
-  def self.load(name, type: :string, allow_nil: false)
-    registry.load(name, type: type, allow_nil: allow_nil)
+  # Load an environment variable into the registry.
+  #
+  # name    - The Symbol name of the item in the registry. Use this when
+  #           looking up the item via `#get`. If `env_var` is not provided
+  #           this will be uppercased and used as the environment variable name.
+  # options - An optional Hash of options (default {}):
+  #           :env_var  - The String name of the environment variable. If
+  #                       omitted the uppercased form of `name` will be used.
+  #           :type     - The Symbol type of the environment variable's value.
+  #                       The value will be coerced to this type. Must be one
+  #                       of :string, :int, or :bool (default :string).
+  #           :required - A Boolean indicating whether the value must be
+  #                       present in the environment. If true, a
+  #                       MissingValueError exception will be raised if the
+  #                       value isn't present in the environment. Otherwise,
+  #                       the value will be set to `nil` if the environment
+  #                       variable isn't present (default true).
+  #
+  # Raises a MissingValueError for required values that are missing.
+  # Raises a TypeMismatchError if a value can't be coerced to the given `type`.
+  # Raises an ArgumentError if an invalid `type` is provided.
+  def self.load(name, options = {})
+    registry.load(name, options)
   end
 
+  # Fetch a value from the registry.
+  #
+  # name - The Symbol name of the variable to look up. The name must have
+  #        previously been `#load`ed into the registry.
+  #
+  # Raises UndeclaredNameError if the name provided has not been loaded into
+  # the registry.
   def self.get(name)
     registry.get(name)
   end
 
+  # Internal: accessor for the shared registry.
   def self.registry
     @registry ||= Registry.new(ENV)
   end
+  private_class_method :registry
 end

data/lib/prius/registry.rb

@@ -2,23 +2,29 @@ require "prius/errors"
 
 module Prius
   class Registry
-    TYPES = [:string, :int, :bool]
-
+    # Initialise a Registry.
+    #
+    # env - A Hash used as a source for environment variables. Usually, ENV
+    #       will be used.
     def initialize(env)
       @env = env
       @registry = {}
     end
 
-    def load(name, env_var: nil, type: :string, allow_nil: false)
-      env_var ||= name.to_s.upcase
+    # See Prius.load for documentation.
+    def load(name, options = {})
+      env_var = options.fetch(:env_var, name.to_s.upcase)
+      type = options.fetch(:type, :string)
+      required = options.fetch(:required, true)
       @registry[name] = case type
-                        when :string then load_string(env_var, allow_nil)
-                        when :int    then load_int(env_var, allow_nil)
-                        when :bool   then load_bool(env_var, allow_nil)
-                        else raise ArgumentError
+                        when :string then load_string(env_var, required)
+                        when :int    then load_int(env_var, required)
+                        when :bool   then load_bool(env_var, required)
+                        else raise ArgumentError, "Invalid type #{type}"
                         end
     end
 
+    # See Prius.get for documentation.
     def get(name)
       @registry.fetch(name)
     rescue KeyError
@@ -27,21 +33,15 @@ module Prius
 
     private
 
-    def check_valid_type(type)
-      unless TYPES.include?(type)
-        raise ArgumentError, "invalid type '#{type}'"
-      end
-    end
-
-    def load_string(name, allow_nil)
+    def load_string(name, required)
       @env.fetch(name)
     rescue KeyError
-      return nil if allow_nil
+      return nil unless required
       raise MissingValueError, "config value '#{name}' not present"
     end
 
-    def load_int(name, allow_nil)
-      value = load_string(name, allow_nil)
+    def load_int(name, required)
+      value = load_string(name, required)
       return value if value.nil?
 
       unless /\A[0-9]+\z/.match(value)
@@ -50,8 +50,8 @@ module Prius
       value.to_i
     end
 
-    def load_bool(name, allow_nil)
-      value = load_string(name, allow_nil)
+    def load_bool(name, required)
+      value = load_string(name, required)
       return nil if value.nil?
 
       if /\A(yes|y|true|t|1)\z/i.match(value)

data/lib/prius/version.rb

@@ -1,3 +1,3 @@
 module Prius
-  VERSION = "0.2.0".freeze
+  VERSION = "1.0.0".freeze
 end

data/prius.gemspec

@@ -19,4 +19,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "rspec", "~> 3.1"
+  spec.add_development_dependency "rubocop", "~> 0.31.0"
 end

data/spec/prius/registry_spec.rb

@@ -17,9 +17,9 @@ describe Prius::Registry do
           to raise_error(Prius::MissingValueError)
       end
 
-      context "when allow_nil is true" do
+      context "when required is false" do
         it "doesn't blow up" do
-          expect { registry.load(:slogan, allow_nil: true) }.to_not raise_error
+          expect { registry.load(:slogan, required: false) }.to_not raise_error
         end
       end
     end
@@ -88,7 +88,7 @@ describe Prius::Registry do
     end
 
     context "given a nillable name that has been loaded" do
-      before { registry.load(:lightsabre, allow_nil: true) }
+      before { registry.load(:lightsabre, required: false) }
       it "returns nil" do
         expect(registry.get(:lightsabre)).to be_nil
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prius
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Harry Marr
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-05 00:00:00.000000000 Z
+date: 2015-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -24,6 +24,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.31.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.31.0
 description: Environmentally-friendly config
 email:
 - engineering@gocardless.com
@@ -32,7 +46,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rubocop.yml
+- .travis.yml
 - Gemfile
+- LICENSE
 - README.md
 - lib/prius.rb
 - lib/prius/errors.rb
@@ -67,3 +84,4 @@ specification_version: 4
 summary: Environmentally-friendly config
 test_files:
 - spec/prius/registry_spec.rb
+has_rdoc: