configurable 0.1.0 → 0.3.0

data/History

@@ -0,0 +1,9 @@
+== 0.3.0 / 2009-02-17
+
+Significant rework of the 0.1.0 release:
+
+* Added CDoc
+* Expanded use of nested configs
+* Added dumping of configs for config files
+* Updates to Range/Regexp validations
+* Numerous bug fixes

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008, Regents of the University of Colorado.
+Copyright (c) 2008-2009, 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

data/README

@@ -1,25 +1,27 @@
 = 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.
+Class configurations that map to the command line.
 
 == 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.
+Configurable allows the declaration of class configurations.  Configurations
+are inheritable, delegate to methods, and have hash-like access. Configurable
+maps configurations to the command line through ConfigParser and is used by
+the Tap[http://tap.rubyforge.org] framework.
 
 Check out these links for development, and bug tracking.
 
 * Website[http://tap.rubyforge.org/configurable]
 * Github[http://github.com/bahuvrihi/configurable/tree/master]
-* Lighthouse[]
+* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/21202-configurable/tickets?q=state%3Aopen]
 * {Google Group}[http://groups.google.com/group/ruby-on-tap]
 
 == Usage
 
-=== Quickstart
+Use the config method to declare class configurations.  A block may be provided
+to validate inputs, and many standard validations are available through the 'c'
+method (an alias for the {Validation}[link:classes/Configurable/Validation.html]
+module).
 
   class ConfigClass
     include Configurable
@@ -38,23 +40,12 @@ Check out these links for development, and bug tracking.
     end
   end
   
-Configurations are present and documented in the class ConfigParser, the
-Configurable equivalent of OptionParser:
+A ConfigParser can parse configurations from command line arguments, and turn
+them into a documented help string:
 
-  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
-  # }
+  parser = ConfigParser.new
+  parser.add(ConfigClass.configurations)
   
-Command line arguments parse as expected:
-
   parser.parse "one two --key=value --flag --no-switch --num 8 --range a..z three"  
   # => ['one', 'two', 'three']
   
@@ -67,21 +58,37 @@ Command line arguments parse as expected:
   # :range => 'a..z',
   # :upcase => 'default'
   # }
+  
+  "\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
+  # }
 
-Validations/transformations occur upon initialization:
+Configurable classes typically call initialize_config to set configurations
+during initialization. The validation/transformation blocks are called as
+configurations are set.  Notice how the :range and :upcase values have been
+transformed from the input config.
   
   c = ConfigClass.new(parser.config)
   c.config.to_hash      
   # => {
   # :key => 'value',
-  # :flag => true,
-  # :switch => false,
+  # :flag => true,            
+  # :switch => false,         
   # :num => 8,
-  # :range => 'a'..'z',
-  # :upcase => 'DEFAULT'
+  # :range => 'a'..'z',       # notice these values
+  # :upcase => 'DEFAULT'      # have been transformed
   # }
 
-Configurations have accessors, and are accessible through config.
+Configurations automatically generate accessors (the blocks are basically
+writer methods), but they are also accessible through the hash-like config
+object.  Configurations are validated every time they are set, regardless of
+whether they are set through an accessor or config.
   
   c.upcase                    # => 'DEFAULT'
   
@@ -91,12 +98,8 @@ Configurations have accessors, and are accessible through config.
   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.
+By default config treats string and symbol keys identically, making YAML an
+obvious choice for configuration files.
 
   yaml_str = %Q{
   key: a new value
@@ -114,113 +117,8 @@ are easily created and used.
   # :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
+See the Configurable module for more details.
 
 == Installation
 
@@ -230,7 +128,7 @@ Configurable is available as a gem on RubyForge[http://rubyforge.org/projects/ta
 
 == Info 
 
-Copyright (c) 2008, Regents of the University of Colorado.
+Copyright (c) 2008-2009, 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/cdoc.rb

@@ -0,0 +1,413 @@
+# RDoc creates a namespace conflict with IRB within 'rdoc/parsers/parse_rb'
+# In that file, RubyToken and RubyLex get defined in the Object namespace,
+# which will conflict with prior definitions from, for instance, IRB.  
+#
+# This code redefines the RDoc RubyToken and RubyLex within the RDoc 
+# namespace.  RDoc is not affected because all includes and uses of 
+# RubyToken and RubyLex are set when RDoc is loaded.  The single exception
+# I know of are several calls to class methods of RubyLex (ex RubyLex.debug?).
+# These calls will be routed to the existing RubyLex.
+#
+# Uses of the existing RubyToken and RubyLex (as by irb) should be 
+# unaffected as the constants are reset after RDoc loads.
+#
+if Object.const_defined?(:RubyToken) || Object.const_defined?(:RubyLex)
+  class Object # :nodoc:
+    old_ruby_token = const_defined?(:RubyToken) ? remove_const(:RubyToken) : nil
+    old_ruby_lex = const_defined?(:RubyLex) ? remove_const(:RubyLex) : nil
+  
+    require 'rdoc/rdoc'
+
+    # if by chance rdoc has ALREADY been loaded then requiring
+    # rdoc will not reset RubyToken and RubyLex... in this case
+    # the old constants are what you want.
+    new_ruby_token = const_defined?(:RubyToken) ? remove_const(:RubyToken) : old_ruby_token
+    new_ruby_lex = const_defined?(:RubyLex) ? remove_const(:RubyLex) : old_ruby_lex
+    
+    RDoc.const_set(:RubyToken, new_ruby_token)
+    RDoc.const_set(:RubyLex, new_ruby_lex)
+  
+    const_set(:RubyToken, old_ruby_token) unless old_ruby_token == nil
+    const_set(:RubyLex, old_ruby_lex) unless old_ruby_lex == nil
+  end
+else
+  require 'rdoc/rdoc'
+
+  if Object.const_defined?(:RubyToken) && !RDoc.const_defined?(:RubyToken)
+    class Object # :nodoc:
+      RDoc.const_set(:RubyToken, remove_const(:RubyToken))
+    end
+  end 
+  
+  if Object.const_defined?(:RubyLex) && !RDoc.const_defined?(:RubyLex)
+    class Object # :nodoc:
+      RDoc.const_set(:RubyLex, remove_const(:RubyLex))
+      RDoc::RubyLex.const_set(:RubyLex, RDoc::RubyLex)
+    end
+  end
+end
+
+unless Object.const_defined?(:TokenStream)
+  TokenStream = RDoc::TokenStream
+  Options = RDoc::Options
+end
+
+# CDoc hooks into and extends RDoc to make Configurable documentation available
+# as attributes.  CDoc provides an extension to the standard RDoc HTMLGenerator
+# and template.
+#
+# === Usage
+# To generate task documentation with configuration information, CDoc must be
+# loaded and the appropriate flags passed to rdoc . Essentially what you want
+# is:
+#
+#   % rdoc --fmt cdoc --template cdoc/cdoc_html_template [file_names....]
+#
+# Unfortunately, there is no way to load or require a file into the rdoc
+# utility directly; the above code causes an 'Invalid output formatter' error.
+# However, CDoc is easy to utilize from a Rake::RDocTask:
+#
+#   require 'rake'
+#   require 'rake/rdoctask'
+#
+#   desc 'Generate documentation.'
+#   Rake::RDocTask.new(:rdoc) do |rdoc|
+#     require 'cdoc'
+#     rdoc.template = 'cdoc/cdoc_html_template'
+#     rdoc.options << '--fmt' << 'cdoc'
+#
+#     # specify whatever else you need
+#     # rdoc.rdoc_files.include(...)
+#   end
+#
+# Now execute the rake task like:
+#
+#   % rake rdoc
+#
+# === Implementation
+#
+# RDoc is a beast to utilize in a non-standard way. One way to make RDoc parse
+# unexpected flags like 'config' or 'config_attr' is to use the '--accessor' 
+# option (see 'rdoc --help' or the RDoc documentation for more details).
+#
+# CDoc hooks into the '--accessor' parsing process to pull out configuration
+# attributes and format them into their own Configuration section on an RDoc
+# html page. When 'cdoc' is specified as an rdoc option, CDoc in effect sets
+# accessor flags for all the standard Task configuration methods, and then
+# extends the RDoc::RubyParser handle these specially.
+#
+# If cdoc is not specified as the rdoc format, CDoc does not affect the RDoc
+# output.  Similarly, the configuration attributes will not appear in the 
+# output unless you specify a template that utilizes them.
+#
+# ==== Namespace conflicts
+#
+# RDoc creates a namespace conflict with other libraries that define RubyToken
+# and RubyLex in the Object namespace (the prime example being IRB). CDoc checks
+# for such a conflict and redfines the RDoc versions of RubyToken and RubyLex 
+# within the RDoc namespace.  Essentially:
+#
+#   original constant    redefined constant
+#   RubyToken            RDoc::RubyToken
+#   RubyLex              RDoc::RubyLex
+#
+# The redefinition should not affect the existing (non RDoc) RubyToken and 
+# RubyLex constants, but if you directly use the RDoc versions after loading
+# CDoc, you should be aware that they must be accessed through the new 
+# constants.  Unfortunatley the trick is not seamless.  The RDoc RubyLex makes
+# a few calls to the RubyLex class method 'debug?'... these will be issued to
+# the existing (non RDoc) RubyLex method and not the redefined 
+# RDoc::RubyLex.debug?
+#
+# In addition, because of the RubyLex calls, the RDoc::RubyLex cannot be fully
+# hidden when CDoc is loaded before the conflicting RubyLex; you cannot load
+# CDoc before loading IRB without raising warnings.  
+#
+# Luckily all these troubles can be avoided very easily by not loading CDoc or
+# RDoc when you're in irb.  On the plus side, going against what I just said,
+# you can now access/use RDoc within irb by requiring <tt>'cdoc'</tt>.
+#
+#-- 
+# Note that tap-0.10.0 heavily refactored CDoc functionality out of the old CDoc
+# and into Lazydoc, and changed the declaration syntax for configurations.  These
+# changes also affected the implementation of CDoc.  Mostly the changes are hacks
+# to get the old system to work in the new system... as hacky as the old CDoc was,
+# now this CDoc is hacky AND may have cruft.  Until it breaks completely, I leave
+# it as is... ugly and hard to fathom.
+#
+module CDoc
+
+  # Encasulates information about the configuration.  Designed to be utilized
+  # by the CDocHTMLGenerator as similarly as possible to standard attributes.
+  class ConfigAttr < RDoc::Attr # :nodoc:
+    # Contains the actual declaration for the config attribute. ex:  "c [:key, 'value']      # comment"
+    attr_accessor :config_declaration, :default
+    
+    def initialize(*args)
+      @comment = nil # suppress a warning in Ruby 1.9
+      super
+    end
+    
+    alias original_comment comment
+    
+    def desc
+      case text.to_s 
+      when /^#--(.*)/ then $1.strip
+      when /^#(.*)/ then $1.strip
+      else
+        nil
+      end
+    end
+    
+    # The description for the config.  Comment is formed from the standard 
+    # attribute comment and the text following the attribute, which is slightly
+    # different than normal:
+    #
+    #   # standard comment
+    #   attr_accessor :attribute              
+    #
+    #  # standard comment
+    #  config_accessor :config    # ...added to standard comment
+    #
+    #  c [:key, 'value']           # hence you can comment inline like this.
+    #
+    # The comments for each of these will be:
+    # attribute:: standard comment
+    # config:: standard comment ...added to standard comment
+    # key:: hence you can comment inline like this.
+    #
+    def comment(add_default=true)
+      # this would include the trailing comment...
+      # text_comment = text.to_s.sub(/^#--.*/m, '')
+      #original_comment.to_s + text_comment + (default && add_default ? " (#{default})" : "")
+      comment = original_comment.to_s.strip
+      comment = desc.to_s if comment.empty?
+      comment + (default && add_default ? " (<tt>#{default}</tt>)" : "")
+    end
+  end
+  
+  module CodeObjectAccess # :nodoc:
+    def comment_sections(section_regexp=//, normalize_comments=false)
+      res = {}
+
+      section = nil
+      lines = []
+      comment_lines = comment.split(/\r?\n/)
+      comment_lines << nil
+      comment_lines.each do |line|
+        case line
+        when nil, /^\s*#\s*=+(.*)/
+          next_section = (line == nil ? nil : $1.to_s.strip)
+
+          if section =~ section_regexp
+            lines << "" unless normalize_comments
+            res[section] = lines.join("\n") unless section == nil
+          end
+
+          section = next_section
+          lines = []
+        else
+          if normalize_comments
+            line =~ /^\s*#\s?(.*)/
+            line = $1.to_s
+          end
+
+          lines << line
+        end
+      end
+
+      res
+    end
+  end
+  
+  module ClassModuleAccess # :nodoc:
+    def find_class_or_module_named(name)
+      return self if full_name == name
+      (@classes.values + @modules.values).each do |c| 
+        res = c.find_class_or_module_named(name)
+        return res if res
+      end
+      nil
+    end
+    
+    def configurations
+      @attributes.select do |attribute|
+        attribute.kind_of?(CDoc::ConfigAttr)
+      end
+    end
+    
+    def find_configuration_named(name)
+      @attributes.each do |attribute|
+        next unless attribute.kind_of?(CDoc::ConfigAttr)
+        return attribute if attribute.name == name
+      end
+      nil
+    end
+  end
+
+  # Overrides the new method automatically extend the new object with
+  # ConfigParser.  Intended to be used like:
+  #   RDoc::RubyParser.extend InitializeConfigParser
+  module InitializeConfigParser # :nodoc:
+    def new(*args)
+      parser = super
+      parser.extend ConfigParser
+      #parser.config_mode = 'config_accessor'
+      parser
+    end
+  end
+  
+  # Provides methods extending an RDoc::RubyParser such that the parser will produce 
+  # CDoc::ConfigAttr instances in the place of RDoc::Attr instances during attribute
+  # parsing. 
+  module ConfigParser # :nodoc:
+    include RDoc::RubyToken
+    include TokenStream
+             
+    CONFIG_ACCESSORS = ['config', 'config_attr']        
+
+    # Gets tokens until the next TkNL
+    def get_tk_to_nl
+      tokens = []
+      while !(tk = get_tk).kind_of?(TkNL)
+        tokens.push tk
+      end
+      unget_tk(tk)
+      tokens
+    end
+
+    # Works like the original parse_attr_accessor, except that the arg
+    # name is parsed from the config syntax and added attribute will
+    # be a CDoc::ConfigAttr.  For example:
+    #
+    #   class ConfigClass
+    #     include Configurable
+    #     config :key, 'value'   # comment
+    #   end
+    #
+    # produces an attribute named :key in the current config_rw mode.
+    #
+    # (see 'rdoc/parsers/parse_rb' line 2509)
+    def parse_config(context, single, tk, comment)
+      tks = get_tk_to_nl
+      
+      key_tk = nil
+      value_tk = nil
+
+      tks.each do |token|
+        next if token.kind_of?(TkSPACE)
+        
+        if key_tk == nil
+          case token
+          when TkSYMBOL then key_tk = token
+          when TkLPAREN then next
+          else break
+          end
+        else
+          case token
+          when TkCOMMA then value_tk = token
+          else
+            value_tk = token if value_tk.kind_of?(TkCOMMA)
+            break
+          end
+        end
+      end
+
+      text = ""
+      if tks.last.kind_of?(TkCOMMENT)
+        text = tks.last.text.chomp("\n").chomp("\r")
+        unget_tk(tks.last)
+          
+        # If nodoc is given, don't document
+          
+        tmp = RDoc::CodeObject.new
+        read_documentation_modifiers(tmp, RDoc::ATTR_MODIFIERS)
+        text = nil unless tmp.document_self
+      end
+      
+      tks.reverse_each {|token| unget_tk(token) }
+      return if key_tk == nil || text == nil
+      
+      arg = key_tk.text[1..-1]
+      default = nil
+      if value_tk
+        if text =~ /(.*):no_default:(.*)/
+          text = $1 + $2
+        else
+          default = value_tk.text
+        end
+      end
+      att = CDoc::ConfigAttr.new(text, arg, "RW", comment)
+      att.config_declaration = get_tkread
+      att.default = default
+       
+      context.add_attribute(att)
+    end
+    
+    # Overrides the standard parse_attr_accessor method to hook in parsing
+    # of the config accessors.  If the input token is not named as one of the
+    # CONFIG_ACCESSORS, it will be processed normally.
+    def parse_attr_accessor(context, single, tk, comment)
+      case tk.name
+      when 'config', 'config_attr'
+          parse_config(context, single,  tk, comment)
+      else
+        super
+      end
+    end
+  end
+end
+
+# Register the CDoc generator (in case you want to actually use it).
+# method echos RDoc generator registration (see 'rdoc/rdoc' line 76)
+Generator = Struct.new(:file_name, :class_name, :key)
+RDoc::RDoc::GENERATORS['cdoc'] = Generator.new(
+  "cdoc/cdoc_html_generator.rb",
+  "CDocHTMLGenerator".intern,
+  "cdoc")
+
+# Add the extended accessors to context classes.
+module RDoc # :nodoc:
+  class CodeObject # :nodoc:
+    include CDoc::CodeObjectAccess  
+  end
+  
+  class ClassModule # :nodoc:
+    include CDoc::ClassModuleAccess
+  end
+end
+
+# Override methods in Options to in effect incorporate the accessor 
+# flags for CDoc parsing. (see 'rdoc/options')  Raise an error if an
+# accessor flag has already been specified. 
+class Options # :nodoc:
+  alias cdoc_original_parse parse
+  
+  def parse(argv, generators)
+    cdoc_original_parse(argv, generators)
+    return unless @generator_name == 'cdoc'
+    
+    accessors = CDoc::ConfigParser::CONFIG_ACCESSORS
+    
+    # check the config_accessor_flags for accessor conflicts
+    extra_accessor_flags.each_pair do |accessor, flag|
+      if accessors.include?(accessor)
+        raise OptionList.error("cdoc format already handles the accessor '#{accessor}'")
+      end
+    end
+    
+    # extra_accessors will be nil if no extra accessors were 
+    # specifed, otherwise it'll be a regexp like /^(...)$/
+    # the string subset assumes
+    #   regexp.to_s # => /(?-mix:^(...)$)/  
+    @extra_accessors ||= /^()$/ 
+    current_accessors_str = @extra_accessors.to_s[9..-4]
+    
+    # echos the Regexp production code in rdoc/options.rb
+    # (see the parse method, line 501)
+    re = '^(' + current_accessors_str + accessors.map{|a| Regexp.quote(a)}.join('|') + ')$' 
+    @extra_accessors = Regexp.new(re)
+    
+    RDoc::RubyParser.extend CDoc::InitializeConfigParser 
+  end
+end