adhearsion-loquacious 1.9.2

data/lib/loquacious/undefined.rb

@@ -0,0 +1,92 @@
+
+module Loquacious
+
+  # Represents an undefined configuration value. An undefined value is
+  # assigned to each configuration propery by default. Any method can be
+  # invoked on an undefined value, and a warning message will be printed to
+  # the IO stream (defaulting to $stderr).
+  #
+  # The purpose of this class is to provide the user with a helpful message
+  # that the configuration values they are trying to use have not been setup
+  # correctly.
+  #
+  class Undefined
+
+    instance_methods(true).each do |m|
+      next if m[::Loquacious::KEEPERS]
+      undef_method m
+    end
+    private_instance_methods(true).each do |m|
+      next if m[::Loquacious::KEEPERS]
+      undef_method m
+    end
+    Kernel.methods.each do |m|
+      next if m[::Loquacious::KEEPERS]
+      module_eval <<-CODE
+        def #{m}( *args, &block )
+          self.method_missing('#{m}', *args, &block)
+        end
+      CODE
+    end
+    undef_method :method_missing rescue nil
+
+    @io = $stderr
+    @first_time = true
+
+    class << self
+      attr_accessor :io
+
+      # Write a warning message to the Undefined class IO stream. By default,
+      # this IO stream is set to the Ruby $stderr output.
+      #
+      def warn( key )
+        if @first_time
+          @io.puts <<-__
+---------------------------------------------------------------------------
+The Loquacious configuration system has detected that one or moe
+settings have an undefined value. An attempt is being made to reference
+sub-properties of these undefined settings. Messages will follow containing
+information about the undefined properties.
+---------------------------------------------------------------------------
+          __
+          @first_time = false
+        end
+
+        @io.puts "Access to undefined value #{key.first.inspect}: #{key.join('.')}"
+      end
+    end
+
+    # Creates a new undefined value returned from the lookup _key_ in some
+    # configuration object. The _key_ is used to alert the user where the
+    # undefined value came from.
+    #
+    def initialize( key )
+      @key = Kernel.Array(key)
+    end
+
+    # An undefined value acts like a +nil+ in that it has no value of its own.
+    # This method always returns +true+.
+    #
+    def nil?() true; end
+
+    # We can respond to any method except :call. The call method is reserved
+    # for Procs and lambdas, and it is used internally by loquacious for lazy
+    # evaluation of configuration parameters.
+    #
+    def respond_to_missing?( id, priv = false ) id != :call; end
+
+    # For every method invoked on an undefined object, generate a warning
+    # message describing the undefined value and the method that was called.
+    #
+    # Returns a new undefined object with the most recent method included in
+    # the key name.
+    #
+    def method_missing( method, *args, &block )
+      key = @key.dup << method.to_s
+      Undefined.warn key
+      return Undefined.new(key)
+    end
+
+  end  # class Undefined
+end  # module Loquacious
+

data/lib/loquacious/utility.rb

@@ -0,0 +1,14 @@
+module Loquacious
+  class Utility
+    class << self
+      # Returns the variable name to use for a value to be picked from ENV
+      #
+      def env_var_name(name, config)
+        parent_list = config.parent_list
+        parent_part = parent_list.empty? ? nil : parent_list.join("_")
+        key_name = name.to_s.split(".").last
+        [::Loquacious.env_prefix, parent_part, config.__name, key_name].compact.join("_").upcase
+      end
+    end
+  end
+end

data/loquacious.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "loquacious"
+  s.version = "1.9.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Pease"]
+  s.date = "2012-01-16"
+  s.description = "Descriptive configuration files for Ruby written in Ruby.\n\nLoquacious provides a very open configuration system written in ruby and\ndescriptions for each configuration attribute. The attributes and descriptions\ncan be iterated over allowing for helpful information about those attributes to\nbe displayed to the user.\n\nIn the simple case we have a file something like\n\n  Loquacious.configuration_for('app') {\n    name 'value', :desc => \"Defines the name\"\n    foo  'bar',   :desc => \"FooBar\"\n    id   42,      :desc => \"Ara T. Howard\"\n  }\n\nWhich can be loaded via the standard Ruby loading mechanisms\n\n  Kernel.load 'config/app.rb'\n\nThe attributes and their descriptions can be printed by using a Help object\n\n  help = Loquacious.help_for('app')\n  help.show :values => true        # show the values for the attributes, too\n\nDescriptions are optional, and configurations can be nested arbitrarily deep.\n\n  Loquacious.configuration_for('nested') {\n    desc \"The outermost level\"\n    a {\n      desc \"One more level in\"\n      b {\n        desc \"Finally, a real value\"\n        c 'value'\n      }\n    }\n  }\n\n  config = Loquacious.configuration_for('nested')\n\n  p config.a.b.c  #=> \"value\"\n\nAnd as you can see, descriptions can either be given inline after the value or\nthey can appear above the attribute and value on their own line."
+  s.email = "tim.pease@gmail.com"
+  s.extra_rdoc_files = ["History.txt", "README.rdoc", "lib/.loquacious.rb.swp", "lib/loquacious/.configuration.rb.swp"]
+  s.files = [".Rakefile.swp", ".gitignore", "History.txt", "README.rdoc", "Rakefile", "examples/gutters.rb", "examples/nested.rb", "examples/simple.rb", "lib/.loquacious.rb.swp", "lib/loquacious.rb", "lib/loquacious/.configuration.rb.swp", "lib/loquacious/configuration.rb", "lib/loquacious/configuration/help.rb", "lib/loquacious/configuration/iterator.rb", "lib/loquacious/core_ext/string.rb", "lib/loquacious/undefined.rb", "spec/configuration_spec.rb", "spec/help_spec.rb", "spec/iterator_spec.rb", "spec/loquacious_spec.rb", "spec/spec_helper.rb", "spec/string_spec.rb", "version.txt"]
+  s.homepage = "http://rubygems.org/gems/loquacious"
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "loquacious"
+  s.rubygems_version = "1.8.10"
+  s.summary = "Descriptive configuration files for Ruby written in Ruby."
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.6"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.6"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.6"])
+  end
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,513 @@
+
+require File.expand_path('spec_helper', File.dirname(__FILE__))
+
+describe Loquacious::Configuration do
+  before(:each) do
+    @obj = Loquacious::Configuration.new
+  end
+
+  it 'should initialize from a block' do
+    obj = Loquacious::Configuration.new  {
+            first    'foo'
+            second   'bar'
+          }
+    obj.first.eql?('foo').should be_true
+    obj.second.eql?('bar').should be_true
+    obj.third.kind_of?(Loquacious::Undefined).should be_true
+  end
+
+  it 'should respond to any method' do
+    @obj.first.kind_of?(Loquacious::Undefined).should be_true
+    @obj.first = 'foo'
+    @obj.first.eql?('foo').should be_true
+
+    @obj.second = 'bar'
+    @obj.second.eql?('bar').should be_true
+  end
+
+  it 'should deine attribute accessors when first used' do
+    @obj.respond_to?(:foo).should be_false
+    @obj.respond_to?(:foo=).should be_false
+
+    @obj.foo
+    @obj.respond_to?(:foo).should be_true
+    @obj.respond_to?(:foo=).should be_true
+  end
+
+  it 'should provide a hash object for storing method descriptions' do
+    h = @obj.__desc
+    @obj.__desc.should equal(h)
+  end
+
+  it 'should allow attributes to be assigned hash values' do
+    cfg = Loquacious::Configuration.new {
+            hash({:one => 1})
+          }
+    cfg.hash.eql?({:one => 1}).should be_true
+  end
+
+  it 'should provide hash accessor notation for attributes' do
+    cfg = Loquacious::Configuration.new {
+            one   1
+            two   2
+            three 3
+          }
+
+    cfg['one'].eql?(1).should be_true
+    cfg[:two].eql?(2).should be_true
+    cfg['three'].eql?(3).should be_true
+
+    cfg[:four].kind_of?(Loquacious::Undefined).should be_true
+    cfg.four = 4
+    cfg[:four].eql?(4).should be_true
+
+    cfg[:five] = 5
+    cfg.five.eql?(5).should be_true
+    cfg[:five].eql?(5).should be_true
+  end
+
+  it 'should allow Kernel methods to be treated as configuration attributes' do
+    cfg = Loquacious::Configuration.new {
+            fork   'spoon knife spork'
+            split  'join'
+            raise  'double down'
+            puts   'not what you think'
+          }
+
+    cfg['fork'].eql?('spoon knife spork').should be_true
+    cfg['split'].eql?('join').should be_true
+    cfg['raise'].eql?('double down').should be_true
+    cfg['puts'].eql?('not what you think').should be_true
+
+    cfg[:fork].eql?('spoon knife spork').should be_true
+    cfg[:split].eql?('join').should be_true
+    cfg[:raise].eql?('double down').should be_true
+    cfg[:puts].eql?('not what you think').should be_true
+
+    cfg.fork.eql?('spoon knife spork').should be_true
+    cfg.split.eql?('join').should be_true
+    cfg.raise.eql?('double down').should be_true
+    cfg.puts.eql?('not what you think').should be_true
+  end
+
+  it 'should not be affected by loading other modules like timeout' do
+    require 'timeout'
+    Loquacious.remove :timeout
+    cfg = Loquacious::Configuration.new {
+            timeout  10
+            foo      'bar'
+            baz      'buz'
+          }
+    cfg.timeout.eql?(10).should be_true
+    cfg.foo.eql?('bar').should be_true
+    cfg.baz.eql?('buz').should be_true
+  end
+
+  it 'should evaluate Proc objects when fetching values' do
+    obj = Loquacious::Configuration.new  {
+            first    'foo'
+            second   'bar'
+          }
+
+    obj.third = Proc.new { obj.first + obj.second }
+    obj.third.eql?('foobar').should be_true
+
+    obj.second = 'baz'
+    obj.third.eql?('foobaz').should be_true
+
+    obj.first = 'Hello '
+    obj.second = 'World!'
+    obj.third.eql?('Hello World!').should be_true
+  end
+
+  it 'should return a value when evaluating inside the DSL' do
+    obj = Loquacious::Configuration.new  {
+            first   'foo'
+            second  {
+              bar    nil
+            }
+          }
+
+    obj.first.eql?('foo').should be_true
+    obj.second.bar.eql?(nil).should be_true
+
+    Loquacious::Configuration::DSL.evaluate(:config => obj) {
+      first 'bar'
+      second.bar 'no longer nil'
+    }
+
+    obj.first.eql?('bar').should be_true
+    obj.second.bar.eql?('no longer nil').should be_true
+  end
+
+  it 'should not delete descriptions' do
+    obj = Loquacious::Configuration.new  {
+            first 'foo', :desc => 'the first value'
+
+            desc 'the second value'
+            second  {
+              bar nil, :desc => 'time to go drinking'
+            }
+          }
+
+    obj.first.eql?('foo').should be_true
+    obj.second.bar.eql?(nil).should be_true
+
+    obj.__desc[:first].should be == 'the first value'
+    obj.__desc[:second].should be == 'the second value'
+    obj.second.__desc[:bar].should be == 'time to go drinking'
+
+    Loquacious::Configuration::DSL.evaluate(:config => obj) {
+      first 'bar'
+      second.bar 'no longer nil'
+    }
+
+    obj.first.eql?('bar').should be_true
+    obj.second.bar.eql?('no longer nil').should be_true
+
+    obj.__desc[:first].should be == 'the first value'
+    obj.__desc[:second].should be == 'the second value'
+    obj.second.__desc[:bar].should be == 'time to go drinking'
+  end
+
+  # -----------------------------------------------------------------------
+  describe 'when merging' do
+    before :each do
+      Loquacious::Configuration.instance_variable_get(:@table).clear
+    end
+
+    it 'should merge the contents of another Configuration' do
+      other = Loquacious::Configuration.new  {
+                first   'foo', :desc => 'foo method'
+                second  'bar', :desc => 'bar method'
+              }
+
+      @obj.first.kind_of?(Loquacious::Undefined).should be_true
+      @obj.second.kind_of?(Loquacious::Undefined).should be_true
+      @obj.__desc.should be == {:first => nil, :second => nil}
+
+      @obj.merge! other
+      @obj.first.eql?('foo').should be_true
+      @obj.second.eql?('bar').should be_true
+      @obj.__desc.should be == {
+        :first => 'foo method',
+        :second => 'bar method'
+      }
+    end
+
+    it 'should recursively merge nested Configuration' do
+      other = Loquacious::Configuration.new  {
+        first   'foo', :desc => 'foo method'
+        second  'bar', :desc => 'bar method'
+
+        desc 'the third group'
+        third {
+          answer 42, :desc => 'life the universe and everything'
+        }
+      }
+
+      @obj = Loquacious::Configuration.new  {
+        third {
+          question '?', :desc => 'perhaps you do not understand'
+        }
+      }
+
+      @obj.merge! other
+
+      @obj.first.eql?('foo').should be_true
+      @obj.second.eql?('bar').should be_true
+      @obj.third.question.eql?('?').should be_true
+      @obj.third.answer.eql?(42).should be_true
+
+      @obj.__desc.should be == {
+        :first => 'foo method',
+        :second => 'bar method',
+        :third => 'the third group'
+      }
+      @obj.third.__desc.should be == {
+        :question => 'perhaps you do not understand',
+        :answer => 'life the universe and everything'
+      }
+    end
+
+    it 'should raise an error when merging with an unknown object' do
+      lambda {@obj.merge! 'foo'}.
+          should raise_error(Loquacious::Configuration::Error, "can only merge another Configuration")
+    end
+  end
+
+  # -----------------------------------------------------------------------
+  describe 'when working with descriptions' do
+
+    it 'should consume leading whitespace' do
+      other = Loquacious::Configuration.new  {
+        desc <<-STR
+          This is the first thing we are defining in this config.
+          It has a multiline comment.
+        STR
+        first   'foo'
+        second  'bar', :desc => "bar method\n  also a multiline comment"
+      }
+
+      other.__desc[:first].should be == "This is the first thing we are defining in this config.\nIt has a multiline comment."
+      other.__desc[:second].should be == "bar method\nalso a multiline comment"
+    end
+
+    it 'should leave whitespace after a gutter marker' do
+      other = Loquacious::Configuration.new  {
+        desc <<-STR
+        |  This is the first thing we are defining in this config.
+        |  It has a multiline comment.
+        STR
+        first   'foo'
+
+        desc <<-DESC
+          This is a short explanation
+
+          Example:
+          |  do this then that
+          |  followed by this line
+        DESC
+        second  'bar'
+      }
+
+      other.__desc[:first].should be == "  This is the first thing we are defining in this config.\n  It has a multiline comment."
+      other.__desc[:second].should be == "This is a short explanation\n\nExample:\n  do this then that\n  followed by this line"
+    end
+  end
+
+  # -----------------------------------------------------------------------
+  describe 'when working with defaults' do
+    before :each do
+      Loquacious::Configuration.instance_variable_get(:@table).clear
+    end
+
+    it 'returns default values when no other value exists' do
+      Loquacious::Configuration.defaults_for('test') {
+        first 'foo', :desc => 'the first value'
+        desc 'the second value'
+        second  {
+          bar nil, :desc => 'time to go drinking'
+        }
+      }
+
+      c = Loquacious::Configuration.for 'test'
+      c.first.eql?('foo').should be_true
+      c.second.bar.eql?(nil).should be_true
+    end
+
+    it 'does not overwrite existing configuration values' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            third 3
+          }
+
+      Loquacious::Configuration.defaults_for('test') {
+        first 'foo', :desc => 'the first value'
+        desc 'the second value'
+        second  {
+          bar nil, :desc => 'time to go drinking'
+        }
+      }
+
+      c.first.eql?(1).should be_true
+      c.third.eql?(3).should be_true
+      c.second.bar.eql?(nil).should be_true
+
+      c.__desc[:first].should be == 'the first value'
+      c.__desc[:second].should be == 'the second value'
+      c.second.__desc[:bar].should be == 'time to go drinking'
+      c.__desc[:third].should be_nil
+    end
+
+    it 'does not overwrite nested configuration values' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            second {
+              bar 'pub'
+              baz {
+                buz 'random text'
+                boo 'who'
+              }
+            }
+            third 3
+          }
+
+      Loquacious::Configuration.defaults_for('test') {
+        first 'foo', :desc => 'the first value'
+        desc 'the second value'
+        second  {
+          bar 'h-bar', :desc => 'time to go drinking'
+          desc 'getting weird'
+          baz {
+            buz 'buz', :desc => 'post drinking feeling'
+            boo nil, :desc => 'no need to cry about it'
+          }
+        }
+      }
+
+      c.first.eql?(1).should be_true
+      c.third.eql?(3).should be_true
+      c.second.bar.eql?('pub').should be_true
+      c.second.baz.buz.eql?('random text').should be_true
+      c.second.baz.boo.eql?('who').should be_true
+
+      c.second.bar = Loquacious::Undefined.new('second.bar')
+      c.second.bar.eql?('h-bar').should be_true
+
+      c.__desc[:first].should be == 'the first value'
+      c.__desc[:second].should be == 'the second value'
+      c.second.__desc[:bar].should be == 'time to go drinking'
+      c.second.__desc[:baz].should be == 'getting weird'
+      c.second.baz.__desc[:buz].should be == 'post drinking feeling'
+      c.second.baz.__desc[:boo].should be == 'no need to cry about it'
+      c.__desc[:third].should be_nil
+    end
+
+    it 'supports differing default type' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            second {
+              bar 'pub'
+              desc 'overwrite me'
+              baz {
+                buz 'random text'
+                boo 'who'
+              }
+            }
+            third 3
+          }
+
+      Loquacious::Configuration.defaults_for('test') {
+        first 'foo', :desc => 'the first value'
+        desc 'the second value'
+        second  {
+          bar 'h-bar', :desc => 'time to go drinking'
+          baz nil, :desc => 'deprecated'
+        }
+      }
+
+      c.second.baz.buz.eql?('random text').should be_true
+      c.second.baz.boo.eql?('who').should be_true
+
+      c.second.baz = Loquacious::Undefined.new('second.bar')
+      c.second.baz.eql?(nil).should be_true
+      c.second.__desc[:baz].should be == 'deprecated'
+    end
+
+    it 'properly handles Proc default values' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            second {
+              bar 'pub'
+            }
+            third 3
+          }
+
+      Loquacious::Configuration.defaults_for('test') {
+        first 'foo', :desc => 'the first value'
+        desc 'the second value'
+        second  {
+          bar 'h-bar', :desc => 'time to go drinking'
+          baz(Proc.new { c.third * 12 }, :desc => 'proc will be evaluated')
+        }
+      }
+
+      c.second.baz.eql?(36).should be_true
+      c.second.__desc[:baz].should be == 'proc will be evaluated'
+    end
+  end
+
+  # -----------------------------------------------------------------------
+  describe 'when converting to a hash' do
+    it "should do so recursively" do
+      c = Loquacious::Configuration.new {
+        first 1, :desc => 'one is the loneliest number'
+        second {
+          bar 'pub', :desc => 'where the magic happens'
+          desc 'overwrite me'
+          baz {
+            buz 'random text'
+            boo 'who'
+          }
+        }
+        third 3
+      }
+      c.to_hash.should == {
+        :first => 1,
+        :second => {
+          :bar => 'pub',
+          :baz => {
+            :buz => 'random text',
+            :boo => 'who'
+          }
+        },
+        :third => 3
+      }
+    end
+
+    it "just returns an empty hash for an empty configuration" do
+      c = Loquacious::Configuration.new { }
+      c.to_hash.should == {}
+    end
+  end
+
+  # Added tests
+  describe "added features for ENV configuration" do
+    before(:all) do
+     Loquacious.env_config = true
+    end
+    after(:all) do
+     Loquacious.env_config = false
+    end
+
+    let(:obj) {
+      Loquacious.configuration_for('app') {
+        name :testing, :desc => "Defines the name", :transform =>  Proc.new{|arg| arg.to_sym }
+        foo  'bar',   :desc => "FooBar"
+        id   42,      :desc => "Ara T. Howard"
+        bar {
+          recur 'sive'
+          baz {
+            inner 'config'
+          }
+        }
+      }
+    }
+
+    it "sets the name for the created config" do
+      obj.__name.eql?("app").should be_true
+    end
+
+    it "sets the name for a nested object" do
+      obj.bar.__name.eql?("bar").should be_true
+    end
+
+    it "sets the parent name for a nested object" do
+      obj.bar.__parent.__name.eql?("app").should be_true
+    end
+
+    it "stores the transform for a configuration key" do
+      obj.__transforms[:name].is_a?(Proc).should be_true
+    end
+
+    it "overrides a value with the correct ENV value" do
+      ENV["LOQ_APP_FOO"] = "envbar"
+      obj.foo.eql?("envbar").should be_true
+    end
+
+    it "transforms the value using the provided lambda" do
+      ENV["LOQ_APP_NAME"] = "envname"
+      obj.name.eql?(:envname).should be_true
+      obj.name.is_a?(Symbol).should be_true
+    end
+
+    describe "#parent_list" do
+      it "returns the correct parent list for a configuration object" do
+        obj.bar.baz.parent_list.eql?(["app", "bar"]).should be_true
+      end
+    end
+
+  end#added features for ENV
+end
+