figaro 0.7.0 → 1.0.0.rc1

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NzdlMWViMjZiNjk2MDk0MTE1YWZiNDcyMzU1ZmExOTAzYjI3ZTQyMA==
-  data.tar.gz: !binary |-
-    MzY4M2FhNmZkZTQ4ZWMxYTQ3NjFjYTUwYjM0YTgyYTNhNTk2YzY2OQ==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    M2Y4NjlmNjJhNTZmOGM2MTAzODhlZjBmYzg3ZGNkMzQxNDFlMWI5ZTgxNzlj
-    YmQ5YmY4NDlhZDI5ZTIyZDA0ODc4NDI0NmViNzVhYjdmMDI1YWM0YWU3Zjkw
-    NTBkNDJmY2ZkYjdiMDk0NzQwZmI0ZmFlM2M4NDBmYTNhOTA1MTI=
-  data.tar.gz: !binary |-
-    YjBlYWZkZDU5MzA3NjJlNjc3N2FlZjE0OWIwZDA1YzA1MjRhM2NiNDI1MzA0
-    MjQxNjYwNzRlYWFiNDM5YzYzY2Q0ODAzZDA3ZDVjZjVmMzcyMTk5Nzk2ZTRh
-    ZDE0MDk1ZmJkZjRjMzkyNjk1ZmU3M2ExNjE5NmJlZGVjMmM0Y2Y=
+SHA1:
+  metadata.gz: be2f663928712ac1479ead89e437afa4de7e36dd
+  data.tar.gz: 6343872755d9414093758aabc50a027bc4eedd6d
+SHA512:
+  metadata.gz: 47fd66bb0def311e27c08271e0f03c0fe16886505882ec98fdfe5ec0b8862d800a6ce79b68f19d2fe741729b76774b98340ce845660712e2de5b264441a41105
+  data.tar.gz: 78fb3923162e6b3f79d23d9ab0e8118d6b267958da1c0401877c287cacdcccf2c90ac6a2ef8b8aee31ee8aa4ac848b81f4652b637afc529578e8107173461f5e

data/.gitignore

@@ -1,4 +1,4 @@
-/.bundle
+.bundle
 /Gemfile.lock
 /coverage
 /gemfiles/*.gemfile.lock

data/.travis.yml

@@ -1,27 +1,32 @@
-branches: master
+before_script:
+  - unset RAILS_ENV
+  - unset RACK_ENV
+branches:
+  only:
+    - master
+env:
+  global:
+    secure: | # CODECLIMATE_REPO_TOKEN
+      Pm3j2/BtAzMtqRMP83rFvDtpUNeIAdLMzwH62In+3h/AE8gHDArGYS+jmChw
+      2hKVjwzVUTWZlpSEocqAg/YIDB3BJzWmyc6UP+VA0gji6HsufXYTmKAVPSVY
+      TQ7mPPP7hm95e3SkFbLdLbGkQfLdjIKeMY5lY/knX+QKUCjO52Y=
 gemfile:
   - gemfiles/rails30.gemfile
   - gemfiles/rails31.gemfile
   - gemfiles/rails32.gemfile
   - gemfiles/rails40.gemfile
+  - gemfiles/rails41.gemfile
 language: ruby
-rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
-before_install:
-  - gem update bundler
-before_script:
-  - unset RAILS_ENV
-  - unset RACK_ENV
 matrix:
-  exclude:
-    - gemfile: gemfiles/rails40.gemfile
-      rvm: 1.8.7
-    - gemfile: gemfiles/rails40.gemfile
-      rvm: 1.9.2
+  allow_failures:
+    - rvm: ruby-head
   include:
-    - gemfile: gemfiles/rails40.gemfile
-      rvm: 2.0.0
+    - gemfile: Gemfile
+      rvm: "2.1"
       env: COVERAGE=1
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - "2.1"
+  - ruby-head
+script: bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,98 @@
+## 1.0.0.rc1 / Unreleased
+
+* [FEATURE] Add bang and boolean methods to `Figaro.env`
+* [ENHANCEMENT] Detach `Figaro.env` from the configuration file hash
+* [FEATURE] Add the ability to swap Figaro's application adapter
+* [FEATURE] Warn when configuration keys or values are not strings
+* [FEATURE] Enable Figaro to load multiple times, overwriting previous values
+* [FEATURE] Load Figaro configuration prior to database configuration
+* [ENHANCEMENT] Test against Ruby 2.1
+* [ENHANCEMENT] Test against Rails 4.1
+* [FEATURE] Replace Rake task with `figaro` executable
+* [BUGFIX] Fix character escaping for `figaro heroku:set` on Windows
+* [FEATURE] Warn when a preexisting configuration key is skipped during load
+* [FEATURE] Add the ability to fail fast in the absence of required keys
+* [FEATURE] Tie into Rails' earliest possible `before_configuration` hook
+
+## 0.7.0 / 2013-06-27
+
+* [FEATURE] Allow configuration values to be overridden on the system level
+* [FEATURE] Enable ERB evaluation of the configuration file
+
+## 0.6.4 / 2013-05-01
+
+* [BUGFIX] Make the configuration file path platform-independent
+* [FEATURE] Make `Figaro.env` proxy method calls case-insensitive
+
+## 0.6.3 / 2013-03-10
+
+* [BUGFIX] Run Heroku commands with a clean Bundler environment
+
+## 0.6.2 / 2013-03-07
+
+* [ENHANCEMENT] Refactor `figaro:heroku` task into a unit-tested class
+* [ENHANCEMENT] Relax development gem dependency version requirements
+* [ENHANCEMENT] Track test coverage
+
+## 0.6.1 / 2013-02-27
+
+* [ENHANCEMENT] Declare development gem dependencies in gemfiles
+* [BUGFIX] Cast boolean configuration values to strings
+* [ENHANCEMENT] Use RSpec `expect` syntax
+
+## 0.6.0 / 2013-02-26
+
+* [ENHANCEMENT] Test against Ruby 2.0.0
+* [ENHANCEMENT] Test against Rails 4.0
+
+## 0.5.4 / 2013-02-22
+
+* [ENHANCEMENT] GitHub Ruby Styleguide conventions
+* [ENHANCEMENT] Remove unnecessary development dependencies
+* [FEATURE] Allow `nil` values in `Figaro.env`
+
+## 0.5.3 / 2013-01-12
+
+* [BUGFIX] Fix `figaro:heroku` to properly capture standard output... again
+
+## 0.5.2 / 2013-01-07
+
+* [BUGFIX] Escape special characters in the `figaro:heroku` task
+
+## 0.5.1 / 2013-01-07
+
+* [BUGFIX] Fix `figaro:heroku` to properly capture standard output
+
+## 0.5.0 / 2012-10-28
+
+* [BUGFIX] Automatically cast configuration keys and values to strings
+* [FEATURE] Allow the `figaro:heroku` task to respect remote Rails environment
+* [FEATURE] Enable `Figaro.env` to act as a proxy to `ENV`
+
+## 0.4.1 / 2012-04-25
+
+* [BUGFIX] Fix `figaro:heroku` Rake task failures
+
+## 0.4.0 / 2012-04-20
+
+* [FEATURE] Allow environment-specific configuration
+
+## 0.3.0 / 2012-04-20
+
+* [ENHANCEMENT] Refactor the loading configuration into `ENV`
+* [FEATURE] Add `figaro:heroku` Rake task
+
+## 0.2.0 / 2012-04-03
+
+* [ENHANCEMENT] Test against multiple Rails versions (3.0, 3.1, 3.2)
+* [FEATURE] Add `figaro:install` Rails generator
+* [BUGFIX] Gracefully parse YAML files containing only comments
+
+## 0.1.1 / 2012-04-02
+
+* [ENHANCEMENT] Remove RSpec development gem dependency
+* [ENHANCEMENT] Introduce Figaro, the mascot
+
+## 0.1.0 / 2012-04-02
+
+* Initial release!

data/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Figaro
+
+Figaro is open source and contributions from the community are encouraged! No
+ contribution is too small.
+
+Please consider:
+
+* Adding a feature
+* Squashing a bug
+* Writing documentation
+* Fixing a typo
+* Correcting [style](https://github.com/styleguide/ruby)
+
+## How do I contribute?
+
+For the best chance of having your changes merged, please:
+
+1. [Fork](https://github.com/laserlemon/figaro/fork) the project.
+2. [Write](http://en.wikipedia.org/wiki/Test-driven_development) a failing test.
+3. [Commit](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) changes that fix the tests.
+4. [Submit](https://github.com/laserlemon/figaro/pulls) a pull request with *at least* one animated GIF.
+5. Be patient.
+
+If your proposed changes only affect documentation, include the following on a
+new line in each of your commit messages:
+
+```
+[ci skip]
+```
+
+This will signal [Travis](https://travis-ci.org) that running the test suite is
+not necessary for these changes.
+
+## Bug Reports
+
+If you are experiencing unexpected behavior and, after having read Figaro's
+documentation, are convinced this behavior is a bug, please:
+
+1. [Search](https://github.com/laserlemon/figaro/issues) existing issues.
+2. Collect enough information to reproduce the issue:
+  * Figaro version
+  * Ruby version
+  * Rails version
+  * Specific setup conditions
+  * Description of expected behavior
+  * Description of actual behavior
+3. [Submit](https://github.com/laserlemon/figaro/issues/new) an issue.
+4. Be patient.

data/Gemfile

@@ -2,13 +2,11 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "rails", ">= 3.0.2", "< 5"
+gem "rails", ">= 3.0.3", "< 5"
 
 group :test do
   gem "aruba", "~> 0.5"
-  gem "coveralls", "~> 0.6", :require => false
-  gem "cucumber", "~> 1.3"
-  gem "rake", "~> 10.0"
-  gem "rspec", "~> 2.13"
-  gem "simplecov", "~> 0.7", :require => false
+  gem "codeclimate-test-reporter", "~> 0.3.0", require: false
+  gem "rspec", "~> 2.14"
+  gem "sqlite3", "~> 1.3"
 end

data/README.md

@@ -1,114 +1,237 @@
-# Figaro
-[![Gem Version](https://badge.fury.io/rb/figaro.png)](http://badge.fury.io/rb/figaro)
-[![Build Status](https://travis-ci.org/laserlemon/figaro.png?branch=master)](https://travis-ci.org/laserlemon/figaro)
-[![Code Climate](https://codeclimate.com/github/laserlemon/figaro.png)](https://codeclimate.com/github/laserlemon/figaro)
-[![Coverage Status](https://coveralls.io/repos/laserlemon/figaro/badge.png?branch=master)](https://coveralls.io/r/laserlemon/figaro)
-[![Dependency Status](https://gemnasium.com/laserlemon/figaro.png)](https://gemnasium.com/laserlemon/figaro)
+# ![Figaro](doc/title.png)
 
-Simple Rails app configuration
+Simple, Heroku-friendly Rails app configuration using `ENV` and a single YAML file
 
-## What is this for?
+[![Gom Version](https://img.shields.io/gem/v/figaro.svg)](http://badge.fury.io/rb/figaro)
+[![Build Status](https://img.shields.io/travis/laserlemon/figaro/master.svg)](https://travis-ci.org/laserlemon/figaro)
+[![Code Climate](https://img.shields.io/codeclimate/github/laserlemon/figaro.svg)](https://codeclimate.com/github/laserlemon/figaro)
+[![Coverage Status](https://img.shields.io/codeclimate/coverage/github/laserlemon/figaro.svg)](https://codeclimate.com/github/laserlemon/figaro)
+[![Dependency Status](https://img.shields.io/gemnasium/laserlemon/figaro.svg)](https://gemnasium.com/laserlemon/figaro)
 
-Figaro is for configuring Rails (3 and 4) apps, especially open source Rails apps.
+## Why does Figaro exist?
 
-Open sourcing a Rails app can be a little tricky when it comes to sensitive configuration information like [Pusher](http://pusher.com/) or [Stripe](https://stripe.com/) credentials. You don't want to check private credentials into the repo but what other choice is there?
+Figaro was written to make it easy to securely configure Rails applications.
 
-Figaro provides a clean and simple way to configure your app and keep the private stuff… private.
+Configuration values often include sensitive information. Figaro strives to be secure by default by encouraging a convention that keeps configuration out of Git.
 
-## How does it work?
+## How does Figaro work?
 
-There are a few similar solutions out there, and a lot of homegrown attempts. Most namespace your configuration under a `Config` (or similar) namespace. That's fine, but there's already a place to describe the application environment… `ENV`!
+Figaro is inspired by the [Twelve-Factor App](http://12factor.net) methodology, which states:
 
-`ENV` is a collection of simple string key/value pairs and it works just great for application configuration.
+> The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.
 
-As an added bonus, this is exactly how apps on [Heroku](http://www.heroku.com/) are configured. So if you configure your Rails app using `ENV`, you're already set to deploy to Heroku.
+This is straightforward in production environments but local development environments are often shared between multiple applications, requiring multiple configurations.
 
-## Give me an example.
+Figaro parses a Git-ignored YAML file in your application and loads its values into `ENV`.
 
-Okay. Add Figaro to your Gemfile and run the `bundle` command to install it:
+### Example
+
+Given the following configuration file:
+
+```yaml
+# config/application.yml
+
+pusher_app_id: "2954"
+pusher_key: "7381a978f7dd7f9a1117"
+pusher_secret: "abdc3b896a0ffb85d373"
+```
+
+You can configure [Pusher](http://pusher.com) in an initializer:
 
 ```ruby
-gem "figaro"
+# config/initializers/pusher.rb
+
+Pusher.app_id = ENV["pusher_app_id"]
+Pusher.key    = ENV["pusher_key"]
+Pusher.secret = ENV["pusher_secret"]
 ```
 
-Next up, use the generator provided by Figaro:
+**Please note:** `ENV` is a simple key/value store. All values will be converted to strings. Deeply nested configuration structures are not possible.
 
-```bash
-rails generate figaro:install
+### Environment-Specific Configuration
+
+Oftentimes, local configuration values change depending on Rails environment. In such cases, you can add environment-specific values to your configuration file:
+
+```yaml
+# config/application.yml
+
+pusher_app_id: "2954"
+pusher_key: "7381a978f7dd7f9a1117"
+pusher_secret: "abdc3b896a0ffb85d373"
+
+test:
+  pusher_app_id: "5112"
+  pusher_key: "ad69caf9a44dcac1fb28"
+  pusher_secret: "83ca7aa160fedaf3b350"
 ```
 
-This creates a commented `config/application.yml` file and ignores it in your `.gitignore`. Add your own configuration to this file and you're done!
+You can also nullify configuration values for a specific environment:
 
-Your configuration will be available as key/value pairs in `ENV`. For example, here's `config/initializers/pusher.rb`:
+```yaml
+# config/application.yml
+
+google_analytics_key: "UA-35722661-5"
+
+test:
+  google_analytics_key: ~
+```
+
+### Using `Figaro.env`
+
+`Figaro.env` is a convenience that acts as a proxy to `ENV`.
+
+In testing, it is sometimes more convenient to stub and unstub `Figaro.env` than to set and reset `ENV`. Whether your application uses `ENV` or `Figaro.env` is entirely a matter of personal preference.
+
+```yaml
+# config/application.yml
+
+stripe_api_key: "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL"
+```
 
 ```ruby
-Pusher.app_id = ENV["PUSHER_APP_ID"]
-Pusher.key    = ENV["PUSHER_KEY"]
-Pusher.secret = ENV["PUSHER_SECRET"]
+ENV["stripe_api_key"] # => "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL"
+ENV.key?("stripe_api_key") # => true
+ENV["google_analytics_key"] # => nil
+ENV.key?("google_analytics_key") # => false
+
+Figaro.env.stripe_api_key # => "sk_live_dSqzdUq80sw9GWmuoI0qJ9rL"
+Figaro.env.stripe_api_key? # => true
+Figaro.env.google_analytics_key # => nil
+Figaro.env.google_analytics_key? # => false
 ```
 
-In addition, you can access these same configuration values through Figaro itself:
+### Required Keys
+
+If a particular configuration value is required but not set, it's appropriate to raise an error. With Figaro, you can either raise these errors proactively or lazily.
+
+To proactively require configuration keys:
 
 ```ruby
-Pusher.app_id = Figaro.env.pusher_app_id
-Pusher.key    = Figaro.env.pusher_key
-Pusher.secret = Figaro.env.pusher_secret
+# config/initializers/figaro.rb
+
+Figaro.require("pusher_app_id", "pusher_key", "pusher_secret")
 ```
 
-But wait… I thought configuration via constant was bad! Well, this is different. Rather than storing a _copy_ of `ENV` internally, `Figaro.env` passes directly through to `ENV`, making it just like using `ENV` itself. So why two approaches? Having your configurations available via method calls makes it easy to stub them out in tests. Either way is fine. The choice is yours!
+If any of the configuration keys above are not set, your application will raise an error during initialization. This method is preferred because it prevents runtime errors in a production application due to improper configuration.
 
-If your app requires Rails-environment-specific configuration, you can also namespace your configuration under a key for `Rails.env`.
+To require configuration keys lazily, reference the variables via "bang" methods on `Figaro.env`:
 
-```yaml
-HELLO: world
-development:
-  HELLO: developers
-production:
-  HELLO: users
+```ruby
+# config/initializers/pusher.rb
+
+Pusher.app_id = Figaro.env.pusher_app_id!
+Pusher.key    = Figaro.env.pusher_key!
+Pusher.secret = Figaro.env.pusher_secret!
 ```
 
-In this case, `ENV["HELLO"]` will produce `"developers"` in development, `"users"` in production and `"world"` otherwise.
+### Deployment
 
-## How does it work with Heroku?
+Figaro is written with deployment in mind. In fact, [Heroku](https://www.heroku.com)'s use of `ENV` for application configuration was the original inspiration for Figaro.
 
-Heroku's beautifully simple application configuration was the [inspiration](http://laserlemon.com/blog/2011/03/08/heroku-friendly-application-configuration/) for Figaro.
+#### Heroku
 
-Typically, to configure your application `ENV` on Heroku, you would do the following from the command line using the `heroku` gem:
+Heroku already makes setting application configuration easy:
 
 ```bash
-heroku config:add PUSHER_APP_ID=8926
-heroku config:add PUSHER_KEY=0463644d89a340ff1132
-heroku config:add PUSHER_SECRET=0eadfd9847769f94367b
-heroku config:add STRIPE_API_KEY=jHXKPPE0dUW84xJNYzn6CdWM2JfrCbPE
-heroku config:add STRIPE_PUBLIC_KEY=pk_HHtUKJwlN7USCT6nE5jiXgoduiNl3
+$ heroku config:set google_analytics_key=UA-35722661-5
 ```
 
-But Figaro provides a rake task to do just that! Just run:
+Using the `figaro` command, you can set values from your configuration file all at once:
 
 ```bash
-rake figaro:heroku
+$ figaro heroku:set -e production
 ```
 
-Optionally, you can pass in the name of the Heroku app:
+For more information:
 
 ```bash
-rake figaro:heroku[my-awesome-app]
+$ figaro help heroku:set
 ```
 
-Additionally, if `RAILS_ENV` is configured on your Heroku server, Figaro will use that environment automatically in determining your proper configuration.
+#### Other Hosts
+
+If you're not deploying to Heroku, you have two options:
+
+* Generate a remote configuration file
+* Set `ENV` variables directly
+
+Generating a remote configuration file is preferred because of:
+
+* familiarity – Management of `config/application.yml` is like that of `config/database.yml`.
+* isolation – Multiple applications on the same server will not produce configuration key collisions.
+
+## Is Figaro like [dotenv](https://github.com/bkeepers/dotenv)?
+
+Yes. Kind of.
+
+Figaro and dotenv were written around the same time to solve similar problems.
+
+### Similarities
+
+* Both libraries are useful for Ruby application configuration.
+* Both are popular and well maintained.
+* Both are inspired by Twelve-Factor App's concept of proper [configuration](http://12factor.net/config).
+* Both store configuration values in `ENV`.
+
+### Differences
+
+* Configuration File
+  * Figaro expects a single file.
+  * Dotenv supports separate files for each environment.
+* Configuration File Format
+  * Figaro expects YAML containing key/value pairs.
+  * Dotenv convention is a collection of `KEY=VALUE` pairs.
+* Security vs. Convenience
+  * Figaro convention is to never commit configuration files.
+  * Dotenv encourages committing configuration files containing development values.
+* Framework Focus
+  * Figaro was written with a focus on Rails development and conventions.
+  * Dotenv was written to accommodate any type of Ruby application.
+
+Either library may suit your configuration needs. It often boils down to personal preference.
+
+## Is application.yml like [secrets.yml](https://github.com/rails/rails/blob/v4.1.0/railties/lib/rails/generators/rails/app/templates/config/secrets.yml)?
+
+Yes. Kind of.
+
+Rails 4.1 introduced the `secrets.yml` convention for Rails application configuration. Figaro predated the Rails 4.1 release by two years.
+
+### Similarities
+
+* Both are useful for Rails application configuration.
+* Both are popular and well maintained.
+* Both expect a single YAML file.
+
+### Differences
+
+* Configuration Access
+  * Figaro stores configuration values in `ENV`.
+  * Rails stores configuration values in `Rails.application.secrets`.
+* Configuration File Structure
+  * Figaro expects YAML containing key/value string pairs.
+  * Secrets may contain nested structures with rich objects.
+* Security vs. Convenience
+  * Figaro convention is to never commit configuration files.
+  * Secrets are committed by default.
+* Consistency
+  * Figaro uses `ENV` for configuration in every environment.
+  * Secrets encourage using `ENV` for production only.
+* Approach
+  * Figaro is inspired by Twelve-Factor App's concept of proper [configuration](http://12factor.net/config).
+  * Secrets are… not.
+
+The emergence of a configuration convention for Rails is an important step, but as long as the last three differences above exist, Figaro will continue to be developed as a more secure, more consistent, and more standards-compliant alternative to `secrets.yml`.
 
-## What if I'm not using Heroku?
+For more information, read the original [The Marriage of Figaro… and Rails](http://www.collectiveidea.com/blog/archives/2013/12/18/the-marriage-of-figaro-and-rails/) blog post.
 
-No problem. Just add `config/application.yml` to your production app on the server.
+## Who wrote Figaro?
 
-## This sucks. How can I make it better?
+My name is Steve Richert and I wrote Figaro in March, 2012 with overwhelming encouragement from my employer, [Collective Idea](http://www.collectiveidea.com). Figaro has improved very much since then, thanks entirely to [inspiration](https://github.com/laserlemon/figaro/issues) and [contribution](https://github.com/laserlemon/figaro/graphs/contributors) from developers everywhere.
 
-1. Fork it.
-2. Make it better.
-3. Send me a pull request.
+**Thank you!**
 
-## Does Figaro have a mascot?
+## How can I help?
 
-Yes.
+Figaro is open source and contributions from the community are encouraged! No contribution is too small.
 
-[![Figaro](http://images2.wikia.nocookie.net/__cb20100628192722/disney/images/5/53/Pinocchio-pinocchio-4947890-960-720.jpg "Figaro's mascot: Figaro")](http://en.wikipedia.org/wiki/Figaro_(Disney\))
+See Figaro's [contribution guidelines](CONTRIBUTING.md) for more information.