TwP-loquacious 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-04-04
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,234 @@
+= Loquacious
+    by Tim Pease
+    http://codeforpeople.rubyforge.org/loquacious
+
+== DESCRIPTION:
+
+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.
+
+== INSTALL:
+
+* sudo gem install loquacious
+
+== EXAMPLES:
+
+==== example/simple.rb
+  # 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
+
+  ====== output ======
+   Your first configuration option
+    - a => "value for 'a'"
+  
+   To be or not to be
+    - b => "William Shakespeare"
+  
+   The underpinings of Ruby
+    - c => 42
+
+==== examples/nested.rb
+  # 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 {
+      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 <<-__
+        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 <<-__
+      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 <<-__
+      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
+  help.show :values => true
+
+  ====== output ======
+   Configuration options for ActiveRecord::Base.
+    - active_record
+   
+   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.
+    - active_record.colorize_logging => true
+   
+   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.
+    - active_record.default_timezone => :local
+   
+   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
+   
+   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"
+   
+   The application's base directory.
+    - root_path                      => "."
+
+==== examples/gutters.rb
+  # 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.
+
+  require 'loquacious'
+  include Loquacious
+
+  Configuration.for(:gutters) {
+    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,
+      |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
+
+  ====== output ======
+   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
+   
+    - log_level => :warn
+   
+   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"
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,43 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'loquacious'
+
+task :default => 'spec:specdoc'
+
+PROJ.name = 'loquacious'
+PROJ.authors = 'Tim Pease'
+PROJ.email = 'tim.pease@gmail.com'
+PROJ.url = 'http://codeforpeople.rubyforge.org/loquacious'
+PROJ.version = Loquacious::VERSION
+PROJ.readme_file = 'README.rdoc'
+PROJ.ignore_file = '.gitignore'
+PROJ.rubyforge.name = 'codeforpeople'
+
+PROJ.spec.opts << '--color'
+PROJ.ruby_opts = %w[-W0]
+
+PROJ.ann.email[:server] = 'smtp.gmail.com'
+PROJ.ann.email[:port] = 587
+PROJ.ann.email[:from] = 'Tim Pease'
+
+task 'ann:prereqs' do
+  PROJ.name = 'Loquacious'
+end
+
+depend_on 'rspec'
+
+# EOF

data/examples/gutters.rb

@@ -0,0 +1,30 @@
+# 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.
+
+require 'loquacious'
+include Loquacious
+
+Configuration.for(:gutters) {
+  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,
+    |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,47 @@
+# 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 {
+    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 <<-__
+      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 <<-__
+    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 <<-__
+    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
+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,75 @@
+
+module Loquacious
+
+  # :stopdoc:
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  class << self
+
+    # 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
+
+    # 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
+    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 )
+      args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+    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 )
+      args.empty? ? PATH : ::File.join(PATH, args.flatten)
+    end
+
+    # Utility method used to require all files ending in .rb that lie in the
+    # directory below this file that has the same name as the filename
+    # passed in. Optionally, a specific _directory_ name can be passed in
+    # such that the _filename_ does not have to be equivalent to the
+    # directory.
+    #
+    def require_all_libs_relative_to( fname, dir = nil )
+      dir ||= ::File.basename(fname, '.*')
+      search_me = ::File.expand_path(
+          ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+      Dir.glob(search_me).sort.each {|rb| require rb}
+    end
+
+  end  # class << self
+end  # module Loquacious
+
+Loquacious.require_all_libs_relative_to(__FILE__)
+
+# EOF