adhearsion-loquacious 1.9.2

data/examples/gutters.rb

@@ -0,0 +1,29 @@
+# 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
+# if you need to provide example code in your descriptions.
+
+require 'loquacious'
+include Loquacious
+
+Configuration.for(:gutters) {
+  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_level :warn, :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.
+    |
+    |  config.log_level = 'debug'
+    |  config.log_level = :warn
+    |
+  __
+}
+
+help = Configuration.help_for :gutters
+help.show :values => true

data/examples/nested.rb

@@ -0,0 +1,43 @@
+# Here we show how to used nested configuration options by taking a subset
+# of some common Rails configuration options. Also, descriptions can be give
+# before the option or they can be given inline using Ruby hash notation. If
+# both are present, then the inline description takes precedence.
+#
+# Multiline descriptions are provided using Ruby heredocs. Leading
+# whitespace is stripped and line breaks are preserved when descriptions
+# are printed using the help object.
+
+require 'loquacious'
+include Loquacious
+
+Configuration.for(:nested) {
+  root_path '.', :desc => "The application's base directory."
+
+  desc "Configuration options for ActiveRecord::Base."
+  active_record {
+    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.
+    __
+
+    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.
+    __
+  }
+
+  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_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).
+  __
+}
+
+help = Configuration.help_for :nested
+help.show :values => true

data/examples/simple.rb

@@ -0,0 +1,20 @@
+# A simple example that configures three options (a b c) along with
+# descriptions for each option. The descriptions along with the
+# values for the configuration options are printed to the terminal.
+
+require 'loquacious'
+include Loquacious
+
+Configuration.for(:simple) {
+  desc 'Your first configuration option'
+  a "value for 'a'"
+
+  desc 'To be or not to be'
+  b "William Shakespeare"
+
+  desc 'The underpinings of Ruby'
+  c 42
+}
+
+help = Configuration.help_for :simple
+help.show :values => true

data/lib/loquacious.rb

@@ -0,0 +1,165 @@
+module Loquacious
+
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  KEEPERS = (RUBY_PLATFORM == 'java') ?
+            %r/^__|^object_id$|^initialize$|^instance_eval$|^singleton_method_added$|^\w+\?$/ :
+            %r/^__|^object_id$|^initialize$|^instance_eval$|^\w+\?$/
+  # :startdoc:
+
+
+  class << self
+    # These control respectively if ENV overrides are used, and which prefix is used
+    # Defaults are true and LOQ, and are declared at the bottom"
+    attr_accessor :env_config
+    attr_accessor :env_prefix
+
+
+    # Returns the configuration associated with the given _name_. If a
+    # _block_ is given, then it will be used to create the configuration.
+    #
+    # The same _name_ can be used multiple times with different
+    # configuration blocks. Each different block will be used to add to the
+    # configuration; i.e. the configurations are additive.
+    #
+    def configuration_for( name, &block )
+      ::Loquacious::Configuration.for(name, &block)
+    end
+    alias :configuration :configuration_for
+    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.
+    #
+    def help_for( name, opts = {} )
+      ::Loquacious::Configuration.help_for(name, opts)
+    end
+    alias :help :help_for
+
+    # Returns the version string for the library.
+    #
+    def version
+      @version ||= File.read(path('version.txt')).strip
+    end
+
+    # Returns the library path for the module. If any arguments are given,
+    # they will be joined to the end of the libray path using
+    # <tt>File.join</tt>.
+    #
+    def libpath( *args, &block )
+      rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+      if block
+        begin
+          $LOAD_PATH.unshift LIBPATH
+          rv = block.call
+        ensure
+          $LOAD_PATH.shift
+        end
+      end
+      return rv
+    end
+
+    # Returns the lpath for the module. If any arguments are given, they
+    # will be joined to the end of the path using <tt>File.join</tt>.
+    #
+    def path( *args, &block )
+      rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
+      if block
+        begin
+          $LOAD_PATH.unshift PATH
+          rv = block.call
+        ensure
+          $LOAD_PATH.shift
+        end
+      end
+      return rv
+    end
+
+    # This is merely a convenience method to remove methods from the
+    # Loquacious::Configuration class. Some ruby gems add lots of crap to the
+    # Kernel module, and this interferes with the configuration system. The
+    # remove method should be used to anihilate unwanted methods from the
+    # configuration class as needed.
+    #
+    #   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|
+        name = name.to_s.delete('=')
+        code = <<-__
+          undef_method :#{name} rescue nil
+          undef_method :#{name}= rescue nil
+        __
+        Loquacious::Configuration.module_eval code
+        Loquacious::Configuration::DSL.module_eval code
+      }
+    end
+
+    # A helper method that will create a deep copy of a given Configuration
+    # object. This method accepts either a Configuration instance or a name
+    # that can be used to lookup the Configuration instance (via the
+    # "Loquacious.configuration_for" method).
+    #
+    #   Loquacious.copy(config)
+    #   Loquacious.copy('name')
+    #
+    # Optionally a block can be given. It will be used to modify the returned
+    # copy with the given values. The Configuration object being copied is
+    # never modified by this method.
+    #
+    #   Loquacious.copy(config) {
+    #     foo 'bar'
+    #     baz 'buz'
+    #   }
+    #
+    def copy( config, &block )
+      config = Configuration.for(config) unless config.instance_of? Configuration
+      return unless config
+
+      rv = Configuration.new
+      rv.merge!(config)
+
+      # deep copy
+      rv.__desc.each do |key,desc|
+        value = rv.__send(key)
+        next unless value.instance_of? Configuration
+        rv.__send("#{key}=", ::Loquacious.copy(value))
+      end
+
+      rv.merge!(Configuration::DSL.evaluate(&block)) if block
+      rv
+    end
+
+  end  # class << self
+
+  @env_config = false
+  @env_prefix = "LOQ"
+end  # module Loquacious
+
+Loquacious.libpath {
+  require 'loquacious/core_ext/string'
+  require 'loquacious/undefined'
+  require 'loquacious/utility'
+  require 'loquacious/configuration'
+  require 'loquacious/configuration/iterator'
+  require 'loquacious/configuration/help'
+}
+

data/lib/loquacious/configuration.rb

@@ -0,0 +1,406 @@
+
+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
+
+    # :stopdoc:
+    class Error < StandardError; end
+    @table = Hash.new
+    # :startdoc:
+
+    class << self
+      # call-seq:
+      #    Configuration.for( name )
+      #    Configuration.for( name ) { block }
+      #
+      # Returns the configuration associated with the given _name_. If a
+      # _block_ is given, then it will be used to create the configuration.
+      #
+      # The same _name_ can be used multiple times with different
+      # configuration blocks. Each different block will be used to add to the
+      # configuration; i.e. the configurations are additive.
+      #
+      def for( name, &block )
+        if block.nil?
+          return @table.has_key?(name) ? @table[name] : nil
+        end
+
+        if @table.has_key? name
+          DSL.evaluate(:config_name => name, :config => @table[name], &block)
+        else
+          @table[name] = DSL.evaluate(:config_name => name, &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(:config_name => name, :defaults_mode => true, &block)
+        end
+      end
+
+      # call-seq:
+      #    Configuration.help_for( name, opts = {} )
+      #
+      # 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.
+      #
+      def help_for( name, opts = {} )
+        ::Loquacious::Configuration::Help.new(name, opts)
+      end
+      alias :help :help_for
+
+      # call-seq:
+      #   Configuration.to_hash( config )
+      #
+      # Recursively convert a configuration object to a hash.
+      #
+      def to_hash( config )
+        cache = { nil => {} }
+
+        Iterator.new(config).each do |node|
+          ary = node.name.split('.')
+          name = ary.pop.to_sym
+          parent = ary.empty? ? nil : ary.join('.')
+
+          if node.config?
+            cache[node.name] = cache[parent][name] = {}
+          else
+            cache[parent][name] = node.obj
+          end
+        end
+
+        return cache[nil]
+      end
+
+      # Returns a string array with the parent tree for the config
+      #
+      def parent_list(config)
+        current_parent = config.__parent
+        parents = []
+        until current_parent.nil? do
+          parents.unshift current_parent.__name
+          current_parent = current_parent.__parent
+        end
+        parents
+      end
+    end#self methods
+
+
+    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
+
+    # 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
+
+    # Name for this configuration object
+    attr_accessor :__name
+
+    # Name of the parent configuration object, used for traversal
+    attr_accessor :__parent
+
+    # Hash holding the transform procs
+    attr_accessor :__transforms
+
+    # Create a new configuration object and initialize it using an optional
+    # _block_ of code.
+    #
+    def initialize( &block )
+      @__desc = Hash.new
+      @__values = Hash.new
+      @__defaults = Hash.new
+      @__transforms = Hash.new
+      @__defaults_mode = false
+      @__parent = nil
+      DSL.evaluate(:config => self, &block) if block
+    end
+
+    # When invoked, an attribute reader and writer are defined for the
+    # _method_. Any arguments given are used to set the value of the
+    # attributes. If a _block_ is given, then the attribute is a nested
+    # configuration and the _block_ is evaluated in the context of a new
+    # configuration object.
+    #
+    def method_missing( method, *args, &block )
+      m = method.to_s.delete('=').to_sym
+
+      __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 value if value.kind_of?(Configuration)
+            value = @__defaults[#{m.inspect}] if value.kind_of?(Loquacious::Undefined) and @__defaults.has_key? #{m.inspect}
+            if Loquacious.env_config
+              env_name = Loquacious::Utility.env_var_name(__method__, self)
+              if ENV.has_key? env_name
+                if @__transforms.has_key? __method__
+                  return @__transforms[__method__].call ENV[env_name]
+                else
+                  return ENV[env_name]
+                end
+              end
+            end
+            return value.respond_to?(:call) ? value.call : value
+          end
+
+          if block
+            v = DSL.evaluate(:parent_config => self, :config_name => __method__.to_s, :defaults_mode => __defaults_mode, &block)
+            if value.kind_of?(Configuration)
+              value.merge! v
+            else
+              @__values[#{m.inspect}] = v
+            end
+          else
+            v = (1 == args.length ? args.first : args)
+            if __defaults_mode
+              @__defaults[#{m.inspect}] = v
+            else
+              @__values[#{m.inspect}] = v
+            end
+          end
+        end
+      CODE
+
+      __desc[m] = nil unless __desc.has_key? m
+
+      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
+
+    # Only invoke public methods on the Configuration instances.
+    #
+    def __send( symbol, *args, &block )
+      if self.respond_to? symbol
+        self.__send__(symbol, *args, &block)
+      else
+        self.method_missing(symbol, *args, &block)
+      end
+    end
+
+    # Evaluate the given _code_ string in the context of this object's
+    # eigenclass (singleton class).
+    #
+    def __eigenclass_eval( code, file, line )
+      ec = class << self; self; end
+      ec.module_eval code, file, line
+    rescue StandardError
+      Kernel.raise Error, "cannot evalutate this code:\n#{code}\n"
+    end
+
+    # Merge the contents of the _other_ configuration into this one. Values
+    # from the _other_ configuratin will overwite values in this
+    # configuration.
+    #
+    # This function is recursive. Nested configurations will be merged with
+    # their counterparts in the _other_ configuration.
+    #
+    def merge!( other )
+      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 = @__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)
+          self.__send__(key, other_value)
+        end
+
+        if other_defaults.has_key? key
+          @__defaults[key] = other_defaults[key]
+        end
+
+        if desc
+          __desc[key] = desc
+        end
+      end
+
+      self
+    end
+
+    # Provides hash accessor notation for configuration values.
+    #
+    #   config = Configuration.for('app') {
+    #              port  1234
+    #            }
+    #   config[:port]  #=> 1234
+    #   config.port    #=> 1234
+    #
+    def []( key )
+      self.__send(key)
+    end
+
+    # Provides hash accessor notation for configuration values.
+    #
+    #   config = Configuration.for('app')
+    #   config[:port] = 8808
+    #   config.port            #=> 8808
+    #
+    def []=( key, value )
+      self.__send(key, value)
+    end
+
+    # Recursively convert the configuration object to a hash.
+    #
+    def to_hash
+      ::Loquacious::Configuration.to_hash(self)
+    end
+
+    # Returns an array of the parents in descending order
+    def parent_list
+      ::Loquacious::Configuration.parent_list(self)
+    end
+
+    # Implementation of a domain specific language for creating configuration
+    # objects. Blocks of code are evaluted by the DSL which returns a new
+    # configuration object.
+    #
+    class DSL
+      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, __FILE__, __LINE__+1
+          def #{m}( *args, &block )
+            self.method_missing('#{m}', *args, &block)
+          end
+        CODE
+      end
+      undef_method :method_missing rescue nil
+
+      # Create a new DSL and evaluate the given _block_ in the context of
+      # the DSL. Returns a newly created configuration object.
+      #
+      def self.evaluate( opts = {}, &block )
+        dsl = self.new(opts, &block)
+        dsl.__config
+      end
+
+      # Returns the configuration object.
+      attr_reader :__config
+
+      # Creates a new DSL and evaluates the given _block_ in the context of
+      # the DSL.
+      #
+      def initialize( opts = {}, &block )
+        @description = nil
+        @transform_to_store = nil
+        @__config = opts[:config] || Configuration.new
+        @__config.__defaults_mode = opts.key?(:defaults_mode) ? opts[:defaults_mode] : false
+        @__config.__name = opts[:config_name] || nil
+        @__config.__parent = opts[:parent_config] || nil
+        instance_eval(&block)
+      ensure
+        @__config.__defaults_mode = false
+      end
+
+      # Dynamically adds the given _method_ to the configuration as an
+      # attribute. The _args_ will be used to set the value of the
+      # attribute. If a _block_ is given then the _args_ are ignored and the
+      # attribute will be a nested configuration object.
+      #
+      def method_missing( method, *args, &block )
+        m = method.to_s.delete('=').to_sym
+
+        if args.length > 1
+          opts = args.last.instance_of?(Hash) ? args.pop : {}
+          self.desc(opts[:desc]) if opts.has_key? :desc
+          self.transform(opts[:transform]) if opts.has_key? :transform
+        end
+
+        rv = __config.__send(m, *args, &block)
+        __config.__desc[m] = @description if @description
+        __config.__transforms[m] = @transform_to_store if @transform_to_store
+        @description = nil
+        @transform_to_store = nil
+        rv
+      end
+
+      # Store the _string_ as the description for the next attribute that
+      # will be configured. This description will be overwritten if the
+      # attribute has a description passed as an options hash.
+      #
+      def desc( string )
+        string = string.to_s
+        string.strip!
+        string.gutter!
+        @description = string.empty? ? nil : string
+      end
+
+      def transform( transform_proc )
+        @transform_to_store = transform_proc
+      end
+
+    end  # class DSL
+
+  end  # class Configuration
+end  # module Loquacious
+