Class: Loquacious::Configuration

### Home Classes Methods

### In Files

- lib/loquacious/configuration.rb
- lib/loquacious/configuration/help.rb
- lib/loquacious/configuration/iterator.rb

### Parent

Object

### Namespace

- CLASS Loquacious::Configuration::DSL
- CLASS Loquacious::Configuration::Error
- CLASS Loquacious::Configuration::Help
- CLASS Loquacious::Configuration::Iterator

### Methods

- ::defaults_for
- ::for
- ::help
- ::help_for
- ::new
- ::to_hash
- #[]
- #[]=
- #__eigenclass_eval
- #__send
- #merge!
- #method_missing
- #to_hash

### Files

- History.txt
- README.rdoc

### Class/Module Index

Quicksearch

- Loquacious
- Loquacious::Configuration
- Loquacious::Configuration::DSL
- Loquacious::Configuration::Help
- Loquacious::Configuration::Iterator
- Loquacious::Undefined
- String

No matching classes.

# Loquacious::Configuration

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.

### Attributes

__defaults[R]

Accessor for configuration defaults

__defaults_mode[RW]

Flag to switch the configuration object into defaults mode. This allows default values to be set instead regular values.

__desc[R]

Accessor for the description hash.

__values[R]

Accessor for configuration values

### Public Class Methods

defaults_for( name ) { block } click to toggle source

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.

    # File lib/loquacious/configuration.rb, line 64
    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

for( name ) click to toggle source
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.

    # File lib/loquacious/configuration.rb, line 38
    def for( name, &block )
      if block.nil?
        return @table.has_key?(name) ? @table[name] : nil
      end

      if @table.has_key? name
        DSL.evaluate(:config => @table[name], &block)
      else
        @table[name] = DSL.evaluate(&block)
      end
    end

help( name, opts = {} ) click to toggle source
Alias for: help_for
help_for( name, opts = {} ) click to toggle source

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.

    # File lib/loquacious/configuration.rb, line 81
    def help_for( name, opts = {} )
      ::Loquacious::Configuration::Help.new(name, opts)
    end

Also aliased as: help
new( &block ) click to toggle source

Create a new configuration object and initialize it using an optional block of code.

    # File lib/loquacious/configuration.rb, line 140
    def initialize( &block )
      @__desc = Hash.new
      @__values = Hash.new
      @__defaults = Hash.new
      @__defaults_mode = false
      DSL.evaluate(:config => self, &block) if block
    end

to_hash( config ) click to toggle source

Recursively convert a configuration object to a hash.

    # File lib/loquacious/configuration.rb, line 91
    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

### Public Instance Methods

[]( key ) click to toggle source

Provides hash accessor notation for configuration values.

    config = Configuration.for('app') {
               port  1234
             }
    config[:port]  #=> 1234
    config.port    #=> 1234

    # File lib/loquacious/configuration.rb, line 257
    def []( key )
      self.__send(key)
    end

[]=( key, value ) click to toggle source

Provides hash accessor notation for configuration values.

    config = Configuration.for('app')
    config[:port] = 8808
    config.port            #=> 8808

    # File lib/loquacious/configuration.rb, line 267
    def []=( key, value )
      self.__send(key, value)
    end

__eigenclass_eval( code, file, line ) click to toggle source

Evaluate the given code string in the context of this object's eigenclass (singleton class).

    # File lib/loquacious/configuration.rb, line 206
    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

__send( symbol, *args, &block ) click to toggle source

Only invoke public methods on the Configuration instances.

    # File lib/loquacious/configuration.rb, line 195
    def __send( symbol, *args, &block )
      if self.respond_to? symbol
        self.__send__(symbol, *args, &block)
      else
        self.method_missing(symbol, *args, &block)
      end
    end

merge!( other ) click to toggle source

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.

    # File lib/loquacious/configuration.rb, line 220
    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

method_missing( method, *args, &block ) click to toggle source

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.

    # File lib/loquacious/configuration.rb, line 154
    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         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}            return value.respond_to?(:call) ? value.call : value          end          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            v = (1 == args.length ? args.first : args)            if __defaults_mode              @__defaults[#{m.inspect}] = v            else              @__values[#{m.inspect}] = v            end          end        end, __FILE__, __LINE__+1

      __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

to_hash() click to toggle source

Recursively convert the configuration object to a hash.

    # File lib/loquacious/configuration.rb, line 273
    def to_hash
      ::Loquacious::Configuration.to_hash(self)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.