configurable 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008, Regents of the University of Colorado.
+
+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/README

@@ -0,0 +1,237 @@
+= Configurable[http://tap.rubyforge.org/configurable]
+
+Class configurations that map to the command line.  Configurable is used by the
+Tap[http://tap.rubyforge.org] framework.
+
+== Description
+
+Configurable allows the declaration of inheritable, class-based configurations
+that map to methods but may be accessed like a hash; a setup that is both fast
+and convenient.  Configurable facilitates the use of configuration files, and
+parsing of configurations from the command line.
+
+Check out these links for development, and bug tracking.
+
+* Website[http://tap.rubyforge.org/configurable]
+* Github[http://github.com/bahuvrihi/configurable/tree/master]
+* Lighthouse[]
+* {Google Group}[http://groups.google.com/group/ruby-on-tap]
+
+== Usage
+
+=== Quickstart
+
+  class ConfigClass
+    include Configurable
+
+    config :key, 'default', :short => 'k'   # a simple config with short
+    config :flag, false, &c.flag            # a flag config
+    config :switch, false, &c.switch        # a --[no-]switch config
+    config :num, 10, &c.integer             # integer only
+    config :range, 1..10, &c.range          # range only
+    config :upcase, 'default' do |value|    # custom transformation
+      value.upcase
+    end
+
+    def initialize(overrides={})
+      initialize_config(overrides)
+    end
+  end
+  
+Configurations are present and documented in the class ConfigParser, the
+Configurable equivalent of OptionParser:
+
+  parser = ConfigClass.parser
+  parser.class                        # => ConfigParser
+  "\n" + parser.to_s
+  # => %Q{
+  #    -k, --key KEY                    a simple config with short
+  #        --flag                       a flag config
+  #        --[no-]switch                a --[no-]switch config
+  #        --num NUM                    integer only
+  #        --range RANGE                range only
+  #        --upcase UPCASE              custom transformation
+  # }
+  
+Command line arguments parse as expected:
+
+  parser.parse "one two --key=value --flag --no-switch --num 8 --range a..z three"  
+  # => ['one', 'two', 'three']
+  
+  parser.config  
+  # => {
+  # :key => 'value',
+  # :flag => true,
+  # :switch => false,
+  # :num => '8',
+  # :range => 'a..z',
+  # :upcase => 'default'
+  # }
+
+Validations/transformations occur upon initialization:
+  
+  c = ConfigClass.new(parser.config)
+  c.config.to_hash      
+  # => {
+  # :key => 'value',
+  # :flag => true,
+  # :switch => false,
+  # :num => 8,
+  # :range => 'a'..'z',
+  # :upcase => 'DEFAULT'
+  # }
+
+Configurations have accessors, and are accessible through config.
+  
+  c.upcase                    # => 'DEFAULT'
+  
+  c.config[:upcase] = 'neW valuE'
+  c.upcase                    # => 'NEW VALUE'
+
+  c.upcase = 'fiNal Value'
+  c.config[:upcase]           # => 'FINAL VALUE'
+
+Note that configurations are validated every time they are set:
+
+  c.num = 'blue'              # !> ValidationError
+
+By default config treats strings and symbols as the same, so YAML config files
+are easily created and used.
+
+  yaml_str = %Q{
+  key: a new value
+  flag: false
+  range: 1..100
+  }
+  
+  c.reconfigure(YAML.load(yaml_str))
+  c.config.to_hash      
+  # => {
+  # :key => 'a new value',
+  # :flag => false,
+  # :switch => false,
+  # :num => 8,
+  # :range => 1..100,
+  # :upcase => 'FINAL VALUE'
+  # }
+  
+=== Declarations
+
+Configurations are added to classes via declarations.  Declarations are a lot
+like specifying an attribute reader, writer, and the initialization code.
+
+  class ConfigClass
+    include Configurable
+
+    config :key, 'value' do |input|
+      input.upcase
+    end
+  
+    def initialize
+      initialize_config
+    end
+  end
+
+Is basically the same as:
+
+  class RegularClass
+    attr_reader :key
+
+    def key=(input)
+      @key = input.upcase
+    end
+
+    def initialize
+      self.key = 'value'
+    end
+  end
+  
+As far as the reader/writer goes, the analogy is quite good.  The writer
+method is defined so it sets the instance variable using the return of the 
+block.  To literally define the writer with the block, use config_attr.
+
+  class ConfigAttrClass
+    include Configurable
+
+    config_attr :key, 'value' do |input|
+      @key = input.upcase
+    end
+  end
+
+Literally defines methods:
+
+  class RegularClass
+    attr_reader :key
+
+    def key=(input)
+      @key = input.upcase
+    end
+  end
+
+=== Validation
+
+When configurations are parsed from the command line, the config writers will
+inevitably receive a string (even though the code may want a different object).
+The {Validation}[link:classes/Configurable/Validation.html] module provides 
+standard blocks for validating and transforming string inputs and is accessible
+in classes via the <tt>c</tt> method (ex: <tt>c.integer</tt> or 
+<tt>c.regexp</tt>).  These blocks (generally) load string inputs as YAML and 
+validate that the result is the correct class; non-string inputs are simply
+validated.
+
+  class ValidatingClass
+    include Configurable
+
+    config :int, 1, &c.integer                 # assures the input is an integer
+    config :int_or_nil, 1, &c.integer_or_nil   # integer or nil only
+    config :array, [], &c.array                # you get the idea
+  end
+
+  vc = ValidatingClass.new
+
+  vc.array = [:a, :b, :c]
+  vc.array                                     # => [:a, :b, :c]
+
+  vc.array = "[1, 2, 3]"
+  vc.array                                     # => [1, 2, 3]
+
+  vc.array = "string"                          # !> ValidationError
+
+Validation blocks sometimes imply metadata.  For instance <tt>c.flag</tt> causes
+the config to appear as a flag on the command line.  Metadata can be manually
+specified in the options:
+
+  class ManualMetadata
+    include Configurable
+
+    config :key, 'default', :type => :flag do
+      # this block is only called if --key
+      # is specified, and will not take a
+      # value
+    end
+  end
+
+=== Documentation
+
+Documentation on the command line is pulled from the code directly using
+Lazydoc[http://tap.rubyforge.org/lazydoc/].  Documentation is a kind of
+metadata for configurations, and may be specified manually as an option:
+
+  class ManualDocumentation
+    include Configurable
+    config :key, 'default', :desc => 'this is the command line description'
+  end
+
+== Installation
+
+Configurable is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+
+  % gem install configurable
+
+== Info 
+
+Copyright (c) 2008, Regents of the University of Colorado.
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
+Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+Licence:: {MIT-Style}[link:files/MIT-LICENSE.html]
+

data/lib/config_parser.rb

@@ -0,0 +1,216 @@
+require 'config_parser/option'
+require 'config_parser/switch'
+
+autoload(:Shellwords, 'shellwords')
+
+class ConfigParser
+  class << self
+    # Splits and nests compound keys of a hash.
+    #
+    #   ConfigParser.nest('key' => 1, 'compound:key' => 2)
+    #   # => {
+    #   # 'key' => 1,
+    #   # 'compound' => {'key' => 2}
+    #   # }
+    #
+    # Nest does not do any consistency checking, so be aware that results will
+    # be ambiguous for overlapping compound keys.
+    #
+    #   ConfigParser.nest('key' => {}, 'key:overlap' => 'value')
+    #   # =? {'key' => {}}
+    #   # =? {'key' => {'overlap' => 'value'}}
+    #
+    def nest(hash, split_char=":")
+      result = {}
+      hash.each_pair do |compound_key, value|
+        if compound_key.kind_of?(String)
+          keys = compound_key.split(split_char)
+      
+          unless keys.length == 1
+            nested_key = keys.pop
+            nested_hash = keys.inject(result) {|target, key| target[key] ||= {}}
+            nested_hash[nested_key] = value
+            next
+          end
+        end
+    
+        result[compound_key] = value
+      end
+  
+      result
+    end
+  end
+  
+  include Utils
+
+  # A hash of (switch, Option) pairs mapping switches to
+  # options.
+  attr_reader :switches
+  
+  attr_reader :config
+  
+  attr_reader :default_config
+
+  def initialize
+    @options = []
+    @switches = {}
+    @config = {}
+    @default_config = {}
+  
+    yield(self) if block_given?
+  end
+
+  # Returns an array of options registered with self.
+  def options
+    @options.select do |opt|
+      opt.kind_of?(Option)
+    end
+  end
+
+  # Adds a separator string to self.
+  def separator(str)
+    @options << str
+  end
+
+  # Registers the option with self by adding opt to options and mapping
+  # the opt switches. Raises an error for conflicting keys and switches.
+  def register(opt)
+    @options << opt unless @options.include?(opt)
+
+    opt.switches.each do |switch|
+      case @switches[switch]
+      when opt then next
+      when nil then @switches[switch] = opt
+      else raise ArgumentError, "switch is already mapped to a different option: #{switch}"
+      end
+    end
+
+    opt
+  end
+
+  # Defines and registers a config with self.
+  def define(key, default_value=nil, options={})
+    # check for conflicts and register
+    if default_config.has_key?(key)
+      raise ArgumentError, "already set by a different option: #{key.inspect}"
+    end
+    default_config[key] = default_value
+    
+    block = case options[:type]
+    when :switch then setup_switch(key, default_value, options)
+    when :flag   then setup_flag(key, default_value, options)
+    when :list   then setup_list(key, options)
+    when nil     then setup_option(key, options)
+    when respond_to?("setup_#{options[:type]}")
+      send("setup_#{options[:type]}", key, default_value, options)
+    else 
+      raise ArgumentError, "unsupported type: #{options[:type]}"
+    end
+    
+    on(options, &block)
+  end
+  
+  def on(*args, &block)
+    options = args.last.kind_of?(Hash) ? args.pop : {}
+    args.each do |arg|
+      # split switch arguments... descriptions
+      # still won't match as a switch even
+      # after a split
+      switch, arg_name = arg.split(' ', 2)
+      
+      # determine the kind of argument specified
+      key = case switch
+      when SHORT_OPTION then :short
+      when LONG_OPTION  then :long
+      else :desc
+      end
+      
+      # check for conflicts
+      if options[key]
+        raise ArgumentError, "conflicting #{key} options: [#{options[key]}, #{arg}]"
+      end
+      
+      # set the option
+      case key
+      when :long, :short
+        options[key] = switch
+        options[:arg_name] = arg_name.strip if arg_name
+      else
+        options[key] = arg.strip
+      end
+    end
+    
+    # check if the option is specifying a Switch
+    klass = case
+    when options[:long].to_s =~ /^--\[no-\](.*)$/ 
+      options[:long] = "--#{$1}"
+      Switch
+    else 
+      Option
+    end
+    
+    # instantiate and register the new option
+    register klass.new(options, &block) 
+  end
+  
+  # Parse is non-destructive to argv.  If a string argv is provided, parse
+  # splits it into an array using Shellwords.
+  #
+  def parse(argv=ARGV, config={})
+    @config = config
+    argv = argv.kind_of?(String) ? Shellwords.shellwords(argv) : argv.dup
+    args = []
+    
+    while !argv.empty?
+      arg = argv.shift
+  
+      # determine if the arg is an option
+      unless arg.kind_of?(String) && arg[0] == ?-
+        args << arg
+        next
+      end
+      
+      # add the remaining args and break
+      # for the option break
+      if arg == OPTION_BREAK
+        args.concat(argv)
+        break
+      end
+  
+      # split the arg...
+      # switch= $1
+      # value = $4 || $3 (if arg matches SHORT_OPTION, value is $4 or $3 otherwise)
+      arg =~ LONG_OPTION || arg =~ SHORT_OPTION || arg =~ ALT_SHORT_OPTION 
+  
+      # lookup the option
+      unless option = @switches[$1]
+        raise "unknown option: #{$1}"
+      end
+  
+      option.parse($1, $4 || $3, argv)
+    end
+    
+    default_config.each_pair do |key, default|
+      config[key] = default unless config.has_key?(key)
+    end
+    
+    args
+  end
+  
+  # Same as parse, but removes parsed args from argv.
+  def parse!(argv=ARGV, config={})
+    argv.replace(parse(argv, config))
+  end
+
+  def to_s
+    comments = @options.collect do |option|
+      next unless option.respond_to?(:desc)
+      option.desc.kind_of?(Lazydoc::Comment) ? option.desc : nil
+    end.compact
+    Lazydoc.resolve_comments(comments)
+    
+    @options.collect do |option|
+      option.to_s.rstrip
+    end.join("\n") + "\n"
+  end
+end