ambience 0.2.0 → 0.3.0

data/CHANGELOG

@@ -1,3 +1,30 @@
+== 0.3.0 (2010-05-13)
+  * Ambience now operates on the instance level. So after setting up a new Ambience config
+    like before:
+    
+      AppConfig = Ambience.new File.join(Rails.root, "config", "ambience.yml")
+    
+    you now have to choose whether you like to have the config returned as a simple Hash
+    or a Hashie::Mash (which was the default since version 0.2.0):
+    
+      AppConfig.to_hash
+      AppConfig.to_mash
+    
+  * Along with support for a basic config and JVM properties, version 0.3.0 adds support
+    for local (user-specific) settings. By default, Ambience tries to load a local YAML
+    config from:
+    
+      File.join ENV["HOME"].to_s, ".ambience", "ambience.yml"
+    
+    Ambience will still work fine if the file does not exist. But if you want to use a
+    local config and change the default location, you can use the +local_config+ class
+    method to do so.
+    
+      Ambience.local_config # => "/Users/you/.ambience/ambience.yml"
+      
+      # Change the location of the local config file:
+      Ambience.local_config = File.join "config", "user_config.yml"
+
 == 0.2.0 (2010-03-06)
   * Complete rewrite. Removed Rails-specific defaults and returning the Ambience config
     as a Hashie::Mash (http://github.com/intridea/hashie). Take a look at the new Readme

data/README.rdoc

@@ -1,6 +1,6 @@
 = Ambience
 
-App configuration feat. YAML and JVM properties. Lets you specify a default configuration in a YAML file and overwrite details via JVM properties for production.
+App configuration feat. YAML and JVM properties. Lets you specify a default configuration in a YAML file and overwrite details via local settings and JVM properties for production.
 
 == Installation
 
@@ -8,14 +8,14 @@ App configuration feat. YAML and JVM properties. Lets you specify a default conf
 
 == How it works
 
-Given you created a YAML config like this one:
+Given you created a YAML config like this:
 
   auth:
     address: http://example.com
     username: ferris
     password: test
 
-You create an Ambience config by passing in the path to your config file:
+You can instantiate an Ambience config by passing in the path to your config file:
 
   AppConfig = Ambience.new File.join(Rails.root, "config", "ambience.yml")
 
@@ -23,23 +23,19 @@ Ambience will load and convert your config into a Hash:
 
   { "auth" => { "address" => "http://example.com", "username" => "ferris", "password" => "test" } }
 
-Then it looks for any JVM properties (if your running JRuby)
+Afterwards it tries to merge these settings with local ones specified in an Ambience.local_config file. Finally it looks for any JVM properties (if your running JRuby) and merge these properties with your config:
 
   auth.address = "http://live.example.com"
   auth.password = "topsecret"
 
-and deep merge them with your Hash:
+The result would be something like this:
 
   { "auth" => { "address" => "http://live.example.com", "username" => "ferris", "password" => "topsecret" } }
 
-Finally, it returns the Hash as a {Hashie::Mash}[http://github.com/intridea/hashie] so you can access values by specifying keys as Symbols or Strings or using method-like accessors:
+In the end you can decide whether you want to return the config as a Hash:
 
-  AppConfig[:auth][:address]
-  # => "http://live.example.com"
+  AppConfig = Ambience.new(File.join(Rails.root, "config", "ambience.yml")).to_hash
 
-  AppConfig["auth"]["username"]
-  # => "http://live.example.com"
-
-  AppConfig.auth.password
-  # => "topsecret"
+or a {Hashie::Mash}[http://github.com/intridea/hashie]:
 
+  AppConfig = Ambience.new(File.join(Rails.root, "config", "ambience.yml")).to_mash

data/lib/ambience/ambience.rb

@@ -1,98 +1,82 @@
 # = Ambience
 #
 # App configuration feat. YAML and JVM properties. Lets you specify a default configuration
-# in a YAML file and overwrite details via JVM properties for production.
-#
-# == How it works
-#
-# Given you created a YAML config like this one:
-#
-#   auth:
-#     address: http://example.com
-#     username: ferris
-#     password: test
-#
-# You create an Ambience config by passing in the path to your config file:
-#
-#   AppConfig = Ambience.new File.join(Rails.root, "config", "ambience.yml")
-#
-# Ambience will load and convert your config into a Hash:
-#
-#   { "auth" => { "address" => "http://example.com", "username" => "ferris", "password" => "test" } }
-#
-# Then it looks for any JVM properties (if your running JRuby)
-#
-#   auth.address = "http://live.example.com"
-#   auth.password = "topsecret"
-#
-# and deep merge them with your Hash:
-#
-#   { "auth" => { "address" => "http://live.example.com", "username" => "ferris", "password" => "topsecret" } }
-#
-# Finally, it returns the Hash as a {Hashie::Mash}[http://github.com/intridea/hashie] so you can
-# access values by specifying keys as Symbols or Strings or using method-like accessors:
-#
-#   AppConfig[:auth][:address]
-#   # => "http://live.example.com"
-#
-#   AppConfig["auth"]["username"]
-#   # => "http://live.example.com"
-#
-#   AppConfig.auth.password
-#   # => "topsecret"
+# in a YAML file and overwrite details via local settings and JVM properties for production.
 class Ambience
-  class << self
 
-    # Returns a new Ambience config from a given YAML +config_file+ for an optional +env+.
-    # Overwrites properties with any JVM properties (in case the application is running on JRuby).
-    def new(config_file, env = nil)
-      config_hash = parse_config load_config(config_file)
-      config_hash = config_hash[env.to_s] || config_hash[env.to_sym] if env
-      config_hash.deep_merge! jvm_property_hash
-      Hashie::Mash.new config_hash
-    end
+  # Sets the path to a local ambience config file.
+  def self.local_config=(local_config)
+    @@local_config = local_config
+  end
 
-    # Returns whether the current Ruby platfrom is JRuby.
-    def jruby?
-      RUBY_PLATFORM =~ /java/
-    end
+  # Returns the path to a local ambience config file for specifying user-specific
+  # settings that don't belong into the application config file.
+  def self.local_config
+    @@local_config ||= File.join ENV["HOME"].to_s, ".ambience", "ambience.yml"
+  end  
 
-  private
+  # Returns whether the current Ruby platfrom is JRuby.
+  def self.jruby?
+   RUBY_PLATFORM =~ /java/
+  end
 
-    # Loads a given +config_file+. Raises an ArgumentError in case the config could not be found.
-    def load_config(config_file)
-      raise ArgumentError, "Missing config: #{config_file}" unless File.exist? config_file
-      File.read config_file
-    end
+  def initialize(config_file, env = nil)
+    @config_file, @env = config_file, env
+  end
 
-    # Returns the ERB-interpreted content from a given YAML +config+ String and returns a Hash
-    # containing the evaluated content. Defaults to returning an empty Hash.
-    def parse_config(config)
-      YAML.load ERB.new(config).result || {}
-    end
+  # Returns the Ambience config as a Hash.
+  def to_hash
+    config = load_config @config_file
+    config = config.deep_merge local_config
+    config.deep_merge jvm_config
+  end
 
-    # Returns a Hash containing any JVM properties.
-    def jvm_property_hash
-      jvm_properties.inject({}) do |hash, (key, value)|
-        hash.deep_merge hash_from_property(key, value)
-      end
-    end
+  # Returns the Ambience config as a Hashie::Mash.
+  def to_mash
+    Hashie::Mash.new to_hash
+  end
 
-    # Returns a Hash generated from a JVM +property+ and its +value+.
-    #
-    # ==== Example:
-    #
-    #   hash_from_property "webservice.auth.address", "http://auth.example.com"
-    #   # => { "webservice" => { "auth" => { "address" => "http://auth.example.com" } } }
-    def hash_from_property(property, value)
-      property.split(".").reverse.inject(value) { |value, item| { item => value } }
-    end
+private
 
-    # Returns the JVM properties.
-    def jvm_properties
-      jruby? ? JavaLang::System.get_properties : {}
+  def load_config(config_file)
+    raise ArgumentError, "Missing config: #{config_file}" unless File.exist? config_file
+    
+    config = File.read config_file
+    config = YAML.load ERB.new(config).result || {}
+    config = config[@env.to_s] || config[@env.to_sym] if @env
+    config
+  end
+
+  # Returns a Hash containing any local settings from the +@@local_config+.
+  def local_config
+    File.exist?(self.class.local_config) ? load_config(self.class.local_config) : {}
+  end
+
+  ## Returns a Hash containing any JVM properties.
+  def jvm_config
+    jvm_properties.inject({}) do |hash, (key, value)|
+      hash.deep_merge hash_from_property(key, value)
     end
+  end
+
+  # Returns the JVM properties.
+  def jvm_properties
+    JavaLang::System.get_properties rescue {}
+  end
+
+  # Returns a Hash generated from a JVM +property+ and its +value+.
+  #
+  # ==== Example:
+  #
+  #   hash_from_property "webservice.auth.address", "http://auth.example.com"
+  #   # => { "webservice" => { "auth" => { "address" => "http://auth.example.com" } } }
+  def hash_from_property(property, value)
+    property.split(".").reverse.inject(value) { |value, item| { item => value } }
+  end
 
+  # Returns the JVM properties.
+  def jvm_properties
+    self.class.jruby? ? JavaLang::System.get_properties : {}
   end
 
   if jruby?

data/spec/ambience/ambience_spec.rb

@@ -3,9 +3,17 @@ require "spec_helper"
 describe Ambience do
   include SpecHelper
 
-  it "should return the content of a given config file as a Hashie::Mash" do
-    config = Ambience.new config_file(:basic)
+  it "should return the content of a given config file as a Hash" do
+    config = Ambience.new(config_file(:basic)).to_hash
+    
+    config.should be_a(Hash)
+    config["auth"]["username"].should == "ferris"
+    config["auth"]["password"].should == "test"
+  end
 
+  it "should return the content of a given config file as a Hashie::Mash" do
+    config = Ambience.new(config_file(:basic)).to_mash
+    
     config.should be_a(Hashie::Mash)
     config.auth.username.should == "ferris"
     config[:auth][:address].should == "http://example.com"
@@ -13,16 +21,16 @@ describe Ambience do
   end
 
   it "should return the config for an optional environment as a Hashie::Mash" do
-    config = Ambience.new config_file(:environments), :production
-
+    config = Ambience.new(config_file(:environments), :production).to_mash
+    
     config.should be_a(Hashie::Mash)
     config.auth.username.should == "ferris"
     config[:auth]["password"].should == "topsecret"
   end
 
   it "should return the config specified as Symbols as a Hashie::Mash" do
-    config = Ambience.new config_file(:symbols), "production"
-
+    config = Ambience.new(config_file(:symbols), "production").to_mash
+    
     config.should be_a(Hashie::Mash)
     config.auth.username.should == "ferris"
     config[:auth]["password"].should == "test"
@@ -30,11 +38,11 @@ describe Ambience do
 
   it "should merge the config with any JVM properties when using JRuby" do
     Ambience.stubs(:jruby?).returns(true)
-    Ambience.stubs(:jvm_properties).returns(
+    Ambience.any_instance.stubs(:jvm_properties).returns(
       "auth.address" => "http://live.example.com",
       "auth.password" => "topsecret"
     )
-    config = Ambience.new config_file(:basic)
+    config = Ambience.new(config_file(:basic)).to_mash
 
     config.should be_a(Hashie::Mash)
     config.auth.username.should == "ferris"
@@ -43,7 +51,7 @@ describe Ambience do
   end
 
   it "should raise an ArgumentError in case the given config file could not be found" do
-    lambda { Ambience.new "missing_config.yml" }.should raise_error(ArgumentError)
+    lambda { Ambience.new("missing_config.yml").to_hash }.should raise_error(ArgumentError)
   end
 
 end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: ambience
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Daniel Harrington
@@ -9,39 +14,51 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-06 00:00:00 +01:00
+date: 2010-05-13 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: hashie
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 2
+        - 0
         version: 0.2.0
-    version: 
+  type: :runtime
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 8
         version: 1.2.8
-    version: 
+  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: mocha
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 7
         version: 0.9.7
-    version: 
+  type: :development
+  version_requirements: *id003
 description: 
 email: me@rubiii.com
 executables: []
@@ -79,18 +96,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: App configuration feat. YAML and JVM properties