markbates-configatron 2.3.2.20090731133933

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Mark Bates
+
+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

@@ -0,0 +1,143 @@
+=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!
+
+==Installation
+
+Installation of Configatron is easy, as it is just a RubyGem:
+
+  $ sudo gem install configatron
+
+If you'd like to live on the bleedin' edge you can install the development version from GitHub:
+
+  $ sudo gem install markbates-configatron --source=http://gems.github.com
+
+Once installed you just need to require it:
+
+  require 'configatron'
+
+==Examples
+
+===Simple
+
+  configatron.email = 'me@example.com'
+  configatron.database_url = "postgres://localhost/mack_framework_rocks"
+
+Now, anywhere in your code you can do the following:
+
+  configatron.email # => "me@example.com"
+  configatron.database_url # => "postgres://localhost/mack_framework_rocks"
+
+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 <tt>database_url</tt> option to be <tt>postgres://localhost/mack_framework_rocks</tt>. 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:
+
+  configatron.database_url = "postgres://localhost/mack_framework_rocks_development"
+
+becomes:
+
+  configatron.email # => "me@example.com"
+  configatron.database_url # => "postgres://localhost/mack_framework_rocks_development"
+
+Notice how our other configuration parameters haven't changed? Cool, eh?
+
+===Hash/YAML
+
+You can configure configatron from a hash as well:
+
+  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...
+
+Notice how they're all namespaced for your as well. The same holds true for YAML files:
+
+  configuration.configure_from_yaml('/path/to/file.yml')
+
+===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.
+
+  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
+
+becomes:
+
+  configatron.email.pop.address # => "pop.example.com"
+  configatron.email.smtp.address # => "smtp.example.com"
+  configatron.website_url # => "http://www.mackframework.com"
+
+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:
+
+  configatron.email.pop.address = "pop2.example.com"
+  
+  configatron.email.pop.address # => "pop2.example.com"
+  configatron.email.smtp.address # => "smtp.example.com"
+
+===Misc.
+
+Even if parameters haven't been set, you can still call them, but you'll get a <tt>Configatron::Store</tt> object back. The Configatron::Store class, however, will respond true to <tt>.nil?</tt> if there are no parameters configured on it.
+
+  configatron.i.dont.exist.nil? # => true
+  configatron.i.dont.exist # => Configatron::Store
+
+If you want to get back an actual <tt>nil</tt> then you can use the <tt>retrieve</tt> method:
+
+  configatron.i.do.exist = [:some, :array]
+  configatron.i.dont.retrieve(:exist, nil) # => nil
+  configatron.i.do.retrieve(:exist, :foo) # => [:some, :array]
+
+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.
+
+  configatron.set_default(:name, 'Mark Bates')
+  configatron.name # => 'Mark Bates'
+  configatron.set_default(:name, 'Me')
+  configatron.name # => 'Mark Bates'
+
+Sometimes in testing, or other situations, you want to temporarily change some settings. You can do this with the <tt>temp</tt> method:
+
+  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
+
+You can also pass in an optional Hash to the <tt>temp</tt>:
+
+  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
+
+Enjoy!
+
+==Contact
+
+Please mail bugs, suggestions and patches to "development@metabates.com":mailto:development@metabates.com
+
+On the web at: "http://www.metabates.com":http://www.metabates.com

data/lib/configatron.rb

@@ -0,0 +1,9 @@
+base = File.join(File.dirname(__FILE__), 'configatron')
+require 'yamler'
+require File.join(base, 'configatron')
+require File.join(base, 'store')
+require File.join(base, 'errors')
+require File.join(base, 'core_ext', 'kernel')
+require File.join(base, 'core_ext', 'object')
+require File.join(base, 'core_ext', 'string')
+require File.join(base, 'core_ext', 'class')

data/lib/configatron/configatron.rb

@@ -0,0 +1,55 @@
+require 'singleton'
+
+class Configatron
+  include Singleton
+  
+  alias_method :send!, :send
+  
+  def initialize # :nodoc:
+    @_namespace = [:default]
+    reset!
+  end
+  
+  # Forwards the method call onto the 'namespaced' Configatron::Store
+  def method_missing(sym, *args)
+    @_store[@_namespace.last].send(sym, *args)
+  end
+  
+  # Removes ALL configuration parameters
+  def 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
+    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
+  
+  undef :inspect # :nodoc:
+  undef :nil? # :nodoc:
+  undef :test # :nodoc:
+  
+end

data/lib/configatron/core_ext/class.rb

@@ -0,0 +1,25 @@
+class Class
+  
+  # Returns access to configuration parameters named after the class.
+  # 
+  # Examples:
+  #   configatron.foo.bar = :bar
+  #   configatron.a.b.c.d = 'D'
+  #   
+  #   class Foo
+  #   end
+  #   
+  #   module A
+  #     module B
+  #       class C
+  #       end
+  #     end
+  #   end
+  # 
+  #   Foo.to_configatron.bar # => :bar
+  #   A::B::C.to_configatron.d # => 'D'
+  def to_configatron(*args)
+    self.name.to_configatron(*args)
+  end
+  
+end

data/lib/configatron/core_ext/kernel.rb

@@ -0,0 +1,8 @@
+module Kernel
+  
+  # Provides access to the Configatron storage system.
+  def configatron
+    Configatron.instance
+  end
+  
+end

data/lib/configatron/core_ext/object.rb

@@ -0,0 +1,9 @@
+class Object # :nodoc:
+  
+  def send_with_chain(methods, *args) # :nodoc:
+    obj = self
+    [methods].flatten.each {|m| obj = obj.send(m, *args)}
+    obj
+  end
+  
+end

data/lib/configatron/core_ext/string.rb

@@ -0,0 +1,90 @@
+class String # :nodoc:
+  
+  def to_configatron(*args)
+    name_spaces = (args + self.split("::")).flatten
+    name_spaces.collect!{|s| s.to_s.methodize}
+    configatron.send_with_chain(name_spaces)
+  end
+  
+  def underscore # :nodoc:
+    self.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+  
+  def methodize # :nodoc:
+    x = self
+    
+    # if we get down to a nil or an empty string raise an exception! 
+    raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    
+    # get rid of the big stuff in the front/back
+    x.strip!
+    
+    # if we get down to a nil or an empty string raise an exception! 
+    raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    
+    x = x.underscore
+    
+    # get rid of spaces and make the _
+    x.gsub!(' ', '_')
+    # get rid of everything that isn't 'safe' a-z, 0-9, ?, !, =, _
+    x.gsub!(/([^ a-zA-Z0-9\_\?\!\=]+)/n, '_')
+    
+    # if we get down to a nil or an empty string raise an exception! 
+    raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    
+    # condense multiple 'safe' non a-z chars to just one.
+    # ie. ___ becomes _ !!!! becomes ! etc...
+    [' ', '_', '?', '!', "="].each do |c|
+      x.squeeze!(c)
+    end
+    
+    # if we get down to a nil or an empty string raise an exception! 
+    raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    
+    #down case the whole thing
+    x.downcase!
+    
+    # get rid of any characters at the beginning that aren't a-z
+    while !x.match(/^[a-z]/)
+      x.slice!(0)
+      
+      # if we get down to a nil or an empty string raise an exception! 
+      raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    end
+    
+    # let's trim this bad boy down a bit now that we've cleaned it up, somewhat.
+    # we should do this before cleaning up the end character, because it's possible to end up with a 
+    # bad char at the end if you trim too late.
+    x = x[0..100] if x.length > 100
+    
+    # get rid of any characters at the end that aren't safe
+    while !x.match(/[a-z0-9\?\!\=]$/)
+      x.slice!(x.length - 1)
+      # if we get down to a nil or an empty string raise an exception! 
+      raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    end
+    
+    # if we get down to a nil or an empty string raise an exception! 
+    raise NameError.new("#{self} cannot be converted to a valid method name!") if x.nil? || x == ''
+    
+    # let's get rid of characters that don't belong in the 'middle' of the method.
+    orig_middle = x[1..(x.length - 2)]
+    n_middle = orig_middle.dup
+    
+    ['?', '!', "="].each do |c|
+      n_middle.gsub!(c, "_")
+    end
+    
+    # the previous gsub can leave us with multiple underscores that need cleaning up.
+    n_middle.squeeze!("_")
+    
+    x.gsub!(orig_middle, n_middle)
+    x.gsub!("_=", "=")
+    x
+  end
+  
+end

data/lib/configatron/errors.rb

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

data/lib/configatron/store.rb

@@ -0,0 +1,283 @@
+class Configatron
+  class Store
+    alias_method :send!, :send
+    
+    # Takes an optional Hash of parameters
+    def initialize(options = {}, name = nil, parent = nil)
+      @_name = name
+      @_parent = parent
+      @_store = {}
+      configure_from_hash(options)
+      @_protected = []
+    end
+    
+    # Returns a Hash representing the configurations
+    def to_hash
+      @_store
+    end
+    
+    def heirarchy
+      path = [@_name]
+      parent = @_parent
+      until parent.nil?
+        path << parent.instance_variable_get('@_name')
+        parent = parent.instance_variable_get('@_parent')
+      end
+      path.compact!
+      path.reverse!
+      path.join('.')
+    end
+    
+    def configatron_keys
+      return @_store.keys.collect{|k| k.to_s}.sort
+    end
+    
+    # Checks whether or not a parameter exists
+    # 
+    # Examples:
+    #   configatron.i.am.alive = 'alive!'
+    #   configatron.i.am.exists?(:alive) # => true
+    #   configatron.i.am.exists?(:dead) # => false
+    def exists?(name)
+      @_store.has_key?(name.to_sym) || @_store.has_key?(name.to_s)
+    end
+    
+    def inspect
+      path = [@_name]
+      parent = @_parent
+      until parent.nil?
+        path << parent.instance_variable_get('@_name')
+        parent = parent.instance_variable_get('@_parent')
+      end
+      path << 'configatron'
+      path.compact!
+      path.reverse!
+      f_out = []
+      @_store.each do |k, v|
+        if v.is_a?(Configatron::Store)
+          v.inspect.each_line do |line|
+            if line.match(/\n/)
+              line.each_line do |l|
+                l.strip!
+                f_out << l
+              end
+            else
+              line.strip!
+              f_out << line
+            end
+          end
+        else
+          f_out << "#{path.join('.')}.#{k} = #{v.inspect}"
+        end
+      end
+      f_out.compact.sort.join("\n")
+    end
+
+    # Allows for the configuration of the system via a Hash
+    def configure_from_hash(options)
+      parse_options(options)
+    end
+
+    # Allows for the configuration of the system from a YAML file.
+    # Takes the path to the YAML file.  Also takes an optional parameter,
+    # <tt>:hash</tt>, that indicates a specific hash that should be
+    # loaded from the file. 
+    def configure_from_yaml(path, opts = {})
+      begin
+        yml = ::Yamler.load(path)
+        yml = yml[opts[:hash]] unless opts[:hash].nil?
+        configure_from_hash(yml)
+      rescue Errno::ENOENT => e
+        puts e.message
+      end
+    end
+
+    # Returns true if there are no configuration parameters
+    def nil?
+      return @_store.empty?
+    end
+
+    # Retrieves a certain parameter and if that parameter
+    # doesn't exist it will return the default_value specified.
+    def retrieve(name, default_value = nil)
+      @_store[name.to_sym] || default_value
+    end
+    
+    # Removes a parameter. In the case of a nested parameter
+    # it will remove all below it.
+    def remove(name)
+      @_store.delete(name.to_sym)
+    end
+
+    # Sets a 'default' value. If there is already a value specified
+    # it won't set the value.
+    def set_default(name, default_value)
+      unless @_store[name.to_sym]
+        @_store[name.to_sym] = parse_options(default_value)
+      end
+    end
+    
+    def method_missing(sym, *args) # :nodoc:
+      if sym.to_s.match(/(.+)=$/)
+        name = sym.to_s.gsub("=", '').to_sym
+        raise Configatron::ProtectedParameter.new(name) if @_protected.include?(name) || methods_include?(name)
+        raise Configatron::LockedNamespace.new(@_name) if @_locked && !@_store.has_key?(name)
+        @_store[name] = parse_options(*args)
+      elsif @_store.has_key?(sym)
+        return @_store[sym]
+      else
+        store = Configatron::Store.new({}, sym, self)
+        @_store[sym] = store
+        return store
+      end
+    end
+    
+    def ==(other) # :nodoc:
+      self.to_hash == other
+    end
+    
+    # Prevents a parameter from being reassigned. If called on a 'namespace' then
+    # all parameters below it will be protected as well.
+    def protect(name)
+      @_protected << name.to_sym
+    end
+
+    # Prevents all parameters from being reassigned.
+    def protect_all!
+      @_protected.clear
+      @_store.keys.each do |k|
+        val = self.send(k)
+        val.protect_all! if val.class == Configatron::Store
+        @_protected << k
+      end
+    end
+    
+    # Removes the protection of a parameter.
+    def unprotect(name)
+      @_protected.reject! { |e| e == name.to_sym }
+    end
+    
+    def unprotect_all!
+      @_protected.clear
+      @_store.keys.each do |k|
+        val = self.send(k)
+        val.unprotect_all! if val.class == Configatron::Store
+      end
+    end
+
+    # Prevents a namespace from having new parameters set. The lock is applied
+    # recursively to any namespaces below it.
+    def lock(name)
+      namespace = @_store[name.to_sym]
+      raise ArgumentError, "Namespace #{name.inspect} does not exist" if namespace.nil?
+      namespace.lock!
+    end
+
+    def unlock(name)
+      namespace = @_store[name.to_sym]
+      raise ArgumentError, "Namespace #{name.inspect} does not exist" if namespace.nil?
+      namespace.unlock!
+    end
+    
+    # = 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
+    
+    protected
+    def lock!
+      @_locked = true
+      @_store.values.each { |store| store.lock! if store.is_a?(Configatron::Store) }
+    end
+
+    def unlock!
+      @_locked = false
+      @_store.values.each { |store| store.unlock! if store.is_a?(Configatron::Store) }
+    end
+    
+    private
+    def methods_include?(name)
+      self.methods.include?(RUBY_VERSION > '1.9.0' ? name.to_sym : name.to_s)
+    end
+    
+    def parse_options(options)
+      if options.is_a?(Hash)
+        options.each do |k,v|
+          if v.is_a?(Hash)
+            self.method_missing(k.to_sym).configure_from_hash(v)
+          else
+            self.method_missing("#{k.to_sym}=", v)
+          end
+        end
+      else
+        return options
+      end
+    end
+    
+    undef :test # :nodoc:
+    
+  end # Store
+end # Configatron

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: markbates-configatron
+version: !ruby/object:Gem::Version 
+  version: 2.3.2.20090731133933
+platform: ruby
+authors: 
+- markbates
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-31 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yamler
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
+    version: 
+description: "configatron was developed by: markbates"
+email: mark@markbates.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/configatron/configatron.rb
+- lib/configatron/core_ext/class.rb
+- lib/configatron/core_ext/kernel.rb
+- lib/configatron/core_ext/object.rb
+- lib/configatron/core_ext/string.rb
+- lib/configatron/errors.rb
+- lib/configatron/store.rb
+- lib/configatron.rb
+- README
+- LICENSE
+has_rdoc: false
+homepage: http://www.metabates.com
+licenses: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: magrathea
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A powerful Ruby configuration system.
+test_files: []
+