loquacious 1.0.0

data/lib/loquacious/core_ext/string.rb

@@ -0,0 +1,75 @@
+
+class String
+
+  # call-seq:
+  #    reduce( width, ellipses = '...' )    #=> string
+  #
+  # Reduce the size of the current string to the given _width_ by removing
+  # characters from the middle of the string and replacing them with
+  # _ellipses_. If the _width_ is greater than the length of the string, the
+  # string is returned unchanged. If the _width_ is less than the length of
+  # the _ellipses_, then the _ellipses_ are returned.
+  #
+  def reduce( width, ellipses = '...')
+    raise ArgumentError, "width cannot be negative: #{width}" if width < 0
+
+    return self if length <= width
+
+    remove = length - width + ellipses.length
+    return ellipses.dup if remove >= length
+
+    left_end = (length + 1 - remove) / 2
+    right_start = left_end + remove
+
+    left = self[0,left_end]
+    right = self[right_start,length-right_start]
+
+    left << ellipses << right
+  end
+
+  # call-seq:
+  #    "foo".indent( 2 )        #=> "  foo"
+  #    "foo".indent( '#  ' )    #=> "# foo"
+  #
+  # Indent the string by the given number of spaces. Alternately, if a
+  # leader string is given it will be used to indent with instead of spaces.
+  # Indentation is performed at the beginning of the string and after every
+  # newline character.
+  #
+  #   "foo\nbar".indent( 2 )    #=> "  foo\n  bar"
+  #
+  def indent( leader )
+    leader =
+        Numeric === leader ? ' ' * leader.to_i : leader.to_s
+    str = self.gsub("\n", "\n"+leader)
+    str.insert(0, leader)
+    str
+  end
+
+  # call-seq:
+  #    "  | foo\n  | bar".gutter!    #=> " foo\n bar"
+  #
+  # Removes a leading _gutter_ from all lines in the string. The gutter is
+  # defined leading whitespace followed by a single pipe character. This
+  # method is very useful with heredocs.
+  #
+  # The string will be altered by this method.
+  #
+  def gutter!
+    gsub! %r/^[\t\f\r ]*\|?/, ''
+    self
+  end
+
+  # call-seq:
+  #    "  | foo\n  | bar".gutter!    #=> " foo\n bar"
+  #
+  # Removes a leading _gutter_ from all lines in the string. The gutter is
+  # defined leading whitespace followed by a single pipe character. This
+  # method is very useful with heredocs.
+  #
+  def gutter
+    self.dup.gutter!
+  end
+end  # class String
+
+# EOF

data/loquacious.gemspec

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{loquacious}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tim Pease"]
+  s.date = %q{2009-04-04}
+  s.description = %q{Descriptive configuration files for Ruby written in Ruby.  Loquacious provides a very open configuration system written in ruby and descriptions for each configuration attribute. The attributes and descriptions can be iterated over allowing for helpful information about those attributes to be displayed to the user.  In the simple case we have a file something like  Loquacious.configuration_for('app') { name 'value', :desc => "Defines the name" foo  'bar',   :desc => "FooBar" id   42,      :desc => "Ara T. Howard" }  Which can be loaded via the standard Ruby loading mechanisms  Kernel.load 'config/app.rb'  The attributes and their descriptions can be printed by using a Help object  help = Loquacious.help_for('app') help.show :values => true        # show the values for the attributes, too  Descriptions are optional, and configurations can be nested arbitrarily deep.  Loquacious.configuration_for('nested') { desc "The outermost level" a { desc "One more level in" b { desc "Finally, a real value" c 'value' } } }  config = Loquacious.configuration_for('nested')  p config.a.b.c  #=> "value"  And as you can see, descriptions can either be given inline after the value or they can appear above the attribute and value on their own line.}
+  s.email = %q{tim.pease@gmail.com}
+  s.extra_rdoc_files = ["History.txt", "README.rdoc"]
+  s.files = ["History.txt", "README.rdoc", "Rakefile", "examples/gutters.rb", "examples/nested.rb", "examples/simple.rb", "lib/loquacious.rb", "lib/loquacious/configuration.rb", "lib/loquacious/configuration/help.rb", "lib/loquacious/configuration/iterator.rb", "lib/loquacious/core_ext/string.rb", "loquacious.gemspec", "spec/configuration_spec.rb", "spec/help_spec.rb", "spec/iterator_spec.rb", "spec/loquacious_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "spec/string_spec.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://codeforpeople.rubyforge.org/loquacious}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{codeforpeople}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Descriptive configuration files for Ruby written in Ruby}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rspec>, [">= 1.1.12"])
+      s.add_development_dependency(%q<bones>, [">= 2.4.2"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.1.12"])
+      s.add_dependency(%q<bones>, [">= 2.4.2"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.1.12"])
+    s.add_dependency(%q<bones>, [">= 2.4.2"])
+  end
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,152 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Loquacious::Configuration do
+  before(:all) do
+    @respond_to = Object.instance_method(:respond_to?)
+  end
+
+  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.should == 'foo'
+    obj.second.should == 'bar'
+    obj.third.should be_nil
+  end
+
+  it 'should respond to any method' do
+    @obj.first.should be_nil
+    @obj.first = 'foo'
+    @obj.first.should == 'foo'
+
+    @obj.second = 'bar'
+    @obj.second.should == 'bar'
+  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.foo
+    m.call(:foo).should == true
+    m.call(:foo=).should == true
+  end
+
+  it 'should provide a hash object for storing method descriptions' do
+    h = @obj.__desc
+    @obj.__desc.should equal(h)
+  end
+
+  # -----------------------------------------------------------------------
+  describe 'when merging' do
+
+    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.should be_nil
+      @obj.second.should be_nil
+      @obj.__desc.should == {}
+
+      @obj.merge! other
+      @obj.first.should == 'foo'
+      @obj.second.should == 'bar'
+      @obj.__desc.should == {
+        :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.should == 'foo'
+      @obj.second.should == 'bar'
+      @obj.third.question.should == '?'
+      @obj.third.answer.should == 42
+
+      @obj.__desc.should == {
+        :first => 'foo method',
+        :second => 'bar method',
+        :third => 'the third group'
+      }
+      @obj.third.__desc.should == {
+        :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 == "This is the first thing we are defining in this config.\nIt has a multiline comment."
+      other.__desc[:second].should == "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 == "  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
+end
+
+# EOF

data/spec/help_spec.rb

@@ -0,0 +1,323 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Loquacious::Configuration::Help do
+
+  before :all do
+    @sio = StringIO.new
+  end
+
+  before :each do
+    @config = Loquacious.configuration_for 'specs'
+    @help = Loquacious::Configuration::Help.new 'specs', :io => @sio
+    @sio.clear
+  end
+
+  it "returns a help object by name" do
+    help = Loquacious::Configuration::Help.new 'specs'
+    config = help.instance_variable_get(:@config)
+    config.should equal(@config)
+  end
+
+  it "returns a help object for a configuration" do
+    help = Loquacious::Configuration::Help.new @config
+    config = help.instance_variable_get(:@config)
+    config.should equal(@config)
+  end
+
+  it "raises an error for invalid attribute names" do
+    lambda {@help.show(42)}.should raise_error(
+        Loquacious::Configuration::Help::Error,
+        "cannot convert 42 into an attribute identifier"
+    )
+  end
+
+  it "prints out all attribues" do
+    str = <<-OUTPUT
+    | foo method
+    |  - first
+    |
+    | bar method
+    |  - second
+    |
+    | the third group
+    |  - third
+    |
+    | life the universe and everything
+    |  - third.answer
+    |
+    | perhaps you do not understand
+    |  - third.question
+    |
+    OUTPUT
+
+    @help.show_all
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "prints out a specific attribute" do
+    str = <<-OUTPUT
+    | bar method
+    |  - second
+    |
+    OUTPUT
+    @help.show_attribute :second
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "properly parses nested attributes" do
+    str = <<-OUTPUT
+    | the third group
+    |  - third
+    |
+    | life the universe and everything
+    |  - third.answer
+    |
+    | perhaps you do not understand
+    |  - third.question
+    |
+    OUTPUT
+    @help.show_attribute 'third'
+    @sio.to_s.should == str.gutter!
+
+    @sio.clear
+    str = <<-OUTPUT
+    | perhaps you do not understand
+    |  - third.question
+    |
+    OUTPUT
+    @help.show_attribute %w[third question]
+    @sio.to_s.should == str.gutter!
+
+    @sio.clear
+    str = <<-OUTPUT
+    | life the universe and everything
+    |  - third.answer
+    |
+    OUTPUT
+    @help.show_attribute 'third.answer'
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "preserves indentation for descriptions" do
+    Loquacious.configuration_for('specs') do
+      desc <<-DESC
+      This is a multiline description that has an example.
+      |
+      |   foo = %w[one two three]
+      |
+      See, the example is right above this line.
+      Hope it was instructive.
+      DESC
+      fourth 'the fourth value'
+    end
+
+    str = <<-OUTPUT
+    | This is a multiline description that has an example.
+    | 
+    |    foo = %w[one two three]
+    | 
+    | See, the example is right above this line.
+    | Hope it was instructive.
+    |  - fourth
+    |
+    OUTPUT
+    @help.show_attribute 'fourth'
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "pretty prints values" do
+    str = <<-OUTPUT
+    | foo method
+    |  - first          => "foo"
+    |
+    | bar method
+    |  - second         => "bar"
+    |
+    | the third group
+    |  - third
+    |
+    | life the universe and everything
+    |  - third.answer   => 42
+    |
+    | perhaps you do not understand
+    |  - third.question => :symbol
+    |
+    OUTPUT
+    @help.show :values => true
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "closely packs attributes when descriptions are omitted" do
+    str = <<-OUTPUT
+    |  - first          => "foo"
+    |  - second         => "bar"
+    |  - third
+    |  - third.answer   => 42
+    |  - third.question => :symbol
+    OUTPUT
+    @help.show_all :values => true, :descriptions => false
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "automatically picks up changes to the configuration" do
+    Loquacious.configuration_for('specs') do
+      fifth 'foo', :desc => 'the fifth configuration setting'
+    end
+
+    str = <<-OUTPUT
+    | the fifth configuration setting
+    |  - fifth
+    |
+    OUTPUT
+    @help.show_attribute 'fifth'
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "uses a custom name leader" do
+    help = Loquacious.help_for 'specs', :io => @sio, :name_leader => ' ## '
+    str = <<-OUTPUT
+    | foo method
+    | ## first
+    |
+    | bar method
+    | ## second
+    |
+    | the third group
+    | ## third
+    |
+    | life the universe and everything
+    | ## third.answer
+    |
+    | perhaps you do not understand
+    | ## third.question
+    |
+    OUTPUT
+    help.show_all
+    @sio.to_s.should == str.gutter!
+
+    @sio.clear
+    str = <<-OUTPUT
+    | ## first          => "foo"
+    | ## second         => "bar"
+    | ## third
+    | ## third.answer   => 42
+    | ## third.question => :symbol
+    OUTPUT
+    help.show_all :values => true, :descriptions => false
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "uses a custom name length" do
+    help = Loquacious.help_for 'specs', :io => @sio, :name_length => 10
+    str = <<-OUTPUT
+    | foo method
+    |  - first
+    |
+    | bar method
+    |  - second
+    |
+    | the third group
+    |  - third
+    |
+    | life the universe and everything
+    |  - thir...wer
+    |
+    | perhaps you do not understand
+    |  - thir...ion
+    |
+    OUTPUT
+    help.show_all
+    @sio.to_s.should == str.gutter!
+
+    @sio.clear
+    str = <<-OUTPUT
+    |  - first      => "foo"
+    |  - second     => "bar"
+    |  - third
+    |  - thir...wer => 42
+    |  - thir...ion => :symbol
+    OUTPUT
+    help.show_all :values => true, :descriptions => false
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "uses a custom name/value separator" do
+    help = Loquacious.help_for 'specs', :io => @sio, :name_value_sep => ' :: '
+    str = <<-OUTPUT
+    | foo method
+    |  - first          :: "foo"
+    |
+    | bar method
+    |  - second         :: "bar"
+    |
+    | the third group
+    |  - third
+    |
+    | life the universe and everything
+    |  - third.answer   :: 42
+    |
+    | perhaps you do not understand
+    |  - third.question :: :symbol
+    |
+    OUTPUT
+    help.show_all :values => true
+    @sio.to_s.should == str.gutter!
+
+    @sio.clear
+    str = <<-OUTPUT
+    |  - first          :: "foo"
+    |  - second         :: "bar"
+    |  - third
+    |  - third.answer   :: 42
+    |  - third.question :: :symbol
+    OUTPUT
+    help.show_all :values => true, :descriptions => false
+    @sio.to_s.should == str.gutter!
+  end
+
+  it "uses a custom description leader" do
+    Loquacious.configuration_for('specs') do
+      desc <<-DESC
+      This is a multiline description that has an example.
+      |
+      |   foo = %w[one two three]
+      |
+      See, the example is right above this line.
+      Hope it was instructive.
+      DESC
+      fourth 'the fourth value'
+    end
+
+    help = Loquacious.help_for 'specs', :io => @sio, :desc_leader => '~'
+    str = <<-OUTPUT
+    |~foo method
+    |  - first          => "foo"
+    |
+    |~This is a multiline description that has an example.
+    |~
+    |~   foo = %w[one two three]
+    |~
+    |~See, the example is right above this line.
+    |~Hope it was instructive.
+    |  - fourth         => "the fourth value"
+    |
+    |~bar method
+    |  - second         => "bar"
+    |
+    |~the third group
+    |  - third
+    |
+    |~life the universe and everything
+    |  - third.answer   => 42
+    |
+    |~perhaps you do not understand
+    |  - third.question => :symbol
+    |
+    OUTPUT
+    help.show_all :values => true
+    @sio.to_s.should == str.gutter!
+  end
+end
+
+# EOF