configatron 2.13.0 → 3.0.0.rc1

data/V2-README.md

@@ -0,0 +1,243 @@
+h1. Configatron
+
+Configatron makes configuring your applications and scripts incredibly easy. No longer is a there a need to use constants or global variables. Now you can use a simple and painless system to configure your life. And, because it's all Ruby, you can do any crazy thing you would like to!
+
+h2. Installation
+
+Installation of Configatron is easy, as it is just a RubyGem:
+
+<pre><code>
+  $ sudo gem install configatron
+</code></pre>
+
+If you'd like to live on the bleedin' edge you can install the development version from GitHub:
+
+<pre><code>
+  $ sudo gem install markbates-configatron --source=http://gems.github.com
+</code></pre>
+
+Once installed you just need to require it:
+
+<pre><code>
+  require 'configatron'
+</code></pre>
+
+h2. Examples
+
+h3. Simple
+
+<pre><code>
+  configatron.email = 'me@example.com'
+  configatron.database_url = "postgres://localhost/mack_framework_rocks"
+</code></pre>
+
+Now, anywhere in your code you can do the following:
+
+<pre><code>
+  configatron.email # => "me@example.com"
+  configatron.database_url # => "postgres://localhost/mack_framework_rocks"
+</code></pre>
+
+Viola! Simple as can be.
+
+Now you're saying, what if I want to have a 'default' set of options, but then override them later, based on other information? Simple again. Let's use our above example. We've configured our @database_url@ option to be @postgres://localhost/mack_framework_rocks@. The problem with that is that is our production database url, not our development url. Fair enough, all you have to do is redeclare it:
+
+<pre><code>
+  configatron.database_url = "postgres://localhost/mack_framework_rocks_development"
+</code></pre>
+
+becomes:
+
+<pre><code>
+  configatron.email # => "me@example.com"
+  configatron.database_url # => "postgres://localhost/mack_framework_rocks_development"
+</code></pre>
+
+Notice how our other configuration parameters haven't changed? Cool, eh?
+
+h3. Hash/YAML
+
+You can configure configatron from a hash as well (this is really only useful in testing or for data driven configuration, it's not recommended for actual configuration):
+
+<pre><code>
+  configatron.configure_from_hash({:email => {:pop => {:address => 'pop.example.com', :port => 110}}, :smtp => {:address => 'smtp.example.com'}})
+
+  configatron.email.pop.address # => 'pop.example.com'
+  configatron.email.pop.port # => 110
+  # and so on...
+</code></pre>
+
+h4. YAML
+
+Support for YAML has been deprecated and will be removed in version 2.9 of Configatron. Please switch to Ruby based configuration of Configatron. Trust me, it's a lot nicer and easier to use. Why would you _not_ want to?
+
+h3. Namespaces
+
+The question that should be on your lips is what I need to have namespaced configuration parameters. It's easy! Configatron allows you to create namespaces.
+
+<pre><code>
+  configatron.website_url = "http://www.mackframework.com"
+  configatron.email.pop.address = "pop.example.com"
+  configatron.email.pop.port = 110
+  configatron.email.smtp.address = "smtp.example.com"
+  configatron.email.smtp.port = 25
+</code></pre>
+
+becomes:
+
+<pre><code>
+  configatron.email.pop.address # => "pop.example.com"
+  configatron.email.smtp.address # => "smtp.example.com"
+  configatron.website_url # => "http://www.mackframework.com"
+</code></pre>
+
+Configatron allows you to nest namespaces to your hearts content! Just keep going, it's that easy.
+
+Of course you can update a single parameter n levels deep as well:
+
+<pre><code>
+  configatron.email.pop.address = "pop2.example.com"
+
+  configatron.email.pop.address # => "pop2.example.com"
+  configatron.email.smtp.address # => "smtp.example.com"
+</code></pre>
+
+h3. Temp Configurations
+
+Sometimes in testing, or other situations, you want to temporarily change some settings. You can do this with the @temp@ method:
+
+<pre><code>
+  configatron.one = 1
+  configatron.letters.a = 'A'
+  configatron.letters.b = 'B'
+  configatron.temp do
+    configatron.letters.b = 'bb'
+    configatron.letters.c = 'c'
+    configatron.one # => 1
+    configatron.letters.a # => 'A'
+    configatron.letters.b # => 'bb'
+    configatron.letters.c # => 'c'
+  end
+  configatron.one # => 1
+  configatron.letters.a # => 'A'
+  configatron.letters.b # => 'B'
+  configatron.letters.c # => nil
+</code></pre>
+
+You can also pass in an optional Hash to the @temp@:
+
+<pre><code>
+  configatron.one = 1
+  configatron.letters.a = 'A'
+  configatron.letters.b = 'B'
+  configatron.temp(:letters => {:b => 'bb', :c => 'c'}) do
+    configatron.one == 1
+    configatron.letters.a # => 'A'
+    configatron.letters.b # => 'bb'
+    configatron.letters.c # => 'c'
+  end
+  configatron.one == 1
+  configatron.letters.a # => 'A'
+  configatron.letters.b # => 'B'
+  configatron.letters.c # => nil
+</code></pre>
+
+h3. Delayed and Dynamic Configurations
+
+There are times when you want to refer to one configuration setting in another configuration setting. Let's look at a fairly contrived example:
+
+<pre><code>
+  configatron.memcached.servers = ['127.0.0.1:11211']
+  configatron.page_caching.servers = configatron.memcached.servers
+  configatron.object_caching.servers = configatron.memcached.servers
+
+  if Rails.env == 'production'
+    configatron.memcached.servers = ['192.168.0.1:11211']
+    configatron.page_caching.servers = configatron.memcached.servers
+    configatron.object_caching.servers = configatron.memcached.servers
+  elsif Rails.env == 'staging'
+    configatron.memcached.servers = ['192.168.0.2:11211']
+    configatron.page_caching.servers = configatron.memcached.servers
+    configatron.object_caching.servers = configatron.memcached.servers
+  end
+</code></pre>
+
+Now, we could've written that slightly differently, but it helps to illustrate the point. With Configatron you can create <code>Delayed</code> and <code>Dynamic</code> settings.
+
+h4. Delayed
+
+With <code>Delayed</code> settings execution of the setting doesn't happen until the first time it is executed.
+
+<pre><code>
+  configatron.memcached.servers = ['127.0.0.1:11211']
+  configatron.page_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}
+  configatron.object_caching.servers = Configatron::Delayed.new {configatron.memcached.servers}
+
+  if Rails.env == 'production'
+    configatron.memcached.servers = ['192.168.0.1:11211']
+  elsif Rails.env == 'staging'
+    configatron.memcached.servers = ['192.168.0.2:11211']
+  end
+</code></pre>
+
+Execution occurs once and after that the result of that execution is returned. So in our case the first time someone calls the setting <code>configatron.page_caching.servers</code> it will find the <code>configatron.memcached.servers</code> setting and return that. After that point if the <code>configatron.memcached.servers</code> setting is changed, the original settings are returned by <code>configatron.page_caching.servers</code>.
+
+h4. Dynamic
+
+<code>Dynamic</code> settings are very similar to <code>Delayed</code> settings, but with one big difference. Every time you call a <code>Dynamic</code> setting is executed. Take this example:
+
+<pre><code>
+  configatron.current.time = Configatron::Dynamic.new {Time.now}
+</code></pre>
+
+Each time you call <code>configatron.current.time</code> it will return a new value to you. While this seems a bit useless, it is pretty useful if you have ever changing configurations.
+
+h3. Misc.
+
+Even if parameters haven't been set, you can still call them, but you'll get a @Configatron::Store@ object back. The Configatron::Store class, however, will respond true to @.nil?@ if there are no parameters configured on it.
+
+<pre><code>
+  configatron.i.dont.exist.nil? # => true
+  configatron.i.dont.exist # => Configatron::Store
+</code></pre>
+
+If you want to get back an actual @nil@ then you can use the @retrieve@ method:
+
+<pre><code>
+  configatron.i.do.exist = [:some, :array]
+  configatron.i.dont.retrieve(:exist, nil) # => nil
+  configatron.i.do.retrieve(:exist, :foo) # => [:some, :array]
+</code></pre>
+
+You can set 'default' values for parameters. If there is already a setting, it won't be replaced. This is useful if you've already done your 'configuration' and you call a library, that needs to have parameters set. The library can set its defaults, without worrying that it might have overridden your custom settings.
+
+<pre><code>
+  configatron.set_default(:name, 'Mark Bates')
+  configatron.name # => 'Mark Bates'
+  configatron.set_default(:name, 'Me')
+  configatron.name # => 'Mark Bates'
+</code></pre>
+
+Enjoy!
+
+h2. Contributors
+
+* Mark Bates
+* Kurtis Rainbolt-Greene
+* Rob Sanheim
+* Cody Maggard
+* Jean-Denis Vauguet
+* Torsten Schönebaum
+* Mat Brown
+* Simon Menke
+* chatgris
+* Gleb Pomykalov
+* Casper Gripenberg
+* mattelacchiato
+* Artiom Diomin
+* Tim Riley
+* Rick Fletcher
+* joe miller
+* Brandon Dimcheff
+* Dan Pickett
+* Josh Nichols

data/configatron.gemspec

@@ -10,40 +10,13 @@ Gem::Specification.new do |gem|
   gem.email         = ["mark@markbates.com"]
   gem.description   = %q{A powerful Ruby configuration system.}
   gem.summary       = %q{A powerful Ruby configuration system.}
-  gem.homepage      = "http://www.metabates.com"
+  gem.homepage      = "https://github.com/markbates/configatron"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($/)
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency("yamler", ">= 0.1.0")
+  gem.add_development_dependency "rake"
 end
-
-
-
-# # -*- encoding: utf-8 -*-
-# require File.expand_path('../lib/configatron/version', __FILE__)
-
-# Gem::Specification.new do |s|
-#   s.name = "configatron"
-#   s.version = Configatron::VERSION
-
-#   s.authors = ["markbates"]
-#   s.description = "configatron was developed by: markbates"
-#   s.email = "mark@markbates.com"
-#   s.extra_rdoc_files = ["LICENSE"]
-
-#   ignored_files = File.read('.gitignore').split("\n").compact.reject(&:empty?) + ["Rakefile", "Gemfile", "configatron.gemspec"]
-#   test_files = Dir['spec/**/*'].reject {|f| File.directory?(f)}
-#   library_files = Dir['**/*'].reject{|f| File.directory?(f)}
-#   s.files = library_files - test_files - ignored_files
-#   s.homepage = "http://www.metabates.com"
-#   s.require_paths = ["lib"]
-#   s.summary = "A powerful Ruby configuration system."
-
-#   s.add_runtime_dependency "yamler", ">= 0.1.0"
-#   s.add_development_dependency 'rake'
-#   s.add_development_dependency 'rspec'
-#   s.add_development_dependency 'gemstub'
-# end

data/lib/configatron/core.rb

@@ -1,94 +1,3 @@
-require 'fileutils'
-require 'singleton'
-require 'logger'
-require 'yamler'
-
-base = File.dirname(__FILE__)
-
-require File.join(base, 'store')
-require File.join(base, 'errors')
-require File.join(base, 'rails')
-require File.join(base, 'proc')
-
-class Configatron
-  include Singleton
-
-  alias_method :send!, :send
-
-  class << self
-
-    attr_accessor :strict, :disable_monkey_patching
-
-    def log
-      unless @logger
-        if defined?(::Rails)
-          @logger = ::Rails.logger
-        end
-        @logger = ::Logger.new(STDOUT) if @logger.nil?
-      end
-      return @logger
-    end
-
-    def reset!
-      @strict = false
-    end
-  end
-
-  def initialize # :nodoc:
-    @_namespace = [:default]
-    reset!
-  end
-
-  # Forwards the method call onto the 'namespaced' Configatron::Store
-  def method_missing(sym, *args, &block)
-    @_store[@_namespace.last].send(sym, *args, &block)
-  end
-
-  # respond_to to respond_to
-  def respond_to?(method)
-    !@_store[@_namespace.last].send(method).nil? || super
-  end
-
-  # Removes ALL configuration parameters
-  def reset!
-    self.class.reset!
-    @_store = {:default => Configatron::Store.new}
-  end
-
-  # Allows for the temporary overriding of parameters in a block.
-  # Takes an optional Hash of parameters that will be applied before
-  # the block gets called. At the end of the block, the temporary
-  # settings are deleted and the original settings are reinstated.
-  def temp(options = nil)
-    begin
-      temp_start(options)
-      yield @_store[@_namespace.last]
-    rescue Exception => e
-      raise e
-    ensure
-      temp_end
-    end
-  end
-
-  def temp_start(options = nil)
-    n_space = rand
-    @_store[n_space] = @_store[@_namespace.last].deep_clone
-    @_namespace << n_space
-    if options
-      self.method_missing(:configure_from_hash, options)
-    end
-  end
-
-  def temp_end
-    @_store.delete(@_namespace.pop)
-  end
-
-  begin
-    undef :inspect # :nodoc:
-    undef :nil? # :nodoc:
-    undef :test # :nodoc:
-  rescue Exception => e
-  end
-
-
-end
+require_relative "deep_clone"
+require_relative "store"
+require_relative "errors"

data/lib/configatron/deep_clone.rb

@@ -0,0 +1,69 @@
+module DeepClone
+  # = DeepClone
+  #
+  # == Version
+  #  1.2006.05.23 (change of the first number means Big Change)
+  #
+  # == Description
+  #  Adds deep_clone method to an object which produces deep copy of it. It means
+  #  if you clone a Hash, every nested items and their nested items will be cloned.
+  #  Moreover deep_clone checks if the object is already cloned to prevent endless recursion.
+  #
+  # == Usage
+  #
+  #  (see examples directory under the ruby gems root directory)
+  #
+  #   require 'rubygems'
+  #   require 'deep_clone'
+  #
+  #   include DeepClone
+  #
+  #   obj = []
+  #   a = [ true, false, obj ]
+  #   b = a.deep_clone
+  #   obj.push( 'foo' )
+  #   p obj   # >> [ 'foo' ]
+  #   p b[2]  # >> []
+  #
+  # == Source
+  # http://simplypowerful.1984.cz/goodlibs/1.2006.05.23
+  #
+  # == Author
+  #  jan molic (/mig/at_sign/1984/dot/cz/)
+  #
+  # == Licence
+  #  You can redistribute it and/or modify it under the same terms of Ruby's license;
+  #  either the dual license version in 2003, or any later version.
+  #
+  def deep_clone( obj=self, cloned={} )
+    if cloned.has_key?( obj.object_id )
+      return cloned[obj.object_id]
+    else
+      begin
+        cl = obj.clone
+      rescue Exception
+        # unclonnable (TrueClass, Fixnum, ...)
+        cloned[obj.object_id] = obj
+        return obj
+      else
+        cloned[obj.object_id] = cl
+        cloned[cl.object_id] = cl
+        if cl.is_a?( Hash )
+          cl.clone.each { |k,v|
+            cl[k] = deep_clone( v, cloned )
+          }
+        elsif cl.is_a?( Array )
+          cl.collect! { |v|
+            deep_clone( v, cloned )
+          }
+        end
+        cl.instance_variables.each do |var|
+          v = cl.instance_eval( var.to_s )
+          v_cl = deep_clone( v, cloned )
+          cl.instance_eval( "#{var} = v_cl" )
+        end
+        return cl
+      end
+    end
+  end
+end

data/lib/configatron/errors.rb

@@ -1,13 +1,9 @@
 class Configatron
-  class ProtectedParameter < StandardError
-    def intialize(name)
-      super("Can not modify protected parameter: '#{name}'")
+  class UndefinedKeyError < StandardError
+    def initialize(msg)
+      super(msg)
     end
   end
-
-  class LockedNamespace < StandardError
-    def initialize(name)
-      super("Cannot add new parameters to locked namespace: #{name.inspect}")
-    end
+  class LockedError < StandardError
   end
-end
+end

data/lib/configatron/rails.rb

@@ -1,14 +1,14 @@
 class Configatron
   # Helpful for making using configatron with Rails even easier!
-  # 
+  #
   # To get started you can use the generator to generate
   # the necessary stub files.
-  # 
-  #   $ ruby script/generate configatron
+  #
+  #   $ rails g configatron:install
   module Rails
-    
+
     # Loads configatron files in the following order:
-    # 
+    #
     # Example:
     #   <Rails.root>/config/configatron/defaults.rb
     #   <Rails.root>/config/configatron/<Rails.env>.rb
@@ -22,11 +22,11 @@ class Configatron
         root = defined?(Rails) ? ::Rails.root : FileUtils.pwd
         base_dir = File.expand_path(File.join(root, 'config', 'configatron'))
       end
-      
+
       if env.nil?
         env = defined?(Rails) ? ::Rails.env : 'development'
       end
-      
+
       config_files = []
 
       config_files << File.join(base_dir, 'defaults.rb')
@@ -48,6 +48,6 @@ class Configatron
         end
       end
     end
-    
+
   end # Rails
 end # Configatron