loquacious 1.7.1 → 1.8.0

data/History.txt

@@ -1,3 +1,8 @@
+== 1.8.0 / 2011-06-03
+
+Enhancements
+  - Support for defalut values on configuration properties
+
 == 1.7.1 / 2011-02-11
 
 Bug Fixes

data/README.rdoc

@@ -1,6 +1,6 @@
 = Loquacious
     by Tim Pease
-    http://codeforpeople.rubyforge.org/loquacious
+    http://rubygems.org/gems/loquacious
 
 == DESCRIPTION:
 
@@ -104,32 +104,28 @@ they can appear above the attribute and value on their own line.
 
     desc "Configuration options for ActiveRecord::Base."
     active_record {
-      desc <<-__
+      colorize_logging true, :desc => <<-__
         Determines whether to use ANSI codes to colorize the logging statements committed
         by the connection adapter. These colors make it much easier to overview things
         during debugging (when used through a reader like +tail+ and on a black background),
         but may complicate matters if you use software like syslog. This is true, by default.
       __
-      colorize_logging true
 
-      desc <<-__
+      default_timezone :local, :desc => <<-__
         Determines whether to use Time.local (using :local) or Time.utc (using :utc)
         when pulling dates and times from the database. This is set to :local by default.
       __
-      default_timezone :local
     }
 
-    desc <<-__
+    log_level :info, :desc => <<-__
       The log level to use for the default Rails logger. In production mode,
       this defaults to :info. In development mode, it defaults to :debug.
     __
-    log_level :info
 
-    desc <<-__
+    log_path 'log/development.log', :desc => <<-__
       The path to the log file to use. Defaults to log/\#{environment}.log
       (e.g. log/development.log or log/production.log).
     __
-    log_path 'log/development.log'
   }
 
   help = Configuration.help_for :nested
@@ -170,14 +166,13 @@ they can appear above the attribute and value on their own line.
   include Loquacious
 
   Configuration.for(:gutters) {
-    desc <<-__
+    log_path "log/development.log", :desc => <<-__
       The path to the log file to use. Defaults to log/\#{environment}.log
       (e.g. log/development.log or log/production.log).
       |
       |  config.log_path = File.join(ROOT, "log", "\#{environment}.log
       |
     __
-    log_path "log/development.log"
 
     log_level :warn, :desc => <<-__
       |The log level to use for the default Rails logger. In production mode,
@@ -212,7 +207,7 @@ they can appear above the attribute and value on their own line.
 
 (The MIT License)
 
-Copyright (c) 2009-2010
+Copyright (c) 2009-2011
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -12,13 +12,12 @@ Bones {
   name         'loquacious'
   authors      'Tim Pease'
   email        'tim.pease@gmail.com'
-  url          'http://gemcutter.org/gems/loquacious'
+  url          'http://rubygems.org/gems/loquacious'
   readme_file  'README.rdoc'
-  ignore_file  '.gitignore'
   spec.opts << '--color'
   use_gmail
 
-  depend_on 'rspec', :development => true
+  depend_on 'rspec', '~> 2.6', :development => true
 }
 
 task 'ann:prereqs' do

data/examples/gutters.rb

@@ -1,20 +1,19 @@
 # Using Ruby heredocs for descriptions, the Loquacious configuration will
 # strip out leading whitespace but preserve line breaks. Gutter lines can be
 # used to mark where leading whitespace should be preserved. This is useful
-# is you need to provide example code in your descriptions.
+# if you need to provide example code in your descriptions.
 
 require 'loquacious'
 include Loquacious
 
 Configuration.for(:gutters) {
-  desc <<-__
+  log_path "log/development.log", :desc => <<-__
     The path to the log file to use. Defaults to log/\#{environment}.log
     (e.g. log/development.log or log/production.log).
     |
     |  config.log_path = File.join(ROOT, "log", "\#{environment}.log
     |
   __
-  log_path "log/development.log"
 
   log_level :warn, :desc => <<-__
     |The log level to use for the default Rails logger. In production mode,

data/examples/nested.rb

@@ -15,32 +15,28 @@ Configuration.for(:nested) {
 
   desc "Configuration options for ActiveRecord::Base."
   active_record {
-    desc <<-__
+    colorize_logging true, :desc => <<-__
       Determines whether to use ANSI codes to colorize the logging statements committed
       by the connection adapter. These colors make it much easier to overview things
       during debugging (when used through a reader like +tail+ and on a black background),
       but may complicate matters if you use software like syslog. This is true, by default.
     __
-    colorize_logging true
 
-    desc <<-__
+    default_timezone :local, :desc => <<-__
       Determines whether to use Time.local (using :local) or Time.utc (using :utc)
       when pulling dates and times from the database. This is set to :local by default.
     __
-    default_timezone :local
   }
 
-  desc <<-__
+  log_level :info, :desc => <<-__
     The log level to use for the default Rails logger. In production mode,
     this defaults to :info. In development mode, it defaults to :debug.
   __
-  log_level :info
 
-  desc <<-__
+  log_path 'log/development.log', :desc => <<-__
     The path to the log file to use. Defaults to log/\#{environment}.log
     (e.g. log/development.log or log/production.log).
   __
-  log_path 'log/development.log'
 }
 
 help = Configuration.help_for :nested

data/lib/loquacious.rb

@@ -25,6 +25,18 @@ module Loquacious
     alias :config_for    :configuration_for
     alias :config        :configuration_for
 
+    # Set the default properties for the configuration associated with the
+    # given _name_. A _block_ must be provided to this method.
+    #
+    # The same _name_ can be used multiple times with different configuration
+    # blocks. Each block will add or modify the configuration; i.e. the
+    # configurations are additive.
+    #
+    def defaults_for( name, &block )
+      ::Loquacious::Configuration.defaults_for(name, &block)
+    end
+    alias :defaults :defaults_for
+
     # Returns a Help instance for the configuration associated with the
     # given _name_. See the Help#initialize method for the options that
     # can be used with this method.
@@ -82,6 +94,7 @@ module Loquacious
     #   Loquacious.remove :gem           # courtesy of rubygems
     #   Loquacious.remove :test, :file   # courtesy of rake
     #   Loquacious.remove :main          # courtesy of main
+    #   Loquacious.remove :timeout       # courtesy of timeout
     #
     def remove( *args )
       args.each { |name|

data/lib/loquacious/configuration.rb

@@ -1,7 +1,20 @@
 
 module Loquacious
 
+  # A Configuration provides a "blank slate" for storing configuration
+  # properties along with descriptions and default values. Configurations are
+  # accessed by name, and hence, the configuration properties can be retrieved
+  # from any location in your code.
   #
+  # Each property has an associated description that can be displayed to the
+  # user via the Configuration::Help class. This is the main point of the
+  # Loquacious library - tell the user what all yoru configruation properties
+  # actually do!
+  #
+  # Each configurationp property can also have a default value that is
+  # returned if no value has been set for that property. Each property should
+  # hae a sensible default - the user should not have to configure every
+  # property in order to use a piece of code.
   #
   class Configuration
 
@@ -28,12 +41,36 @@ module Loquacious
         end
 
         if @table.has_key? name
-          DSL.new(@table[name], &block)
+          DSL.evaluate(:config => @table[name], &block)
         else
           @table[name] = DSL.evaluate(&block)
         end
       end
 
+      # call-seq:
+      #    Configuration.defaults_for( name ) { block }
+      #
+      # Set the default values for the configuration associated with the given
+      # _name_. A _block_ is required by this method.
+      #
+      # Default values do not interfere with normal configuration values. If
+      # both are defined for a particualr configruation setting, then the
+      # regular configuration value will be returned.
+      #
+      # Defaults allow the user to define configuration values before the
+      # library defaults have been loaded. They prevent library defaults from
+      # overriding user settings.
+      #
+      def defaults_for( name, &block )
+        raise "defaults require a block" if block.nil?
+
+        if @table.has_key? name
+          DSL.evaluate(:config => @table[name], :defaults_mode => true, &block)
+        else
+          @table[name] = DSL.evaluate(:defaults_mode => true, &block)
+        end
+      end
+
       # call-seq:
       #    Configuration.help_for( name, opts = {} )
       #
@@ -64,12 +101,25 @@ module Loquacious
     # Accessor for the description hash.
     attr_reader :__desc
 
+    # Accessor for configuration values
+    attr_reader :__values
+
+    # Accessor for configuration defaults
+    attr_reader :__defaults
+
+    # Flag to switch the configuration object into defaults mode. This allows
+    # default values to be set instead regular values.
+    attr_accessor :__defaults_mode
+
     # Create a new configuration object and initialize it using an optional
     # _block_ of code.
     #
     def initialize( &block )
       @__desc = Hash.new
-      self.merge!(DSL.evaluate(&block)) if block
+      @__values = Hash.new
+      @__defaults = Hash.new
+      @__defaults_mode = false
+      DSL.evaluate(:config => self, &block) if block
     end
 
     # When invoked, an attribute reader and writer are defined for the
@@ -81,31 +131,40 @@ module Loquacious
     def method_missing( method, *args, &block )
       m = method.to_s.delete('=').to_sym
 
-      __eigenclass_eval "attr_writer :#{m}"
-      __eigenclass_eval <<-CODE
+      __eigenclass_eval "def #{m}=( value ) @__values[#{m.inspect}] = value; end", __FILE__, __LINE__
+      __eigenclass_eval <<-CODE, __FILE__, __LINE__+1
         def #{m}( *args, &block )
+          value = @__values[#{m.inspect}]
+
           if args.empty? and !block
-            return @#{m} if @#{m}.kind_of?(Configuration)
-            return @#{m}.respond_to?(:call) ? @#{m}.call : @#{m}
+            return value if value.kind_of?(Configuration)
+            value = @__defaults[#{m.inspect}] if value.kind_of?(Loquacious::Undefined) and @__defaults.has_key? #{m.inspect}
+            return value.respond_to?(:call) ? value.call : value
           end
 
-          v = (1 == args.length ? args.first : args)
-          v = DSL.evaluate(&block) if block
-
-          if @#{m}.kind_of?(Configuration)
-            @#{m}.merge! v
+          if block
+            v = DSL.evaluate(:defaults_mode => __defaults_mode, &block)
+            if value.kind_of?(Configuration)
+              value.merge! v
+            else
+              @__values[#{m.inspect}] = v
+            end
           else
-            @#{m} = v
+            v = (1 == args.length ? args.first : args)
+            if __defaults_mode
+              @__defaults[#{m.inspect}] = v
+            else
+              @__values[#{m.inspect}] = v
+            end
           end
 
-          return @#{m} if @#{m}.kind_of?(Configuration)
-          return @#{m}.respond_to?(:call) ? @#{m}.call : @#{m}
+          return self.#{m}
         end
       CODE
 
       __desc[m] = nil unless __desc.has_key? m
 
-      default = (args.empty? and !block) ? Loquacious::Undefined.new(m.to_s) : nil
+      default = ((__defaults_mode or args.empty?) and !block) ? Loquacious::Undefined.new(m.to_s) : nil
       self.__send("#{m}=", default)
       self.__send("#{m}", *args, &block)
     end
@@ -123,9 +182,9 @@ module Loquacious
     # Evaluate the given _code_ string in the context of this object's
     # eigenclass (singleton class).
     #
-    def __eigenclass_eval( code )
+    def __eigenclass_eval( code, file, line )
       ec = class << self; self; end
-      ec.module_eval code
+      ec.module_eval code, file, line
     rescue StandardError
       Kernel.raise Error, "cannot evalutate this code:\n#{code}\n"
     end
@@ -141,14 +200,26 @@ module Loquacious
       return self if other.equal? self
       Kernel.raise Error, "can only merge another Configuration" unless other.kind_of?(Configuration)
 
+      other_values = other.__values
+      other_defaults = other.__defaults
+
       other.__desc.each do |key,desc|
-        value = other.__send(key)
-        if self.__send(key).kind_of?(Configuration)
-          self.__send(key).merge! value
-        else
-          self.__send("#{key}=", value)
+        value = @__values[key]
+        other_value = other_values[key]
+
+        if value.kind_of?(Configuration) and other_value.kind_of?(Configuration)
+          value.merge! other_value
+        elsif !other_value.kind_of?(Loquacious::Undefined)
+          @__values[key] = other_value
+        end
+
+        if other_defaults.has_key? key
+          @__defaults[key] = other_defaults[key]
+        end
+
+        if desc
+          __desc[key] = desc
         end
-        __desc[key] = desc
       end
 
       self
@@ -192,7 +263,7 @@ module Loquacious
       end
       Kernel.methods.each do |m|
         next if m[::Loquacious::KEEPERS]
-        module_eval <<-CODE
+        module_eval <<-CODE, __FILE__, __LINE__+1
           def #{m}( *args, &block )
             self.method_missing('#{m}', *args, &block)
           end
@@ -203,8 +274,8 @@ module Loquacious
       # Create a new DSL and evaluate the given _block_ in the context of
       # the DSL. Returns a newly created configuration object.
       #
-      def self.evaluate( &block )
-        dsl = self.new(&block)
+      def self.evaluate( opts = {}, &block )
+        dsl = self.new(opts, &block)
         dsl.__config
       end
 
@@ -214,10 +285,13 @@ module Loquacious
       # Creates a new DSL and evaluates the given _block_ in the context of
       # the DSL.
       #
-      def initialize( config = nil, &block )
+      def initialize( opts = {}, &block )
         @description = nil
-        @__config = config || Configuration.new
+        @__config = opts[:config] || Configuration.new
+        @__config.__defaults_mode = opts.key?(:defaults_mode) ? opts[:defaults_mode] : false
         instance_eval(&block)
+      ensure
+        @__config.__defaults_mode = false
       end
 
       # Dynamically adds the given _method_ to the configuration as an

data/spec/configuration_spec.rb

@@ -2,10 +2,6 @@
 require File.expand_path('spec_helper', File.dirname(__FILE__))
 
 describe Loquacious::Configuration do
-  before(:all) do
-    @respond_to = Object.instance_method(:respond_to?)
-  end
-
   before(:each) do
     @obj = Loquacious::Configuration.new
   end
@@ -30,13 +26,12 @@ describe Loquacious::Configuration do
   end
 
   it 'should deine attribute accessors when first used' do
-    m = @respond_to.bind(@obj)
-    m.call(:foo).should == false
-    m.call(:foo=).should == false
+    @obj.respond_to?(:foo).should == false
+    @obj.respond_to?(:foo=).should == false
 
     @obj.foo
-    m.call(:foo).should == true
-    m.call(:foo=).should == true
+    @obj.respond_to?(:foo).should == true
+    @obj.respond_to?(:foo=).should == true
   end
 
   it 'should provide a hash object for storing method descriptions' do
@@ -97,6 +92,7 @@ describe Loquacious::Configuration do
 
   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'
@@ -135,7 +131,7 @@ describe Loquacious::Configuration do
     obj.first.should == 'foo'
     obj.second.bar.should be_nil
 
-    Loquacious::Configuration::DSL.new(obj) {
+    Loquacious::Configuration::DSL.evaluate(:config => obj) {
       first 'bar'
       second.bar 'no longer nil'
     }
@@ -161,7 +157,7 @@ describe Loquacious::Configuration do
     obj.__desc[:second].should == 'the second value'
     obj.second.__desc[:bar].should == 'time to go drinking'
 
-    Loquacious::Configuration::DSL.new(obj) {
+    Loquacious::Configuration::DSL.evaluate(:config => obj) {
       first 'bar'
       second.bar 'no longer nil'
     }
@@ -275,8 +271,149 @@ describe Loquacious::Configuration do
       other.__desc[:first].should == "  This is the first thing we are defining in this config.\n  It has a multiline comment."
       other.__desc[:second].should == "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.should == 'foo'
+      c.second.bar.should be_nil
+    end
+
+    it 'does not overwrite existing configuration values' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            thrid 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.should == 1
+      c.third.should == 3
+      c.second.bar.should be_nil
+
+      c.__desc[:first].should == 'the first value'
+      c.__desc[:second].should == 'the second value'
+      c.second.__desc[:bar].should == 'time to go drinking'
+      c.__desc[:thrid].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'
+              }
+            }
+            thrid 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.should == 1
+      c.third.should == 3
+      c.second.bar.should == 'pub'
+      c.second.baz.buz.should == 'random text'
+      c.second.baz.boo.should == 'who'
+
+      c.second.bar = Loquacious::Undefined.new('second.bar')
+      c.second.bar.should == 'h-bar'
+
+      c.__desc[:first].should == 'the first value'
+      c.__desc[:second].should == 'the second value'
+      c.second.__desc[:bar].should == 'time to go drinking'
+      c.second.__desc[:baz].should == 'getting weird'
+      c.second.baz.__desc[:buz].should == 'post drinking feeling'
+      c.second.baz.__desc[:boo].should == 'no need to cry about it'
+      c.__desc[:thrid].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'
+              }
+            }
+            thrid 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.should == 'random text'
+      c.second.baz.boo.should == 'who'
+
+      c.second.baz = Loquacious::Undefined.new('second.bar')
+      c.second.baz.should be_nil
+      c.second.__desc[:baz].should == 'deprecated'
+    end
+
+    it 'properly handles Proc default values' do
+      c = Loquacious::Configuration.for('test') {
+            first 1
+            second {
+              bar 'pub'
+            }
+            thrid 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.should == 36
+      c.second.__desc[:baz].should == 'proc will be evaluated'
+    end
   end
+
 end
 
-# EOF

data/spec/spec_helper.rb

@@ -1,7 +1,7 @@
 
 require File.expand_path('../lib/loquacious', File.dirname(__FILE__))
 
-Spec::Runner.configure do |config|
+RSpec.configure do |config|
   # == Mock Framework
   #
   # RSpec uses it's own mocking framework by default. If you prefer to
@@ -59,4 +59,3 @@ class StringIO
   end
 end
 
-# EOF

data/version.txt

@@ -1 +1 @@
-1.7.1
+1.8.0

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: loquacious
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 55
   prerelease: false
   segments: 
   - 1
-  - 7
-  - 1
-  version: 1.7.1
+  - 8
+  - 0
+  version: 1.8.0
 platform: ruby
 authors: 
 - Tim Pease
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-11 00:00:00 -07:00
+date: 2011-06-03 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -24,14 +24,13 @@ dependencies:
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
-        hash: 25
+        hash: 15
         segments: 
-        - 1
-        - 3
-        - 1
-        version: 1.3.1
+        - 2
+        - 6
+        version: "2.6"
   type: :development
   version_requirements: *id001
 description: |-
@@ -108,7 +107,7 @@ files:
 - spec/string_spec.rb
 - version.txt
 has_rdoc: true
-homepage: http://gemcutter.org/gems/loquacious
+homepage: http://rubygems.org/gems/loquacious
 licenses: []
 
 post_install_message: