loquacious 1.0.0

data/lib/loquacious/configuration.rb

@@ -0,0 +1,197 @@
+
+module Loquacious
+
+  #
+  #
+  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
+
+        cfg = DSL.evaluate(&block)
+
+        if @table.has_key? name
+          @table[name].merge! cfg
+        else
+          @table[name] = cfg
+        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
+    end
+
+    exceptions = %w[instance_of? kind_of? equal?]
+    instance_methods.each do |m|
+      undef_method m unless m[%r/^__/] or exceptions.include? m.to_s
+    end
+
+    # Accessor for the description hash.
+    attr_reader :__desc
+
+    # 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
+    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 "attr_writer :#{m}"
+      __eigenclass_eval <<-CODE
+        def #{m}( *args, &block )
+          v = (1 == args.length ? args.first : args)
+          v = nil if args.empty?
+          v = DSL.evaluate(&block) if block
+          
+          return @#{m} unless v
+
+          if @#{m}.kind_of?(Configuration)
+            @#{m}.merge! v
+          else
+            @#{m} = v
+          end
+          return @#{m}
+        end
+      CODE
+
+      __desc[m]
+      self.__send__("#{m}=", nil)
+      self.__send__("#{m}", *args, &block)
+    end
+
+    # Evaluate the given _code_ string in the context of this object's
+    # eigenclass (singleton class).
+    #
+    def __eigenclass_eval( code )
+      ec = class << self; self; end
+      ec.module_eval code
+    rescue StandardError
+      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
+      raise Error, "can only merge another Configuration" unless other.kind_of?(Configuration)
+
+      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)
+        end
+        __desc[key] = desc
+      end
+
+      self
+    end
+
+    # Implementation of a doman specific language for creating configuration
+    # objects. Blocks of code are evaluted by the DSL which returns a new
+    # configuration object.
+    #
+    class DSL
+      alias :__instance_eval :instance_eval
+
+      instance_methods.each do |m|
+        undef_method m unless m[%r/^__/]
+      end 
+
+      # 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)
+        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( &block )
+        @description = nil
+        @__config = Configuration.new
+        self.__instance_eval(&block) if block
+      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
+
+        opts = args.last.instance_of?(Hash) ? args.pop : {}
+        self.desc(opts[:desc]) if opts.has_key? :desc
+
+        __config.__send__(m, *args, &block)
+        __config.__desc[m] = @description
+
+        @description = nil
+      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
+    end  # class DSL
+
+  end  # class Configuration
+end  # module Loquacious
+
+# EOF

data/lib/loquacious/configuration/help.rb

@@ -0,0 +1,151 @@
+
+require 'pp'
+require 'stringio'
+
+class Loquacious::Configuration
+
+  # Generate nicely formatted help messages for a configuration. The Help
+  # class iterates over all the attributes in a configuration and outputs
+  # the name, value, and description to an IO stream. The format of the
+  # messages can be configured, and the description and/or value of the
+  # attribute can be shown or hidden independently.
+  #
+  class Help
+
+    # :stopdoc:
+    @@defaults = {
+      :io => $stdout,
+      :name_leader => '  - '.freeze,
+      :name_length => 0,
+      :name_value_sep => ' => '.freeze,
+      :desc_leader => ' '.freeze
+    }.freeze
+
+    class Error < StandardError; end
+    # :startdoc:
+
+    # Create a new Help instance for the given configuration where _config_
+    # can be either a Configuration instance or a configuration name or
+    # symbol. Several options can be provided to determine how the
+    # configuration information will be printed to the IO stream.
+    #
+    #   :name_leader      String appearing before the attribute name
+    #   :name_length      Maximum length for an attribute name
+    #   :name_value_sep   String separating the attribute name from the value
+    #   :desc_leader      String appearing before the description
+    #   :io               The IO object where help will be written
+    #
+    # The description is printed before each attribute name and value on its
+    # own line.
+    #
+    def initialize( config, opts = {} )
+      opts = @@defaults.merge opts
+      @config = config.kind_of?(::Loquacious::Configuration) ? config :
+                ::Loquacious::Configuration.for(config)
+
+      @io = opts[:io]
+      @name_length = Integer(opts[:name_length])
+      @desc_leader = opts[:desc_leader]
+
+      unless @name_length > 0
+        Iterator.new(@config).each do |node|
+          length = node.name.length
+          @name_length = length if length > @name_length
+        end
+      end
+
+      name_leader = opts[:name_leader]
+      name_value_sep = opts[:name_value_sep]
+      extra_length = name_leader.length + name_value_sep.length
+      name_value_sep = name_value_sep.gsub('%', '%%')
+
+      @value_length = 78 - @name_length - extra_length
+      @value_leader = "\n" + ' '*(@name_length + extra_length)
+      @format = "#{name_leader}%-#{@name_length}s#{name_value_sep}%s"
+      @name_format = "#{name_leader}%s"
+
+      @desc_leader.freeze
+      @value_leader.freeze
+      @format.freeze
+      @name_format.freeze
+    end
+
+    # call-seq:
+    #    show_attribute( name = nil, opts = {} )
+    #
+    # TODO: finish comments and docos
+    #
+    # show available attributes (with/without descriptions)
+    # show current config
+    # show everything
+    #
+    def show_attribute( name = nil, opts = {} )
+      name, opts = nil, name if name.is_a?(Hash)
+      opts = {
+        :descriptions => true,
+        :values => false
+      }.merge!(opts)
+
+      name = normalize_attr(name)
+      show_description = opts[:descriptions]
+      show_value = opts[:values]
+
+      Iterator.new(@config).each(name) do |node|
+        print_node(node, show_description, show_value)
+      end
+    end
+    alias :show :show_attribute
+
+    # Show all attributes for the configuration. The same options allowed by
+    # the +show+ method are also supported by this method.
+    #
+    def show_all( opts = {} )
+      show_attribute(nil, opts)
+    end
+    alias :show_attributes :show_all
+
+    # Normalize the attribute _name_.
+    #
+    def normalize_attr( name )
+      case name
+      when String, nil; name
+      when Symbol; name.to_s
+      when Array;  name.join('.')
+      else
+        raise Error, "cannot convert #{name.inspect} into an attribute identifier"
+      end
+    end
+
+    # Format the attribute name, value, and description and print the
+    # results. The value can be printed or not by setting the _show_value_
+    # flag to either +true+ or +false+. The description can be printed or
+    # not by setting the _show_description_ flag to either +true+ or
+    # +false+.
+    #
+    def print_node( node, show_description, show_value )
+      desc = node.desc.to_s.dup
+      show_description = false if desc.empty?
+      @io.puts(desc.indent(@desc_leader)) if show_description
+      @io.puts(format_name(node, show_value))
+      @io.puts if show_description
+    end
+
+    # Format the name of the attribute pointed at by the given _node_. If
+    # the _show_value_ flag is set to +true+, then the attribute value will
+    # also be included in the returned string.
+    #
+    def format_name( node, show_value )
+      name = node.name.reduce @name_length
+      return @name_format % name if node.config? or !show_value
+
+      sio = StringIO.new
+      PP.pp(node.obj, sio, @value_length)
+      sio.seek 0
+      obj = sio.read.chomp.gsub("\n", @value_leader)
+      @format % [name, obj]
+    end
+
+  end  # class Help
+end  # module Loquacious
+
+# EOF

data/lib/loquacious/configuration/iterator.rb

@@ -0,0 +1,152 @@
+
+class Loquacious::Configuration
+
+  # Provides an external iteraotr for a Loquacious::Configuration object.
+  # The iterator allows the user to retrieve all the configuration settings
+  # along with their descriptions and values.
+  #
+  #   cfg = Configuration.for('foo') {
+  #     bar  'value', :desc => 'the bar attribute'
+  #     baz  42,      :desc => 'the baz attribute'
+  #   }
+  #
+  #   i = Iterator.new(cfg)
+  #   i.each do |node|
+  #     puts "#{node.name} :: #{node.desc}"
+  #   end
+  #
+  # Results in
+  #
+  #   bar :: the bar attribute
+  #   baz :: the baz attribute
+  #
+  class Iterator
+
+    # :stopdoc:
+    attr_reader :stack
+    private :stack
+    # :startdoc:
+
+    # Create a new iterator that will operate on the _config_ (configuration
+    # object). The iterator allows the attributes of the configuration object
+    # to be accessed -- this includes nested configuration objects.
+    #
+    def initialize( config )
+      @config = config
+      @stack = []
+      reset
+    end
+
+    # Iterate over each node in the configuration object yielding each to
+    # the supplied block in turn. The return value of the block is returned
+    # from this method. +nil+ is returned if there are no nodes in the
+    # iterator.
+    #
+    # If an _attribute_ is given, then the iteration starts at that
+    # particular attribute and recurse if it is a nested configuration.
+    # Otherwise, only that attribute is yielded to the block.
+    #
+    def each( attribute = nil )
+      reset
+      rv = nil
+
+      if attribute and !attribute.empty?
+        node = while (n = next_node) do
+                 break n if n.name == attribute
+               end
+        return if node.nil?
+
+        rv = yield node
+        return rv unless node.config?
+
+        stack.clear
+        stack << new_frame(node.obj, node.name) if node.config?
+      end
+
+      while (node = next_node) do
+        rv = yield node
+      end
+      return rv
+    end
+
+    # Find the given named _attribute_ in the iterator. Returns a node
+    # representing the attribute; or +nil+ is returned if the named
+    # attribute could not be found.
+    #
+    def find( attribute )
+      attribute = attribute.to_s
+      return if attribute.empty?
+
+      node = self.each {|n| break n if n.name == attribute}
+      reset
+      return node
+    end
+
+  private
+
+    # Reset the iterator back to the beginning.
+    #
+    def reset
+      stack.clear
+      stack << new_frame(@config)
+    end
+
+    # Returns the next node from the current iteration stack frame. Returns
+    # +nil+ if there are no more nodes in the iterator.
+    #
+    def next_node
+      frame = stack.last
+      node = new_node(frame)
+
+      while node.nil?
+        stack.pop
+        return if stack.empty?
+        frame = stack.last
+        node = new_node(frame)
+      end
+
+      frame.index += 1
+      stack << new_frame(node.obj, node.name) if node.config?
+
+      return node
+    end
+
+    # Create a new stack frame from the given _cfg_ (configuration object)
+    # and the optional _prefix_. The _prefix_ is used to complete the full
+    # name for each attribute key in the configuration object.
+    #
+    def new_frame( cfg, prefix = nil )
+      keys = cfg.__desc.keys.map {|k| k.to_s}
+      keys.sort!
+      keys.map! {|k| k.to_sym}
+
+      Frame.new(cfg, prefix.to_s, keys, 0)
+    end
+
+    # Create the next iteration node from the given stack _frame_. Returns
+    # +nil+ when there are no more nodes in the _frame_.
+    #
+    def new_node( frame )
+      key = frame.keys[frame.index]
+      return if key.nil?
+
+      cfg = frame.config
+      name = frame.prefix.empty? ? key.to_s : frame.prefix + ".#{key}"
+      Node.new(cfg, name, cfg.__desc[key], key)
+    end
+
+    # Structure describing a single iteration stack frame. A new stack frame
+    # is created when we descend into a nested Configuration object.
+    #
+    Frame = Struct.new( :config, :prefix, :keys, :index )
+
+    # This is a single node in a Configuration object. It corresponds to a
+    # single configuration attribute.
+    #
+    Node = Struct.new( :config, :name, :desc, :key ) {
+      def obj() config.__send__(key); end
+      def config?() obj.kind_of? ::Loquacious::Configuration; end
+    }
+
+  end  # class Iterator
+end  # class Loquacious::Configuration