app_config.gemspec lib/closed_struct.rb @@ -1,2 +1,8 @@ 10/03/2008 -* recursively merge the configuration hashes \ No newline at end of file +* recursively merge the configuration hashes + +07/01/2009 +* Packaged as a gem (but still works as a Rails plugin). +* The app config object is now an instance of ApplicationConfiguration. +* NoMethodError raised if you try to access a config element that doesn't exist. +* ApplicationConfiguration#reload! to reread the config files and rebuild the app config object. \ No newline at end of file CHANGELOG @@ -1,80 +1,59 @@ == Summary Application level configuration. +== Features + + * simple YAML config files + * config files support ERB + * config files support inheritance + * access config information via convenient object member notation + +=== Basic Usage + +You simply write a configuration file in YAML. Notice you can use ERB. + +config.yml + aws: + access_key: 123ABC + secret_key: ABC123 + now: <%= Time.now %> + servers: [ {name: example1.com}, {name: example2.com} ] + +Then somewhere in your code, you create a global constant from the config file. Then access the config data via object member notation. + +_code_ + ::AppConfig = ApplicationConfiguration.new("config.yml") + AppConfig.aws.access_key # => "123ABC" + AppConfig.aws.secret_key # => "ABC123" + AppConfig.now # => Tue May 05 21:55:15 -0500 2009 + AppConfig.servers[0].name # => "example1.com" + +=== Inheritance + +You can have a second config file that is recursively merged with the first config file. + +base.yml + app_name: MyCoolApp + domain: dev.mycoolapp.com + +production.yml + domain: www.mycoolapp.com + +_code_ + ::AppConfig = ApplicationConfiguration.new("base.yml", "production.yml") + AppConfig.app_name # => "MyCoolApp" + AppConfig.domain # => "www.mycoolapp.com" + +=== Using in a Rails app + +You just need to create an initializer that looks something like this. + + require 'app_config' + ::AppConfig = ApplicationConfiguration.new(RAILS_ROOT+"/config/app_config.yml", + RAILS_ROOT+"/config/environments/#{RAILS_ENV}.yml") + +If you installed this as a Rails plugin instead of a gem, that code is already run for you in +the plugin's init.rb. + == Author -Christopher J. Bottaro - -=== Accessing the AppConfig object -After installing this plugin, the AppConfig object will be global available. Entries are accessed via object member notation: - AppConfig.my_config_entry -Nested entries are supported: - AppConfig.my_section.some_entry - -=== Common config file -Config entries defined in - RAILS_ROOT/config/app_config.yml -will be available to all environments. - -=== Environment specific config files -You can have environment specific config files. Environment specific config entries take precedence over common config entries. - -Example development environment config file: - RAILS_ROOT/config/environments/development.yml - -Example production environment config file: - RAILS_ROOT/config/environments/production.yml - -==== UPDATE (10/03/2008) -The config files are recursively merged now. Thus the following works: - -<tt>RAILS_ROOT/config/app_config.yml:</tt> - servers: - dev: dev.domain.com - test: test.domain.com - -<tt>RAILS_ROOT/config/environments/production.yml:</tt> - servers: - test: testing.domain.com - prod: prod.domain.com - -<tt>(application code):</tt> - AppConfig.servers.dev # => dev.domain.com - AppConfig.servers.test # => testing.domain.com - AppConfig.servers.prod # => prod.domain.com - -Whereas before, the "servers" section of <tt>production.yml</tt> would completely overwrite the "servers" section of <tt>app_config.yml</tt> and you would get: - - AppConfig.servers.dev # => nil - AppConfig.servers.test # => testing.domain.com - AppConfig.servers.prod # => prod.domain.com - -=== Embedded Ruby (ERB) - Embedded Ruby is allowed in the configuration files. See examples below. - -=== Examples -Consider the two following config files. - -RAILS_ROOT/config/app_config.yml: - size: 1 - server: google.com - -RAILS_ROOT/config/environments/development.yml: - size: 2 - computed: <%= 1 + 2 + 3 %> - section: - size: 3 - servers: [ {name: yahoo.com}, {name: amazon.com} ] - -Notice that the environment specific config entries overwrite the common entries. - AppConfig.size -> 2 - AppConfig.server -> google.com - -Notice the embedded Ruby. - AppConfig.computed -> 6 - -Notice that object member notation is maintained even in nested entries. - AppConfig.section.size -> 3 - -Notice array notation and object member notation is maintained. - AppConfig.section.servers[0].name -> yahoo.com - AppConfig.section.servers[1].name -> amazon.com \ No newline at end of file +Christopher J. Bottaro \ No newline at end of file README.rdoc @@ -2,6 +2,22 @@ require 'rake' require 'rake/testtask' require 'rake/rdoctask' +begin + require 'jeweler' + Jeweler::Tasks.new do |gem| + gem.name = "app_config" + gem.summary = %Q{Application level configuration.} + gem.description = %Q{Application level configuration that supports YAML config file, inheritance, ERB, and object member notation.} + gem.email = "cjbottaro@alumni.cs.utexas.edu" + gem.homepage = "http://github.com/cjbottaro/app_config" + gem.authors = ["Christopher J Bottaro"] + + # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings + end +rescue LoadError + puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com" +end + desc 'Default: run unit tests.' task :default => :test @@ -17,6 +33,6 @@ Rake::RDocTask.new(:rdoc) do |rdoc| rdoc.rdoc_dir = 'rdoc' rdoc.title = 'AppConfig' rdoc.options << '--line-numbers' << '--inline-source' - rdoc.rdoc_files.include('README') + rdoc.rdoc_files.include('README.rdoc') rdoc.rdoc_files.include('lib/**/*.rb') end Rakefile @@ -1,4 +1,4 @@ --- -:major: 0 +:major: 1 :minor: 0 :patch: 0 VERSION.yml @@ -1,4 +1,4 @@ require 'app_config' -::AppConfig = ApplicationConfig.load_files(RAILS_ROOT+"/config/app_config.yml", +::AppConfig = ApplicationConfiguration.new(RAILS_ROOT+"/config/app_config.yml", RAILS_ROOT+"/config/environments/#{RAILS_ENV}.yml") \ No newline at end of file init.rb @@ -1,31 +1,51 @@ -require 'ostruct' +require 'closed_struct' require 'yaml' require 'erb' -# == Summary -# This is API documentation, NOT documentation on how to use this plugin. For that, see the README. -module ApplicationConfig - - # Create a config object (OpenStruct) from a yaml file. If a second yaml file is given, then the sections of that file will overwrite the sections - # if the first file if they exist in the first file. - def self.load_files(conf_path_1, conf_path_2 = nil) - - conf1 = YAML.load(ERB.new(IO.read(conf_path_1)).result) if conf_path_1 and File.exists?(conf_path_1) - conf1 = {} if !conf1 or conf1.empty? - - conf2 = YAML.load(ERB.new(IO.read(conf_path_2)).result) if conf_path_2 and File.exists?(conf_path_2) - conf2 = {} if !conf2 or conf2.empty? - - conf = recursive_merge(conf1, conf2) - (!conf or conf.empty?) ? OpenStruct.new : convert(conf) - +class ApplicationConfiguration + + # Create a new ApplicationConfiguration object. <tt>conf_path_1</tt> is the path to your YAML configuration file. + # If <tt>conf_path_2</tt> is given, the contents are recursively merged with the contents of <tt>conf_path_1</tt>. + # This allows you to have a "base" configuration with settings that are overrided by "environment specific" + # (developement, test, production, etc) settings. + # + # Ex: + # ApplicationConfiguration.new(RAILS_ROOT+"/config/base.yml", RAILS_ROOT+"/environments/#{RAILS_ENV}_config.yml") + def initialize(conf_path_1, conf_path_2 = nil) + @conf_path_1, @conf_path_2 = conf_path_1, conf_path_2 + reload! + end + + # Rereads your configuration files and rebuilds your ApplicationConfiguration object. This is useful + # for when you edit your config files, but don't want to restart your web server. + def reload! + conf1 = load_conf_file(@conf_path_1) + conf2 = load_conf_file(@conf_path_2) + conf = recursive_merge(conf1, conf2) + @config = convert(conf) + end + +private + + def method_missing(name, *args) + if @config.respond_to?(name) + @config.send(name, *args) + else + super + end + end + + def load_conf_file(conf_path) + return {} if !conf_path or conf_path.empty? + File.open(conf_path, "r") do |file| + YAML.load(ERB.new(file.read).result) || {} + end end - # Recursively converts Hashes to OpenStructs (including Hashes inside Arrays) - def self.convert(h) #:nodoc: - s = OpenStruct.new + # Recursively converts Hashes to ClosedStructs (including Hashes inside Arrays) + def convert(h) #:nodoc: + s = ClosedStruct.new(h.keys) h.each do |k, v| - s.new_ostruct_member(k) if v.instance_of?(Hash) s.send( (k+'=').to_sym, convert(v)) elsif v.instance_of?(Array) @@ -39,8 +59,8 @@ module ApplicationConfig end # Recursively merges hashes. h2 will overwrite h1. - def self.recursive_merge(h1, h2) #:nodoc: + def recursive_merge(h1, h2) #:nodoc: h1.merge(h2){ |k, v1, v2| v2.kind_of?(Hash) ? recursive_merge(v1, v2) : v2 } end - + end \ No newline at end of file lib/app_config.rb @@ -4,48 +4,61 @@ require 'app_config' class AppConfigTest < Test::Unit::TestCase def test_missing_files - config = ApplicationConfig.load_files('not_here1', 'not_here2') - assert_equal OpenStruct.new, config + assert_raise(Errno::ENOENT){ ApplicationConfiguration.new('not_here1', 'not_here2') } end def test_empty_files - config = ApplicationConfig.load_files('test/empty1.yml', 'test/empty2.yml') - assert_equal OpenStruct.new, config + config = ApplicationConfiguration.new('test/empty1.yml', 'test/empty2.yml') + assert_equal OpenStruct.new, config.instance_variable_get("@config") end def test_common - config = ApplicationConfig.load_files('test/app_config.yml') + config = ApplicationConfiguration.new('test/app_config.yml') assert_equal 1, config.size assert_equal 'google.com', config.server end - def test_environment_override - config = ApplicationConfig.load_files('test/app_config.yml', 'test/development.yml') + def test_override + config = ApplicationConfiguration.new('test/app_config.yml', 'test/development.yml') assert_equal 2, config.size assert_equal 'google.com', config.server end def test_nested - config = ApplicationConfig.load_files('test/development.yml') + config = ApplicationConfiguration.new('test/development.yml') assert_equal 3, config.section.size end def test_array - config = ApplicationConfig.load_files('test/development.yml') + config = ApplicationConfiguration.new('test/development.yml') assert_equal 'yahoo.com', config.section.servers[0].name assert_equal 'amazon.com', config.section.servers[1].name end def test_erb - config = ApplicationConfig.load_files('test/development.yml') + config = ApplicationConfiguration.new('test/development.yml') assert_equal 6, config.computed end def test_recursive_merge - config = ApplicationConfig.load_files('test/app_config.yml', 'test/development.yml') + config = ApplicationConfiguration.new('test/app_config.yml', 'test/development.yml') assert_equal 'support@domain.com', config.emails.support assert_equal 'webmaster@domain.com', config.emails.webmaster assert_equal 'feedback@domain.com', config.emails.feedback end + def test_exception_on_non_existant_values + config = ApplicationConfiguration.new('test/app_config.yml') + assert_raise(NoMethodError){ config.not_here1 = "blah" } + assert_raise(NoMethodError){ config.not_here2 } + end + + def test_reload + config = ApplicationConfiguration.new('test/app_config.yml') + config.size = 2 + assert_equal 2, config.size + config.reload! + assert_equal 1, config.size + end + end test/app_config_test.rb README 00829378a24de65d394a189ea4b3fcd49209197f cjbottaro cjbottaro@alumni.cs.utexas.edu http://github.com/cjbottaro/app_config/commit/e49426822be0460052dee3cc8279b9f1303dc3c8 e49426822be0460052dee3cc8279b9f1303dc3c8

2009-07-01T15:42:31-07:00

Packaged as a gem, mini rewrite, see README.rdoc and CHANGELOG. dee5a7b5066e0e526763da8a1ef5a58b3131b6f8 cjbottaro cjbottaro@alumni.cs.utexas.edu